@doclea/mcp

Local MCP server for Doclea - persistent memory for AI coding assistants.

Installation

Prerequisites

• Bun v1.0+ (curl -fsSL https://bun.sh/install | bash)
• Docker & Docker Compose
• Git

Step 1: Clone and Build

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

# 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):

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

{
  "mcpServers": {
    "doclea": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/doclea/packages/doclea-mcp/dist/index.js"]
    }
  }
}

Option C: For development (uses source directly):

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

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

# 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

# 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