Dmcp

🚀 DMCP - 動態模型上下文協議

為MCP實現語義工具發現 - 通過向量搜索使工具發現以查詢為驅動，解決“工具過多”的問題。

🚀 快速開始

前提條件

• Docker 與 Docker Compose
• 一個暴露工具的MCP服務器網關（例如，Agent Gateway）

1. 克隆並啟動

git clone https://github.com/yourusername/dmcp.git
cd dmcp

# 啟動所有服務：Redis、嵌入服務和 DMCP 服務器
docker compose up -d

# 等待服務啟動完成（嵌入模型加載大約需要2 - 3分鐘）
docker compose ps

2. 索引工具

# 運行索引器，將 MCP 網關中的工具填充到 Redis 中
docker compose run --rm indexer

# 驗證工具是否已索引
curl http://localhost:3001/health
# → {"status":"healthy","toolCount":420,...}

3. 配置 VS Code

在 .vscode/mcp.json 中添加以下內容：

{
  "servers": {
    "dmcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

完成！ 現在，search_tools 元工具已可在 VS Code / GitHub Copilot 中使用。

✨ 主要特性

• 🔍 語義搜索：使用 ToolRet 訓練的 E5 模型進行準確的工具檢索
• ⚡ 快速：約 50ms 的搜索延遲，減少 98% 的令牌使用
• 🔄 連接恢復能力：自動重試、健康檢查和重新連接
• 🐳 Docker 就緒：包含 Redis VSS + 嵌入服務的完整堆棧
• 📊 可觀測性：提供健康端點、會話日誌和連接狀態
• ✅ 經過測試：使用 vitest 進行了 56 個單元測試

📦 安裝指南

克隆倉庫

git clone https://github.com/yourusername/dmcp.git
cd dmcp

啟動服務

docker compose up -d

索引工具

docker compose run --rm indexer

配置 VS Code

在 .vscode/mcp.json 中添加：

{
  "servers": {
    "dmcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

💻 使用示例

基礎用法

User: "Create a GitHub issue for this bug"

LLM calls: search_tools(query="create GitHub issue")
    → Returns top-15 relevant tools (via semantic vector search)
    → Tools become available for use

LLM calls: github_create_issue(...)
    → Issue created!

高級用法

User: "search for kubernetes tools"
→ search_tools("kubernetes")
← Returns: 15 k8s tools (get_pods, list_deployments, ...)

📚 詳細文檔

🏗️ 架構

┌─────────────────────────────────────────────────────────────────────────────┐
│                           VS Code / GitHub Copilot                          │
│                                                                             │
│  User: "search for kubernetes tools"                                        │
│        → search_tools("kubernetes")                                         │
│        ← Returns: 15 k8s tools (get_pods, list_deployments, ...)           │
└─────────────────────────────────┬───────────────────────────────────────────┘
                                  │ HTTP (Streamable HTTP Transport)
                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         DMCP Server (port 3001)                             │
│                                                                             │
│  • Exposes 1 meta-tool: search_tools                                        │
│  • Pure vector search (COSINE similarity, HNSW index)                       │
│  • Sends listChanged notifications when tools discovered                    │
│  • Connection keep-alive with health checks (30s interval)                  │
│  • Auto-retry on connection failures (3 attempts, exponential backoff)      │
└────────────┬──────────────────────────────────────────────────┬─────────────┘
             │                                                  │
             │ Query embeddings                                 │ Tool calls (SSE)
             ▼                                                  ▼
┌────────────────────────────────┐                ┌────────────────────────────┐
│   Redis Stack (port 6380)      │                │     Backend MCP Servers    │
│                                │                │     (via Agent Gateway)    │
│  • Vector Index (HNSW)         │                │                            │
│  • COSINE similarity           │                │  • GitHub, Jira, Confluence│
│  • 400+ tools indexed          │                │  • Google Workspace, Notion│
└────────────────────────────────┘                │  • Kubernetes, AWS, Azure  │
             ▲                                    │  • And more...             │
             │                                    └────────────────────────────┘
┌────────────────────────────────┐
│  Infinity Embedding Service    │
│  (port 5000)                   │
│                                │
│  • ToolRet e5-large-v2 model   │
│  • 1024 dimensions             │
│  • OpenAI-compatible API       │
└────────────────────────────────┘

📁 項目結構

dmcp/
├── docker-compose.yml          # Full stack configuration
├── server/                     # DMCP Server (TypeScript)
│   ├── src/
│   │   ├── dmcp-server.ts      # Main server with connection management
│   │   ├── redis-vss.ts        # Redis vector similarity search
│   │   ├── custom-embedding-provider.ts
│   │   ├── dmcp-server.test.ts # Unit tests (28 tests)
│   │   └── redis-vss.test.ts   # Unit tests (28 tests)
│   ├── vitest.config.ts
│   └── package.json
├── indexer/                    # Tool Indexer (TypeScript)
│   └── src/
│       └── index.ts            # CLI indexer with parallel discovery
└── README.md

🐳 Docker 命令

# 啟動完整堆棧
docker compose up -d

# 查看日誌
docker compose logs -f dmcp-server

# 運行一次性索引
docker compose run --rm indexer

# 啟動持續同步工作器
docker compose --profile worker up -d

# 代碼更改後重建
docker compose build dmcp-server && docker compose up -d dmcp-server

# 停止所有服務
docker compose down

# 停止並刪除索引數據
docker compose down -v

⚙️ 配置

環境變量

連接恢復能力

Docker Compose 服務

🔍 搜索工作原理

DMCP 使用 純向量搜索 和 ToolRet 嵌入模型：

1. 使用 ToolRet 訓練的 E5-large-v2 對查詢進行嵌入
2. Redis 執行 HNSW 最近鄰搜索
3. 按餘弦相似度對前 K 個結果進行排序並返回
4. 通過 notifications/tools/list_changed 使工具可用

示例查詢：

🏥 健康與監控

健康端點

curl http://localhost:3001/health

響應：

{
  "status": "healthy",
  "toolCount": 440,
  "activeSessions": 2,
  "backendConnections": {
    "total": 5,
    "healthy": 5,
    "details": [
      {"serverId": "github", "healthy": true, "lastCheck": 1704700000000},
      {"serverId": "serena", "healthy": true, "lastCheck": 1704700000000}
    ]
  },
  "config": {
    "retryAttempts": 3,
    "retryDelayMs": 1000,
    "healthIntervalMs": 30000,
    "connectionTimeoutMs": 10000
  },
  "uptime": 3600
}

服務器日誌

docker compose logs -f dmcp-server

# 示例輸出：
# 16:38:36 [DMCP] 🚀 Server listening on http://0.0.0.0:3000
# 16:38:36 [DMCP] ✓ Found 440 indexed tools
# 16:38:52 [DMCP] POST /mcp [initialize]
# 16:38:52 [DMCP] 📡 New connection request (session #1)
# 16:39:01 [DMCP] 🔍 Search: "kubernetes pods" (limit: 15)
# 16:39:01 [DMCP] ✓ Found 12 tools in 45ms

🧪 測試

cd server

# 運行測試
npm test

# 以監聽模式運行
npm run test:watch

# 運行並生成覆蓋率報告
npm run test:coverage

測試覆蓋率：56 個測試涵蓋：

• 工具名稱清理和解析
• 連接重試和健康檢查邏輯
• Redis 向量搜索操作
• 嵌入操作

🔧 本地開發

# 僅啟動基礎設施
docker compose up -d redis-vss embedding-service

# 在本地運行服務器
cd server
npm install
REDIS_PORT=6380 EMBEDDING_URL=http://localhost:5000 npm run start

# 運行測試
npm test

➕ 添加 MCP 服務器

DMCP 可與任何 MCP 服務器配合使用。示例配置位於 gateway/config_parts/ 中。

Notion MCP 服務器

Notion MCP 提供用於搜索、讀取和創建 Notion 頁面/數據庫的工具。

1. 在 notion.so/my-integrations 創建一個 Notion 集成
2. 將以下內容添加到網關配置文件（gateway/config_parts/70-notion.yaml）中：

targets:
  - name: notion
    type: mcp
    target_config:
      command: npx
      args:
        - -y
        - "@notionhq/notion-mcp-server"
      env:
        OPENAPI_MCP_HEADERS: '{"Authorization": "Bearer ${NOTION_API_KEY}", "Notion-Version": "2022-06-28"}'

3. 設置 API 密鑰：export NOTION_API_KEY=ntn_...
4. 重啟網關並重新索引：docker compose run --rm indexer

其他流行的 MCP 服務器

📊 性能

📐 MCP 規範合規性

實現了 MCP 規範 並使用 可流式 HTTP 傳輸：

• ✅ listChanged: true 功能
• ✅ notifications/tools/list_changed 通知
• ✅ 基於搜索的動態工具可用性
• ✅ 可流式 HTTP 傳輸（POST/GET/DELETE）
• ✅ 使用 UUID 會話 ID 進行會話管理
• ✅ 使用 SSE 進行異步通知

🔬 研究基礎

基於 "Retrieval Models Aren't Tool-Savvy"（ACL 2025）實現：

• 📄 論文
• 🤗 模型：mangopy/ToolRet-trained-e5-large-v2
• 🏠 GitHub

關鍵見解：通用信息檢索模型在工具檢索方面表現不佳，特定於工具的訓練至關重要。

🎬 靈感來源

• 📺 MCP 工具過載問題 - YouTube
• 📝 Redis 博客：從推理到檢索

📄 許可證

本項目採用 MIT 許可證。