@conveniencepro/ctp-examples

Example tool implementations for the ConveniencePro Tool Protocol (CTP).

Overview

This package provides reference implementations demonstrating CTP best practices:

• JSON Formatter - Synchronous tool with multiple parameters
• Base64 Encoder - Bidirectional tool with conditional parameters
• Hash Generator - Async tool using Web Crypto API

Installation

npm install @conveniencepro/ctp-examples
# or
yarn add @conveniencepro/ctp-examples

Usage

Create Registry with Example Tools

import { createExampleRegistry } from '@conveniencepro/ctp-examples';

const registry = createExampleRegistry();

// Execute a tool
const result = await registry.execute('json-formatter', {
  json: '{"name":"test"}',
  indent: '2',
});

console.log(result.data.formatted);

Add to Existing Registry

import { createRegistry } from '@conveniencepro/ctp-runtime';
import { registerExampleTools } from '@conveniencepro/ctp-examples';

const registry = createRegistry();
registerExampleTools(registry);

// Your tools + example tools now available

Use Individual Tools

import {
  jsonFormatterDefinition,
  jsonFormatterFn,
  base64EncoderDefinition,
  base64EncoderFn,
  hashGeneratorDefinition,
  hashGeneratorFn,
} from '@conveniencepro/ctp-examples';

// Register only specific tools
registry.register(jsonFormatterDefinition, jsonFormatterFn);

Get Tool Definitions

import { getToolDefinitions, getToolById } from '@conveniencepro/ctp-examples';

// Get all definitions
const definitions = getToolDefinitions();

// Get specific tool
const jsonFormatter = getToolById('json-formatter');

Example Tools

JSON Formatter

ID: json-formatter Category: formatters

Format, validate, and beautify JSON data.

Parameters: | Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| | json | textarea | Yes | - | JSON string to format | | indent | select | No | 2 | Indentation (0, 2, 4, tab) | | sortKeys | boolean | No | false | Sort keys alphabetically |

Example:

const result = await registry.execute('json-formatter', {
  json: '{"b":2,"a":1}',
  indent: '2',
  sortKeys: true,
});

// Output:
// {
//   "a": 1,
//   "b": 2
// }

Base64 Encoder/Decoder

ID: base64-encoder Category: encoders

Encode text to Base64 or decode Base64 to text.

Parameters: | Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| | input | textarea | Yes | - | Text or Base64 string | | mode | select | No | encode | Operation mode | | urlSafe | boolean | No | false | Use URL-safe variant |

Example:

// Encode
const encoded = await registry.execute('base64-encoder', {
  input: 'Hello, World!',
  mode: 'encode',
});
// Output: SGVsbG8sIFdvcmxkIQ==

// Decode
const decoded = await registry.execute('base64-encoder', {
  input: 'SGVsbG8sIFdvcmxkIQ==',
  mode: 'decode',
});
// Output: Hello, World!

Hash Generator

ID: hash-generator Category: generators

Generate cryptographic hashes using SHA algorithms.

Parameters: | Name | Type | Required | Default | Description | |------|------|----------|---------|-------------| | input | textarea | Yes | - | Text to hash | | algorithm | select | No | SHA-256 | Hash algorithm | | format | select | No | hex | Output format |

Example:

const result = await registry.execute('hash-generator', {
  input: 'hello world',
  algorithm: 'SHA-256',
  format: 'hex',
});
// Output: b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

Creating Your Own Tools

Use these examples as templates. Key patterns:

1. Define Types

interface MyToolResult {
  output: string;
  // ...
}

2. Create Definition

const myToolDefinition: ToolDefinition = {
  id: 'my-tool',
  name: 'My Tool',
  description: '...',
  category: 'utilities',
  tags: ['example'],
  method: 'POST',
  parameters: [...],
  outputDescription: '...',
  example: { input: {...}, output: {...} },
};

3. Implement Function

const myToolFn: ToolFunction<MyToolResult> = (params) => {
  // Validate
  if (!params.input) {
    return { success: false, error: '...', errorCode: 'MISSING_REQUIRED' };
  }

  // Process
  const output = processInput(params.input);

  // Return
  return {
    success: true,
    data: { output },
    metadata: { executionTime: 0 },
  };
};

4. Export Both

export default { definition: myToolDefinition, fn: myToolFn };

Related Packages

• @conveniencepro/ctp-core - Core types
• @conveniencepro/ctp-runtime - Execution runtime
• @conveniencepro/ctp-spec - Protocol specification

License

MIT © ConveniencePro