# Claude Integration Plan

## Overview

Tatlock uses a bidirectional Claude architecture:
- **Scenario A**: Tatlock powered by Claude backend (with Ollama fallback) — **COMPLETE**
- **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.internal/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