MCP Zero Langgraph

MCP-Zero 与 LangGraph 集成

  

使用智能MCP工具选择 MCP-Zero的两阶段分层检索，缠绕着 langchain-mcp-adapters 以实现与LangGraph的无缝集成。

特点/功能

• 零修改 到 langchain-mcp-adapters（易于维护）
• 搜索空间减少98% （2,797个工具 → 3-5个相关工具）
• 快速选择 （约1-2秒，包括大型语言模型（LLM）和嵌入向量处理时间）
• 手动注册表 用于服务器描述（易于管理）
• 懒加载 （仅从匹配的服务器加载工具）
• 缓存 （嵌入和工具）
• 基于诗歌的 依赖管理

建筑学

User Query
    ↓
[LLM] Extract server + tool descriptions
    ↓
[MCP-Zero Stage 1] Match top-5 servers (308 → 5)
    ↓
[MCP-Zero Stage 2] Match top-3 tools (2,797 → 3)
    ↓
[MultiServerMCPClient] Load only matched tools
    ↓
[LangGraph] Reasoning with 3-5 tools

安装

先决条件

• Python 3.12+
• 诗歌（用于依赖管理）
• Node.js（用于MCP服务器）

设置

1. 克隆仓库

   git clone https://github.com/QuangNguyen2609/MCP-Zero-Langgraph
   cd mcp-zero-langgraph

1. 创建一个虚拟环境

   python3.12 -m venv .venv

1. 激活虚拟环境

   # On macOS/Linux
   source .venv/bin/activate

   # On Windows
   .venv\Scripts\activate

1. 使用 Poetry 安装依赖项

   poetry install

或者如果你更喜欢使用 pip：

   pip install -e .

1. 配置环境变量

   cp .env.example .env
   # Edit .env with your API keys

1. 配置MCP服务器

复制示例配置并进行自定义：

   cp mcp_servers.example.yaml mcp_servers.yaml

编辑 mcp_servers.yaml 与您的MCP服务器：

   servers:
     github:
       connection:
         transport: stdio
         command: npx
         args: ["-y", "@modelcontextprotocol/server-github"]
         env:
           GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
       metadata:
         description: "GitHub repository and issue management"
         summary: "Access GitHub APIs to search repositories..."
         aliases: ["github", "git", "repository"]
         category: "development"

1. 构建嵌入数据集 （一次性设置）

   python examples/build_dataset.py

这将会：

- 连接到所有已配置的MCP服务器 - 加载所有可用工具 - 为服务器/工具描述生成嵌入表示 - 保存带有嵌入信息的数据集（约83 MB）

时间： 根据服务器数量，大约需要5-10分钟。

快速入门

1. 作为库进行安装

pip install git+https://github.com/QuangNguyen2609/MCP-Zero-Langgraph.git

2. 创建您的MCP服务器配置

复制示例配置并进行自定义：

cp mcp_servers.example.yaml my_servers.yaml

编辑 my_servers.yaml 与您的MCP服务器一起：

servers:
  github:
    connection:
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    metadata:
      description: "GitHub repository management"
      summary: "Access GitHub APIs for repos, issues, and PRs"
      aliases: ["github", "git", "repo"]
      category: "development"

3. 构建嵌入数据集（一次性）

import asyncio
from mcp_zero_langgraph import build_dataset_from_config
from langchain_openai import OpenAIEmbeddings

async def build():
    embeddings = OpenAIEmbeddings(model="text-embedding-3-large")
    stats = await build_dataset_from_config(
        config_path="my_servers.yaml",
        output_path="my_dataset.json",
        embedding_client=embeddings
    )
    print(f"Built: {stats['total_servers']} servers, {stats['total_tools']} tools")

asyncio.run(build())

4. 使用智能工具选择功能

import asyncio
from mcp_zero_langgraph import create_tool_selector
from langchain_openai import OpenAIEmbeddings, ChatOpenAI

async def main():
    # Create embeddings
    embeddings = OpenAIEmbeddings(model="text-embedding-3-large")

    # Create tool selector
    selector = await create_tool_selector(
        config_path="my_servers.yaml",
        dataset_path="my_dataset.json",
        embedding_client=embeddings
    )

    # Select tools for a query
    tools = await selector.select_tools(
        user_query="Search for Python repos on GitHub",
        llm=ChatOpenAI(model="gpt-4")
    )

    print(f"Selected {len(tools)} tools:")
    for tool in tools:
        print(f"  - {tool.name}: {tool.description}")

asyncio.run(main())

5. LangGraph 集成

from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

async def run_agent(query: str):
    """Run agent with intelligently selected tools."""
    # Create LLM
    llm = ChatOpenAI(model="gpt-4o")

    # Select tools for the query
    tools = await selector.select_tools(
        user_query=query,
        llm=llm
    )

    # Create ReAct agent with selected tools
    agent = create_react_agent(model=llm, tools=tools)

    # Run agent
    result = await agent.ainvoke({"messages": [("user", query)]})
    return result

# Example usage
result = await run_agent("Search for Python repos on GitHub")
print(result["messages"][-1].content)

高级配置

自定义Top-K值

from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(model="text-embedding-3-large")

selector = await create_tool_selector(
    config_path="my_servers.yaml",
    dataset_path="my_dataset.json",
    embedding_client=embeddings,
    top_servers=10,  # Match top-10 servers (default: 5)
    top_tools=5      # Match top-5 tools (default: 3)
)

获取统计数据

stats = selector.get_stats()
print(stats)
# {
#   "embedding_cache_size": 42,
#   "tool_cache_size": 5,
#   "total_servers": 308,
#   "cached_servers": ["github", "filesystem", "postgres"]
# }

项目结构

mcp-zero-langgraph/
├── mcp_zero_langgraph/            # Main package
│   ├── __init__.py                # Package exports
│   ├── configuration.py           # Configuration management
│   ├── server_registry.py         # Server configuration loader
│   ├── embedding_builder.py       # Dataset builder
│   ├── matcher.py                 # MCP-Zero two-stage matcher
│   └── tool_selector.py           # Main tool selector
├── examples/
│   ├── build_dataset.py           # Build embedding dataset
│   ├── simple_usage.py            # Basic usage example
│   └── langgraph_agent.py         # LangGraph integration example
├── tests/                         # Unit tests
├── mcp_servers.example.yaml       # Example MCP server configuration
├── pyproject.toml                 # Poetry configuration
├── .env.example                   # Environment variables

发展

安装开发依赖项

poetry install --with dev

运行测试

poetry run pytest

格式代码

poetry run black .
poetry run ruff check --fix .

类型检查

poetry run mypy mcp_zero_langgraph

建筑优势

对 langchain-mcp-adapters 无更改

所有的智慧都在于 包装层这意味着：

• 轻松更新 langchain-mcp-adapters，避免冲突
• 清晰的职责分离
• 保持与 langchain-mcp-adapters 更新的兼容性

手动注册表控制

服务器描述位于一个（部分/位置） YAML 配置文件，所以你可以：

• 精选高质量描述
• 添加别名和分类
• 对您的元数据进行版本控制
• 跨团队共享配置

惰性加载（或延迟加载）

工具仅被加载 按需（的）:

• 第一阶段匹配服务器（不加载工具）
• 第二阶段匹配工具（仅从匹配的服务器加载）
• 结果：服务器连接数从308减少到5

故障排除

“未找到数据集”

执行构建步骤：

python examples/build_dataset.py

“未选择工具”

检查以下内容：

1. 你的问题已经足够具体了
2. YAML中的服务器描述与您的域匹配
3. 嵌入式API密钥有效（已检查 .env）

“连接被拒绝”

某些MCP服务器可能需要：

• API密钥（设置在环境变量中）
• 网络访问
• 特定的依赖项（npm 包）

查阅MCP服务器的文档。

诗歌安装问题

如果Poetry安装失败：

# Update Poetry
poetry update

# Clear cache
poetry cache clear . --all

# Reinstall
poetry install

参考文献

• MCP-零纸（或译为“MCP-零碳纸”，具体翻译可能需根据上下文调整） - 两阶段分层检索
• LangChain-MCP适配器 - LangChain与MCP的集成
• 模型上下文协议 - MCP规范

贡献

欢迎投稿！请：

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支（git checkout -b feature/amazing-feature)
3. 提交您的更改（git commit -m 'Add amazing feature')
4. 推送到分支（git push origin feature/amazing-feature)
5. 提交一个拉取请求

许可证

这个项目遵循MIT许可证授权——详见 许可证 详情请见文件。

引用

如果您在研究中使用了此项目，请引用：

@software{mcp_zero_langgraph,
  title = {MCP-Zero LangGraph Integration},
  author = {Nguyen Dang Quang},
  year = {2025},
  url = {hhttps://github.com/QuangNguyen2609/MCP-Zero-Langgraph}
}

致谢

• MCP-Zero的两位作者提出了两阶段检索方法
• LangChain 团队负责 langchain-mcp-adapters