Dive MCP Host

✨ 为什么选择 Dive MCP Host？

MCP 生态正在快速发展，但大多数主机都与单一大模型、单一传输方式或单一前端紧密耦合。Dive MCP Host 则恰恰相反：它是一个与传输方式和模型无关的运行时，可将任意 MCP 服务集合转变为单一 Agent 后端。

• 🧠 任意大模型 — OpenAI、Anthropic、Google、AWS Bedrock、Mistral、DeepSeek、Ollama、Azure OpenAI——任何 LangChain 支持的模型。
• 🔌 任意 MCP 服务 — stdio、sse、streamable-http、websocket，以及“启动并连接”本地 HTTP 模式。
• 🛰 三种使用方式 — 嵌入 SDK、调用 HTTP API，或通过命令行驱动。
• 🧩 符合规范的能力协商 — 仅当服务声明支持时才调用 tools/list / prompts/list；并能妥善处理 Method not found。
• 💬 将 MCP 提示词作为一等功能 — 支持列出、获取、渲染，并在收到 notifications/prompts/list_changed 时刷新。
• 🔐 内置 OAuth 和信息征询 — 交互流程可直接呈现给主机，无需针对每个服务编写专用胶合代码。
• 🗃 持久化会话 — 通过 LangGraph 使用 SQLite 或 Postgres 进行检查点保存；消息、OAuth 令牌和对话状态在重启后仍可保留。

🏗 架构一览

flowchart LR
    subgraph Clients
        UI[Dive Desktop<br/>Electron / Tauri]
        CLI[dive_cli]
        SDK[Python SDK<br/>DiveMcpHost]
    end

    subgraph Host[dive-mcp-host]
        HTTP[FastAPI<br/>dive_httpd]
        Core[DiveMcpHost<br/>+ ToolManager<br/>+ Chat / LangGraph]
        DB[(SQLite / Postgres<br/>messages • OAuth • checkpoints)]
    end

    subgraph LLMs
        OAI[OpenAI]
        Anthropic[Anthropic]
        Ollama[Ollama]
        Etc[…and more]
    end

    subgraph MCPServers[MCP Servers]
        Stdio[stdio<br/>local subprocess]
        SSE[SSE]
        StreamHTTP[streamable-http]
        WS[websocket]
    end

    UI --> HTTP
    CLI --> Core
    SDK --> Core
    HTTP --> Core
    Core --> LLMs
    Core --> MCPServers
    Core --> DB

三个入口共用同一个 DiveMcpHost 核心。HTTP 层是一个精简的 FastAPI 封装；命令行和 SDK 则更加精简。

生命周期

所有对象都是异步上下文管理器（ContextProtocol）。资源严格嵌套，确保清理过程可预测：

sequenceDiagram
    participant App
    participant Host as DiveMcpHost
    participant TM as ToolManager
    participant Srv as McpServer × N
    participant Chat

    App->>Host: async with DiveMcpHost(config)
    Host->>TM: enter
    TM->>Srv: spawn / connect each server (parallel)
    Srv->>Srv: initialize() → read capabilities
    Srv-->>Srv: tools/list (if advertised)
    Srv-->>Srv: prompts/list (if advertised)
    App->>Host: host.chat(chat_id=...)
    Host->>Chat: build LangGraph agent over tools
    App->>Chat: query("hello")
    Chat-->>App: stream events
    App->>Host: __aexit__
    Host->>TM: shutdown all servers

🚀 快速开始

安装

# Recommended: uv (respects uv.lock)
uv sync --frozen

# Or with pip
pip install -e .

# With dev tools (pytest, ruff, …)
uv sync --extra dev --frozen

需要 Python 3.12+。

运行 HTTP 服务

dive_httpd

默认在 0.0.0.0:61990 上提供服务。通过 dive_httpd.json 配置（数据库、检查点保存器、CORS）。

试用命令行

dive_cli "Summarize today's news"
dive_cli -c CHAT_ID "and what about tech?"   # resume a thread

在 Python 中嵌入

from dive_mcp_host.host.host import DiveMcpHost
from dive_mcp_host.host.conf import HostConfig

config = HostConfig(...)  # see model_config.json / mcp_config.json samples

async with DiveMcpHost(config) as host:
    async with host.chat(chat_id="demo") as chat:
        async for event in chat.query("hello"):
            print(event)

⚙️ 配置

服务由三个 JSON 文件驱动。示例文件位于仓库根目录。

{
  "mcpServers": {
    "fetch": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch@latest"]
    },
    "weather": {
      "transport": "streamable",
      "url": "https://example.com/mcp"
    }
  }
}

{
  "activeProvider": "ollama",
  "configs": {
    "openai":     { "modelProvider": "openai",    "model": "gpt-4o-mini", "apiKey": "..." },
    "anthropic":  { "modelProvider": "anthropic", "model": "claude-sonnet-4-5" },
    "ollama":     { "modelProvider": "ollama",    "model": "qwen2.5:14b",
                    "configuration": { "baseURL": "http://localhost:11434" } }
  }
}

{
  "db":           { "uri": "sqlite:///db.sqlite", "async_uri": "sqlite+aiosqlite:///db.sqlite", "migrate": true },
  "checkpointer": { "uri": "sqlite:///db.sqlite" },
  "cors_origin":  "http://localhost:5173"
}

🧩 MCP 能力支持

Dive 按照 MCP 规范协商能力：检查每个服务的 initialize 响应，只查询已声明的端点。这可以避免因“服务未实现 X 导致宿主崩溃”这一整类问题。

提示词 HTTP API

GET  /api/tools/{server}/prompts          # list (?refresh=true bypasses cache)
POST /api/tools/{server}/prompts/get      # body: {"name": "...", "arguments": {...}}

两个端点都返回仓库标准的 DataResult[T] 封装 （{success, message, data}）；data 是提示词列表或已渲染的 GetPromptResult（包含描述和有序的 PromptMessage）， 可直接追加到聊天线程中。

🔭 HTTP API 一览

🧪 开发

# Install dev deps
uv sync --extra dev --frozen

# (Optional) local Postgres for tests/dev
./scripts/run_pg.sh

# Run the full suite
pytest

# Single test
pytest tests/test_tools.py::test_mcp_server_info

# Integration tests only
pytest -m integration

# Lint & format (ruff is the only tool you need)
ruff check .
ruff format .

# DB migrations
alembic upgrade head
alembic revision --autogenerate -m "describe change"

不激活 venv：

uv run --extra dev --frozen pytest

🤝 参与贡献

此仓库是 Dive 桌面应用 的 Python 后端。修改线缆格式的 PR 必须与已发布的 Dive 版本保持向后兼容——优先添加字段和新端点，而不是破坏现有功能。

📜 许可证

MIT — 参见 LICENSE。