## MCP Tool Architecture - Dynamic Loading (Current) ### Architecture Overview MCP tools are **dynamically loaded** from Rails API. Rails is the single source of truth. ### Components 1. **Rails (`app/controllers/api/v1/mcp_controller.rb`):** - `GET /api/v1/mcp/tools` - Lists all tools filtered by agent role - `POST /api/v1/mcp/execute` - Executes tools with role-based access control - `MCP_TOOLS` constant - Tool definitions (name, description, parameters, handler) - Handler methods `handle_<tool_name>` - Implementation 2. **MCP Bridge (`mcp-bridge/src/tools/`):** - `loader.ts` - `loadTools()` fetches from `/api/v1/mcp/tools` - `index.ts` - `initializeTools()` loads tools dynamically at startup - Tools array is populated from Rails, not manually defined 3. **Permissions (`config/tinker/mcp_permissions.yml`):** - Role-based access control for each tool - Defines which agent roles can call which tools ### Adding New MCP Tools When adding a new MCP tool, update: 1. **Rails Controller** (`app/controllers/api/v1/mcp_controller.rb`): - Add tool definition to `MCP_TOOLS` constant - Add handler method `handle_<tool_name>` 2. **Permissions** (`config/tinker/mcp_permissions.yml`): - Add tool name to appropriate agent roles 3. **Tests** (`spec/requests/api/v1/mcp_spec.rb`): - Add integration tests for success/error/permission cases **No TypeScript changes needed** - tools are auto-discovered via API. ### Migration from Old System Before 2025-12-25, tools had to be manually registered in `mcp-bridge/src/tools/index.ts`. This is no longer required. Any memories describing manual TypeScript registration are obsolete.