Skip to content

Commit 6db1edc

Browse files
Das-rebelDas-rebel
committed
feat: Python MCP server with 4 tools (a3m_route, a3m_ensemble, a3m_classify, a3m_providers)
MCP server for A3M Router using stdio transport. Works with Claude Desktop, Cursor, Windsurf, Codex, n8n, and any MCP-compatible client. Tools: - a3m_route: Route query to optimal LLM provider (no execution) - a3m_ensemble: Execute across multiple providers in parallel - a3m_classify: Classify query type and get provider recommendations - a3m_providers: List all configured providers with cost and status Requires: mcp>=1.0.0 package (pip install mcp) Run: python -m a3m_mcp Or: pip install a3m-mcp-server
1 parent 84167b8 commit 6db1edc

5 files changed

Lines changed: 565 additions & 0 deletions

File tree

‎python/mcp-server/README.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# A3M Router MCP Server (Python)
2+
3+
[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for [A3M Router](https://github.com/Das-rebel/a3m-router) — parallel multi-LLM execution for AI agents.
4+
5+
Allows any MCP-compatible AI agent (Claude Desktop, Cursor, Windsurf, Codex, n8n, etc.) to use A3M's intelligent routing and ensemble execution directly from Python.
6+
7+
## Tools
8+
9+
| Tool | Description |
10+
|------|-------------|
11+
| `a3m_route` | Route a query to the optimal LLM provider — returns model, tier, cost, reasoning |
12+
| `a3m_ensemble` | Execute a query across multiple providers in parallel and merge results |
13+
| `a3m_classify` | Classify query type (fast/creative/deep/code) and get provider recommendations |
14+
| `a3m_providers` | List all configured providers with cost and availability |
15+
16+
## Installation
17+
18+
```bash
19+
# From source
20+
cd python/mcp-server
21+
pip install -e .
22+
23+
# Or install the package directly (when published)
24+
pip install a3m-mcp-server
25+
```
26+
27+
## Configuration
28+
29+
Set environment variables:
30+
31+
```bash
32+
# Required: A3M Router URL (must be running)
33+
export A3M_BASE_URL=http://localhost:8787
34+
35+
# Optional
36+
export A3M_API_KEY=not-needed # default
37+
export A3M_TIMEOUT=30.0
38+
```
39+
40+
## Start A3M Router
41+
42+
```bash
43+
# Node.js way
44+
npx a3m-router serve
45+
46+
# Python way
47+
pip install a3m-router
48+
a3m-router serve
49+
```
50+
51+
## Usage
52+
53+
### Claude Desktop
54+
55+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
56+
57+
```json
58+
{
59+
"mcpServers": {
60+
"a3m-router": {
61+
"command": "python",
62+
"args": ["-m", "a3m_mcp"],
63+
"env": {
64+
"A3M_BASE_URL": "http://localhost:8787"
65+
}
66+
}
67+
}
68+
}
69+
```
70+
71+
### Cursor
72+
73+
Settings → Features → MCP Servers → Add:
74+
75+
```
76+
Name: A3M Router
77+
Command: python
78+
Arguments: -m a3m_mcp
79+
```
80+
81+
### n8n MCP Trigger
82+
83+
Add MCP Trigger node with:
84+
85+
```json
86+
{
87+
"server": "a3m-router",
88+
"command": "python",
89+
"args": ["-m", "a3m_mcp"]
90+
}
91+
```
92+
93+
### Direct stdio (pipe JSON-RPC)
94+
95+
```bash
96+
# List tools
97+
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python -m a3m_mcp
98+
99+
# Call a3m_route
100+
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"a3m_route","arguments":{"query":"Write a Python quicksort"}}}' | python -m a3m_mcp
101+
```
102+
103+
## Examples
104+
105+
### Route a query
106+
107+
```python
108+
# a3m_route tool
109+
Input: {"query": "Write a Python function to sort a list"}
110+
Output:
111+
{
112+
"model": "groq/llama-3.3-70b-versatile",
113+
"tier": "cheap",
114+
"cost": 0.000012,
115+
"reasoning": "Code query detected, routing to fast coding provider",
116+
"classification": "code"
117+
}
118+
```
119+
120+
### Ensemble execution
121+
122+
```python
123+
# a3m_ensemble tool
124+
Input: {"query": "Explain quantum computing in 3 sentences", "providers": ["groq", "google", "cerebras"]}
125+
Output:
126+
{
127+
"query": "Explain quantum computing in 3 sentences",
128+
"parallel_responses": [
129+
{"provider": "groq", "content": "Quantum computing is..."},
130+
{"provider": "google", "content": "At its core, quantum..."},
131+
{"provider": "cerebras", "content": "Quantum computing leverages..."}
132+
],
133+
"best_answer": "Quantum computing is...",
134+
"stats": {"total_providers": 3, "successful": 3, "failed": 0}
135+
}
136+
```
137+
138+
## Architecture
139+
140+
```
141+
┌──────────────────────────────────────────────────────┐
142+
│ MCP Client (Claude, Cursor, Codex, n8n) │
143+
└──────────────────────┬───────────────────────────────┘
144+
│ MCP Protocol (stdio)
145+
┌──────────────────────▼───────────────────────────────┐
146+
│ A3M Router MCP Server (Python) │
147+
│ │
148+
│ a3m_route a3m_ensemble a3m_classify a3m_providers │
149+
└──────────────────────┬───────────────────────────────┘
150+
│ HTTP API
151+
┌──────────────────────▼───────────────────────────────┐
152+
│ A3M Router (a3m-router serve) │
153+
│ │
154+
│ routeQuery() parallelEnsemble() providers │
155+
└───────┬────────────┬────────────┬─────────────────────┘
156+
│ │ │
157+
┌────▼───┐ ┌────▼───┐ ┌────▼───┐
158+
│ Groq │ │ Google │ │Cerebras│ ...
159+
└────────┘ └────────┘ └────────┘
160+
```
161+
162+
## Testing
163+
164+
```bash
165+
cd python/mcp-server
166+
pip install -e ".[dev]"
167+
pytest
168+
```
169+
170+
## License
171+
172+
MIT

‎python/mcp-server/a3m_mcp/__init__.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
"""A3M Router MCP Server — Model Context Protocol server for A3M Router.
2+
3+
Usage:
4+
python -m a3m_mcp # Start the MCP server
5+
pip install a3m-mcp-server # Install as package
6+
"""
7+
try:
8+
from .server import main, HAS_MCP, SERVER_NAME
9+
except ImportError:
10+
main = None
11+
HAS_MCP = False
12+
SERVER_NAME = "a3m-router"
13+
14+
__version__ = "1.0.0"
15+
__all__ = ["main", "HAS_MCP", "SERVER_NAME", "__version__"]

‎python/mcp-server/a3m_mcp/__main__.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
"""Entry point: python -m a3m_mcp"""
2+
import sys
3+
import os
4+
5+
# Add parent directory to path so a3m_mcp can find sibling packages
6+
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
7+
8+
from .server import main, HAS_MCP
9+
10+
if __name__ == "__main__":
11+
if not HAS_MCP:
12+
print("ERROR: mcp package required. Install with: pip install mcp", file=sys.stderr)
13+
sys.exit(1)
14+
import asyncio
15+
asyncio.run(main())

0 commit comments

Comments
 (0)