[Refactoring] Auto-generate MCP Tool Definitions - Reduce server.ts Boilerplate

[gloomcheng]

Problem

src/core/mcp/server.ts is 2013 lines, with:

• 822 lines of tool definitions (lines 334-1156)
• 264 lines of tool call handlers (lines 1156-1420)
• Massive repetitive boilerplate for 59 tools

Current approach: Manually write tool schema for every handler method.

Impact

• Maintainability: Hard to add new tools
• Error-prone: Type definitions can drift from handlers
• Context usage: 7.5% of 200K context consumed by tool definitions
• Developer experience: Discourages adding new tools

Proposed Solution

Auto-generate Tool Definitions from Handler Signatures

// handlers/workflow/spec-handler.ts
export class SpecHandler {
  @MCPTool({
    description: "Initialize workflow with project specification",
    required: ["description"]
  })
  async handleSpec(args: { description: string }): Promise<MCPToolResult> {
    // implementation
  }
}

Auto-generated output:

// tools/tool-definitions.ts (generated)
{
  name: "spec",
  description: "Initialize workflow with project specification",
  inputSchema: {
    type: "object",
    properties: {
      description: { type: "string", description: "..." }
    },
    required: ["description"]
  }
}

Architecture

src/core/mcp/
  server.ts (200 lines) ← 90% reduction
  tools/
    tool-registry.ts (decorator-based registration)
    tool-generator.ts (auto-generate schemas from TypeScript)
    tool-definitions.ts (generated file)

Benefits

✅ Type Safety: Tool schemas derived from TypeScript signatures
✅ DRY: Single source of truth (handler signature)
✅ Reduced Boilerplate: 1800+ lines eliminated
✅ Auto-completion: Better IDE support
✅ Validation: Compile-time checks for tool definitions

Implementation Plan

1. Create decorator system (@MCPTool, @MCPParam)
2. Build schema generator (TypeScript AST parsing)
3. Migrate existing tools incrementally
4. Generate tool-definitions.ts in build step
5. Update server.ts to use generated definitions

Acceptance Criteria

• server.ts reduced to <300 lines
• All 59 tools migrated to decorator pattern
• Tool definitions auto-generated in build
• Zero manual tool schema writing
• Build passing, all tests green
• Documentation updated

Priority

🔴 Critical - Blocks scalability of adding new tools

Effort Estimate

2 days

[gloomcheng]

Implemented in commit 248b40c

Summary

• Created @mcptool decorator system for declarative tool definitions
• Created MCPToolRegistry for auto-discovery and routing
• Migrated all 47 tools to use decorators
• Reduced server.ts from 2013 → 941 lines (53% reduction)
• Removed StableWorkflowHandler and 8 unused files

New tools can now be added with just a decorator annotation instead of manual schema definitions.