@epoch-agent/plugin-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,219 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+--------------------------------------------------------------------------------
+
+epoch-agent
+Copyright 2024-2026 bowen
+
+Portions of this software are derived from the Gemini CLI
+(https://github.com/google-gemini/gemini-cli), Copyright 2025 Google LLC,
+licensed under the Apache License, Version 2.0. Those files have been modified;
+each one retains its original copyright notice and SPDX-License-Identifier
+header. See the NOTICE file in the project source repository for the complete
+list of derived files.
+
+This software also quotes, with attribution, two lines of prose from OpenAI
+Codex (https://github.com/openai/codex), Copyright 2025 OpenAI, licensed under
+the Apache License, Version 2.0. No source file is a derived work of Codex.
+See the NOTICE file for details.

package/README.md

@@ -0,0 +1,197 @@
+# @epoch-agent/plugin-mcp
+
+MCP (Model Context Protocol) 客户端插件。连接外部 MCP server 扩展工具集。
+
+配置文件位置由 `@epoch-agent/infra` 的 `mcpConfigPath()` 决定
+（认 `EPOCH_HOME` / `EPOCH_PROFILE`），默认 `~/.epoch/mcp.json`。
+
+## 支持 Transport
+
+| Transport       | 配置                                           | 场景                 |
+| --------------- | ---------------------------------------------- | -------------------- |
+| Stdio           | `command` + `args`                             | 本地 MCP server 进程 |
+| SSE             | `url`                                          | 远程 MCP server      |
+| Streamable HTTP | `url` + `transport: "http"`（或 `streamable`） | 远程 HTTP 流式       |
+
+> ⚠️ **stdio 那档要机器上有 Node。** `command` 是从 **PATH** 解析的
+> （SDK 用 cross-spawn、`shell: false`），而官方配置几乎都是
+> `npx -y @modelcontextprotocol/server-xxx` —— PATH 上没有 `npx` / `node` 就是 ENOENT，
+> 那台 server 起不来（stderr 里那行会进日志）。
+> CLI 用户天然有 Node；**嵌入宿主的用户没有**，那边要宿主自己把 ship 的 node 目录
+> prepend 到 `process.env.PATH`，见 [EMBEDDING.md](../../../docs/EMBEDDING.md) 的
+> 「用户机器上没装 Node」一节。HTTP / SSE 那两档不起子进程，不受这条影响。
+
+`transport` 不写时按 `url` 有无推断：有 `url` 走 SSE，没有走 stdio。
+**`type` 是 `transport` 的别名**（MCP 生态里多数客户端的 mcp.json 用的是 `type`），
+两个都写时听 `transport` 的。收它不是为了顺手：不收的话 `{"type":"http","url":…}`
+会掉进上面那条「按 `url` 推断」的路，一个 Streamable HTTP server 被**静默连成 SSE**。
+
+## 配置示例
+
+`servers` 是**以 server 名为键的对象**，不是数组：
+
+> **这份文件现在有两条写法：手写，或者 `epoch web` 的连接器页那枚「添加 server」**
+> （2026-08-18，`POST /api/mcp`）。
+>
+> 界面那条只收三样（传输类型 / 命令或 URL / 环境变量）—— 下面那几格
+> （`timeout` / `oauth` / `headers` …）**仍然只能手写**，所以它加完会把
+> 「写进了哪个文件」印出来，让你接着去补。
+>
+> ⚠️ 界面那条**往原文里插一段**，你的注释、键序、缩进、以及 `connect_timeout` /
+> `type` 这类别名一个字节都不动（它不是「读进来 → 改 → 整份写回」）。
+> 判据全文在 [runtime/src/mcp-config-write.ts](../../runtime/src/mcp-config-write.ts)。
+>
+> ⚠️ 界面那条给的 server 名**收得比这份文件严**（只许字母数字和 `_` `-`）——
+> 手写的不受这条管。理由同下面「插件带的名字为什么更严」：名字会原样进工具名。
+
+```json
+{
+  "servers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+      "env": { "LOG_LEVEL": "warn" }
+    },
+    "remote": {
+      "transport": "http",
+      "url": "https://mcp.example.com/mcp",
+      "headers": { "Authorization": "Bearer xxx" }
+    }
+  }
+}
+```
+
+### 字段
+
+| 字段                   | 类型                    | 说明                            |
+| ---------------------- | ----------------------- | ------------------------------- |
+| `transport` / `type`   | `stdio\|sse\|http`      | 不写按 `url` 推断；互为别名     |
+| `command` / `args`     | `string` / `string[]`   | stdio 必填                      |
+| `url`                  | `string`                | sse / http 必填                 |
+| `streamable`           | `boolean`               | 远程用 Streamable HTTP 而非 SSE |
+| `headers`              | `Record<string,string>` | 远程请求头（如 auth）           |
+| `env`                  | `Record<string,string>` | 子进程环境变量                  |
+| `timeout`              | 秒                      | 单次请求超时，默认 300          |
+| `connect_timeout`      | 秒                      | 建连（含握手）超时，默认 60     |
+| `keepalive_interval`   | 秒                      | 心跳间隔，默认 180              |
+| `idle_timeout_seconds` | 秒                      | 空闲自动断开，0 表示不断        |
+| `max_lifetime_seconds` | 秒                      | 连接最大寿命，0 表示不限        |
+| `supports_parallel`    | `boolean`               | 是否允许并行调用                |
+| `skip_preflight`       | `boolean`               | 跳过启动预检                    |
+
+snake_case 和 camelCase 两种写法都收。**未知字段会进启动诊断**（多半是拼错了），
+配置写错不再静默变成「没有 MCP」—— 每条问题都带文件名 + 字段路径。
+
+⚠️ **`source` 不是这张表里的字段，写在 `mcp.json` 里不生效。** 那一格在
+`McpServerStatus` 上（不在配置上），由**调用方**在 `connectAll(configs, source)`
+那一下填死。分开是刻意的：来源要是配置的一个字段，用户就能给自己那台贴上
+「宿主注入」的标 —— 同角色那条「命名空间由装配层拼，宿主自己写的不算数」。
+
+## server 是从哪儿来的：`McpServerStatus.source`
+
+三档：
+
+| `source` | 谁带来的                                                  | 名字长什么样            |
+| -------- | --------------------------------------------------------- | ----------------------- |
+| `user`   | 上面那份 `~/.epoch/mcp.json`                              | 你自己写的那个          |
+| `host`   | 嵌入宿主 `buildRuntime({hostCapabilities: {mcpServers}})` | `<namespace>__<server>` |
+| `plugin` | 已装插件根下那份 `mcp.json`（方案 44 PR-3）               | `<插件名>__<server>`    |
+
+前两档一个字节都不落盘 / 落在插件目录里，能力页的连接器那一栏就是按这一格分组的。
+
+⚠️ **加一档要连着改能力页那张 `MCP_GROUPS` 数组**（`web/src/capability/connectors.tsx`）
+—— 那是 `satisfies readonly {…}[]`，多一格**不会**编译红，而页面按组过滤后渲染，
+漏改的表现是那一档一行都不显示、也没有任何报错。PR-2 实测复现过一次。
+
+**后两档的名字都由装配层拼**，用**两个下划线**，而不是专家 / 技能那条路上的
+`<namespace>:`。这不是两套风格：
+
+- server 名会原样变成工具名的一部分（`prefixedName()` 拼的
+  `mcp__<server>__<tool>`），而工具名是**真的发给 provider** 的；
+- 2026-08-17 实测：带 `:` 的工具名被硬拒 ——
+  `tools.0.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,128}$'`，
+  同一发换成 `mcp__gh__search_issues` 就 200 正常回；
+- 角色名 / 技能名**不上网线进 provider**，所以那边拼 `:` 一直没事。
+
+判据全文（含「为什么这两批的名字收得比 `mcp.json` 严」、两个前缀的**来路差别**
+（宿主那个是 `buildRuntime` 的参数、装配时校验；插件那个是插件名、**安装时**就被
+`PLUGIN_NAME_PATTERN` 卡过了）、以及为什么这一格是必填）在
+[types.ts](src/types.ts) 的 `McpServerStatus.source` 上。
+
+## 功能
+
+- 三 transport（stdio / SSE / Streamable HTTP）
+- 工具名前缀 `mcp__<server>__<tool>`，撞名交 `ToolRegistry` 处理
+- 配置校验：语法错误 / 类型错误 / 缺必填字段都进诊断，逐 server 隔离
+- `tools/list` annotations + title 透传到 `EpochTool.annotations`（权限系统消费）
+- schema 缓存：内存优先，磁盘（0600）作降级；按连接配置指纹失效
+- 看门狗式重连：断连**不阻塞**工具调用，重连在后台按 1s/2s/4s 退避
+- keepalive 心跳、idle 超时断开、最大生命周期
+- **OAuth**（`oauth/`）：`epoch mcp login` / `logout` 的后端，本机回调 server +
+  token 刷新（带 skew）+ 0600 存储。认证过不去时置 `needsLogin`——重连解决不了
+  这个问题，只有重新登录能
+- **resources**：包成每个 server 一对工具
+  `mcp__<server>__list_resources` / `mcp__<server>__read_resource`
+- **prompts**：`McpRegistry.listPrompts()` / `getPrompt()`
+- **一台一台地断 / 问它此刻按的哪份配置**（2026-08-18）：
+  `McpRegistry.disconnect(name)` / `configOf(name)`。在这之前只有 `disconnectAll()`
+  —— 而「让**一台** server 在这个进程里消失」是装配层那条「应用 `mcp.json` 的改动」
+  必须做到的事（runtime 的 `applyMcpConfig`）：全断再全连会把宿主注入的和插件带来的
+  那两批也连带断掉，而它们一个字节都不在那份文件里。
+  ⚠️ `disconnect()` **连带失效 schema 缓存**（同 `reconnect()`），但**不碰工具表**
+  —— 把 `mcp:<名字>` 那一组工具从 `ToolRegistry` 里摘掉是装配层的事
+
+resources 和 prompts 都**先看 capability 再问**（server 没声明就别问，问了多半得到
+`-32601 Method not found`），都**翻页**（`nextCursor`，上限 50 页），都把
+method-not-found **当空**处理——有些 server 声明了 capability 却没实现，
+「没有 resources」比「MCP 初始化失败」更贴近事实。
+
+resources 包成工具而不是注入上下文：一个 server 挂几十份文档是常态，全量注入等于
+每一轮都为「模型多半用不到的东西」付 token；而工具是按需调用的，天然懒加载。
+
+## 还没做
+
+`notifications/tools/list_changed` 收得到，但**不是热更新**：`AgentLoop` 的工具集是
+构造参数，本进程内换不掉。registry 只把「工具表已经不是启动时那份了」冒泡给宿主，
+真正换掉要重启。
+
+## 明确不做的三条（**带判据，不是「以后再说」**）
+
+- **sampling / elicitation**（server 反过来请求 client：帮我调一次模型 / 帮我问用户
+  一句）。它要一个新的 `AgentEvent` 变体加一道权限闸门 —— 也就是**动 protocol**，
+  而那是全仓最贵的改动面。硬门槛在权限那一侧而不是协议那一侧：一个 server 能让我们
+  代它调模型，等于它能花我们的钱、并且把内容塞进我们的上下文，那需要先有一套
+  「这次反向请求要不要问用户」的语义。**要做就先定那套语义**，别从 SDK 那头往回接。
+- **MCP server 的目录 / 市场**（对标 hermes 的 `mcp_catalog.py` + `mcp_picker.py`）。
+  ⚠️ **别和[方案 32](../../../docs/verify/VERIFY_RECORD-32-runtime-plugins.md) 的插件市场
+  混为一谈**：32 管的是**我们自己的插件**（`~/.epoch/plugins/`），这一条管的是
+  「上哪儿找第三方 MCP server」。两件事，两套来源，两套信任模型。
+- **MCP server 模式**（把 epoch 自己暴露成 MCP server 给别的 agent 用）。
+  hermes 有 `mcp_serve.py`、codex 有整个 `codex-mcp/` crate，但那是「被集成」
+  而不是「集成」。更强的版本连同一条**永久红线**（真做也只暴露 `epoch_run`，
+  不把内置工具逐个转出去 —— 那等于让对方绕过我们的权限层）写在
+  [方案 28 验收记录第五章](../../../docs/verify/VERIFY_RECORD-28-headless-protocol.md)（那一版
+  `epoch mcp serve` 已经砍掉，红线连同重开的条件一起记在那儿）。
+
+## 依赖
+
+- `@modelcontextprotocol/sdk`
+- `zod`（配置校验，走 infra 的 `parseLenient`）
+- [protocol](../../protocol) 和 [infra](../../infra) 是 peer
+
+## 开发
+
+```bash
+pnpm --filter @epoch-agent/plugin-mcp test
+```
+
+`__tests__/orphan-reap.test.ts` 真起 server、真查残留，钉的是
+`closeTransportAndReap()` 那三步（拍快照 → 优雅关 → 清扫快照）。**Windows 和 macOS
+都跑**，改 disconnect 路径必须跑它。
+
+⚠️ 用例里那个「启动器」中间层**必须是 shell**（Windows 生成一个 `.cmd`，POSIX 用
+`/bin/sh -c`），换成 node 写的启动器用例就是空的：Windows 上 node 起的非 detached
+子进程会被 libuv 的全局 Job Object 连坐收掉，父进程一死孙进程自动没，把清扫整段
+删掉照样全绿。shell 也更接近真实形态——`npx -y mcp-remote …` 在 Windows 上就是被
+cross-spawn 改写成 `cmd.exe /c npx.cmd …` 的。细节记在
+[验收记录](../../../docs/verify/VERIFY_RECORD-16-process-tree.md) 的「追加二」。