Skip to content

Commit 3928dcd

Browse files
offx-zinthoffx-zinth
authored
Merge pull request #25 from offx-zinth/master
mcp_implimentation
2 parents c69e49b + 5982ab7 commit 3928dcd

30 files changed

Lines changed: 1659 additions & 113 deletions

‎MCP_SERVER.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
# SMP as MCP Server
2+
3+
The Structural Memory Protocol (SMP) is now available as a **Model Context Protocol (MCP) Server**, enabling AI agents to query and manipulate code knowledge graphs through a standardized interface.
4+
5+
## Overview
6+
7+
**File:** `smp/protocol/mcp.py`
8+
9+
The MCP server wraps SMP's JSON-RPC 2.0 API as MCP tools and resources, making all SMP capabilities accessible to Claude and other MCP-compatible AI agents.
10+
11+
## Supported Tools (36 total)
12+
13+
### Graph Intelligence (8 tools)
14+
Query and navigate the code knowledge graph:
15+
- `smp_navigate` - Search for entities and their relationships
16+
- `smp_trace` - Trace dependencies and references across the graph
17+
- `smp_context` - Extract surrounding context for a file
18+
- `smp_impact` - Assess the impact of changes
19+
- `smp_locate` - Find specific code entities
20+
- `smp_search` - Semantic search using vector embeddings
21+
- `smp_flow` - Find paths or flows between entities
22+
- `smp_why` - Explain why relationships exist
23+
24+
### Memory & Enrichment (10 tools)
25+
Update the graph and enhance code understanding:
26+
- `smp_update` - Update or ingest a file
27+
- `smp_batch_update` - Apply multiple file updates
28+
- `smp_reindex` - Reindex the graph
29+
- `smp_enrich` - Enrich a node with semantic metadata
30+
- `smp_enrich_batch` - Batch enrich multiple nodes
31+
- `smp_enrich_stale` - Find stale enriched nodes
32+
- `smp_enrich_status` - Check enrichment coverage
33+
- `smp_annotate` - Manually annotate a node
34+
- `smp_annotate_bulk` - Bulk annotation
35+
- `smp_tag` - Add/remove/replace tags
36+
37+
### Safety & Integrity (10 tools)
38+
Manage session safety and verify integrity:
39+
- `smp_session_open` - Open a safety session
40+
- `smp_session_close` - Close a session
41+
- `smp_guard_check` - Check against safety guards
42+
- `smp_dryrun` - Simulate a change
43+
- `smp_checkpoint` - Create recovery checkpoint
44+
- `smp_rollback` - Restore to checkpoint
45+
- `smp_lock` - Lock files
46+
- `smp_unlock` - Unlock files
47+
- `smp_audit_get` - Retrieve audit logs
48+
- `smp_verify_integrity` - Verify node integrity
49+
50+
### Execution & Sandbox (3 tools)
51+
Execute code in isolated environments:
52+
- `smp_sandbox_spawn` - Create sandbox
53+
- `smp_sandbox_execute` - Execute commands
54+
- `smp_sandbox_destroy` - Destroy sandbox
55+
56+
### Coordination & Observability (5 tools)
57+
Manage handoffs and monitor execution:
58+
- `smp_handoff_review` - Create code review
59+
- `smp_handoff_approve` - Approve review
60+
- `smp_handoff_reject` - Reject review
61+
- `smp_handoff_pr` - Create pull request
62+
- `smp_telemetry` - Query telemetry data
63+
64+
### System Resources (2 resources)
65+
- `smp://stats` - System statistics
66+
- `smp://health` - Health status
67+
68+
## Getting Started
69+
70+
### Prerequisites
71+
- Python 3.11+
72+
- Neo4j database running
73+
- Chroma vector store configured
74+
- Environment variables set:
75+
- `SMP_NEO4J_URI` (default: `bolt://localhost:7687`)
76+
- `SMP_NEO4J_USER` (default: `neo4j`)
77+
- `SMP_NEO4J_PASSWORD`
78+
- `SMP_SAFETY_ENABLED` (optional: `true`/`false`)
79+
80+
### Starting the Server
81+
82+
```bash
83+
# Start as stdio server (for local use with Claude Desktop)
84+
python3.11 -m smp.protocol.mcp
85+
86+
# Or as background process
87+
python3.11 -m smp.cli run smp-mcp -- python3.11 -m smp.protocol.mcp
88+
```
89+
90+
### Claude Desktop Integration
91+
92+
Add to `claude_desktop_config.json`:
93+
94+
```json
95+
{
96+
"mcpServers": {
97+
"smp": {
98+
"command": "python3.11",
99+
"args": ["-m", "smp.protocol.mcp"],
100+
"cwd": "/path/to/SMP"
101+
}
102+
}
103+
}
104+
```
105+
106+
## Architecture
107+
108+
### Lifespan Management
109+
The server uses `app_lifespan()` to:
110+
1. Initialize Neo4j graph store
111+
2. Connect Chroma vector store
112+
3. Create embedding service
113+
4. Set up query engines and builders
114+
5. Optionally enable safety features
115+
6. Provide state to all tools via FastMCP context
116+
117+
### Tool Pattern
118+
Each MCP tool:
119+
1. Accepts Pydantic-validated input
120+
2. Retrieves server state from context
121+
3. Routes to SMP's dispatcher via `_call_rpc()`
122+
4. Returns structured results
123+
124+
### Error Handling
125+
- Pydantic validation errors → `-32602` (Invalid params)
126+
- Handler errors → `-32001` (Server error)
127+
- Internal errors → `-32603` (Internal error)
128+
- Method not found → `-32601` (Method not found)
129+
130+
## Example Usage
131+
132+
### With Claude Desktop
133+
```
134+
User: "Show me all functions in main.py that have complex dependencies"
135+
Agent: [Calls smp_locate with query="functions" and file filter]
136+
137+
User: "What would break if I deleted this function?"
138+
Agent: [Calls smp_impact to assess change effects]
139+
140+
User: "Create a code review for these changes"
141+
Agent: [Calls smp_handoff_review]
142+
```
143+
144+
### Programmatic (Python)
145+
```python
146+
from smp.protocol.mcp import mcp
147+
import asyncio
148+
149+
async def query_graph():
150+
# Use the dispatcher to call tools
151+
from smp.protocol.dispatcher import get_dispatcher
152+
dispatcher = get_dispatcher()
153+
154+
handler = dispatcher.get_handler("smp/navigate")
155+
result = await handler.handle(
156+
{"query": "find_function"},
157+
context={...}
158+
)
159+
return result
160+
161+
asyncio.run(query_graph())
162+
```
163+
164+
## Configuration
165+
166+
### Environment Variables
167+
```bash
168+
# Neo4j
169+
SMP_NEO4J_URI=bolt://localhost:7687
170+
SMP_NEO4J_USER=neo4j
171+
SMP_NEO4J_PASSWORD=your_password
172+
173+
# Safety Features
174+
SMP_SAFETY_ENABLED=true
175+
176+
# Logging
177+
RUST_LOG=info
178+
```
179+
180+
### Safety Mode
181+
When `SMP_SAFETY_ENABLED=true`, the following are initialized:
182+
- SessionManager - Track agent sessions
183+
- GuardEngine - Enforce safety checks
184+
- CheckpointManager - Create recovery points
185+
- AuditLogger - Log all changes
186+
- SandboxExecutor - Isolated code execution
187+
188+
## Performance
189+
190+
- **Graph traversal**: O(depth) where depth is user-specified
191+
- **Vector search**: O(log n) with ChromaDB indexing
192+
- **Enrichment**: Batched for efficiency
193+
- **Concurrent sessions**: Supported with locking
194+
195+
## Security
196+
197+
- Session-based isolation
198+
- File locking for concurrent access
199+
- Guard checks for destructive operations
200+
- Audit logging of all changes
201+
- Sandboxed execution environment
202+
203+
## Troubleshooting
204+
205+
### Server won't start
206+
```bash
207+
# Check Python version
208+
python3.11 --version
209+
210+
# Check dependencies
211+
pip list | grep mcp
212+
213+
# Verify Neo4j connection
214+
telnet localhost 7687
215+
```
216+
217+
### Tools not appearing in Claude
218+
- Restart Claude Desktop
219+
- Check `claude_desktop_config.json` syntax
220+
- Verify server process is running
221+
222+
### Performance issues
223+
- Check `SMP_NEO4J_URI` points to local instance
224+
- Verify ChromaDB is running
225+
- Monitor Neo4j memory usage
226+
227+
## Implementation Details
228+
229+
**File Structure:**
230+
```
231+
smp/
232+
├── protocol/
233+
│ ├── mcp.py ← MCP Server (you are here)
234+
│ ├── dispatcher.py ← Route to handlers
235+
│ ├── router.py ← Legacy JSON-RPC router
236+
│ ├── handlers/ ← Tool implementations
237+
│ └── server.py ← FastAPI endpoint
238+
```
239+
240+
**Key Components:**
241+
1. `app_lifespan()` - Initialize and manage server resources
242+
2. `_call_rpc()` - Route MCP tools to SMP handlers
243+
3. Pydantic models - Validate all tool inputs
244+
4. MCP decorators - Register tools and resources
245+
5. Annotations - Mark tools as read-only/destructive
246+
247+
## Future Enhancements
248+
249+
- [ ] Streaming for large result sets
250+
- [ ] Caching frequently accessed paths
251+
- [ ] Incremental graph updates
252+
- [ ] Machine learning model integration
253+
- [ ] Custom graph analyzers
254+
- [ ] Remote Neo4j support with auth
255+
256+
## Contributing
257+
258+
When adding new tools:
259+
1. Create Pydantic input model
260+
2. Create MCP tool function
261+
3. Add to appropriate tool category comment
262+
4. Include docstring with examples
263+
5. Test with `ruff check` and `mypy`
264+
6. Update tool count in this document
265+
266+
## References
267+
268+
- MCP Specification: https://modelcontextprotocol.io
269+
- FastMCP Documentation: https://github.com/modelcontextprotocol/python-sdk
270+
- SMP Protocol: See PROTOCOL.md

‎docker-compose.yml‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,8 @@ services:
66
NEO4J_dbms_security_procedures_unrestricted: apoc.*
77
NEO4J_dbms_security_procedures_allowlist: apoc.*
88
ports:
9-
<<<<<<< HEAD
10-
- "7475:7474" # Host 7475 maps to Container 7474
11-
- "7688:7687" # Host 7688 maps to Container 7687
12-
=======
139
- "7474:7474"
1410
- "7687:7687"
15-
>>>>>>> 87cfd9650622e51c4c94d43d490450a82a87ad3d
1611
volumes:
1712
- neo4j_data:/data
1813
- neo4j_logs:/logs
@@ -54,8 +49,4 @@ volumes:
5449
neo4j_data:
5550
neo4j_logs:
5651
chroma_data:
57-
<<<<<<< HEAD
5852
smp_data:
59-
=======
60-
smp_data:
61-
>>>>>>> 87cfd9650622e51c4c94d43d490450a82a87ad3d

‎pyproject.toml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,7 @@ dependencies = [
2121
"tree-sitter-typescript>=0.23",
2222
"python-dotenv>=1.0",
2323
"structlog>=24.0",
24-
<<<<<<< HEAD
25-
"chromadb",
26-
=======
27-
>>>>>>> 87cfd9650622e51c4c94d43d490450a82a87ad3d
24+
"chromadb",
2825
]
2926

3027
[project.optional-dependencies]

0 commit comments

Comments
 (0)