agentic_huge_data_base / wiki
页面 Cognee · 13.4 MCP 协议参考·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 13.4

13.4 · MCP 协议参考（MCP Protocol Reference）

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节13.4 状态全文译文 模块安装与启动、接口与服务契约、界面与交互、配置治理
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节MCP Protocol Reference 上一章13.3 下一章14
源码线索
  • .github/workflows/dockerhub-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
模块标签
  • 安装与启动
  • 接口与服务契约
  • 界面与交互
  • 配置治理
  • 系统架构

章节正文

MCP 协议参考

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/13.4-mcp-protocol-reference

MCP 协议参考

相关源文件

本章引用的主要源码文件：

  • .github/workflows/dockerhub-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/uv.lock
  • cognee/alembic/versions/7c5d4e2f8a91_add_parent_user_id_to_users.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/unit/test_add_parent_user_id_migration.py
  • docker-compose.yml
  • entrypoint.sh

本文档提供了 Cognee 的模型上下文协议（MCP）服务器实现的技术参考。内容涵盖协议架构、传输模式、工具接口、消息格式以及配置选项。

协议架构总览

Cognee 使用 FastMCP 框架实现了模型上下文协议（MCP）规范 cognee-mcp/src/server.py:73。该服务器充当 MCP 客户端（如 Claude Desktop、Cursor、Cline 等 AI 助手）与 Cognee 知识引擎之间的桥梁，将认知操作暴露为 MCP 工具。

该实现支持两种操作模式，定义在 CogneeClient 抽象层中：

  • 直接模式：服务器直接导入并使用本地 cognee 包执行 Cognee 函数 cognee-mcp/src/cognee_client.py:64-68。
  • API 模式：服务器使用 httpx.AsyncClient 将请求代理到运行中的 Cognee REST API 服务器 cognee-mcp/src/cognee_client.py:58-62。
核心 MCP 组件

标题：MCP 协议架构与数据流

Cognee · 核心 MCP 组件 · 图 1
Cognee · 核心 MCP 组件 · 图 1

来源：cognee-mcp/src/server.py:73-77、cognee-mcp/src/cognee_client.py:31-68、Dockerfile:48-54

传输协议

MCP 服务器支持三种传输模式，通过 --transport 参数或 TRANSPORT_MODE 环境变量选择 cognee-mcp/entrypoint.sh:45-46。

传输模式对比
传输模式使用场景默认端口协议连接模型
stdio本地 CLI 工具、IDE无标准输入/输出双向管道
sseWeb 客户端、实时通信8000HTTP GET + SSE长连接 HTTP
httpWeb 部署8000HTTP POST请求-响应
stdio 传输

标准输入/输出传输是默认模式 cognee-mcp/entrypoint.sh:45。它使用标准管道进行通信，推荐用于本地 IDE 集成，如 Claude Desktop。

SSE 传输

服务器推送事件传输用于实时更新。服务器使用 CORSMiddleware 允许 Web 客户端访问 cognee-mcp/src/server.py:168-175。

服务器初始化：

# cognee-mcp/src/server.py:166-184
async def run_sse_with_cors():
    sse_app = mcp.sse_app()
    sse_app.add_middleware(
        CORSMiddleware,
        allow_origins=_get_cors_origins(),
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )
    ...
    server = uvicorn.Server(config)
    await server.serve()
HTTP 可流式传输

基于 HTTP POST 的无状态请求-响应通信，使用 streamable_http_app() cognee-mcp/src/server.py:189。

来源：cognee-mcp/src/server.py:166-203、cognee-mcp/entrypoint.sh:44-57

MCP 工具接口规范

工具通过 @mcp.tool() 装饰器注册，该装饰器会生成符合 MCP 规范的 JSON 模式 cognee-mcp/src/server.py:18-19。

remember 工具

暴露一个简化的 API 用于存储记忆。它抽象了添加数据和触发认知处理的过程 cognee-mcp/src/server.py:257-263。

工具签名：

# cognee-mcp/src/server.py:257-263
@mcp.tool(name="remember", description="将信息存储到永久记忆中")
async def remember(
    data: str,
    dataset_name: str = "main_dataset",
    is_session_memory: bool = False,
) -> list[types.TextContent]:
召回工具

提供一个统一的接口用于检索存储的知识 cognee-mcp/src/server.py:469-474。

工具签名：

# cognee-mcp/src/server.py:469-474
@mcp.tool(name="recall", description="在记忆中搜索信息")
async def recall(
    query: str,
    search_type: str = "GRAPH_COMPLETION",
    top_k: int = 10,
) -> list[types.TextContent]:

支持的搜索类型： GRAPH_COMPLETION、RAG_COMPLETION、CODE、CHUNKS、SUMMARIES、CYPHER、FEELING_LUCKY cognee-mcp/src/server.py:483-492。

cognify_status 工具

允许客户端监控后台处理任务的进度 cognee-mcp/src/server.py:318-322。

来源：cognee-mcp/src/server.py:257-316、cognee-mcp/src/server.py:469-540

后端抽象层

CogneeClient 类为本地执行和远程 API 代理提供了一个统一的接口。

标题：CogneeClient 执行流程

Cognee · 后端抽象层 · 图 2
Cognee · 后端抽象层 · 图 2

来源：cognee-mcp/src/cognee_client.py:44-68、cognee-mcp/src/cognee_client.py:107-155

模式选择逻辑

如果在初始化时提供了 api_url，客户端会切换到 API 模式，否则默认使用直接模式并导入本地 cognee 包 cognee-mcp/src/cognee_client.py:44-68。

配置与启动

环境变量

服务器配置主要由环境变量驱动，尤其是在 Docker 中运行时 cognee-mcp/entrypoint.sh:45-57。

变量默认值描述
TRANSPORT_MODEstdio传输协议（stdio、sse、http）
HTTP_PORT8000网络传输的绑定端口
API_URLNone远程 Cognee API 服务器的 URL
EXTRASNone运行时安装的可选依赖组
传输安全

Cognee 实现了 DNS 重绑定保护以及 Host/Origin 请求头校验，用于网络传输 cognee-mcp/src/server.py:106-154。

  • DNS 重绑定保护：默认启用，除非 MCP_DISABLE_DNS_REBINDING_PROTECTION 设置为 "true" cognee-mcp/src/server.py:119-126。
  • 允许的主机：可通过 MCP_ALLOWED_HOSTS 环境变量配置 cognee-mcp/src/server.py:128-136。

来源：cognee-mcp/src/server.py:106-154、cognee-mcp/entrypoint.sh:44-57

Docker 部署

MCP 服务器以多阶段 Docker 镜像形式分发 cognee-mcp/Dockerfile:1-13。

镜像入口点

entrypoint.sh 脚本负责环境设置，包括将 API_URL 中的 localhost 转换为 host.docker.internal，以便与宿主机上运行的服务进行通信 cognee-mcp/entrypoint.sh:62-81。

可选依赖： 如果设置了 EXTRAS 环境变量，可以在运行时使用 uv pip install 安装可选依赖组（例如 postgres、neo4j）cognee-mcp/entrypoint.sh:6-40。

来源：cognee-mcp/Dockerfile:1-94、cognee-mcp/entrypoint.sh:1-102