# @doclea/mcp
Local MCP server for Doclea - persistent memory for AI coding assistants.
## Installation
### Prerequisites
- [Bun](https://bun.sh) v1.0+ (`curl -fsSL https://bun.sh/install | bash`)
- [Docker](https://docs.docker.com/get-docker/) & Docker Compose
- Git
### Step 1: Clone and Build
```bash
git clone https://github.com/your-org/doclea.git
cd doclea/packages/doclea-mcp
# Install dependencies
bun install
# Download embedding model (first time only, ~130MB)
./scripts/setup-models.sh
# Build
bun run build
```
### Step 2: Start Services
```bash
# Start Qdrant + Embeddings
bun run docker:up
# Verify services
curl http://localhost:6333/readyz # Should return "ok"
curl http://localhost:8080/health # Should return "ok"
```
### Step 3: Add to Claude Code
**Option A: Claude Code CLI** (`~/.claude.json` or project `.claude.json`):
```json
{
"mcpServers": {
"doclea": {
"command": "bun",
"args": ["run", "/absolute/path/to/doclea/packages/doclea-mcp/dist/index.js"]
}
}
}
```
**Option B: Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"doclea": {
"command": "bun",
"args": ["run", "/absolute/path/to/doclea/packages/doclea-mcp/dist/index.js"]
}
}
}
```
**Option C: For development** (uses source directly):
```json
{
"mcpServers": {
"doclea": {
"command": "bun",
"args": ["run", "/absolute/path/to/doclea/packages/doclea-mcp/src/index.ts"]
}
}
}
```
### Step 4: Restart Claude Code
After updating config, restart Claude Code to load the MCP server.
### Step 5: Initialize Your Project
In Claude Code, navigate to your project and ask:
```
Initialize doclea for this project
```
This scans your codebase, git history, and documentation to bootstrap memories.
## Usage
Once installed, Claude Code automatically has access to these tools:
### Store a Decision
```
Store this as a decision: We're using PostgreSQL because we need ACID
compliance for financial transactions. Tag it with "database" and "infrastructure".
```
### Search for Context
```
Search memories for authentication patterns
```
### Generate Commit Message
```
Generate a commit message for my staged changes
```
### Generate PR Description
```
Create a PR description for this branch
```
### Find Code Experts
```
Who should review changes to src/auth/?
```
### Generate Changelog
```
Generate a changelog from v1.0.0 to HEAD for users
```
## Configuration
Create `.doclea/config.json` in your project root (optional - uses defaults):
```json
{
"embedding": {
"provider": "local",
"endpoint": "http://localhost:8080"
},
"qdrant": {
"url": "http://localhost:6333",
"collectionName": "doclea_memories"
},
"storage": {
"dbPath": ".doclea/local.db"
}
}
```
### Embedding Providers
| Provider | Config |
|----------|--------|
| **local** (default) | `{ "provider": "local", "endpoint": "http://localhost:8080" }` |
| **openai** | `{ "provider": "openai", "apiKey": "sk-...", "model": "text-embedding-3-small" }` |
| **nomic** | `{ "provider": "nomic", "apiKey": "...", "model": "nomic-embed-text-v1.5" }` |
| **voyage** | `{ "provider": "voyage", "apiKey": "...", "model": "voyage-3" }` |
| **ollama** | `{ "provider": "ollama", "endpoint": "http://localhost:11434", "model": "nomic-embed-text" }` |
## MCP Tools Reference
### Memory Tools
| Tool | Description |
|------|-------------|
| `doclea_store` | Store a memory (decision, solution, pattern, architecture, note) |
| `doclea_search` | Semantic search across memories |
| `doclea_get` | Get memory by ID |
| `doclea_update` | Update existing memory |
| `doclea_delete` | Delete memory |
### Git Tools
| Tool | Description |
|------|-------------|
| `doclea_commit_message` | Generate conventional commit from staged changes |
| `doclea_pr_description` | Generate PR description with context |
| `doclea_changelog` | Generate changelog between refs (markdown/json, developers/users) |
### Expertise Tools
| Tool | Description |
|------|-------------|
| `doclea_expertise` | Map codebase expertise, identify bus factor risks |
| `doclea_suggest_reviewers` | Suggest PR reviewers based on file ownership |
### Bootstrap Tools
| Tool | Description |
|------|-------------|
| `doclea_init` | Initialize project, scan git history, docs, and code |
| `doclea_import` | Import from markdown files or ADRs |
## Memory Types
- **decision** - Architectural decisions, technology choices
- **solution** - Bug fixes, problem resolutions
- **pattern** - Code patterns, conventions
- **architecture** - System design notes
- **note** - General documentation
## Troubleshooting
### Docker services not starting
```bash
# Check logs
docker compose -f docker-compose.test.yml logs
# Restart
bun run docker:down
bun run docker:up
```
### First startup is slow
The embeddings service downloads the model (~130MB) on first run. After that, it's cached.
### Port conflicts
Default ports: Qdrant (6333), Embeddings (8080). Edit `docker-compose.test.yml` to change.
### MCP server not appearing in Claude
1. Verify the path in config is absolute
2. Check that `bun run build` completed successfully
3. Restart Claude Code completely
## Development
```bash
# Run in development mode (hot reload)
bun run dev
# Run all tests
bun test
# Run unit tests only
bun run test:unit
# Run integration tests (requires Docker services)
bun run test:integration
# Type check
bun run typecheck
# Build for production
bun run build
```
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Claude Code │
│ ↓ MCP │
├─────────────────────────────────────────────────────────┤
│ Doclea MCP Server │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌───────────┐ │
│ │ Memory │ │ Git │ │Expertise │ │ Bootstrap │ │
│ │ Tools │ │ Tools │ │ Tools │ │ Tools │ │
│ └────┬────┘ └────┬────┘ └────┬─────┘ └─────┬─────┘ │
│ └───────────┴───────────┴─────────────┘ │
│ ↓ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ SQLite │ │ Qdrant │ │ Embeddings │ │
│ │ (metadata) │ │ (vectors) │ │ (local/API) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
```
## License
MIT
