tatlock/docs/claude-integration.md

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

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

{
  "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