ai-counsel: Skill for Claude Code

MCP Server Enhancement Skill

This skill provides a systematic approach to extending the AI Counsel MCP server (server.py) with new tools while maintaining protocol compliance, stdio safety, and proper error handling.

Architecture Overview

The AI Counsel MCP server communicates via stdio (stdin/stdout) using the Model Context Protocol. Key architectural constraints:

• Stdio Safety: stdout is RESERVED for MCP protocol JSON. All logging MUST go to file (mcp_server.log) or stderr
• Protocol Compliance: Tools must follow MCP specification for request/response format
• Type Safety: Use Pydantic models for all request/response validation
• Error Isolation: Tool failures should return structured error responses, not crash the server
• Async First: All tool handlers are async functions using asyncio

Current Tool Architecture

Tool 1: deliberate (Primary Tool)

• Purpose: Multi-round AI model deliberation with consensus building
• Handler: call_tool() function (lines 242-327 in server.py)
• Request Model: DeliberateRequest (models/schema.py)
• Response Model: DeliberationResult (models/schema.py)
• Engine: Uses DeliberationEngine.execute() for orchestration

Tool 2: query_decisions (Decision Graph Tool)

• Purpose: Search and analyze past deliberations in decision graph memory
• Handler: handle_query_decisions() function (lines 329-415 in server.py)
• Request Schema: Inline in list_tools() (lines 196-237)
• Response: Custom JSON structure (not a Pydantic model)
• Conditional: Only exposed if config.decision_graph.enabled == True

Step-by-Step: Adding a New MCP Tool

Step 1: Define Pydantic Request/Response Models

Location: models/schema.py

Create type-safe models for your tool's inputs and outputs:

# In models/schema.py

class NewToolRequest(BaseModel):
    """Model for new_tool request."""

    parameter1: str = Field(
        ...,
        min_length=1,
        description="Description of parameter1"
    )
    parameter2: int = Field(
        default=5,
        ge=1,
        le=10,
        description="Integer parameter with range validation"
    )
    optional_param: Optional[str] = Field(
        default=None,
        description="Optional parameter"
    )

class NewToolResponse(BaseModel):
    """Model for new_tool response."""

    status: Literal["success", "partial", "failed"] = Field(
        ...,
        description="Operation status"
    )
    result_data: str = Field(..., description="Main result data")
    metadata: dict = Field(default_factory=dict, description="Additional metadata")