MCP-Ables

# MCP-Ables YAML Specification Guide for AI Agents **Purpose:** Instructions for AI agents on how to generate YAML specifications that convert CLI tools and commands into MCP-compatible tools for Claude Code. --- ## Quick Start When a user wants to convert a command-line tool into an MCP tool, follow these steps: 1. **Identify the command** - Get the actual working command from the user 2. **Extract parameters** - Identify which parts should be configurable arguments 3. **Define argument schema** - Create detailed argument definitions with types, descriptions, and constraints 4. **Generate YAML** - Output a properly formatted YAML specification --- ## YAML Structure ### Single Tool Format Use this when defining one tool per file: ```yaml name: tool_name description: Clear, concise description of what this tool does run: kind: shell cmd: "command {{arg1}} {{arg2}}" args: arg1: type: string description: "Detailed description for AI to understand usage" required: true arg2: type: int description: "Detailed description with examples" required: false default: 10 ``` ### Multi-Tool Format Use this when defining multiple related tools in one file: ```yaml tools: - name: tool1 description: First tool description run: kind: shell cmd: "command1 {{arg}}" args: arg: type: string description: "Argument description" required: true - name: tool2 description: Second tool description run: kind: shell cmd: "command2 {{arg}}" args: arg: type: string description: "Argument description" required: true ``` --- ## Argument Types and Schema ### Supported Types - `string` - Text values (URLs, paths, names, etc.) - `int` - Integer numbers - `float` - Decimal numbers - `bool` - True/false values ### Argument Properties - **type** (required) - Data type from above - **description** (required) - Detailed explanation that helps AI understand when and how to use this argument - **required** (required) - `true` or `false` - **default** (optional) - Default value if not provided (only for optional arguments) ### Writing Good Descriptions Descriptions should be detailed and help the AI agent understand: - What the argument does - Valid formats or ranges - Examples of typical values - Any constraints or special requirements **Good:** ```yaml target: type: string description: "Target URL or IP address to scan (e.g., https://example.com, 192.168.1.1)" required: true ``` **Bad:** ```yaml target: type: string description: "Target" required: true ``` --- ## Template Syntax Use Jinja2-style templating in the `cmd` field: - `{{variable_name}}` - Simple substitution - Variables must match argument names exactly - No spaces inside braces: `{{arg}}` not `{{ arg }}` --- ## Conversion Process ### Step 1: Analyze the Command Given a command like: ```bash nuclei -c 10 -t https://example.com -t ~/nuclei-templates/ ``` Identify: - Base command: `nuclei` - Fixed flags: `-c`, `-t` - Variable values: `10`, `https://example.com`, `~/nuclei-templates/` ### Step 2: Determine Arguments Decide what should be configurable: - `concurrency`: The `-c 10` value - `target`: The URL/IP to scan - `template_path`: The path to templates ### Step 3: Define Argument Schema For each argument, determine: - **Type**: Is it a string, int, float, or bool? - **Required**: Must it always be provided? - **Default**: Should there be a sensible default? - **Description**: How do you explain this to an AI? ### Step 4: Build the Command Template Replace variable parts with `{{argument_name}}`: ```yaml cmd: "nuclei -c {{concurrency}} -t {{target}} -t {{template_path}}" ``` ### Step 5: Complete the YAML ```yaml name: nuclei_scan description: Security vulnerability scanner using Nuclei templates run: kind: shell cmd: "nuclei -c {{concurrency}} -t {{target}} -t {{template_path}}" args: target: type: string description: "Target URL or IP address to scan (e.g., https://example.com)" required: true template_path: type: string description: "Path to Nuclei templates directory" required: true concurrency: type: int description: "Number of concurrent requests (1-100)" required: false default: 10 ``` --- ## Best Practices ### 1. Naming Conventions - **Tool names**: Use snake_case (e.g., `nuclei_scan`, `nmap_discovery`) - **Argument names**: Use snake_case (e.g., `template_path`, `max_retries`) - Keep names descriptive but concise ### 2. Security Considerations - Always validate input types through the schema - Use descriptive constraints in descriptions - Avoid shell injection by keeping commands simple - Don't expose dangerous flags without clear warnings ### 3. User Experience - Provide sensible defaults for optional arguments - Include examples in descriptions - Group related tools in multi-tool files - Use clear, action-oriented tool names ### 4. Documentation - Description should answer "What does this tool do?" - Argument descriptions should answer "What is this for?" and "What format?" - Include typical use cases in tool descriptions --- ## Common Patterns ### Pattern 1: Simple Command with Options ```yaml name: port_scan description: Scan network ports using nmap run: kind: shell cmd: "nmap {{flags}} {{target}}" args: target: type: string description: "Target IP address or hostname" required: true flags: type: string description: "Nmap flags (e.g., '-sV -T4' for version detection)" required: false default: "-sV" ``` ### Pattern 2: File Input/Output ```yaml name: convert_format description: Convert file formats using custom tool run: kind: shell cmd: "converter --input {{input_file}} --output {{output_file}} --format {{format}}" args: input_file: type: string description: "Path to input file" required: true output_file: type: string description: "Path to output file" required: true format: type: string description: "Output format (json, xml, csv)" required: false default: "json" ``` ### Pattern 3: Boolean Flags ```yaml name: scan_with_options description: Scan with optional verbose mode run: kind: shell cmd: "scanner {{target}}{% if verbose %} --verbose{% endif %}" args: target: type: string description: "Target to scan" required: true verbose: type: bool description: "Enable verbose output" required: false default: false ``` --- ## Validation Checklist Before outputting a YAML specification, verify: - [ ] Tool name is descriptive and uses snake_case - [ ] Description clearly explains what the tool does - [ ] Command template uses correct `{{variable}}` syntax - [ ] All template variables have corresponding arguments - [ ] All arguments have type, description, and required fields - [ ] Optional arguments have sensible defaults - [ ] Descriptions are detailed enough for AI understanding - [ ] YAML syntax is valid (proper indentation, quotes where needed) --- ## Example Workflow **User says:** "I want to run `curl -X POST https://api.example.com/scan -d '{"target": "example.com"}'` from Claude" **AI Agent should:** 1. Analyze: Base command is `curl`, needs POST method, URL, and data payload 2. Identify variables: URL endpoint and target value 3. Design schema: ```yaml name: api_scan_trigger description: Trigger security scan via API endpoint run: kind: shell cmd: "curl -X POST {{api_url}} -d '{\"target\": \"{{target}}\"}'" args: api_url: type: string description: "API endpoint URL (e.g., https://api.example.com/scan)" required: true target: type: string description: "Target domain or IP to scan" required: true ``` 4. Validate against checklist 5. Output the YAML --- ## Notes for AI Agents - When user provides a working command, preserve its exact structure - Ask clarifying questions if argument purpose is unclear - Suggest sensible defaults based on common usage - Warn about security implications of certain commands - Recommend multi-tool format when user has multiple related commands - Always test that template variables match argument names exactly