​
Repository-Based Tools

Repository-based tools are standalone projects that can be published and shared with other Compozy users. You can create tools using either TypeScript (running on Deno runtime) or Python, which can be compiled into platform-specific binaries for efficient distribution.

​
Repository Structure

my-tool/
├── deno.json          # Deno configuration and tasks
├── manifest.yaml      # Tool metadata and schema definitions
├── README.md          # Documentation
├── src/               # Source code directory
│   ├── index.ts       # Main entry point
│   └── lib/           # Additional modules
├── tests/             # Test files
│   └── index.test.ts
├── dist/              # Compiled binaries
└── my-tool

​
Project Configuration

The deno.json file configures your development environment and build process:
{
  "tasks": {
    "dev": "deno run --allow-read --allow-net src/index.ts",
    "test": "deno test --allow-read --allow-net tests/",
    "compile": "deno compile --allow-read --allow-net --output dist/stock-price src/index.ts",
  },
}
The compile task is required in your deno.json file. Compozy uses this task to compile your tool into a platform-specific binary during the publishing process.

​
Manifest File

The manifest.yaml defines your tool’s metadata, configuration, and I/O schema. Here’s a comprehensive example:
The type field is required and must be set to tool. For Python projects, set main: src/main.py instead of src/index.ts.
type: tool
name: stock-price
version: 1.0.0
license: MIT
description: Fetch real-time stock prices from various financial markets
repository: https://github.com/your-org/stock-price
main: src/index.ts  # Use src/main.py for Python projects

tags:
  - stocks
  - finance

author:
  name: Your Name
  email: your.email@example.com
  organization: Your Organization

schema:
  config:
    type: object
    properties:
      api_key:
        type: string
        description: "API key for accessing stock data"
      rate_limit:
        type: number
        description: "Maximum API calls per minute"
        default: 60
    required: [api_key]

  input:
    type: object
    properties:
      symbol:
        type: string
        description: "Stock symbol (e.g., AAPL, GOOGL)"
        pattern: "^[A-Z]{1,5}$"
      market:
        type: string
        description: "Stock exchange (e.g., NYSE, NASDAQ)"
        enum: ["NYSE", "NASDAQ", "LSE", "TSE"]
        default: "NYSE"
    required: [symbol]

  output:
    type: object
    properties:
      price:
        type: number
        description: "Current stock price"
      currency:
        type: string
        description: "Price currency (ISO 4217)"
        pattern: "^[A-Z]{3}$"
      timestamp:
        type: string
        description: "Last update timestamp (ISO 8601)"
        format: "date-time"
      change_24h:
        type: number
        description: "Price change in the last 24 hours (%)"
    required: [price, currency, timestamp]

​
Implementation

Your src/index.ts should implement the schema defined in the manifest:
// You can use imports as usual with Deno
import { StockAPI } from 'npm:stock-api';
import { validateInput } from 'jsr:@std/validation';

interface Config {
  api_key: string;
  rate_limit?: number;
}

interface Input {
  symbol: string;
  market?: 'NYSE' | 'NASDAQ' | 'LSE' | 'TSE';
}

interface Output {
  price: number;
  currency: string;
  timestamp: string;
  change_24h?: number;
}

export async function run(input: Input, config: Config): Promise<Output> {
  // Validate input
  validateInput(input);

  // Initialize API with rate limiting
  const api = new StockAPI({
    apiKey: config.api_key,
    rateLimit: config.rate_limit ?? 60
  });

  // Fetch stock data
  const data = await api.getPrice(input.symbol, input.market);

  return {
    price: data.price,
    currency: data.currency,
    timestamp: new Date().toISOString(),
    change_24h: data.change_24h
  };
}

​
Publishing Process

1

Prepare Your Repository

  • Initialize a GitHub repository
  • Set up CI/CD workflows for testing and releases
  • Include comprehensive documentation in README.md
2

Quality Checks

  • Write unit tests covering main functionality
  • Add integration tests for API interactions
  • Ensure proper error handling and input validation
3

Version and Release

  • Use semantic versioning (MAJOR.MINOR.PATCH)
  • Create GitHub releases with detailed changelogs
  • Tag releases (e.g., v1.0.0)
4

Build and Distribution

# Compile for all platforms
deno task compile
5

Submit to Registry

Once your tool is ready for distribution:
# Login to Compozy CLI
compozy login

# Submit your tool
compozy publish
After submission, our team will review your tool to ensure it meets our quality and security standards. You’ll receive notifications about the review process and when your tool is approved and listed in the registry.
Make sure your repository is public and the latest release tag matches the version in your manifest.yaml before publishing.