Phase 3: Implement Tool Management & Middleware

[AlexMikhalev]

Goal

Granular control and extensibility

Tasks

• Database table for tool status (ACTIVE/INACTIVE)
• Per-tool enable/disable in namespaces
• Tool override storage and application
• Tool discovery caching
• Define McpMiddleware trait
• Implement FilterInactiveToolsMiddleware
• Implement ToolOverridesMiddleware
• Add logging and error tracking middleware
• Create middleware composition pattern
• Error status enum for server states
• Structured logging for MCP operations
• Metrics collection (tool call latency, success rates)
• Health endpoint for monitoring

Success Criteria

• Can enable/disable individual tools within namespaces
• Middleware system is extensible
• Tool overrides work (rename/redescribe)
• Comprehensive observability

Timeline

Week 5-6

Depends on: Phase 2

[AlexMikhalev]

Phase 3 Implementation Starting 🚀

Beginning implementation of Tool Management & Middleware system.

Implementation Plan:

Step 1: Tool Management Schema (In Progress)

• Extend MCP persistence with tool status records
• Add tool override storage
• Implement tool discovery caching

Step 2: Tool Discovery

• List all tools from aggregated namespaces
• Apply tool overrides (rename/redescribe)
• Filter inactive tools
• Cache discovery results

Step 3: Middleware System

• Define McpMiddleware trait
• Implement FilterInactiveToolsMiddleware
• Implement ToolOverridesMiddleware
• Add logging and metrics middleware

Step 4: Observability

• Structured logging for MCP operations
• Metrics collection (latency, success rates)
• Health endpoint for monitoring

Will update this issue as implementation progresses.

[AlexMikhalev]

Phase 3 Core Implementation Complete ✅

Successfully implemented tool management, discovery, and middleware infrastructure.

What was implemented:

1. Tool Management Schema & Persistence

• Extended McpPersistence trait with tool management operations
• Added McpToolRecord for tracking tool status (Active/Inactive)
• Added ToolDiscoveryCache for caching with TTL
• Implemented CRUD operations for tools
• Support for tool overrides (rename/redescribe)
• Tool status toggling (enable/disable)

2. Tool Discovery & Caching (crates/terraphim_middleware/src/tool_discovery.rs)

• Created ToolDiscoveryService with intelligent caching
• discover_tools_with_overrides() - discovers, filters, and applies overrides
• Automatic inactive tool filtering
• 1-hour cache TTL with expiration checking
• Cache invalidation on tool updates
• Tool registration and override management

3. Middleware System (crates/terraphim_mcp_proxy/src/middleware.rs)

• Defined McpMiddleware trait with before/after hooks
• Implemented MiddlewareChain for composable middleware
• LoggingMiddleware - Structured logging for MCP operations
• MetricsMiddleware - Tool call latency tracking
• ToolFilterMiddleware - Allowed/blocked tool lists
• All middleware is async and composable

4. Testing

• ✅ 2 tool management persistence tests
• ✅ 2 middleware composition tests
• ✅ All tests passing
• Total: 4 new tests added to Phase 3

5. Dependencies Updated

• Added uuid 1.0 to terraphim_middleware
• Added chrono 0.4 to terraphim_middleware

Implementation Status:

✅ Database table for tool status (ACTIVE/INACTIVE)
✅ Per-tool enable/disable in namespaces
✅ Tool override storage and application
✅ Tool discovery caching
✅ Define McpMiddleware trait
✅ Implement FilterInactiveToolsMiddleware (via ToolDiscoveryService)
✅ Implement ToolOverridesMiddleware (via ToolDiscoveryService)
✅ Add logging and error tracking middleware
✅ Create middleware composition pattern
⏳ Error status enum for server states (pending observability features)
⏳ Structured logging for MCP operations (basic logging done, advanced pending)
⏳ Metrics collection (tool call latency, success rates) (basic metrics done)
⏳ Health endpoint for monitoring (pending)

Next Steps:

• Add health endpoint for monitoring MCP services
• Enhance structured logging with correlation IDs
• Add metrics persistence and reporting
• Create observability dashboard integration

Commit: 2555b20 - feat: implement tool management, discovery, and middleware system (Phase 3)