101 lines
2.8 KiB
Markdown
101 lines
2.8 KiB
Markdown
# Claude Integration Plan
|
|
|
|
## Overview
|
|
|
|
Tatlock uses a bidirectional Claude architecture:
|
|
- **Scenario A**: Tatlock powered by Claude backend (with Ollama fallback) — **COMPLETE**, then **rolled back to local-first**: Ollama/gemma4 is primary, Claude is retained as fallback (`PREFER_CLOUD_BACKEND=false`)
|
|
- **Scenario B**: Tatlock exposed as MCP server for external Claude instances — **OPEN**
|
|
- **Scenario C**: Offline operation via Ollama — **COMPLETE**
|
|
|
|
---
|
|
|
|
## MCP Server (Expose Tools to Claude) — NOT STARTED
|
|
|
|
Create an MCP server that exposes Tatlock's household tools to external Claude instances.
|
|
|
|
### New Files
|
|
|
|
```
|
|
src/mcp/
|
|
├── __init__.py
|
|
├── server.py # MCP server using mcp Python SDK
|
|
├── tool_adapters.py # Convert PydanticAI tools → MCP schemas
|
|
├── auth.py # API key authentication
|
|
└── transport.py # Streamable HTTP transport
|
|
```
|
|
|
|
### Docker Stack Addition
|
|
|
|
```yaml
|
|
tatlock-mcp:
|
|
image: git.schweitz.net/jpmschweitzer/tatlock:latest
|
|
command: ["python", "-m", "src.mcp.server"]
|
|
ports:
|
|
- "8002:8002"
|
|
environment:
|
|
- MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
|
|
networks:
|
|
- docker-dataplane
|
|
```
|
|
|
|
### Claude Desktop Configuration
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"tatlock": {
|
|
"command": "npx",
|
|
"args": ["mcp-remote", "https://mcp.schweitz.net/sse", "--header", "Authorization: Bearer ${MCP_AUTH_TOKEN}"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Checklist
|
|
|
|
- [ ] Create `src/mcp/` module
|
|
- [ ] Tool adapters (PydanticAI → MCP schema)
|
|
- [ ] Authentication middleware
|
|
- [ ] Streamable HTTP transport
|
|
- [ ] Docker stack configuration
|
|
|
|
---
|
|
|
|
## Future Phases
|
|
|
|
- **LiteLLM Gateway** — Unified endpoint for all models, config-driven routing
|
|
- **Multi-Provider** — Add OpenAI, Vertex AI, etc.
|
|
- **Smart Routing** — Context-aware model selection, cost ceiling enforcement
|
|
|
|
---
|
|
|
|
## Offline Behavior
|
|
|
|
| Scenario | Behavior |
|
|
|----------|----------|
|
|
| No API key | Use Ollama exclusively |
|
|
| API unreachable | Use Ollama, log warning |
|
|
| API rate limited | Fallback to Ollama |
|
|
|
|
| Aspect | Claude | Ollama |
|
|
|--------|--------|--------|
|
|
| Context | 200k tokens | ~8k tokens |
|
|
| Latency | 1-3s (network) | 0.5-1s (local) |
|
|
| Personality | Preserved | Preserved |
|
|
| Tools | All work | All work |
|
|
| Cost | API charges | Free |
|
|
|
|
---
|
|
|
|
## Related Repo Handovers
|
|
|
|
Handover documents created in each repo: `PROJECT_CLAUDIFICATION_HANDOVER.md`
|
|
|
|
### Open Items
|
|
|
|
- **library-desk**: Review HybridRAG response size limits, smart_create endpoint, response formats
|
|
- **core-api**: Review list_devices response format, error messages, rate limiting
|
|
- **portainer-core**: Update stack with new env vars, configure secrets, update CONTAINERS.md
|
|
- **webber**: Review content truncation limits, extraction quality
|
|
- **tatlock-ui**: Test streaming with Claude backend, conversation history, tool call display
|