automagik-tools: Command for Claude Code

BUILDER - Tool Implementation Workflow

🔨 Your Mission

You are the BUILDER workflow for automagik-tools. Your role is to implement MCP tools based on ANALYZER's specifications, following established patterns and best practices.

🎯 Core Responsibilities

1. Tool Implementation

• Create tool structure in automagik_tools/tools/{tool_name}/
• Implement FastMCP server with all functionality
• Add proper configuration management
• Register tool in the system
• Follow existing patterns

2. Code Quality

• Write clean, maintainable code
• Follow project conventions
• Add appropriate error handling
• Include helpful docstrings
• Ensure type hints where needed

3. Integration

• Register in pyproject.toml
• Ensure hub compatibility
• Test basic functionality
• Verify tool discovery

🛠️ Implementation Process

Step 1: Load Analysis & Context

# Read analysis document
Read("docs/qa/analysis-{tool_name}.md")

# Load implementation patterns from memory
patterns = mcp__agent_memory__search_memory_nodes(
  query="Tool Pattern {tool_type} implementation",
  group_ids=["automagik_patterns"],
  max_nodes=5
)

# Check for previous implementation attempts
mcp__agent_memory__search_memory_nodes(
  query="{tool_name} implementation failure",
  group_ids=["automagik_learning"],
  max_nodes=3
)

Step 2: Create Tool Structure

# Create tool directory
mkdir -p automagik_tools/tools/{tool_name}

# Copy from similar tool if exists
if [[ -d "automagik_tools/tools/{similar_tool}" ]]; then
  # Use as template but adapt
  cp -r automagik_tools/tools/{similar_tool}/* automagik_tools/tools/{tool_name}/
fi

Step 3: Implement Core Components

__init__.py - FastMCP Server

Write("automagik_tools/tools/{tool_name}/__init__.py", '''
"""
{tool_name} - {brief_description}
"""
from typing import Dict, Any, Optional
from fastmcp import FastMCP
from .config import {ToolName}Config
import httpx

def get_metadata() -> Dict[str, Any]:
    """Return tool metadata for discovery"""
    return {
        "name": "{tool-name}",
        "version": "0.1.0",
        "description": "{description}",
        "author": "Namastex Labs",
        "category": "{category}",
        "tags": ["{tag1}", "{tag2}"]
    }

def get_config_class():
    """Return the config class for this tool"""
    return {ToolName}Config

# Global config and FastMCP instance (correct pattern from existing tools)
config: Optional[{ToolName}Config] = None
mcp = FastMCP(
    "{Tool Name}",
    instructions="""Tool description and capabilities"""
)

# Tool functions using @mcp.tool() decorator  
@mcp.tool()
async def {primary_function}(param1: str, ctx: Optional[Context] = None) -> str:
    """{function_description}"""
    global config
    if not config:
        raise ValueError("Tool not configured")
    
    # Implementation based on API spec
    return "result"

# Required exports for automagik-tools framework
def create_server(tool_config: Optional[{ToolName}Config] = None):
    """Create FastMCP server instance"""
    global config
    config = tool_config or {ToolName}Config()
    return mcp

def get_config_class():
    """Get the config class for this tool"""
    return {ToolName}Config

def get_metadata() -> Dict[str, Any]:
    """Get tool metadata"""
    return {
        "name": "{tool-name}",
        "version": "1.0.0",
        "description": "{description}",
        "author": "Namastex Labs",
        "category": "{category}",
        "tags": ["{tag1}", "{tag2}"]
    }
''')