# Example Usage

## Creating a Simple Converter Tool

**User Request:**
```
Create a tool that converts CSV to JSON
```

**MCP Server Response:**
```json
{
  "success": true,
  "tool": {
    "id": "csv-to-json",
    "name": "CSV to JSON",
    "category": "converters",
    "executionMode": "client"
  },
  "files": [
    {
      "path": "src/tools/csv-to-json-definition.ts",
      "content": "...",
      "description": "Tool definition following CTP specification"
    },
    {
      "path": "src/tools/csv-to-json.ts",
      "content": "...",
      "description": "Tool implementation"
    },
    {
      "path": "src/tools/__tests__/csv-to-json.test.ts",
      "content": "...",
      "description": "Test suite"
    }
  ],
  "nextSteps": [
    "1. Review the generated code",
    "2. Implement the actual logic in the implementation file",
    "3. Run tests: npm test",
    "4. Register the tool in your registry"
  ]
}
```

## Generated Tool Definition

```typescript
/**
 * CSV to JSON Tool Definition
 *
 * Convert CSV data to JSON format
 *
 * Category: converters
 * Execution Mode: client
 */

import { ToolDefinition, ToolFunction, ToolResult } from '@conveniencepro/ctp-core';

export const csvToJsonDefinition: ToolDefinition = {
  id: 'csv-to-json',
  name: 'CSV to JSON',
  description: 'Convert CSV data to JSON format',
  category: 'converters',
  tags: ['converters', 'csv', 'json', 'data'],
  method: 'POST',
  parameters: [
    {
      name: 'input',
      type: 'textarea',
      label: 'Input',
      description: 'Input data to process',
      required: true,
      placeholder: 'Enter your input here...',
    },
  ],
  outputDescription: 'Result of csv to json operation',
  example: {
    input: {
      input: 'name,age\nJohn,30\nJane,25',
    },
    output: {
      output: '[{"name":"John","age":"30"},{"name":"Jane","age":"25"}]',
      inputLength: 26,
      outputLength: 58,
    },
    name: 'Example CSV to JSON',
  },
  version: '1.0.0',
  icon: '🔄',
  executionMode: 'client',
};
```

## Validating an Existing Tool

**User Request:**
```
Validate this tool definition: { id: 'my-tool', name: 'My Tool' }
```

**MCP Server Response:**
```json
{
  "success": false,
  "valid": false,
  "errors": [
    {
      "field": "description",
      "code": "required",
      "message": "Field 'description' is required"
    },
    {
      "field": "category",
      "code": "required",
      "message": "Field 'category' is required"
    }
  ],
  "suggestions": [
    "Add the required field: description",
    "Add the required field: category"
  ]
}
```

## Searching for Duplicates

**User Request:**
```
Search for tools similar to "base64 encoder"
```

**MCP Server Response:**
```json
{
  "success": true,
  "found": true,
  "matches": [
    {
      "id": "base64-encoder",
      "name": "Base64 Encoder",
      "category": "encoders",
      "similarity": "high"
    }
  ],
  "message": "Found 1 similar tool(s). Consider reviewing these before creating a new one.",
  "canProceed": true
}
```

## Complete Workflow Example

### 1. Check for Duplicates
```
Use ctp_search_duplicates with:
- description: "URL query string parser"
- category: "parsers"
```

### 2. Create the Tool
```
Use ctp_create_tool with:
- description: "Parse URL query strings into key-value objects"
- category: "parsers"
- executionMode: "client"
```

### 3. Implement the Logic

Edit the generated `src/tools/url-query-parser.ts`:

```typescript
export const urlQueryParserFn: ToolFunction<UrlQueryParserResult> = (
  params
): ToolResult<UrlQueryParserResult> => {
  const startTime = performance.now();

  try {
    const input = params.input;
    if (!input) {
      return failure('Input is required');
    }

    // Implementation
    const queryString = input.split('?')[1] || input;
    const params = new URLSearchParams(queryString);
    const result: Record<string, string> = {};

    params.forEach((value, key) => {
      result[key] = value;
    });

    const duration = performance.now() - startTime;

    return success({
      output: result,
      inputLength: input.length,
      paramCount: Object.keys(result).length,
    }, {
      durationMs: duration,
    });
  } catch (error) {
    return failure(
      error instanceof Error ? error.message : 'Unknown error occurred'
    );
  }
};
```

### 4. Run Tests

```bash
npm test
```

### 5. Build and Deploy

```bash
npm run build
# Tool is now ready to use
```

## Advanced: Custom Templates

You can customize the templates in `src/templates/`:

1. `tool-definition.hbs` - Customize tool definition structure
2. `client-implementation.hbs` - Customize implementation boilerplate
3. `test-suite.hbs` - Customize test generation

Example custom template helper:

```typescript
// In template-engine.ts
Handlebars.registerHelper('customHelper', function(context) {
  // Your custom logic
  return transformedValue;
});
```