dive-mcp-host CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Role

This repo is dive-mcp-host — the Python MCP host service. It is consumed two ways:

• as a standalone HTTP service (dive_httpd) and CLI (dive_cli)
• as the Python submodule of the Dive desktop app (Electron + Tauri), which spawns this service as a child process

Backend changes that touch the wire format must stay backwards-compatible with whatever Dive frontend is in the field. See memory/feedback_backcompat.md for the discipline.

Common Commands

# Install runtime + dev deps (uv is preferred)
uv sync --extra dev --frozen
# fallback: pip install -e ".[dev]"

# Start HTTP service on 0.0.0.0:61990
dive_httpd

# One-shot CLI chat
dive_cli "hello"
dive_cli -c CHAT_ID "follow-up"   # resume a thread

# Tests
pytest                                              # full suite
pytest tests/test_tools.py::test_mcp_server_info    # single test
pytest -m integration                               # integration only
uv run --extra dev --frozen pytest                  # without activating venv

# Lint / format (ruff is the only linter; ruff format is the formatter)
ruff check .
ruff format .

# Local Postgres for tests/dev (optional)
./scripts/run_pg.sh

# DB migrations (alembic.ini → ./dive_mcp_host/httpd/database/migrations/)
alembic upgrade head
alembic revision --autogenerate -m "<message>"

Running tests in this sandbox

Tests subprocess-spawn python3 from PATH. If running outside the project venv, prepend it explicitly so the child processes see the installed deps:

PATH="$PWD/.venv/bin:$PATH" \
PYTHONPATH=/path/to/extra/deps:$PWD \
.venv/bin/python -m pytest tests/...

Architecture

Layered structure

dive_mcp_host/
├── host/         ← core SDK (no HTTP, embeddable)
├── httpd/        ← FastAPI server wrapping the SDK
├── cli/          ← dive_cli entry point
├── models/       ← LLM provider loaders
├── skills/       ← skill (markdown-with-frontmatter) loader
├── plugins/      ← plugin discovery
├── oap_plugin/   ← OpenAgentPlatform integration
├── internal_tools/ ← built-in non-MCP tools (fetch, bash, file IO)
└── scheduler/    ← background scheduling