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

导读

本文是 Omi（Friend）开源仓库中 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 Protocol（MCP）服务器，位于 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-omi"，requires-python = ">=3.11.6"，MIT 协议，当前分类为 Beta（Development Status :: 4 - Beta）；
• 运行时依赖：click>=8.1.7、mcp[cli]>=1.0.0、pydantic>=2.0.0、requests>=2.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锁定mcp==2.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是 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", count=True) 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(level=logging_level, stream=sys.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 Inspector：

npx @modelcontextprotocol/inspector

更精确的用法是直接把启动命令作为参数传给 Inspector。例如在仓库根目录（或mcp/目录）下针对本地源码调试：

npx @modelcontextprotocol/inspector uv run mcp-server-omi

Inspector 会打开一个 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、other），Conversation 有 35 个分类（personal、education、health、finance 等），非法分类会被_parse_categories丢弃并记录 warning，非列表输入直接抛ValueError——tests/test_parse_categories.py 记录了这背后的一个真实崩溃回归：原始实现曾把 JSON 字符串直传导致'str' object has no attribute 'value'；
• base URL 可配置：base_url = os.getenv("OMI_API_BASE_URL", "https://api.omi.me/v1/mcp/")，支持自托管后端场景（详见下文"自定义后端地址"）。

四、发布流程：一条命令完成版本、PyPI 与 Docker 三连发

维护文档明确指出：发布只需运行sh release.sh，脚本会自动完成三件事：

1. 在 src/mcp_server_omi/__about__.py 中递增版本号（patch 位 +1）；
2. 发布到 PyPI；
3. 构建并部署 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_BYTECODE=1与UV_LINK_MODE=copy，利用--mount=type=cache与--mount=type=bind先按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.py：HTTP 状态处理与对话搜索的行为验证。

在mcp/目录下运行uv run pytest即可执行全部测试。

六、自定义后端地址：自托管场景的适配

虽然维护文档未展开，但 mcp/README.md 与 server.py 明确支持通过环境变量指向自建后端：

export OMI_API_BASE_URL="https://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/）：

• DSPy：dspy_ex.py
• OpenAI Agents SDK：openai_agents_sdk_ex.py
• LangChain：langchain_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）

维护文档明确列出了当前项目的三个后续方向，贡献者可以此作为切入点：

1. 清理 TODO：检查代码中遗留的 TODO 项并逐步清理；
2. 改进检索能力：让对话检索（conversation retrieval）具备 QA（问答式）排序能力——从 server.py 看，search_memories与search_conversations目前均为基于自然语言查询的语义搜索（/v1/mcp/memories/search、/v1/mcp/conversations/search），返回按相关性排序的结果列表，QA 化意味着向"直接给出答案"演进；
3. 连接认证/密钥处理：将认证与密钥管理进一步体系化（当前实现为每工具可选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