2.4 · 面向智能体的 MCP 服务端（MCP Server for AI Agents）

面向智能体的 MCP 服务端（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/2.4-mcp-server-for-ai-agents

翻译时间：2026-05-27T08:45:16.521Z

翻译模型：deepseek-chat

原文字符数：11653

项目：Cognee (cognee)

---

AI 智能体的 MCP 服务器

相关源文件

以下文件为本维基页面的生成提供了上下文：

• .github/actions/install_cognee/action.yml
• .github/workflows/cli_tests.yml
• .github/workflows/dockerhub-mcp.yml
• .github/workflows/test_mcp.yml
• Dockerfile
• cognee-mcp/Dockerfile
• cognee-mcp/README.md
• cognee-mcp/entrypoint.sh
• cognee-mcp/pyproject.toml
• cognee-mcp/src/__init__.py
• cognee-mcp/src/client.py
• cognee-mcp/src/cognee_client.py
• cognee-mcp/src/server.py
• cognee-mcp/src/test_client.py
• cognee-mcp/tests/test_mcp_server_hardening.py
• cognee-mcp/uv.lock
• cognee/alembic/versions/7c5d4e2f8a91_add_parent_user_id_to_users.py
• cognee/modules/engine/models/__init__.py
• cognee/modules/tools/__init__.py
• cognee/modules/tools/path_safety.py
• cognee/modules/users/authentication/default/default_transport.py
• cognee/modules/users/authentication/get_api_auth_backend.py
• cognee/modules/users/authentication/get_client_auth_backend.py
• cognee/tests/cli_tests/cli_integration_tests/__init__.py
• cognee/tests/cli_tests/cli_integration_tests/test_cli_integration.py
• cognee/tests/cli_tests/cli_unit_tests/__init__.py
• cognee/tests/cli_tests/cli_unit_tests/test_cli_runner.py
• cognee/tests/unit/test_add_parent_user_id_migration.py
• docker-compose.yml
• entrypoint.sh

Cognee MCP 服务器通过模型上下文协议（MCP）暴露了 Cognee 知识引擎的功能，使 Claude Desktop、Cursor 和 VS Code 等 AI 助手能够在工作流中构建和查询知识图谱。该服务器使用 FastMCP 框架实现 cognee-mcp/src/server.py:73，通过可调用的工具将 MCP 客户端桥接到 Cognee 的处理引擎，并支持多种传输和连接模式。

架构总览

该服务器支持两种主要的连接模式：

• 直接模式：直接导入 cognee 库并在本地执行操作 cognee-mcp/src/cognee_client.py:65-68。此模式需要完整安装 Cognee 及其数据库适配器。
• API 模式：作为 HTTP 客户端连接到远程的 Cognee FastAPI 服务器，服务器地址通过 --api-url 参数指定 cognee-mcp/src/cognee_client.py:44-47。

传输选项包括：

• stdio：默认模式，MCP 客户端将服务器作为子进程启动，并通过标准输入/输出管道进行通信 cognee-mcp/src/server.py:988-989。
• SSE：服务器推送事件（Server-Sent Events），在 http://host:port/sse 暴露服务器 cognee-mcp/src/server.py:166-185。
• HTTP：可流式传输的 HTTP 传输方式，在 http://host:port/mcp 暴露服务器 cognee-mcp/src/server.py:187-206。

来源：cognee-mcp/README.md:38-49，cognee-mcp/src/server.py:73-206，cognee-mcp/src/cognee_client.py:1-7

文件结构

MCP 服务器代码库位于 cognee-mcp/ 目录下：

cognee-mcp/
├── src/
│   ├── server.py              # 主入口点、工具定义和传输逻辑
│   ├── cognee_client.py       # 直接模式与 API 模式的抽象层
│   ├── server_utils.py        # 格式化和校验工具函数
│   ├── retrieval_utils.py     # 基于图的检索辅助函数
│   ├── __init__.py            # 包入口点和 main_mcp 运行器
│   ├── strip_vectors.py       # 从响应中移除向量数据的工具函数
│   └── codingagents/          # 开发者规则关联的逻辑
├── pyproject.toml             # 项目元数据和依赖
├── Dockerfile                 # 容器定义
└── entrypoint.sh              # 容器启动编排

代码实体映射

server.py - 核心 MCP 服务器实现

graph TB
    ServerPy["server.py"]

    subgraph "全局状态"
        MCPInstance["mcp = FastMCP('Cognee')<br/>第 73 行"]
        Logger["logger = get_logger()<br/>第 75 行"]
        Client["cognee_client: Optional[CogneeClient]<br/>第 77 行"]
        TaskErrors["_task_errors: dict[str, Deque]<br/>第 82 行"]
    end

    subgraph "传输处理器"
        RunSSE["async def run_sse_with_cors()<br/>第 166-185 行"]
        RunHTTP["async def run_http_with_cors()<br/>第 187-206 行"]
        Security["_configure_transport_security()<br/>第 106-154 行"]
    end

    subgraph "MCP 工具"
        Remember["@mcp.tool()<br/>async def remember()<br/>第 232-343 行"]
        Recall["@mcp.tool()<br/>async def recall()<br/>第 371-536 行"]
        Forget["@mcp.tool()<br/>async def forget()<br/>第 562-650 行"]
        Workspace["@mcp.tool()<br/>async def open_cognee_workspace()<br/>第 824-846 行"]
    end

    subgraph "入口点"
        Main["async def main()<br/>第 885-1011 行"]
    end

    ServerPy --> MCPInstance
    ServerPy --> Client
    ServerPy --> RunSSE
    ServerPy --> RunHTTP
    ServerPy --> Remember
    ServerPy --> Recall
    ServerPy --> Main

cognee_client.py - 后端抽象层

graph TB
    ClientPy["cognee_client.py"]

    subgraph "CogneeClient 类"
        Init["__init__(api_url, api_token)<br/>第 44-68 行"]
        UseAPI["self.use_api: bool<br/>第 47 行"]
        CogneeLib["self.cognee (import cognee)<br/>第 68 行"]
        HTTPClient["self.client = httpx.AsyncClient<br/>第 62 行"]
    end

    subgraph "方法 - 统一接口"
        Add["async def add()<br/>第 107-149 行"]
        Cognify["async def cognify()<br/>第 150-205 行"]
        Search["async def search()<br/>第 207-266 行"]
    end

    ClientPy --> Init
    Init --> UseAPI

    UseAPI -->|False| CogneeLib
    UseAPI -->|True| HTTPClient

    Add -->|直接模式| AddDirect["await self.cognee.add()"]
    Add -->|API 模式| AddAPI["POST /api/v1/add"]

    Cognify -->|直接模式| CogDirect["await self.cognee.cognify()"]
    Cognify -->|API 模式| CogAPI["POST /api/v1/cognify"]

来源：cognee-mcp/src/server.py:73-846，cognee-mcp/src/cognee_client.py:31-266

传输模式

传输模式决定了 MCP 客户端（例如 Claude Desktop）与 Cognee 服务器的通信方式。

传输实现

server.py 中的 main() 函数根据 --transport 参数分发服务器。

传输模式	描述	实现位置
stdio	标准输入/输出管道。本地 IDE 的默认模式。	cognee-mcp/src/server.py:988-989
sse	服务器推送事件。适用于通过 HTTP 进行实时更新。	cognee-mcp/src/server.py:166-185
http	通过 uvicorn 实现的可流式传输的 HTTP 传输方式。	cognee-mcp/src/server.py:187-206

安全说明： 对于 SSE 和 HTTP 模式，_configure_transport_security() 会根据 MCP_ALLOWED_HOSTS 和 MCP_CORS_ALLOW_ORIGINS 环境变量处理 DNS 重新绑定防护和 CORS 设置 cognee-mcp/src/server.py:106-154。

来源：cognee-mcp/src/server.py:106-206，cognee-mcp/src/server.py:988-989

连接模式：直接模式与 API 模式

CogneeClient 类抽象了 Cognee 逻辑是在本地运行还是在远程服务器上运行。

模式初始化

在 cognee_client.py 中，模式通过 api_url 的存在与否来切换：

• 直接模式：self.use_api 为 False。客户端会延迟导入 cognee 库 cognee-mcp/src/cognee_client.py:68。
• API 模式：self.use_api 为 True。客户端会初始化一个超时时间为 300 秒的 httpx.AsyncClient cognee-mcp/src/cognee_client.py:62。

功能支持对比

功能	直接模式支持	API 模式支持
add / cognify	完整支持	通过 /api/v1/add 和 /api/v1/cognify 代理
search	本地搜索引擎	通过 /api/v1/search 代理
prune	支持	不支持（API 中未实现）
cognify_status	本地管线检查	不支持

来源：cognee-mcp/src/cognee_client.py:44-68，cognee-mcp/src/cognee_client.py:107-266

MCP 工具参考

工具是 AI 智能体与 Cognee 交互的主要接口。服务器暴露了一组精简的以记忆为中心的工具 cognee-mcp/src/test_client.py:13-25。

核心记忆工具

• remember：整合了 add 和 cognify 操作。它可以将数据存储在会话缓存中以实现快速检索，也可以触发完整的 cognify 流程以创建永久性的图谱记忆 cognee-mcp/src/server.py:232-343。
• recall：统一的查询工具。支持查询会话缓存、向量搜索和知识图谱搜索类型（例如 GRAPH_COMPLETION）cognee-mcp/src/server.py:371-536。
• forget：删除工具。允许移除特定数据集或清除所有拥有的记忆 cognee-mcp/src/server.py:562-650。

工作区和开发者工具

• visualize_graph_ui：从预构建的 React 包中提供交互式图谱可视化服务 cognee-mcp/src/server.py:787-822。
• open_cognee_workspace：提供用于管理数据集和图谱探索的集成用户界面 cognee-mcp/src/server.py:824-846。
• 开发者规则：诸如 bootstrap_developer_rules 和 add_rules 之类的工具允许智能体将编码标准和架构规则直接持久化到图谱中 cognee-mcp/src/server.py:702-747。

来源：cognee-mcp/src/server.py:232-846，cognee-mcp/src/test_client.py:13-25

部署与配置

Docker 部署

cognee-mcp 服务器可以使用提供的 Dockerfile 进行容器化。它采用多阶段构建，首先构建 React UI 包，然后使用 uv 设置 Python 环境 cognee-mcp/Dockerfile:1-55。

关键环境变量：

• TRANSPORT_MODE：stdio、sse 或 http cognee-mcp/entrypoint.sh:45。
• API_URL：API 模式下远程 Cognee 服务器的地址 cognee-mcp/entrypoint.sh:63。
• EXTRAS：以逗号分隔的 Cognee 附加组件列表（例如 postgres,neo4j），在运行时安装 cognee-mcp/entrypoint.sh:7-40。

IDE 集成

要与 Cursor 或 Claude Desktop 集成，用户通常需要配置 stdio 传输方式。入口点是 cognee-mcp cognee-mcp/pyproject.toml:72。

{
  "mcpServers": {
    "Cognee": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/cognee/cognee-mcp",
        "run", "cognee-mcp"
      ]
    }
  }
}

来源：cognee-mcp/Dockerfile:1-94，cognee-mcp/entrypoint.sh:1-102，cognee-mcp/pyproject.toml:70-73