mirror of
https://github.com/katanemo/plano.git
synced 2026-06-17 15:25:17 +02:00
more changes
This commit is contained in:
Adil Hafeez
parent
dcfc85ca74
commit
4140c1cde4
15 changed files with 883 additions and 109 deletions
174
docs/MCP_AGENT_INTEGRATION.md
Normal file
174
docs/MCP_AGENT_INTEGRATION.md
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
# MCP Agent Description Integration
|
||||
|
||||
## Overview
|
||||
|
||||
This implementation adds support for fetching agent tool descriptions from MCP (Model Context Protocol) endpoints during agent selection. This allows the system to use the actual tool descriptions from MCP servers for intelligent agent routing instead of relying solely on static descriptions in the configuration file.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Components Modified
|
||||
|
||||
1. **MCP Client Module** (`brightstaff/src/utils/mcp_client.rs`)
|
||||
- New module that handles communication with MCP servers via SSE
|
||||
- Fetches tool lists and descriptions from MCP endpoints
|
||||
- Parses MCP URLs in multiple formats
|
||||
|
||||
2. **Configuration Structs** (`common/src/configuration.rs`)
|
||||
- Added optional `tool` field to `Agent` struct
|
||||
- Added optional `tool` field to `AgentFilter` struct
|
||||
- Supports specifying which MCP tool to invoke
|
||||
|
||||
3. **Agent Selector** (`brightstaff/src/handlers/agent_selector.rs`)
|
||||
- Enhanced to fetch tool descriptions from MCP endpoints
|
||||
- Uses MCP descriptions for agent routing when available
|
||||
- Falls back to configuration descriptions if MCP fetch fails
|
||||
|
||||
4. **Agent Chat Completions** (`brightstaff/src/handlers/agent_chat_completions.rs`)
|
||||
- Updated to pass agent_map to agent selector
|
||||
- Ensures agent information is available during selection
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Configuration
|
||||
|
||||
Agents can now be configured with MCP URLs and optional tool names:
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
- id: rag_agent
|
||||
url: mcp://host.docker.internal:10501
|
||||
tool: invoke # Optional: defaults to agent id
|
||||
|
||||
- id: travel_agent
|
||||
url: mcp://host.docker.internal:10502
|
||||
|
||||
agent_filters:
|
||||
- id: query_rewriter
|
||||
url: mcp://host.docker.internal:10500
|
||||
tool: rewrite_query_with_archgw # Optional
|
||||
```
|
||||
|
||||
### 2. MCP URL Parsing
|
||||
|
||||
The MCP client supports three URL formats:
|
||||
|
||||
```
|
||||
mcp://host:port # Basic format
|
||||
mcp://host:port/tool_name # Tool in path
|
||||
mcp://host:port?tool=tool_name # Tool as query param
|
||||
```
|
||||
|
||||
### 3. Description Fetching
|
||||
|
||||
During agent selection:
|
||||
|
||||
1. Agent selector checks if agent URL starts with `mcp://`
|
||||
2. If yes, calls MCP client to fetch tool description from endpoint
|
||||
3. MCP client makes GET request to `http://host:port/sse/tools/list`
|
||||
4. Parses SSE response to extract tool descriptions
|
||||
5. Returns description for specified tool (from config or URL)
|
||||
6. Falls back to config description if MCP fetch fails
|
||||
|
||||
### 4. Agent Routing
|
||||
|
||||
The fetched MCP tool descriptions are used in routing preferences:
|
||||
|
||||
```rust
|
||||
ModelUsagePreference {
|
||||
model: agent_id,
|
||||
routing_preferences: vec![RoutingPreference {
|
||||
name: agent_id,
|
||||
description: mcp_description, // From MCP endpoint
|
||||
}],
|
||||
}
|
||||
```
|
||||
|
||||
The LLM router uses these descriptions to select the appropriate agent based on the user's request.
|
||||
|
||||
## Key Features
|
||||
|
||||
1. **Automatic Description Fetching**: Tool descriptions are automatically fetched from MCP servers when agents have `mcp://` URLs
|
||||
|
||||
2. **Graceful Fallback**: If MCP endpoint is unavailable or doesn't return a description, falls back to the description in arch_config.yaml
|
||||
|
||||
3. **Multiple URL Formats**: Supports flexible MCP URL specification for tool names
|
||||
|
||||
4. **Async Operation**: All MCP fetching is done asynchronously to avoid blocking
|
||||
|
||||
5. **Comprehensive Logging**: Debug and warning logs track MCP interactions
|
||||
|
||||
## Example Usage
|
||||
|
||||
### Configuration (arch_config.yaml)
|
||||
|
||||
```yaml
|
||||
version: v0.3.0
|
||||
|
||||
agents:
|
||||
- id: rag_agent
|
||||
url: mcp://host.docker.internal:10501
|
||||
# Description will be fetched from MCP endpoint
|
||||
|
||||
agent_filters:
|
||||
- id: query_rewriter
|
||||
url: mcp://host.docker.internal:10500
|
||||
tool: rewrite_query_with_archgw
|
||||
|
||||
listeners:
|
||||
- type: agent
|
||||
port: 8001
|
||||
router: arch_agent_router
|
||||
agents:
|
||||
- id: rag_agent
|
||||
description: fallback description if MCP unavailable
|
||||
filter_chain:
|
||||
- query_rewriter
|
||||
```
|
||||
|
||||
### Flow
|
||||
|
||||
1. User sends request to listener
|
||||
2. Agent selector creates agent map from configuration
|
||||
3. For each agent in listener:
|
||||
- Checks if agent URL is MCP (`mcp://`)
|
||||
- Fetches tool description from MCP endpoint
|
||||
- Uses fetched description for routing
|
||||
4. LLM router selects best agent based on descriptions
|
||||
5. Filter chain processes request using selected agent
|
||||
|
||||
## Testing
|
||||
|
||||
Unit tests cover:
|
||||
- MCP URL parsing (basic, path, query param formats)
|
||||
- Agent selection with MCP descriptions
|
||||
- Fallback to config descriptions
|
||||
- Agent map creation
|
||||
|
||||
Integration tests verify:
|
||||
- End-to-end agent selection flow
|
||||
- Pipeline processing with MCP agents
|
||||
|
||||
## Error Handling
|
||||
|
||||
The implementation handles:
|
||||
- Invalid MCP URLs (returns error)
|
||||
- Unreachable MCP endpoints (logs warning, uses config description)
|
||||
- Missing tool in MCP response (returns error)
|
||||
- Empty descriptions (logs warning, uses config description)
|
||||
- Network errors (falls back to config description)
|
||||
|
||||
## Backward Compatibility
|
||||
|
||||
The changes are fully backward compatible:
|
||||
- `tool` field is optional on Agent and AgentFilter
|
||||
- Non-MCP agents work as before
|
||||
- Config descriptions still work when MCP is not used
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Possible improvements:
|
||||
1. Cache MCP tool descriptions to reduce network calls
|
||||
2. Support for MCP stdio transport in addition to SSE
|
||||
3. Periodic refresh of MCP descriptions
|
||||
4. Support for fetching tool schemas along with descriptions
|
||||
5. Metrics for MCP endpoint availability and response times
|
||||
132
docs/MCP_QUICK_START.md
Normal file
132
docs/MCP_QUICK_START.md
Normal file
|
|
@ -0,0 +1,132 @@
|
|||
# MCP Agent Description - Quick Start
|
||||
|
||||
## What This Feature Does
|
||||
|
||||
When processing agent filter chains in Brightstaff, the system can now automatically fetch tool descriptions from MCP (Model Context Protocol) endpoints. These descriptions are used by the LLM router to intelligently select the appropriate agent for handling user requests.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Basic Setup
|
||||
|
||||
Add agents with MCP URLs to your `arch_config.yaml`:
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
- id: rag_agent
|
||||
url: mcp://host.docker.internal:10501
|
||||
|
||||
- id: query_rewriter
|
||||
url: mcp://host.docker.internal:10500
|
||||
tool: rewrite_query_with_archgw # Optional: specify tool name
|
||||
|
||||
listeners:
|
||||
- type: agent
|
||||
port: 8001
|
||||
router: arch_agent_router
|
||||
agents:
|
||||
- id: rag_agent
|
||||
description: "RAG agent for document retrieval" # Fallback if MCP fails
|
||||
filter_chain:
|
||||
- query_rewriter
|
||||
```
|
||||
|
||||
### MCP URL Formats
|
||||
|
||||
Three formats are supported:
|
||||
|
||||
```yaml
|
||||
# 1. Basic - uses agent id as tool name
|
||||
url: mcp://localhost:10500
|
||||
|
||||
# 2. Tool in path
|
||||
url: mcp://localhost:10500/my_tool_name
|
||||
|
||||
# 3. Tool as query parameter
|
||||
url: mcp://localhost:10500?tool=my_tool_name
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Request arrives** at agent listener
|
||||
2. **Agent selector** needs to choose which agent to handle request
|
||||
3. **For MCP agents**, description is fetched from endpoint:
|
||||
```
|
||||
GET http://host:port/sse/tools/list
|
||||
Accept: text/event-stream
|
||||
```
|
||||
4. **Tool description extracted** from SSE response
|
||||
5. **LLM router uses descriptions** to select best agent
|
||||
6. **Selected agent processes** the request through its filter chain
|
||||
|
||||
## Example MCP Response
|
||||
|
||||
Your MCP server should respond to `/sse/tools/list` with:
|
||||
|
||||
```
|
||||
data: {"tools": [{"name": "rewrite_query_with_archgw", "description": "Rewrites user queries using LLM for better retrieval", "inputSchema": {...}}]}
|
||||
```
|
||||
|
||||
## Fallback Behavior
|
||||
|
||||
If MCP endpoint fails or returns empty description:
|
||||
- System logs a warning
|
||||
- Falls back to `description` field from arch_config.yaml
|
||||
- Processing continues normally
|
||||
|
||||
## Logging
|
||||
|
||||
Enable debug logging to see MCP interactions:
|
||||
|
||||
```bash
|
||||
RUST_LOG=debug cargo run
|
||||
```
|
||||
|
||||
Look for logs like:
|
||||
```
|
||||
Agent rag_agent is an MCP agent, fetching tool description from: mcp://host.docker.internal:10501
|
||||
Fetched MCP description for agent rag_agent: Rewrites user queries...
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Test your MCP endpoint manually:
|
||||
|
||||
```bash
|
||||
# Check if endpoint is accessible
|
||||
curl -H "Accept: text/event-stream" http://localhost:10500/sse/tools/list
|
||||
|
||||
# Expected response format
|
||||
data: {"tools": [{"name": "my_tool", "description": "My tool description"}]}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Failed to fetch MCP description"
|
||||
- Check if MCP server is running
|
||||
- Verify URL format is correct
|
||||
- Ensure `/sse/tools/list` endpoint exists
|
||||
- Check network connectivity
|
||||
|
||||
### "MCP tool description is empty"
|
||||
- Verify MCP server returns tool in response
|
||||
- Check tool name matches configuration
|
||||
- Ensure `description` field is populated in MCP response
|
||||
|
||||
### "Tool not found"
|
||||
- Verify tool name in config matches MCP server
|
||||
- Check if tool is listed in `/sse/tools/list` response
|
||||
- Try without explicit tool name (uses agent id)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always provide fallback descriptions** in arch_config.yaml
|
||||
2. **Use descriptive tool names** that match your config
|
||||
3. **Keep MCP servers running** before starting Brightstaff
|
||||
4. **Monitor logs** for MCP fetch failures
|
||||
5. **Test MCP endpoints** independently before integration
|
||||
|
||||
## See Also
|
||||
|
||||
- [MCP Agent Integration Documentation](./MCP_AGENT_INTEGRATION.md)
|
||||
- [RAG Agent Demo](../demos/use_cases/rag_agent/README.md)
|
||||
- [Agent Configuration Reference](../demos/use_cases/rag_agent/arch_config.yaml)
|
||||
Loading…
Add table
Add a link
Reference in a new issue