Graphiti项目MCP服务器启动问题分析与解决方案

问题背景

在使用Graphiti项目的MCP服务器时，开发者在Windows 11 WSL2 Ubuntu环境下遇到了启动失败的问题。错误信息显示LLMConfig.__init__()方法收到了一个意外的关键字参数small_model，导致服务器初始化失败。

错误分析

该错误源于Graphiti核心库版本不匹配的问题。具体表现为：

1. 代码中尝试使用small_model参数初始化LLMConfig类
2. 但当前安装的graphiti-core版本(0.10.5)中的LLMConfig类并不支持这个参数
3. 这是典型的API向后不兼容问题，在新版本中该参数已被移除

解决方案

针对此问题，开发者提供了两种可行的解决方案：

方案一：修改代码适配旧版本

可以直接修改graphiti_mcp_server.py文件，删除对small_model参数的调用：

# 修改前
llm_client_config = LLMConfig(api_key=self.api_key, model=self.model, small_model=self.model)

# 修改后
llm_client_config = LLMConfig(api_key=self.api_key, model=self.model)

方案二：升级graphiti-core依赖

更推荐的解决方案是升级graphiti-core到最新版本：

1. 在mcp_server目录下执行：

uv lock --upgrade-package graphiti-core
uv sync

2. 这将确保使用支持最新API的graphiti-core版本

技术原理

该问题的本质是依赖版本管理问题。在软件开发中，当库的API发生变化时：

• 新增参数通常是向后兼容的
• 但移除参数会导致不兼容变化
• 需要确保代码和依赖版本严格匹配

Graphiti项目团队已经在新版本中移除了small_model参数，因此需要同步更新依赖才能正常运行。

最佳实践建议

1. 对于开源项目，建议定期更新依赖以获取最新修复
2. 使用虚拟环境隔离项目依赖
3. 仔细阅读项目的变更日志，了解API变化
4. 优先采用升级依赖的方案而非修改代码，以保持与上游同步

总结

通过分析Graphiti MCP服务器的启动错误，我们了解到这是典型的API版本不匹配问题。开发者可以采用修改代码或升级依赖两种方案解决。在开源项目协作中，保持依赖版本同步是避免此类问题的关键。