MCP Server Omi 维护全指南：从本地开发调试到 PyPI 与 Docker 发布

MCP Server Omi 维护全指南从本地开发调试到 PyPI 与 Docker 发布【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend导读本文是 OmiFriend开源仓库中 mcp/maintain.README.md 的深度展开版面向需要二次开发、本地调试与发布mcp-server-omi的维护者与贡献者。你将掌握基于 uv 的本地开发工作流、MCP Inspector 调试方法、uv run/uvx/python -m三种启动方式的区别、借助 Claude Desktop 做端到端工具验证的技巧以及通过release.sh一键完成版本升级、PyPI 发布与 Docker 镜像部署的完整发布链路。一、模块定位一个轻量 MCP 服务直连主后端 MCP 路由mcp-server-omi是 Omi 项目中的一个 Model Context ProtocolMCP服务器位于 mcp/ 目录。它提供 8 个工具用于读取、搜索、创建、编辑和删除用户的 Memories 与 Conversations让 Claude 等 MCP 客户端能够直接操作 Omi 的记忆与对话数据。从维护视角看最核心的一句架构事实是Tools are wrapping aroundbackend/routers/mcp.pyroutes directly on main backend.即 MCP 层本身不存储数据它是对主后端 backend/routers/mcp.py 中/v1/mcp/*路由的轻量包装。通过检索 backend/routers/mcp.py 可以看到这些路由的真实形态GET /v1/mcp/memories、POST /v1/mcp/memories、DELETE /v1/mcp/memories/{memory_id}、PATCH /v1/mcp/memories/{memory_id}、GET /v1/mcp/memories/search、GET /v1/mcp/conversations、GET /v1/mcp/conversations/search、GET /v1/mcp/conversations/{conversation_id}等统一通过get_uid_from_mcp_api_key依赖完成用户身份解析。这意味着如果你在主后端修改了 MCP 路由的入参或返回结构本 MCP 服务端的调用代码需要同步跟进。二、开发环境理解并善用 uv 工具链mcp-server-omi的工程管理完全基于 uv 定义了工程的全貌项目元数据name mcp-server-omirequires-python 3.11.6MIT 协议当前分类为 BetaDevelopment Status :: 4 - Beta运行时依赖click8.1.7、mcp[cli]1.0.0、pydantic2.0.0、requests2.32.3命令行入口[project.scripts]中mcp-server-omi mcp_server_omi:main这是uv run mcp-server-omi、uvx mcp-server-omi以及容器ENTRYPOINT能直接执行的根本原因开发依赖pyright、ruff、pytest并通过constraint-dependencies锁定mcp2.0.0、pyjwt、starlette、cryptography等测试配置testpaths [tests]测试文件遵循test_*.py命名版本来源[tool.hatch.version]指示版本号读取自 src/mcp_server_omi/__about__.py当前为0.1.9这是发布流程中版本自动递增的锚点。工程目录结构如下mcp/ ├── src/mcp_server_omi/ # 服务端源码server.py、__main__.py、__init__.py、__about__.py ├── tests/ # 单元与生命周期测试 ├── examples/ # DSPy / OpenAI Agents SDK / LangChain 接入示例 ├── Dockerfile # 多阶段镜像构建 ├── pyproject.toml # 工程与发布配置 ├── release.sh # 一键发布脚本 └── uv.lock # 锁定依赖版本三、本地开发与调试三种启动方式怎么选维护文档给出的核心准则是本地开发时用uv run指向本地源码而不是uvx指向已发布的包。两者一字之差指向的天壤之别启动方式指向适用场景uvx mcp-server-omiPyPI 上已发布的包验证线上版本行为uv run mcp-server-omi当前工作区源码本地开发与改动验证python -m mcp_server_omi当前环境安装的本地包不使用 uv 时的替代方案其中uvx是 uv 提供的免安装运行 Python 包工具——它临时拉取并执行包不污染当前环境。而python -m mcp_server_omi之所以可行是因为 src/mcp_server_omi/__main__.py 提供了模块入口内部直接调用from mcp_server_omi import main; main()。3.1 启动参数与日志级别mcp/src/mcp_server_omi/__init__.py 使用 click 定义了main命令支持-v/--verbose计数参数click.option(-v, --verbose, countTrue) def main(verbose: bool) - None: logging_level logging.WARN if verbose 1: logging_level logging.INFO elif verbose 2: logging_level logging.DEBUG logging.basicConfig(levellogging_level, streamsys.stderr) asyncio.run(serve(None))这就是维护文档中uv run mcp-server-omi -v中-v的来源加一个-v看 INFO 级日志加两个-v进入 DEBUG 级日志输出到 stderr便于在 MCP Inspector 或 Claude Desktop 中观察服务行为。3.2 使用 MCP Inspector 进行交互式调试维护文档推荐的调试路径是启动官方 MCP Inspectornpx modelcontextprotocol/inspector更精确的用法是直接把启动命令作为参数传给 Inspector。例如在仓库根目录或mcp/目录下针对本地源码调试npx modelcontextprotocol/inspector uv run mcp-server-omiInspector 会打开一个 Dashboard 页面你可以在其中配置服务器命令本地开发时填command: uv、args: run mcp-server-omi -v、逐个调用工具、查看请求/响应报文。改完代码后无需重启 Inspector 进程只需刷新 Dashboard 页面并重新连接即可加载最新改动——这是文档特别强调的高效迭代技巧。注意如果误用uvx mcp-server-omi你实际测试到的是 PyPI 上已发布的那份代码本地改动不会生效这是最常见的排查误区。3.3 用 Claude Desktop 做更真实的端到端测试Inspector 验证的是协议与参数层面若想验证真实客户端体验可修改 Claude Desktop 的claude_desktop_config.json将服务器指向本地代码mcpServers: { omi: { command: uv, args: [run, mcp-server-omi, -v], env: { OMI_API_KEY: omi_mcp_YOUR_KEY_HERE } } }python -m方式同样可行只需将command换成python、args换成[-m, mcp_server_omi, -v]。修改配置后重启 Claude Desktop即可在工具列表中看到该服务器暴露的 8 个工具。这一测试路径的价值在于它走的是完整 MCP 初始化握手initialize → list_tools → call_tool能暴露 Inspector 中不易发现的手感问题如工具描述不清、参数必填性错误、日志刷屏等。关于 MCP 客户端与服务器交互的通用规范可参考 MCP 官方的 examples 章节详见 mcp/README.md 中引用的 modelcontextprotocol.io。3.4 工具层实现与安全细节所有工具的参数模型、执行逻辑集中在 mcp/src/mcp_server_omi/server.py其中几个维护者必须知道的实现细节统一的 API Key 参数每个工具都带api_key字段可选未传时回退读取OMI_API_KEY环境变量见_execute_tool中arguments.get(api_key) or os.getenv(OMI_API_KEY)缺失则抛ValueError日志脱敏_execute_tool记录参数时会将api_key替换为***{k: (v if k ! api_key else ***)}防止密钥泄漏进日志——tests/test_server_lifecycle.py 中有专门的回归测试test_execute_tool_redacts_api_key_in_logs断言密钥不会出现在日志中错误响应不泄露敏感信息_response_json对失败的 HTTP 请求统一抛出Omi API request failed (HTTP {status})刻意不暴露查询字符串与响应体分类参数严格枚举Memory 有 9 个分类core、hobbies、lifestyle、interests、habits、work、skills、learnings、otherConversation 有 35 个分类personal、education、health、finance 等非法分类会被_parse_categories丢弃并记录 warning非列表输入直接抛ValueError——tests/test_parse_categories.py 记录了这背后的一个真实崩溃回归原始实现曾把 JSON 字符串直传导致str object has no attribute valuebase URL 可配置base_url os.getenv(OMI_API_BASE_URL, https://api.omi.me/v1/mcp/)支持自托管后端场景详见下文自定义后端地址。四、发布流程一条命令完成版本、PyPI 与 Docker 三连发维护文档明确指出发布只需运行sh release.sh脚本会自动完成三件事在 src/mcp_server_omi/__about__.py 中递增版本号patch 位 1发布到 PyPI构建并部署 Docker 镜像。结合 mcp/release.sh 的源码可以还原出完整的发布机制# 1. 从 __about__.py 读取当前版本并递增 patch 位 current_version$(grep -o .* src/mcp_server_omi/__about__.py | tr -d ) IFS. read -r major minor patch $current_version new_patch$((patch 1)) new_version$major.$minor.$new_patch sed -i s/__version__ \.*\/__version__ \$new_version\/ src/mcp_server_omi/__about__.py # 2. uv 构建与发布默认被注释可按需开启 # uv sync # uv build # uv publish # 3. Docker 登录、构建与双 tag 推送 echo $DOCKER_ACCESS_TOKEN | docker login -u omiai --password-stdin docker build -t omiai/mcp-server . docker push omiai/mcp-server:$new_version docker push omiai/mcp-server:latest发布时需要留意的几点版本号锚点pyproject.toml中版本是动态的dynamic [version]由 hatchling 从__about__.py读取所以脚本只需改这一个文件镜像命名Docker 镜像发布到omiai/mcp-server仓库维护文档也注明 Dockerfile 归属于 omiai/mcp-server并同时推送:latest与:新版本号两个 tag凭证DOCKER_ACCESS_TOKEN环境变量用于免交互登录 Docker Hub前置条件本地需安装 uv、docker且 PyPI 与 Docker Hub 凭证就绪。4.1 Dockerfile 的多阶段构建逻辑mcp/Dockerfile 采用两阶段构建理解它对排查发布问题很有帮助阶段一uv 镜像基于ghcr.io/astral-sh/uv:python3.12-bookworm-slim开启UV_COMPILE_BYTECODE1与UV_LINK_MODEcopy利用--mounttypecache与--mounttypebind先按uv.lock冻结安装依赖uv sync --frozen --no-install-project --no-dev --no-editable再拷贝源码安装项目本体——依赖层与源码层分离最大化层缓存阶段二运行时镜像基于python:3.12-slim-bookworm安装 git从阶段一复制 uv 本地目录与.venv将/app/.venv/bin前置到PATH最终ENTRYPOINT [mcp-server-omi]直接调用控制台脚本。五、测试保障发布前的质量闸门仓库 mcp/tests/ 下的测试直接守护了维护文档所描述的改代码→刷新→再测迭代链路发布前应确保全部通过tests/test_server.py针对get_memories、get_conversations核心函数的参数化验证limit 截断、categories 过滤等tests/test_parse_categories.py分类解析的回归测试合法字符串转枚举、空列表、非法分类丢弃并告警、非列表抛错、返回元素必须具备.value属性tests/test_server_lifecycle.py模拟 MCP 客户端会话验证list_tools返回 8 个工具、create_server可正常构造初始化选项、日志密钥脱敏以及旧版 MCP 1.x 初始化路径list_tools/call_tool装饰器风格的兼容性tests/test_http_status.py、tests/test_search_conversations.pyHTTP 状态处理与对话搜索的行为验证。在mcp/目录下运行uv run pytest即可执行全部测试。六、自定义后端地址自托管场景的适配虽然维护文档未展开但 mcp/README.md 与 server.py 明确支持通过环境变量指向自建后端export OMI_API_BASE_URLhttps://your-backend-url.com默认值为https://api.omi.me/v1/mcp/。若OMI_API_BASE_URL为空服务器启动时会直接抛异常raise Exception(Base URL not found)因此自托管用户务必显式配置。该变量同样适用于 Docker 运行方式docker run --rm -i -e OMI_API_KEY... -e OMI_API_BASE_URL... omiai/mcp-server。七、客户端接入示例与排查思路对于想基于 MCP 做二次集成的维护者mcp/examples/README.md 提供了三种框架的参考实现位于 mcp/examples/DSPydspy_ex.pyOpenAI Agents SDKopenai_agents_sdk_ex.pyLangChainlangchain_ex.py调试阶段建议配合日志文件排查客户端侧问题以下为 MCP 生态通用路径作为运维参考# macOS跟随 Claude Desktop 的 MCP 服务器日志 tail -n 20 -f ~/Library/Logs/Claude/mcp-server-omi.log # Windows PowerShell Get-Content $env:APPDATA\Claude\logs\mcp-server-omi.log -Tail 20 -Wait常见排查顺序先确认 API Key 有效omi_mcp_...前缀由 Omi 应用生成再确认启动方式指向正确本地开发用uv run而非uvx最后用-v提升日志级别观察 stderr 输出。八、后续路线Next Steps维护文档明确列出了当前项目的三个后续方向贡献者可以此作为切入点清理 TODO检查代码中遗留的 TODO 项并逐步清理改进检索能力让对话检索conversation retrieval具备 QA问答式排序能力——从 server.py 看search_memories与search_conversations目前均为基于自然语言查询的语义搜索/v1/mcp/memories/search、/v1/mcp/conversations/search返回按相关性排序的结果列表QA 化意味着向直接给出答案演进连接认证/密钥处理将认证与密钥管理进一步体系化当前实现为每工具可选api_key参数 OMI_API_KEY环境变量回退托管端点则走 OAuth 通道本地 stdio 包走 manual-key 路径详见 mcp/README.md 的 Configuration 章节。结语mcp-server-omi是一个小而精的 MCP 服务其维护要点可以浓缩为三条开发用uv run指本地、调试靠 Inspector 的刷新重连、发布走release.sh一键三连。无论你是想为它贡献新工具、改进检索质量还是接入自己的 MCP 客户端理解工具包装主后端路由这一架构本质都能让你在改代码时精准定位前后端两侧的对应关系避免本地改了但测的是线上包之类的经典陷阱。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考