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

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

项目Cognee 章节2.4 状态全文译文模块安装与启动、认证、权限与安全、智能体运行时、接口与服务契约

项目要点页2.5 参考项目项目章节目录Cognee DeepWiki 原始章节MCP Server for AI Agents 上一章2.3 下一章2.5

源码线索

.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

模块标签

安装与启动
认证、权限与安全
智能体运行时
接口与服务契约
界面与交互

章节正文

面向智能体的 MCP 服务端

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

AI 智能体的 MCP 服务器

架构总览

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

直接模式：直接导入 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 服务器实现

Cognee · 代码实体映射 · 图 1

cognee_client.py - 后端抽象层

Cognee · 代码实体映射 · 图 2

来源：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