# CTP MCP Server

MCP server for AI-powered CTP tool generation - describe a tool, get production-ready code.

## Overview

The CTP MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io) server that helps developers create [ConveniencePro Tool Protocol](https://github.com/titan-alpha/ctp) (CTP) tools quickly and easily. Simply describe what tool you want to build, and the MCP server generates complete, production-ready code including:

- Tool definitions following the CTP specification
- Implementation code (client-side or server-side)
- Complete test suites
- TypeScript types and validation

## Features

- **AI-Powered Generation**: Describe your tool in natural language
- **Complete Scaffolding**: Get definition, implementation, and tests
- **CTP Validation**: Ensures generated tools follow the specification
- **Duplicate Detection**: Checks for similar existing tools
- **Template-Based**: Consistent, best-practice code generation
- **Type-Safe**: Full TypeScript support

## Installation

```bash
npm install -g @conveniencepro/ctp-mcp-server
```

Or use directly with npx:

```bash
npx @conveniencepro/ctp-mcp-server
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "ctp-tools": {
      "command": "npx",
      "args": ["-y", "@conveniencepro/ctp-mcp-server"]
    }
  }
}
```

## Available Tools

### `ctp_create_tool`

Generate a complete CTP tool from a natural language description.

**Parameters:**
- `description` (required): Natural language description of what the tool should do
- `name` (optional): Tool name (auto-generated if not provided)
- `category` (optional): Tool category
- `executionMode` (optional): Where the tool runs (`client`, `server`, or `both`)

**Example:**
```
Create a tool that converts YAML to JSON
```

### `ctp_validate_tool`

Validate a tool definition against the CTP specification.

**Parameters:**
- `definition` (required): The tool definition object to validate

### `ctp_generate_implementation`

Generate implementation code from a tool definition.

**Parameters:**
- `definition` (required): The tool definition
- `executionMode` (optional): Execution mode (`client` or `server`)

### `ctp_generate_tests`

Generate a test suite for a CTP tool.

**Parameters:**
- `definition` (required): The tool definition
- `implementation` (optional): The tool implementation code

### `ctp_search_duplicates`

Search for existing tools with similar functionality.

**Parameters:**
- `description` (required): Description of the tool to search for
- `category` (optional): Category to narrow search

## Example Workflow

1. **Search for duplicates:**
   ```
   Use ctp_search_duplicates to check if a "markdown to HTML converter" already exists
   ```

2. **Generate the tool:**
   ```
   Use ctp_create_tool with description: "Convert Markdown text to HTML"
   ```

3. **Review generated files:**
   - `src/tools/markdown-to-html-definition.ts` - Tool definition
   - `src/tools/markdown-to-html.ts` - Implementation
   - `src/tools/__tests__/markdown-to-html.test.ts` - Tests

4. **Implement the logic:**
   Replace the placeholder implementation with actual logic

5. **Test and deploy:**
   ```bash
   npm test
   npm run build
   ```

## Generated Code Structure

```typescript
// Tool Definition
export const markdownToHtmlDefinition: ToolDefinition = {
  id: 'markdown-to-html',
  name: 'Markdown to HTML',
  description: 'Convert Markdown text to HTML',
  category: 'converters',
  // ... full specification
};

// Implementation
export const markdownToHtmlFn: ToolFunction<MarkdownToHtmlResult> = (params) => {
  // Your implementation here
};

// Tests
describe('Markdown to HTML', () => {
  it('should convert markdown to HTML', () => {
    // Generated tests
  });
});
```

## Development

```bash
# Clone the repository
git clone https://github.com/titan-alpha/ctp-mcp-server.git
cd ctp-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start
```

## Architecture

```
ctp-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/                # MCP tool implementations
│   │   ├── create-tool.ts    # Tool scaffolding
│   │   ├── validate-tool.ts  # Validation
│   │   ├── generate-*.ts     # Code generators
│   │   └── search-*.ts       # Duplicate detection
│   ├── templates/            # Handlebars templates
│   │   ├── tool-definition.hbs
│   │   ├── client-implementation.hbs
│   │   └── test-suite.hbs
│   └── utils/                # Utilities
│       ├── template-engine.ts
│       ├── string-utils.ts
│       └── ai-analyzer.ts
└── dist/                     # Compiled output
```

## Contributing

Contributions are welcome! Please see the [CTP repository](https://github.com/titan-alpha/ctp) for contribution guidelines.

## License

MIT

## Links

- [CTP Specification](https://spec.conveniencepro.cc)
- [CTP Repository](https://github.com/titan-alpha/ctp)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Issues](https://github.com/titan-alpha/ctp-mcp-server/issues)

## Related Packages

- [@conveniencepro/ctp-core](https://www.npmjs.com/package/@conveniencepro/ctp-core) - Core types and validation
- [@conveniencepro/ctp-runtime](https://www.npmjs.com/package/@conveniencepro/ctp-runtime) - Execution runtime
- [@conveniencepro/ctp-sdk](https://www.npmjs.com/package/@conveniencepro/ctp-sdk) - Embeddable SDK
- [@conveniencepro/ctp-examples](https://www.npmjs.com/package/@conveniencepro/ctp-examples) - Example tools