agentic_huge_data_base / wiki
页面 Graphiti · 8.1 面向智能体的 MCP 服务端·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 8.1

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

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节8.1 状态全文译文 模块模型调用与提供方适配、界面与交互、配置治理、图谱与关系
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节MCP Server for AI Agents 上一章8 下一章8.2
源码线索
  • mcp_server/.env.example
  • mcp_server/README.md
  • mcp_server/config/config-docker-falkordb-combined.yaml
  • mcp_server/config/config-docker-falkordb.yaml
  • mcp_server/config/config-docker-neo4j.yaml
  • mcp_server/config/config.yaml
  • mcp_server/pyproject.toml
  • mcp_server/src/config/schema.py
  • mcp_server/src/graphiti_mcp_server.py
  • mcp_server/src/models/response_types.py
模块标签
  • 模型调用与提供方适配
  • 界面与交互
  • 配置治理
  • 图谱与关系
  • 系统架构

章节正文

面向智能体的 MCP 服务端

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/8.1-mcp-server-for-ai-agents

AI 智能体的 MCP 服务器

相关源文件

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

  • mcp_server/.env.example
  • mcp_server/README.md
  • mcp_server/config/config-docker-falkordb-combined.yaml
  • mcp_server/config/config-docker-falkordb.yaml
  • mcp_server/config/config-docker-neo4j.yaml
  • mcp_server/config/config.yaml
  • mcp_server/pyproject.toml
  • mcp_server/src/config/schema.py
  • mcp_server/src/graphiti_mcp_server.py
  • mcp_server/src/models/response_types.py
  • mcp_server/uv.lock
  • server/pyproject.toml
  • server/uv.lock

MCP（模型上下文协议）服务器通过标准化的工具接口，将 Graphiti 的时序知识图谱能力暴露给 AI 助手。它实现为一个 FastAPI 应用程序，提供了一套 MCP 工具，用于事件入库、实体搜索和图操作。

本文档涵盖了服务器实现、工具处理器、传输协议和运行时配置。关于底层 Graphiti 操作，请参阅 Graphiti 核心客户端。关于 Docker 部署，请参阅 Docker 和容器部署。

目的与范围

MCP 服务器通过以下方式将 AI 助手与 Graphiti 知识图谱操作连接起来：

  • MCP 工具处理器：实现为异步函数，包括 add_episode、search_nodes、search_facts、get_entity_edge、delete_entity_edge、get_episodes、delete_episode、clear_graph 和 get_status。
  • 双传输支持：HTTP（默认，FastAPI 运行在 /mcp/）和 stdio（进程标准输入/输出）。
  • 配置层级：YAML 文件 → .env 文件 → CLI 参数。
  • 基于队列的处理：通过 SEMAPHORE_LIMIT 配置并发限制，实现异步事件入库。

服务器实例化一个 Graphiti 客户端，并将操作委托给核心方法，如 graphiti.add_episode()、graphiti.search() 和 graphiti.get_entity_edge()。

来源：mcp_server/README.md:10-29, mcp_server/src/models/response_types.py:1-44

架构总览

系统组件与代码结构

MCP 服务器组件映射

Graphiti · 系统组件与代码结构 · 图 1
Graphiti · 系统组件与代码结构 · 图 1

代码组织

MCP 服务器实现使用了几个关键文件：

  • mcp_server/src/config/schema.py:76-218：使用 Pydantic 定义了 ServerConfig、LLMConfig、EmbedderConfig 和 DatabaseConfig。
  • mcp_server/src/config/schema.py:16-74：YamlSettingsSource 实现了 YAML 配置的递归环境变量展开（例如 ${VAR:default}）。
  • mcp_server/config/config.yaml:1-111：服务器的默认配置，包括大语言模型（LLM）、数据库提供者和实体类型。
  • mcp_server/src/services/factories.py:97-207：LLMClientFactory 根据配置实例化特定的客户端，如 OpenAIClient、AnthropicClient 或 AzureOpenAILLMClient。

来源：mcp_server/src/config/schema.py, mcp_server/config/config.yaml, mcp_server/src/services/factories.py

传输机制

MCP 服务器支持两种传输协议：

传输方式配置使用场景
HTTP（默认）server.transport: "http"Cursor、VS Code 和远程客户端。
stdioserver.transport: "stdio"Claude Desktop 和基于本地进程的工具。
HTTP 传输实现

HTTP 传输是大多数 IDE 集成的推荐模式。它运行一个 FastAPI 服务器，监听指定的主机和端口（默认 0.0.0.0:8000）。MCP 端点位于 /mcp/。

来源：mcp_server/config/config.yaml:8-11, mcp_server/src/config/schema.py:76-85, mcp_server/README.md:27-27

stdio 传输实现

stdio 传输是 Claude Desktop 等通过进程管道通信的客户端所必需的。在这种模式下，服务器通过标准输入和输出进行通信。可以在客户端的 JSON 配置中使用 command 和 args 字段进行配置。

来源：mcp_server/README.md:44-54

可用的 MCP 工具

MCP 服务器暴露了多个工具，供 AI 智能体用于与知识图谱交互。

工具分类
工具参数描述
add_episodename、episode_body、source、reference_time将新数据入库到图谱中。
search_nodesquery、num_results、group_id对实体执行语义搜索。
search_factsquery、num_results、group_id对关系（边）执行语义搜索。
get_entity_edgeedge_uuid检索特定关系的详细信息。
clear_graphgroup_id删除所有数据并重建索引。
get_status-返回服务器和图谱的状态。

来源：mcp_server/README.md:14-29, mcp_server/src/models/response_types.py:1-44

事件入库流程（基于队列）

为了处理基于大语言模型（LLM）提取的高延迟，同时不阻塞 MCP 客户端，服务器使用了内部队列和工作线程模式。

Graphiti · 事件入库流程（基于队列） · 图 2
Graphiti · 事件入库流程（基于队列） · 图 2

来源：mcp_server/README.md:28-29, mcp_server/.env.example:20-32

配置系统

配置模式与 YAML 支持

服务器使用 pydantic-settings 管理配置。它支持在 YAML 文件中进行递归环境变量展开。

关键配置类 mcp_server/src/config/schema.py：

  • ServerConfig：传输方式、主机和端口 mcp_server/src/config/schema.py:76-85。
  • LLMConfig：提供者（OpenAI、Anthropic、Gemini、Groq、Azure）、模型和最大 Token 数 mcp_server/src/config/schema.py:146-156。
  • EmbedderConfig：提供者（OpenAI、Azure、Gemini、Voyage）和模型维度 mcp_server/src/config/schema.py:167-174。
  • DatabaseConfig：提供者（FalkorDB、Neo4j）和连接详情 mcp_server/src/config/schema.py:201-206。
  • GraphitiAppConfig：Graphiti 特定的设置，如 group_id 和默认的 entity_types mcp_server/src/config/schema.py:215-218。
YAML 环境变量展开

YamlSettingsSource 类处理 config.yaml 中的 ${VAR:default} 语法。它将布尔型字符串（true、1、yes）转换为实际的 Python 布尔值，并处理可选字段的空字符串 mcp_server/src/config/schema.py:23-58。

来源：mcp_server/src/config/schema.py, mcp_server/config/config.yaml

大语言模型（LLM）与提供者支持

MCP 服务器利用 LLMClientFactory 和 EmbedderClientFactory 来支持广泛的提供者。

Azure OpenAI 集成

Azure OpenAI 通过 AzureOpenAIProviderConfig 类得到支持 mcp_server/src/config/schema.py:95-103。它对推理模型（例如 o1、o3）使用 responses.parse API 进行专门处理，同时对 gpt-4o 等其他模型使用标准的聊天补全解析。

Azure 推理支持

# graphiti_core/llm_client/azure_openai_client.py:164-167
def _supports_reasoning_features(model: str) -> bool:
    """当 Azure 模型支持推理/详细程度选项时返回 True。"""
    reasoning_prefixes = ('o1', 'o3', 'gpt-5')
    return model.startswith(reasoning_prefixes)

来源：mcp_server/src/config/schema.py:95-103, mcp_server/src/services/factories.py:141-190

数据库集成

MCP 服务器支持多个后端，通过配置的 database 部分进行配置。

提供者默认 URI配置部分
FalkorDBredis://localhost:6379database.providers.falkordb
Neo4jbolt://localhost:7687database.providers.neo4j

来源：mcp_server/config/config.yaml:73-87, mcp_server/src/config/schema.py:176-199

并发与速率限制

服务器使用 SEMAPHORE_LIMIT 管理大语言模型（LLM）的速率限制。这个环境变量控制工作线程同时处理的事件数量。

  • 默认值：10（适用于 OpenAI Tier 3）。
  • 调优建议：
    • OpenAI Tier 1：1-2
    • Anthropic 默认值：5-8
    • 本地 Ollama：1-5

来源：mcp_server/.env.example:20-32, mcp_server/config/config.yaml:4-6

与 AI 助手的集成

Cursor 和 VS 代码

这些 IDE 通常使用 HTTP 传输。将 MCP 客户端指向 http://localhost:8000/mcp/。如果通过 Docker 运行，请确保端口 8000 已正确映射。

Claude 桌面

Claude Desktop 需要使用 stdio 传输。配置涉及将服务器添加到 Claude Desktop 配置文件中，包含运行服务器的命令（例如 uv run），并将 server.transport 设置为 stdio。

来源：mcp_server/README.md:44-76