基于 MCP 连接 Omi 数据DSPy、OpenAI Agents SDK 与 LangChain 实战示例解析【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend本篇技术指南聚焦 Friend 仓库中 mcp/examples 目录下的官方示例应用讲解如何通过 Model Context ProtocolMCP以自然语言方式访问、检索与操作 Omi 智能眼镜采集到的 Memories记忆与 Conversations对话数据。你将掌握环境搭建、三种主流 Agent 框架DSPy、OpenAI Agents SDK、LangChain的接入写法以及基于 Streamlit 的交互式聊天界面的运行方式并深入了解底层mcp-server-omi服务器暴露的 8 个 MCP 工具及其后端实现原理。背景为什么用 MCP 连接 Omi 数据Omi 是看得见屏幕、听得见对话、告诉你该做什么的 AI 设备其核心资产是持续沉淀的个人记忆Memories和会话记录Conversations。要让任意 LLM Agent 以统一、标准化的方式消费这些数据Friend 仓库采用了 MCPModel Context Protocol作为连接协议并在 mcp 目录下提供了完整的服务端与示例客户端服务端mcp/src/mcp_server_omi/server.py 实现了一个本地 stdio 模式的 MCP 服务器将 Omi 后端能力封装为一个个可被 LLM 直接调用的工具Tool客户端示例mcp/examples 提供了三个框架示例与一个 Streamlit 交互应用演示不同 Agent 编排方式下如何挂载这些 MCP 工具。从 mcp/maintain.README.md 可以确认这些 MCP 工具并非独立实现而是直接包装 backend/routers/mcp.py 路由——即与 App 端、Web 端共用同一套后端数据接口保证了数据访问语义的一致性。前置条件与环境准备示例 README 明确了运行示例所需的四项前置条件结合仓库实际情况整理如下前置条件说明获取方式Python 3.8所有示例脚本均为 Python官方 Python 安装包或系统包管理器uvx命令行工具MCP 服务器通过uvx mcp-server-omi方式拉起无需预先 pip 安装服务端pip install uvx或安装 uv 工具链后自带uvxOpenAI API Key示例默认使用 OpenAI 的o4-mini/o3等推理模型作为 Agent 的 LLM 后端OpenAI 开发者平台Omi UID用户在 Omi 体系中的唯一标识用于定位其 Memories 与 Conversations 数据Omi 应用内获取需要特别强调的是uvx的地位所有示例都以uvx mcp-server-omi作为 MCP 服务器的启动方式uvx会在运行时自动从 PyPI 下载并执行已发布的mcp-server-omi包当前仓库版本为0.1.9见 mcp/src/mcp_server_omi/about.py因此客户端侧无需手动安装该包。安装依赖按原文档步骤执行python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate pip install -r requirements.txtrequirements.txt 是一份经过uv pip compile解析的完整锁定清单核心依赖包括MCP 协议层mcp1.28.1、openai-agents0.17.3三个框架示例dspy3.2.1、langchain-mcp-adapters0.2.2、langchain-openai1.2.1、langgraph1.2.0、langgraph-prebuilt1.1.0交互应用streamlit1.57.0环境配置与底层python-dotenv、openai2.37.0、httpx、pydantic2.13.4等。配置环境变量在项目根目录创建.env文件写入两项核心变量OPENAI_API_KEYyour_openai_api_key OMI_UIDyour_omi_uid各示例脚本顶部均调用load_dotenv()例如 dspy_ex.py、openai_agents_sdk_ex.py启动时会自动加载该文件。值得注意的是原文档中的.env只覆盖了 LLM 调用与 UID 定位。若要让 MCP 服务器实际访问数据还需要通过OMI_API_KEY提供 MCP 专用 API 密钥见下文API 密钥机制一节该变量同样可写入.env或通过环境变量注入。另外server.py 读取OMI_API_BASE_URL作为后端地址自托管后端时可用它覆盖默认的https://api.omi.me/v1/mcp/。三个框架示例同一条 MCP 数据管道三种 Agent 编排原文档给出了三个示例脚本的启动命令其核心价值在于展示同一份 Omi 数据、同一套 MCP 工具在不同 Agent 框架中的接入姿势。三个示例运行的是同一个演示任务——查看我的 Memories了解我是什么样的人然后检索最近 5 次对话并总结python dspy_ex.py python openai_agents_sdk_ex.py python langchain_ex.pyDSPy 示例以 Signature 声明式定义 Agent 任务dspy_ex.py 展示了 DSPy 风格的接入方式其特点是用Signature签名声明输入输出用ReAct编排工具调用建立 MCP 会话通过mcp.ClientSession与stdio_client建立 stdio 连接StdioServerParameters(commanduvx, args[mcp-server-omi])指定服务器启动方式初始化并列出工具await session.initialize()完成 MCP 握手await session.list_tools()获取服务器声明的工具清单工具转换用dspy.Tool.from_mcp_tool(session, tool)把 MCP 工具逐一包装为 DSPy 可调用的工具对象构建 Agent定义DSPyOmiAgent签名输入user_request、user_uid输出response以dspy.ReAct(DSPyOmiAgent, toolsdspy_tools)构建 ReAct Agent配置语言模型dspy.configure(lmdspy.LM(openai/o4-mini, temperature1, max_tokens24000))采用 OpenAI o4-mini 推理模型max_tokens24000为长文本总结预留充足输出空间。server_params StdioServerParameters(commanduvx, args[mcp-server-omi], envNone) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() dspy_tools [dspy.Tool.from_mcp_tool(session, tool) for tool in tools.tools] react dspy.ReAct(DSPyOmiAgent, toolsdspy_tools) result await react.acall(user_requestuser_request, user_uidos.getenv(OMI_UID)) print(result.response)该示例演示了 DSPy 的核心思想无需手写复杂的 prompt 与工具调用循环任务语义由 Signature 声明工具选择与调用顺序由 ReAct 自动推理完成。OpenAI Agents SDK 示例MCP Server 作为一等公民挂载openai_agents_sdk_ex.py 展示了 OpenAI Agents SDK 的接入方式这也是Streamlit 应用底层使用的同一套 API创建 MCP 服务器句柄MCPServerStdio(cache_tools_listFalse, params{command: uvx, args: [mcp-server-omi]})cache_tools_listFalse意味着每次会话都重新拉取工具列表避免工具更新后缓存不刷新挂载到 AgentAgent(nameOmi Agent, instructionsf...user UID is {uid}, mcp_servers[mcp_server], modelo4-mini)MCP 服务器通过mcp_servers参数直接注入工具无需手动枚举启用推理ModelSettings(reasoningReasoning(efforthigh, generate_summaryauto))开启高强度的推理模式执行Runner.run(starting_agentagent, inputmessage)驱动 Agent 完成任务。async with MCPServerStdio( cache_tools_listFalse, params{command: uvx, args: [mcp-server-omi]}, ) as server: agent Agent( nameOmi Agent, instructionsfYou are a helpful assistant that answers questions based on the users OMI data, the user UID is {uid}., mcp_servers[server], modelo4-mini, model_settingsModelSettings(reasoningReasoning(efforthigh, generate_summaryauto)), ) result await Runner.run(starting_agentagent, inputmessage) print(result.final_output)脚本启动时会校验uvx是否可用if not shutil.which(uvx): raise RuntimeError(...)这是原文档 Troubleshooting 中uvx 未安装错误的直接来源。LangChain / LangGraph 示例MultiServerMCPClient 桥接langchain_ex.py 展示了 LangChain 生态LangGraph langchain-mcp-adapters的接入方式模型初始化ChatOpenAI(modelo4-mini-2025-04-16)使用指定版本的 o4-mini多服务器客户端MultiServerMCPClient({omi: {command: uvx, args: [mcp-server-omi, -v], transport: stdio}})以字典形式声明 MCP 服务器该结构天然支持同时挂载多个 MCP 服务器工具获取client.get_tools()将 MCP 工具桥接为 LangChain 工具Agent 构建create_react_agent(model, client.get_tools())基于 LangGraph Prebuilt 快速构建 ReAct Agentawait agent.ainvoke(...)执行。async with MultiServerMCPClient( {omi: {command: uvx, args: [mcp-server-omi, -v], transport: stdio}} ) as client: agent create_react_agent(model, client.get_tools()) response await agent.ainvoke({messages: prompt}) print(response[messages][-1].content)注意此处命令行参数多了-vverbose 模式与 Streamlit 应用及 maintain.README.md 中推荐的调试启动方式一致便于在 Agent 运行过程中观察 MCP 服务器日志。三种接入方式的对比维度DSPyOpenAI Agents SDKLangChain / LangGraph任务定义Signature 声明 ReAct 编排Agent instructions mcp_serverscreate_react_agent 工具列表MCP 客户端mcp.ClientSessionstdio_clientMCPServerStdio一等公民MultiServerMCPClient工具接入dspy.Tool.from_mcp_tool逐个转换mcp_servers参数自动注入client.get_tools()批量桥接代表模型openai/o4-minio4-minio4-mini-2025-04-16适用场景希望用声明式 Signatures 约束任务追求 MCP 原生集成与官方 Agent 运行时已深度使用 LangChain/LangGraph 生态Streamlit 交互式聊天应用零代码接入 Omi 数据app.py 是示例集的主应用——一个基于 Streamlit 的聊天界面运行命令streamlit run app.py启动后浏览器会自动打开应用。使用前需在侧边栏 Settings中输入 OMI UID否则界面会提示 Please enter your OMI UID in the sidebar settings to start chatting 并停止。从源码看该应用有几个值得关注的设计细节前置校验启动时通过shutil.which(uvx)检查uvx是否在 PATH 中缺失则直接st.error(...)并st.stop()这与 openai_agents_sdk_ex.py 的校验逻辑互为印证事件循环管理run_async_task函数为每个请求新建独立事件循环asyncio.new_event_loop()避免 Streamlit 环境中已有事件循环导致的冲突这是 Streamlit asyncio 集成的经典实践Agent 配置底层与 OpenAI Agents SDK 示例同构——MCPServerStdio(cache_tools_listFalse, params{command: uvx, args: [mcp-server-omi, -v]})Agent 使用modelo3源码中注释保留了litellm/anthropic/claude-3-7-sonnet-20250219作为可选模型并配置ModelSettings(reasoningReasoning(efforthigh))多轮对话将完整会话历史含最新用户消息传给Runner.runAgent 基于 Omi 数据连续作答每次响应的new_items推理过程与工具调用详情被记录可在 View Reasoning/Tool Calls 折叠面板中查看追踪能力with trace(workflow_nameStramlit Omi MCP Example):为整个执行流程打上可观测性标记。async with MCPServerStdio( cache_tools_listFalse, params{command: uvx, args: [mcp-server-omi, -v]}, ) as server: omi_agent Agent( nameOmi Agent, instructionsfYou are a helpful assistant that answers questions based on my Omi data, my UID is {uid}. ..., mcp_servers[server], modelo3, model_settingsModelSettings(reasoningReasoning(efforthigh)), ) with trace(workflow_nameStramlit Omi MCP Example): run_output await Runner.run(starting_agentomi_agent, inputagent_input_messages)底层工具集mcp-server-omi 暴露的 8 个 MCP 工具三个示例和 Streamlit 应用共享同一个 MCP 服务器。要理解 Agent 能做什么需要看服务器实际声明的工具集。根据 server.py 的_get_tools()实现服务器共暴露8 个工具覆盖 Memories 与 Conversations 两类数据的读、搜、写操作工具名类别核心参数默认值底层接口get_memories记忆limit(100)、offset(0)、categoriesGET /memoriessearch_memories记忆query(必填)、limit(10)GET /memories/searchcreate_memory记忆content(必填)、category(必填)POST /memoriesedit_memory记忆memory_id(必填)、content(必填)PATCH /memories/{id}delete_memory记忆memory_id(必填)DELETE /memories/{id}get_conversations对话start_date、end_date、categories、limit(100)、offset(0)GET /conversationsget_conversation_by_id对话conversation_id(必填)GET /conversations/{id}search_conversations对话query(必填)、limit(10)、start_date、end_dateGET /conversations/search几个值得展开的实现细节分类枚举记忆分类MemoryCategory包含core、hobbies、lifestyle、interests、habits、work、skills、learnings、other对话分类ConversationCategory多达 33 项覆盖personal、finance、health、sports、politics、technology等领域。分类过滤通过逗号拼接多值实现例如params[categories] ,.join([c.value for c in categories])日期语义get_conversations对end_date做了当日 23:59:59的收尾处理——(datetime.strptime(end_date, %Y-%m-%d) timedelta(days1) - timedelta(seconds1)).isoformat()确保结束日期整天都被包含鉴权方式每个工具都带可选api_key参数_API_KEY_FIELD调用时优先取参数值否则回退到OMI_API_KEY环境变量两者皆无则抛出ValueError。日志输出时 api_key 会被掩码为***见_execute_tool的log_args避免密钥泄漏错误处理_response_json统一调用raise_for_status()HTTP 失败时抛出不含查询串与响应体的安全错误信息结果序列化所有工具返回TextContent(typetext, textjson.dumps(result, indent2))即返回格式化的 JSON 文本方便 LLM 直接阅读与再加工。这些工具在仓库测试中也有直接覆盖test_server.py 验证了get_memories的 limit 截断与分类过滤、get_conversations的include_discarded与 limit 行为test_parse_categories.py、test_search_conversations.py、test_http_status.py 则分别覆盖分类解析、对话搜索与 HTTP 状态处理。API 密钥机制与后端实现MCP 服务器的鉴权与后端路由是理解整个链路的关键。根据 mcp/README.md在 Omi macOS 应用中于 Use omi memory anywhere 下选择基于 key 的目标展开 Manual installation 复制生成的密钥跨平台应用中则在Settings Developer Settings的MCP Server区块的API Keys列表中创建生成的完整omi_mcp_...值即为OMI_API_KEY密钥可随每次工具调用传入也可省略以使用OMI_API_KEY环境变量本地 stdio 包采用手动密钥路径托管的 Omi MCP 端点对注册云客户端额外支持 OAuth。在 backend/routers/mcp.py765 行中可以看到这些工具对应的后端能力依赖注入get_uid_from_mcp_api_key完成 API Key 到用户 UID 的解析工具数据分别来自database.memories、database.conversations、database.vector_db向量语义搜索等模块对话列表还会经redact_conversations_for_list、populate_speaker_names等工具做脱敏与说话人姓名填充。也就是说MCP 工具层只是协议适配层真正的数据读写、语义搜索与隐私处理全部复用主后端既有能力这保证了本地 MCP 客户端与 App/Web 端看到的数据口径一致。调试与故障排查常见错误与解决办法原文档的 Troubleshooting 部分可直接作为排查清单uvx缺失错误报错信息通常为RuntimeError: uvx is not installed. Please install it with pip install uvx见 openai_agents_sdk_ex.py或在 Streamlit 应用中显示 Critical Error:uvxcommand not found。解决方式pip install uvx并确认其已加入 PATH环境变量未设置检查.env中OPENAI_API_KEY与OMI_UID是否填写正确以及文件是否位于启动命令的工作目录下依赖未安装重新执行pip install -r requirements.txtMCP 服务器鉴权失败确认OMI_API_KEYomi_mcp_...密钥已配置——这是原文档.env清单之外但实际运行必需的变量自托管后端地址不对通过OMI_API_BASE_URL指定后端地址见下文。使用 MCP Inspector 调试开发调试时可借助 MCP 官方 Inspector 工具直观查看工具声明与调用结果# 针对通过 uvx 发布的服务器 npx modelcontextprotocol/inspector uvx mcp-server-omi # 本地开发uv run 指向本地源码 npx modelcontextprotocol/inspector uv run mcp-server-omimaintain.README.md 还给出两条本地开发提示在 Inspector 中测试时启动命令可设为uvrun mcp-server-omi -v如果改用uvxmcp-server-omi则会指向已发布到 PyPI 的包而非本地改动uv run之外也可用python -m mcp_server_omi直接以模块方式启动。查看 Claude Desktop 日志将 MCP 服务器接入 Claude Desktop 后配置方法见 mcp/README.md 的 uvx / docker / pip 三种方案可通过以下命令跟踪其日志# macOS 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自托管后端如果自行部署 Omi 后端可覆盖 MCP 服务器的 API 基地址export OMI_API_BASE_URLhttps://your-backend-url.com该变量在 server.py 启动时读取默认值为https://api.omi.me/v1/mcp/为空时会抛出Exception(Base URL not found)。从示例到自研应用三步接入路径综合以上内容将 Omi 数据接入自有 Agent 应用只需三步准备运行环境安装 Python 3.8 与uvx配置OPENAI_API_KEY、OMI_UID、OMI_API_KEY三个关键变量选择接入方式按团队技术栈在三种模式中选择——DSPy 的声明式签名、OpenAI Agents SDK 的 MCP 原生集成、LangChain/LangGraph 的生态复用或直接以uvx mcp-server-omi为起点用任意支持 MCP 的客户端消费这 8 个工具调试与验证用python -v观察服务器日志用 MCP Inspector 验证工具声明与返回用 Claude Desktop 日志确认真实环境下的调用链路。这套示例组合覆盖了当前主流的 Agent 编排框架既可作为 Omi 二次开发的起点也是一份同一 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），仅供参考 基于 MCP 连接 Omi 数据：DSPy、OpenAI Agents SDK 与 LangChain 实战示例解析
基于 MCP 连接 Omi 数据DSPy、OpenAI Agents SDK 与 LangChain 实战示例解析【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend本篇技术指南聚焦 Friend 仓库中 mcp/examples 目录下的官方示例应用讲解如何通过 Model Context ProtocolMCP以自然语言方式访问、检索与操作 Omi 智能眼镜采集到的 Memories记忆与 Conversations对话数据。你将掌握环境搭建、三种主流 Agent 框架DSPy、OpenAI Agents SDK、LangChain的接入写法以及基于 Streamlit 的交互式聊天界面的运行方式并深入了解底层mcp-server-omi服务器暴露的 8 个 MCP 工具及其后端实现原理。背景为什么用 MCP 连接 Omi 数据Omi 是看得见屏幕、听得见对话、告诉你该做什么的 AI 设备其核心资产是持续沉淀的个人记忆Memories和会话记录Conversations。要让任意 LLM Agent 以统一、标准化的方式消费这些数据Friend 仓库采用了 MCPModel Context Protocol作为连接协议并在 mcp 目录下提供了完整的服务端与示例客户端服务端mcp/src/mcp_server_omi/server.py 实现了一个本地 stdio 模式的 MCP 服务器将 Omi 后端能力封装为一个个可被 LLM 直接调用的工具Tool客户端示例mcp/examples 提供了三个框架示例与一个 Streamlit 交互应用演示不同 Agent 编排方式下如何挂载这些 MCP 工具。从 mcp/maintain.README.md 可以确认这些 MCP 工具并非独立实现而是直接包装 backend/routers/mcp.py 路由——即与 App 端、Web 端共用同一套后端数据接口保证了数据访问语义的一致性。前置条件与环境准备示例 README 明确了运行示例所需的四项前置条件结合仓库实际情况整理如下前置条件说明获取方式Python 3.8所有示例脚本均为 Python官方 Python 安装包或系统包管理器uvx命令行工具MCP 服务器通过uvx mcp-server-omi方式拉起无需预先 pip 安装服务端pip install uvx或安装 uv 工具链后自带uvxOpenAI API Key示例默认使用 OpenAI 的o4-mini/o3等推理模型作为 Agent 的 LLM 后端OpenAI 开发者平台Omi UID用户在 Omi 体系中的唯一标识用于定位其 Memories 与 Conversations 数据Omi 应用内获取需要特别强调的是uvx的地位所有示例都以uvx mcp-server-omi作为 MCP 服务器的启动方式uvx会在运行时自动从 PyPI 下载并执行已发布的mcp-server-omi包当前仓库版本为0.1.9见 mcp/src/mcp_server_omi/about.py因此客户端侧无需手动安装该包。安装依赖按原文档步骤执行python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate pip install -r requirements.txtrequirements.txt 是一份经过uv pip compile解析的完整锁定清单核心依赖包括MCP 协议层mcp1.28.1、openai-agents0.17.3三个框架示例dspy3.2.1、langchain-mcp-adapters0.2.2、langchain-openai1.2.1、langgraph1.2.0、langgraph-prebuilt1.1.0交互应用streamlit1.57.0环境配置与底层python-dotenv、openai2.37.0、httpx、pydantic2.13.4等。配置环境变量在项目根目录创建.env文件写入两项核心变量OPENAI_API_KEYyour_openai_api_key OMI_UIDyour_omi_uid各示例脚本顶部均调用load_dotenv()例如 dspy_ex.py、openai_agents_sdk_ex.py启动时会自动加载该文件。值得注意的是原文档中的.env只覆盖了 LLM 调用与 UID 定位。若要让 MCP 服务器实际访问数据还需要通过OMI_API_KEY提供 MCP 专用 API 密钥见下文API 密钥机制一节该变量同样可写入.env或通过环境变量注入。另外server.py 读取OMI_API_BASE_URL作为后端地址自托管后端时可用它覆盖默认的https://api.omi.me/v1/mcp/。三个框架示例同一条 MCP 数据管道三种 Agent 编排原文档给出了三个示例脚本的启动命令其核心价值在于展示同一份 Omi 数据、同一套 MCP 工具在不同 Agent 框架中的接入姿势。三个示例运行的是同一个演示任务——查看我的 Memories了解我是什么样的人然后检索最近 5 次对话并总结python dspy_ex.py python openai_agents_sdk_ex.py python langchain_ex.pyDSPy 示例以 Signature 声明式定义 Agent 任务dspy_ex.py 展示了 DSPy 风格的接入方式其特点是用Signature签名声明输入输出用ReAct编排工具调用建立 MCP 会话通过mcp.ClientSession与stdio_client建立 stdio 连接StdioServerParameters(commanduvx, args[mcp-server-omi])指定服务器启动方式初始化并列出工具await session.initialize()完成 MCP 握手await session.list_tools()获取服务器声明的工具清单工具转换用dspy.Tool.from_mcp_tool(session, tool)把 MCP 工具逐一包装为 DSPy 可调用的工具对象构建 Agent定义DSPyOmiAgent签名输入user_request、user_uid输出response以dspy.ReAct(DSPyOmiAgent, toolsdspy_tools)构建 ReAct Agent配置语言模型dspy.configure(lmdspy.LM(openai/o4-mini, temperature1, max_tokens24000))采用 OpenAI o4-mini 推理模型max_tokens24000为长文本总结预留充足输出空间。server_params StdioServerParameters(commanduvx, args[mcp-server-omi], envNone) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools await session.list_tools() dspy_tools [dspy.Tool.from_mcp_tool(session, tool) for tool in tools.tools] react dspy.ReAct(DSPyOmiAgent, toolsdspy_tools) result await react.acall(user_requestuser_request, user_uidos.getenv(OMI_UID)) print(result.response)该示例演示了 DSPy 的核心思想无需手写复杂的 prompt 与工具调用循环任务语义由 Signature 声明工具选择与调用顺序由 ReAct 自动推理完成。OpenAI Agents SDK 示例MCP Server 作为一等公民挂载openai_agents_sdk_ex.py 展示了 OpenAI Agents SDK 的接入方式这也是Streamlit 应用底层使用的同一套 API创建 MCP 服务器句柄MCPServerStdio(cache_tools_listFalse, params{command: uvx, args: [mcp-server-omi]})cache_tools_listFalse意味着每次会话都重新拉取工具列表避免工具更新后缓存不刷新挂载到 AgentAgent(nameOmi Agent, instructionsf...user UID is {uid}, mcp_servers[mcp_server], modelo4-mini)MCP 服务器通过mcp_servers参数直接注入工具无需手动枚举启用推理ModelSettings(reasoningReasoning(efforthigh, generate_summaryauto))开启高强度的推理模式执行Runner.run(starting_agentagent, inputmessage)驱动 Agent 完成任务。async with MCPServerStdio( cache_tools_listFalse, params{command: uvx, args: [mcp-server-omi]}, ) as server: agent Agent( nameOmi Agent, instructionsfYou are a helpful assistant that answers questions based on the users OMI data, the user UID is {uid}., mcp_servers[server], modelo4-mini, model_settingsModelSettings(reasoningReasoning(efforthigh, generate_summaryauto)), ) result await Runner.run(starting_agentagent, inputmessage) print(result.final_output)脚本启动时会校验uvx是否可用if not shutil.which(uvx): raise RuntimeError(...)这是原文档 Troubleshooting 中uvx 未安装错误的直接来源。LangChain / LangGraph 示例MultiServerMCPClient 桥接langchain_ex.py 展示了 LangChain 生态LangGraph langchain-mcp-adapters的接入方式模型初始化ChatOpenAI(modelo4-mini-2025-04-16)使用指定版本的 o4-mini多服务器客户端MultiServerMCPClient({omi: {command: uvx, args: [mcp-server-omi, -v], transport: stdio}})以字典形式声明 MCP 服务器该结构天然支持同时挂载多个 MCP 服务器工具获取client.get_tools()将 MCP 工具桥接为 LangChain 工具Agent 构建create_react_agent(model, client.get_tools())基于 LangGraph Prebuilt 快速构建 ReAct Agentawait agent.ainvoke(...)执行。async with MultiServerMCPClient( {omi: {command: uvx, args: [mcp-server-omi, -v], transport: stdio}} ) as client: agent create_react_agent(model, client.get_tools()) response await agent.ainvoke({messages: prompt}) print(response[messages][-1].content)注意此处命令行参数多了-vverbose 模式与 Streamlit 应用及 maintain.README.md 中推荐的调试启动方式一致便于在 Agent 运行过程中观察 MCP 服务器日志。三种接入方式的对比维度DSPyOpenAI Agents SDKLangChain / LangGraph任务定义Signature 声明 ReAct 编排Agent instructions mcp_serverscreate_react_agent 工具列表MCP 客户端mcp.ClientSessionstdio_clientMCPServerStdio一等公民MultiServerMCPClient工具接入dspy.Tool.from_mcp_tool逐个转换mcp_servers参数自动注入client.get_tools()批量桥接代表模型openai/o4-minio4-minio4-mini-2025-04-16适用场景希望用声明式 Signatures 约束任务追求 MCP 原生集成与官方 Agent 运行时已深度使用 LangChain/LangGraph 生态Streamlit 交互式聊天应用零代码接入 Omi 数据app.py 是示例集的主应用——一个基于 Streamlit 的聊天界面运行命令streamlit run app.py启动后浏览器会自动打开应用。使用前需在侧边栏 Settings中输入 OMI UID否则界面会提示 Please enter your OMI UID in the sidebar settings to start chatting 并停止。从源码看该应用有几个值得关注的设计细节前置校验启动时通过shutil.which(uvx)检查uvx是否在 PATH 中缺失则直接st.error(...)并st.stop()这与 openai_agents_sdk_ex.py 的校验逻辑互为印证事件循环管理run_async_task函数为每个请求新建独立事件循环asyncio.new_event_loop()避免 Streamlit 环境中已有事件循环导致的冲突这是 Streamlit asyncio 集成的经典实践Agent 配置底层与 OpenAI Agents SDK 示例同构——MCPServerStdio(cache_tools_listFalse, params{command: uvx, args: [mcp-server-omi, -v]})Agent 使用modelo3源码中注释保留了litellm/anthropic/claude-3-7-sonnet-20250219作为可选模型并配置ModelSettings(reasoningReasoning(efforthigh))多轮对话将完整会话历史含最新用户消息传给Runner.runAgent 基于 Omi 数据连续作答每次响应的new_items推理过程与工具调用详情被记录可在 View Reasoning/Tool Calls 折叠面板中查看追踪能力with trace(workflow_nameStramlit Omi MCP Example):为整个执行流程打上可观测性标记。async with MCPServerStdio( cache_tools_listFalse, params{command: uvx, args: [mcp-server-omi, -v]}, ) as server: omi_agent Agent( nameOmi Agent, instructionsfYou are a helpful assistant that answers questions based on my Omi data, my UID is {uid}. ..., mcp_servers[server], modelo3, model_settingsModelSettings(reasoningReasoning(efforthigh)), ) with trace(workflow_nameStramlit Omi MCP Example): run_output await Runner.run(starting_agentomi_agent, inputagent_input_messages)底层工具集mcp-server-omi 暴露的 8 个 MCP 工具三个示例和 Streamlit 应用共享同一个 MCP 服务器。要理解 Agent 能做什么需要看服务器实际声明的工具集。根据 server.py 的_get_tools()实现服务器共暴露8 个工具覆盖 Memories 与 Conversations 两类数据的读、搜、写操作工具名类别核心参数默认值底层接口get_memories记忆limit(100)、offset(0)、categoriesGET /memoriessearch_memories记忆query(必填)、limit(10)GET /memories/searchcreate_memory记忆content(必填)、category(必填)POST /memoriesedit_memory记忆memory_id(必填)、content(必填)PATCH /memories/{id}delete_memory记忆memory_id(必填)DELETE /memories/{id}get_conversations对话start_date、end_date、categories、limit(100)、offset(0)GET /conversationsget_conversation_by_id对话conversation_id(必填)GET /conversations/{id}search_conversations对话query(必填)、limit(10)、start_date、end_dateGET /conversations/search几个值得展开的实现细节分类枚举记忆分类MemoryCategory包含core、hobbies、lifestyle、interests、habits、work、skills、learnings、other对话分类ConversationCategory多达 33 项覆盖personal、finance、health、sports、politics、technology等领域。分类过滤通过逗号拼接多值实现例如params[categories] ,.join([c.value for c in categories])日期语义get_conversations对end_date做了当日 23:59:59的收尾处理——(datetime.strptime(end_date, %Y-%m-%d) timedelta(days1) - timedelta(seconds1)).isoformat()确保结束日期整天都被包含鉴权方式每个工具都带可选api_key参数_API_KEY_FIELD调用时优先取参数值否则回退到OMI_API_KEY环境变量两者皆无则抛出ValueError。日志输出时 api_key 会被掩码为***见_execute_tool的log_args避免密钥泄漏错误处理_response_json统一调用raise_for_status()HTTP 失败时抛出不含查询串与响应体的安全错误信息结果序列化所有工具返回TextContent(typetext, textjson.dumps(result, indent2))即返回格式化的 JSON 文本方便 LLM 直接阅读与再加工。这些工具在仓库测试中也有直接覆盖test_server.py 验证了get_memories的 limit 截断与分类过滤、get_conversations的include_discarded与 limit 行为test_parse_categories.py、test_search_conversations.py、test_http_status.py 则分别覆盖分类解析、对话搜索与 HTTP 状态处理。API 密钥机制与后端实现MCP 服务器的鉴权与后端路由是理解整个链路的关键。根据 mcp/README.md在 Omi macOS 应用中于 Use omi memory anywhere 下选择基于 key 的目标展开 Manual installation 复制生成的密钥跨平台应用中则在Settings Developer Settings的MCP Server区块的API Keys列表中创建生成的完整omi_mcp_...值即为OMI_API_KEY密钥可随每次工具调用传入也可省略以使用OMI_API_KEY环境变量本地 stdio 包采用手动密钥路径托管的 Omi MCP 端点对注册云客户端额外支持 OAuth。在 backend/routers/mcp.py765 行中可以看到这些工具对应的后端能力依赖注入get_uid_from_mcp_api_key完成 API Key 到用户 UID 的解析工具数据分别来自database.memories、database.conversations、database.vector_db向量语义搜索等模块对话列表还会经redact_conversations_for_list、populate_speaker_names等工具做脱敏与说话人姓名填充。也就是说MCP 工具层只是协议适配层真正的数据读写、语义搜索与隐私处理全部复用主后端既有能力这保证了本地 MCP 客户端与 App/Web 端看到的数据口径一致。调试与故障排查常见错误与解决办法原文档的 Troubleshooting 部分可直接作为排查清单uvx缺失错误报错信息通常为RuntimeError: uvx is not installed. Please install it with pip install uvx见 openai_agents_sdk_ex.py或在 Streamlit 应用中显示 Critical Error:uvxcommand not found。解决方式pip install uvx并确认其已加入 PATH环境变量未设置检查.env中OPENAI_API_KEY与OMI_UID是否填写正确以及文件是否位于启动命令的工作目录下依赖未安装重新执行pip install -r requirements.txtMCP 服务器鉴权失败确认OMI_API_KEYomi_mcp_...密钥已配置——这是原文档.env清单之外但实际运行必需的变量自托管后端地址不对通过OMI_API_BASE_URL指定后端地址见下文。使用 MCP Inspector 调试开发调试时可借助 MCP 官方 Inspector 工具直观查看工具声明与调用结果# 针对通过 uvx 发布的服务器 npx modelcontextprotocol/inspector uvx mcp-server-omi # 本地开发uv run 指向本地源码 npx modelcontextprotocol/inspector uv run mcp-server-omimaintain.README.md 还给出两条本地开发提示在 Inspector 中测试时启动命令可设为uvrun mcp-server-omi -v如果改用uvxmcp-server-omi则会指向已发布到 PyPI 的包而非本地改动uv run之外也可用python -m mcp_server_omi直接以模块方式启动。查看 Claude Desktop 日志将 MCP 服务器接入 Claude Desktop 后配置方法见 mcp/README.md 的 uvx / docker / pip 三种方案可通过以下命令跟踪其日志# macOS 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自托管后端如果自行部署 Omi 后端可覆盖 MCP 服务器的 API 基地址export OMI_API_BASE_URLhttps://your-backend-url.com该变量在 server.py 启动时读取默认值为https://api.omi.me/v1/mcp/为空时会抛出Exception(Base URL not found)。从示例到自研应用三步接入路径综合以上内容将 Omi 数据接入自有 Agent 应用只需三步准备运行环境安装 Python 3.8 与uvx配置OPENAI_API_KEY、OMI_UID、OMI_API_KEY三个关键变量选择接入方式按团队技术栈在三种模式中选择——DSPy 的声明式签名、OpenAI Agents SDK 的 MCP 原生集成、LangChain/LangGraph 的生态复用或直接以uvx mcp-server-omi为起点用任意支持 MCP 的客户端消费这 8 个工具调试与验证用python -v观察服务器日志用 MCP Inspector 验证工具声明与返回用 Claude Desktop 日志确认真实环境下的调用链路。这套示例组合覆盖了当前主流的 Agent 编排框架既可作为 Omi 二次开发的起点也是一份同一 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），仅供参考