Skip to content

Commit 34c11d9

Browse files
authored
feat(extensions): give extensions the MCP servers a client passes, a way to tell the user, and turn barriers (#35)
The agent still has no MCP client and does not read mcp.json. The user chose an optional extension package (pi-mcp-py) that connects the servers a client passes in session/new, session/load and session/resume. Core, harness and CLI only get the data and the hooks that such an extension needs. Data and hooks: - ClientMcpServer (pi_agent_core.extensions): one server as plain data. The fields that can hold a token (command, args, env, url, headers) are repr=False. - ExtensionAPI.client_mcp_servers and claim_client_mcp_servers(names). AgentHarness.set_client_mcp_servers() takes the list before the extensions load; unclaimed_client_mcp_servers says which servers nobody took over. - ExtensionAPI.notify(text) shows one line to the user (NoticeEvent, an agent message in ACP). The model does not see it and the session does not save it. - ExtensionAPI.register_cleanup(callback): the public name of what the bridge already had. - ExtensionAPI.add_turn_barrier(wait): the harness awaits it before it builds the tool list of a turn. A wait that is cancelled leaves the phase idle. - HarnessBridge has four more members; test doubles must add them. CLI: - client_mcp.py turns the ACP models into records and hands them to the harness on session/new, load, resume and the reopen of a blank session. - The notice about ignored MCP servers names only the servers nobody claimed, and its text is correct for one server and for many. With the pi-mcp entry point installed it does not tell the user to install anything. - initialize offers http and sse servers only when the pi-mcp entry point is installed (package metadata only; nothing is imported). The wire shape is the same as before when it is not. - A line from notify() waits until the deferred setup has advertised the commands (the client drops earlier updates, zed#60199), then goes out in order. - prompt() waits for the turn barriers and lets session/cancel, closing the session and opening it again end the wait. Fix: a session that the client opened again (a second session/load, Zed's Retry) built a new harness and dropped the old one without close(), so the cleanup callbacks of its extensions never ran. The new harness now replaces the old one first, and the old one is closed. Design: docs/specs/2026-10-23-mcp-extension-design.md
1 parent fa4887b commit 34c11d9

21 files changed

Lines changed: 2610 additions & 99 deletions

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/specs/2026-09-22-phase7-extension-api-design.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -682,7 +682,9 @@ workflow}`),名单之外的工具——包括任何扩展注册的——不
682682
- 提示是工具作者的一面之词,运行时不验证。内置与随包工具是我们自己的;扩展是用户选择加载的代码(它本来就能做更糟的
683683
事,标错一个提示并没有让它多出能力)。MCP 规范要求客户端把 annotations 视为不可信,除非来自受信任的服务器(恶意服务器
684684
可以把破坏性的工具标成只读);`from_langchain_tool` 原样转交 `tool.metadata` 里的提示,所以连接了不信任的 MCP 服务器的
685-
调用者要先去掉这些提示。本 CLI 目前不把 ACP `session/new` 的 `mcpServers` 接成工具(该参数被忽略),不受此影响。
685+
调用者要先去掉这些提示。本 CLI 自己不把 ACP `session/new` 的 `mcpServers` 接成工具,不受此影响。(2026-10-23:`mcpServers`
686+
现在作为数据交给扩展,见 `ExtensionAPI.client_mcp_servers`;可选扩展 `pi-mcp-py` 连接它们。那些工具的提示怎么处理,见
687+
[MCP 扩展设计](2026-10-23-mcp-extension-design.md) §6.3。)
686688
没有按工具放行的配置项:想放行一个没声明的第三方工具,只能补上 annotations,或改用 `auto` 模式。
687689
- 行为变化:`ask` 模式下,不声明 annotations 的扩展工具现在会询问(此前直接执行)。
688690

@@ -691,6 +693,11 @@ workflow}`),名单之外的工具——包括任何扩展注册的——不
691693
(§13,后台结果的交付)。`HarnessBridge` 是 `runtime_checkable` 协议,自制 bridge(测试替身之类)要补上该方法才能通过
692694
`isinstance`。
693695

696+
2026-10-23 又加四个成员:`client_mcp_servers`(属性)、`claim_client_mcp_servers(names)`、`notify(text)`、
697+
`add_turn_barrier(wait)`,对应 `ExtensionAPI` 的同名入口(另有 `ExtensionAPI.register_cleanup`,它公开了 bridge 早就有的
698+
`register_cleanup`)。自制 bridge 要再补上这四个。它们是一组通用入口,MCP 只是第一个用户;设计见
699+
[MCP 扩展设计](2026-10-23-mcp-extension-design.md) §4。
700+
694701
---
695702

696703
## 13. Background run / result delivery / 会话生命周期 ✅

‎docs/specs/2026-09-24-phase6-extended-integrations-design.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
> 上游参照:[earendil-works/pi](https://github.com/earendil-works/pi) `packages/coding-agent`。
88
> 上游 README 写明 **No MCP**:core 与 CLI 不连接服务器、不发现 `mcp.json`。需要 MCP 的人写扩展,或自己把工具接进来。
99
> pi-python 对齐这一点。MCP 服务器产出的工具若要进循环,调用方先经 `langchain-mcp-adapters` 得到 `BaseTool`,再走已有的 `from_langchain_tool()`。本期不新增 MCP 模块。
10+
>
11+
> **修订(2026-10-23)**:用户另选了一条通路:可选扩展包 `pi-mcp-py`,连接**客户端**(编辑器)随 `session/new` 传来的 MCP server。本文的立场不变:core、harness 与 CLI 里仍没有 MCP 客户端,不发现 `mcp.json`,不管理 stdio 子进程。它们只多了一个数据类型(`ClientMcpServer`)和几个通用的扩展入口,MCP 本身留在扩展里,正是本文说的「需要 MCP 的人写扩展」。下文 §1.2、§3 是当时的决定,原样保留。设计与理由见 [MCP 扩展设计](2026-10-23-mcp-extension-design.md)。(「Phase 4 非目标」的说法不准确:Phase 4 规格没有讨论 MCP,出处是本文。)
1012
1113
---
1214

‎docs/specs/2026-10-23-mcp-extension-design.md‎

Lines changed: 415 additions & 0 deletions
Large diffs are not rendered by default.

‎packages/pi-agent-cli/AGENTS.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,16 @@ The Rust TUI (`zypi`) spawns the Python agent via (priority order):
6262

6363
## MCP servers
6464

65-
The agent connects to **no** MCP server (Phase 4 non-goal; tools come from the harness and its extensions). `session/new`, `load` and `resume` accept `mcp_servers` and ignore them, which departs from ACP, whose session setup says an agent MUST support stdio servers; `initialize` advertises no `mcpCapabilities` (no `http`, no `sse`). The departure is made visible instead of silent: each time a session is set up with a non-empty list, the agent logs a warning and sends one agent message naming the servers (`mcp_notice`, from `_deferred_session_setup`, after the response has flushed like the other notices). Only the **names** are used: `env`, `headers`, `args` and `url` routinely hold tokens. `zypi` itself sends an empty list (it used to forward whatever it found in `.mcp.json`, `~/.claude.json` and Cursor's `mcp.json`), so there the notice never appears; it is for other ACP clients (an editor that passes its own servers). `tests/test_mcp_notice.py`. To implement MCP, start from the notice: it is the one place that sees the list.
65+
The agent has **no** MCP client: it opens no MCP connection and starts no MCP server process. Phase 6 decided this, in line with upstream pi ("No MCP"). The 0.5.0 notes called it a Phase 4 non-goal, but Phase 4 did not discuss MCP. What a client passes in `mcp_servers` (`session/new`, `load`, `resume`, and the reopen of a blank session) goes to the harness as data, and an extension can use it:
66+
67+
- **Hand-over.** `client_mcp.client_mcp_servers()` turns the ACP models (or plain dicts) into `ClientMcpServer` records (`pi_agent_core.extensions`: `name`, `transport`, `command`, `args`, `env`, `url`, `headers`; the fields that can hold a token are `repr=False`). A name is one line of printable text. An empty name becomes `server-<n>`, and a repeated name gets `-2`, `-3`. A server that cannot be used (no command, no URL, unknown type) is skipped with a warning that names it. `_bind_session` gives the list to `harness.set_client_mcp_servers()` before the extensions load. An extension reads it as `pi.client_mcp_servers` and takes servers with `pi.claim_client_mcp_servers(names)`. The optional `pi-mcp-py` package is such an extension (design: `docs/specs/2026-10-23-mcp-extension-design.md`).
68+
- **Capabilities.** `initialize` always sends an `mcpCapabilities` object. `http` and `sse` are `true` only when the `pi-mcp` entry point is installed (`mcp_extension_installed()` reads package metadata and imports nothing, so a broken extension still counts). ACP allows stdio servers always.
69+
- **The notice.** A server that no extension claimed is not connected. For these servers, and only these, the agent logs a warning (names only) and sends one agent message (`mcp_notice`, from `_deferred_session_setup`, after the response has flushed like the other notices). It tells the user to install `pi-mcp-py`, or, when the entry point is there, that no extension took the servers over. Only the **names** are used: `env`, `headers`, `args` and `url` routinely hold tokens. `zypi` sends an empty list (it used to forward whatever it found in `.mcp.json`, `~/.claude.json` and Cursor's `mcp.json`), so there the notice never appears. It is for other ACP clients (an editor that passes its own servers).
70+
- **Lines for the user from an extension.** `pi.notify(text)` becomes a `NoticeEvent`, and `project_event` shows it as an agent message. The client drops what it gets before it knows the session (zed#60199), so the agent holds such a line (`_held_notices`) until `_deferred_session_setup` has advertised the commands (`_open_notices`). Later lines go out at once. Opening the session again closes this gate again. Closing or deleting the session forgets what was held.
71+
- **Turn barriers.** An extension can register `pi.add_turn_barrier(wait)`. `prompt()` awaits `harness.wait_turn_barriers()` after the question about the project and before the turn starts. `session/cancel` ends that wait (the prompt returns `cancelled`). Closing or deleting the session, or opening it again, ends it too (`_drop_trust` sets the cancel event). The harness awaits the same barriers before it builds the tool list, and a barrier that is done returns at once.
72+
- **A session that is opened again.** `_bind_session` puts the new harness in place first, and then closes the old one (`close()` stops its turn and runs the cleanup callbacks of its extensions). Before, the old harness was dropped without `close()`, and what its extensions had started (an MCP server is a child process) kept running.
73+
74+
Tests: `tests/test_client_mcp.py`, `tests/test_mcp_notice.py`; the hooks: `pi_agent_core/tests/test_client_mcp_hooks.py`, `packages/pi-agent-harness/tests/test_client_mcp_harness.py`.
6675

6776
## Listing sessions
6877

@@ -115,7 +124,8 @@ The agent must reap the tools it is running when its client goes away: the TUI c
115124
| `trust_store.py` | `<home>/agent/trust.json`: answers saved per directory with the fingerprint they were about |
116125
| `trust_prompt.py` | The `session/request_permission` question (shape, option ids, how an answer is read) and its explanation message |
117126
| `extension_notices.py` | The "these extensions failed to load" notice (`AgentHarness.failed_extensions`): ACP agent message after `session/new`, headless stderr |
118-
| `mcp_notice.py` | The "these MCP servers were ignored" notice: names only, never `env` / `headers` / `args` / `url` |
127+
| `client_mcp.py` | The MCP servers a client passes (ACP models or dicts) as `ClientMcpServer` records for the harness; `mcp_extension_installed()` (entry-point metadata only) |
128+
| `mcp_notice.py` | The "these MCP servers were not connected" notice: names only, never `env` / `headers` / `args` / `url` |
119129
| `system_prompt.py` | `build_system_prompt`, tool snippet/guideline consumption |
120130
| `context_files.py` | AGENTS.md / CLAUDE.md / .pi/SYSTEM.md discovery |
121131
| `git_context.py` | Read-only branch and `git status` snapshot for the system prompt |

0 commit comments

Comments
 (0)