Skip to main content

Quickstart

This guide will walk you through creating a CTP-compliant tool from scratch.

Installation

npm install @conveniencepro/ctp-core @conveniencepro/ctp-runtime

Create a Tool

Create a new file my-tool.ts:
import type { ToolDefinition, ToolFunction } from '@conveniencepro/ctp-core';

// 1. Define the tool's result type
interface UppercaseResult {
  result: string;
  originalLength: number;
}

// 2. Create the tool definition
export const uppercaseDefinition: ToolDefinition = {
  id: 'uppercase-converter',
  name: 'Uppercase Converter',
  description: 'Convert text to uppercase.',
  category: 'converters',
  tags: ['uppercase', 'text', 'convert'],
  method: 'POST',
  parameters: [
    {
      name: 'text',
      type: 'textarea',
      label: 'Input Text',
      description: 'Text to convert to uppercase',
      required: true,
    },
  ],
  outputDescription: 'Uppercase version of the input text',
  example: {
    input: { text: 'hello world' },
    output: { result: 'HELLO WORLD', originalLength: 11 },
  },
  executionMode: 'client',
};

// 3. Implement the tool function
export const uppercaseFn: ToolFunction<UppercaseResult> = (params) => {
  const text = params.text as string;

  if (!text) {
    return {
      success: false,
      error: 'Text is required',
      errorCode: 'MISSING_REQUIRED',
    };
  }

  return {
    success: true,
    data: {
      result: text.toUpperCase(),
      originalLength: text.length,
    },
  };
};

export default { definition: uppercaseDefinition, fn: uppercaseFn };

Register and Execute

import { ToolRegistry, createRuntime } from '@conveniencepro/ctp-runtime';
import uppercaseTool from './my-tool';

// Create registry and register the tool
const registry = new ToolRegistry();
registry.register(uppercaseTool.definition, uppercaseTool.fn);

// Create runtime
const runtime = createRuntime(registry);

// Execute the tool
const result = await runtime.execute('uppercase-converter', {
  text: 'hello world',
});

console.log(result);
// {
//   success: true,
//   data: { result: 'HELLO WORLD', originalLength: 11 }
// }

Validate Your Tool

import { validateToolDefinition } from '@conveniencepro/ctp-core';

const validation = validateToolDefinition(uppercaseTool.definition);

if (!validation.valid) {
  console.error('Validation errors:', validation.errors);
} else {
  console.log('Tool is CTP-compliant!');
}

Generate Discovery Documents

import {
  generateOpenAPISpec,
  generateMCPManifest
} from '@conveniencepro/ctp-discovery';

// Generate OpenAPI 3.1 specification
const openapi = generateOpenAPISpec([uppercaseTool.definition]);

// Generate MCP-compatible manifest
const mcpManifest = generateMCPManifest([uppercaseTool.definition]);

Next Steps