Prime Agent 中通过官方 MCP 服务器读写 Linearlinear Skill 的登录、工具发现与调用实战【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent导读本文讲解 Prime Agent 内置的linearPython 技能Skill它让编码 Agent 通过 Linear 官方托管的 MCP 服务器在 Python 内核中直接读写 Linear 的 issue、project、cycle、comment 等数据。读完本文你将掌握如何通过/login或/mcp login linear完成 OAuth 连接、如何遵循先发现再调用的准则在运行时自动发现工具、如何使用await linear.tool(...)与转义通道call_tool两种方式调用工具并理解其背后McpIntegration基类的凭据解析与连接复用机制。linear Skill 概览一条面向 Python 内核的 MCP 通道linear是一个以 Python 包形式发布的 Prime Agent 技能其入口定义位于 packages/coding-agent/skills/linear/SKILL.mdfrontmatter 声明Read and write Linear issues, projects, cycles, comments, and more via Linears official MCP server. Tools are auto-discovered from the server at runtime.关键信息有三点能力边界覆盖 Linear 的 issue、project、cycle、comment 等核心对象的读写连接方式通过Linear 官方托管 MCP 服务器https://mcp.linear.app/mcp通信而非自定义的私有实现工具来源所有工具在运行时从服务器自动发现auto-discoveredskill 本身不硬编码任何工具名或参数名。从源码看这个技能包非常精简。src/linear/init.py 中Linear只是McpIntegration的一个子类仅声明服务器标识与端点from rlm import McpIntegration class Linear(McpIntegration): server linear url https://mcp.linear.app/mcp linear Linear()pyproject.tomlpackages/coding-agent/skills/linear/pyproject.toml将该包命名为prime-agent-skill-linear依赖mcp、httpx与prime-agent-runtime——也就是说MCP 连接由官方mcpPython SDK 在内核中建立宿主host只负责交互式登录与凭据管理。这一点与 Prime Agent 的单工具设计一致MCP 集成不会暴露为新的 Agent 工具而是以 Python 技能的形式由模型导入并调用参见 packages/coding-agent/docs/mcp-integrations.md。连接与启用从登录到自动启用两种等效的登录方式linear技能默认禁用登录即启用方式一图形界面在 TUI 中打开/login切换到Services标签页选择Linear在浏览器中完成 OAuth 授权方式二命令行直接在 TUI 命令行输入/mcp login linear效果相同。登录成功后该技能会自动启用模型即可在会话中导入它。你可以用/mcp查看各集成的连接状态用/mcp logout linear断开连接。凭据存储与启用判定凭据统一存放在~/.prime/agent/auth.json中键名为mcp:server即mcp:linear。启用状态完全由是否存在有效凭据推导并没有独立的开关位——这是 packages/coding-agent/docs/mcp-integrations.md 明确描述的 Enable-by-login 生命周期。从 prime-agent-runtime/src/rlm/mcp_base.py 的源码可以看到这条凭据链路的具体实现_read_auth(provider)直接读取auth.json并兼容PRIME_AGENT_CODING_AGENT_DIR/PI_CODING_AGENT_DIR环境变量或默认~/.prime/agent作为配置目录_token()按优先级解析令牌优先使用静态 Bearer Token 环境变量其次是auth.json中的 OAuth 凭据accessexpires且带30 秒提前过期窗口_EXPIRY_SKEW_SECONDS 30保证令牌不会在请求中途失效当令牌缺失或过期时_resolve_token()通过host_request(mcp.refresh, {server: linear})请求宿主刷新刷新失败而非从未登录会被明确报为可恢复错误而不是误导为需要重新登录。遇到 NotEnabled 怎么办如果调用时抛出NotEnabled含义是技能已安装但用户未登录没有可用凭据。此时正确的处理方式是引导用户执行/login或/mcp login linear而不是让用户去设置环境变量。这个指引也内置在NotEnabled异常自身的消息中prime-agent-runtime/src/rlm/mcp_base.pyThe linear integration is not enabled: no credentials found. Tell the user to run /mcp login linear in Prime Agent to connect it. Do not ask them to set environment variables.使用模式先发现再调用linear技能的工具集由服务器定义而非技能定义。因此使用铁律是先调用list_tools()发现可用工具再发起实际调用不要臆测工具名或参数名。以下是 SKILL.md 给出的标准三段式用法import linear # 1. Discover available tools for tool in await linear.list_tools(): print(tool[name], -, tool[description]) # 2. Inspect a specific tools arguments (rendered from its JSON Schema) help(linear.list_issues) # 3. Call it; keyword args must match the tools input schema result await linear.list_issues(teamEngineering) print(result)每一步的含义发现工具await linear.list_tools()返回形如[{name, description, inputSchema}]的列表。这一步会建立到https://mcp.linear.app/mcp的流式 HTTP 会话并拉取服务器声明的全部工具检查参数help(linear.list_issues)展示该工具的参数结构——它是从该工具的 JSON Schema 渲染出来的 docstring。注意help 的内容只有在执行过list_tools()之后才会被填充因为工具 schema 是在运行时发现的发起调用关键字参数必须与该工具输入 Schema 匹配例如teamEngineering。三条关键注意事项一切皆 async每个工具都是async方法必须await结果已是解析好的 Python 对象结构化输出为dict纯文本输出为str其他情况为内容块列表——无需再json.loads非法标识符的转义通道对于名称不是合法 Python 标识符的工具例如含连字符的名称使用显式转义await linear.call_tool(tool-name, {arg: value})。为什么先发现再调用如此重要因为服务器才是工具名称与参数的真实来源source of truth。服务器升级可能增删工具、调整参数名任何在 skill 里硬编码的假设都会过时。list_tools()不只返回清单它还填充了help()展示的 schema因此在依赖help()或假定某个工具存在之前务必先运行一次list_tools()。模块级转发的便捷性设计在 Python 中import linear后直接写linear.list_issues是可行的这得益于 src/linear/init.py 的模块级__getattr___RESERVED {run, __wrapped__, __call__} def __getattr__(name: str): if name.startswith(_) or name in _RESERVED: raise AttributeError(name) return getattr(linear, name)它把裸模块级访问如linear.list_issues转发到Linear实例上让import linear; await linear.list_issues(...)无需写成linear.linear.list_issues(...)。源码注释还揭示了一个值得注意的细节_RESERVED中的run、__wrapped__、__call__之所以不能被转发是因为内核引导程序bootstrap会探测模块是否为可调用技能——如果转发这些名字getattr(module, run)会返回一个 MCP 工具存根模块会被误包装为可调用从而破坏await linear.tool()的派发机制。底层原理McpIntegration 如何工作Linear继承的McpIntegration基类位于 prime-agent-runtime/src/rlm/mcp_base.py它定义了整个 MCP 集成家族的通用行为1. 动态工具绑定__getattr__任何未在实例上直接找到的属性访问都会被解释为一次工具调用def __getattr__(self, name: str): if name.startswith(_): raise AttributeError(name) async def _call(**kwargs: Any) - Any: await self._ensure_tools() if self._tools is not None and name not in self._tools: available , .join(sorted(self._tools)) or (none) raise AttributeError(f{self.server} has no tool {name}. Available: {available}) return await self.call_tool(name, kwargs) _call.__name__ name _call.__qualname__ f{type(self).__name__}.{name} if self._tools and name in self._tools: schema self._tools[name].get(inputSchema) or {} desc self._tools[name].get(description) or _call.__doc__ f{desc}\n\nArguments (JSON Schema):\n{json.dumps(schema, indent2)} return _call可见调用不存在的工具会得到带有可用工具清单的AttributeError而help()展示的 docstring 正是这里动态拼装的描述 完整 JSON Schema。2. 工具发现的缓存与并发安全_ensure_tools()仅在首次使用时建立连接并调用session.list_tools()结果缓存在self._tools中通过asyncio.Lock保证并发安全并用AsyncExitStack管理会话生命周期。工具 schema 的读取兼容mcp2的input_schema字段与旧版inputSchema别名。3. 每次调用新建会话call_tool()的实现注释说明了一个重要设计决策每次调用都打开一个全新的 MCP 会话AsyncExitStack_open_session而非长期持有。原因有二一是 MCP 会话无法安全地跨内核的 snapshot/restore 保存二是按调用建连对空闲会话与令牌轮换更加健壮代价只是可接受的少量延迟。4. 结果解析与错误归一化_parse_result()负责把CallToolResult归一化为普通 Python 对象服务器标记is_error的结果会被提升为McpToolError避免失败被当成成功优先返回structured_content/structuredContent结构化数据空{}、[]也是合法结果不会被误判为空其次是文本内容拼接图片、嵌入资源等非文本内容块则以 JSON 兼容的 dict 列表返回。5. 宿主与内核的协作边界linear技能运行时内核负责通过mcpPython SDK 建立流式 HTTP 连接并携带Authorization: Bearer token头额外配置头在前、Authorization 恒为最后以优先覆盖宿主的职责被收敛为两件事交互式登录浏览器 OAuth与在auth.json中铸造/刷新凭据。内核到宿主的通信经由rlm.host_request(...)定义于 prime-agent-runtime/src/rlm/init.py。此外仓库中还提供了面向通用 MCP 服务器的运行时注册表 prime-agent-runtime/src/rlm/mcp.py支持 http 与 stdio 两种传输、启停工具白名单/黑名单enabledTools/disabledTools、启动/调用超时、以及 stderr 脱敏等能力。需要说明的是linear这类内置集成不会读取用户的mcpServers配置——同名条目不能重定向内置集成这会导致凭据跟随错乱若要指向自定义端点必须改名为如linear-proxy的条目走通用运行时且mcp add会直接拒绝linear这类保留名。典型排查路径现象含义与处理调用抛出NotEnabled未登录。引导用户执行/login→ Services → Linear或/mcp login linear不要引导设置环境变量AttributeError: linear has no tool xxx服务器上不存在该工具。错误信息会列出可用工具先await linear.list_tools()确认正确名称help(linear.list_issues)无内容尚未执行过list_tools()schema 未被填充先运行发现步骤工具名不是合法 Python 标识符使用转义通道await linear.call_tool(tool-name, {arg: value})令牌过期/刷新失败内核会先请求宿主mcp.refresh刷新失败会给出可恢复错误而非误导为重新登录小结linear技能是 Prime Agent内置 MCP 集成即 Python 技能这一设计的具体范例skill 只声明服务器标识与端点全部工具在运行时从 Linear 官方 MCP 服务器自动发现通过McpIntegration基类动态绑定为可await的方法。对使用者而言只需记住三件事——登录即启用/login或/mcp login linear、先list_tools()再help()再调用、一切工具皆为 async 且返回值已是 Python 原生对象——即可在编码工作流中无缝读写 Linear 的数据。若想了解如何在其他服务上复刻这一模式例如 Notion 的同构实现可对比阅读 packages/coding-agent/skills/notion/SKILL.md 与 packages/coding-agent/docs/mcp-integrations.md。【免费下载链接】prime-agentA self-improving RLM agent for coding workflows and long-running autonomous tasks.项目地址: https://gitcode.com/GitHub_Trending/pr/prime-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考