feat(mcp): turn off a global server for Pi from the project switch

A Pi project entry replaces the global one and is skipped without a
command or url, so a switch-only entry left the server on in Pi and the
project page could not turn it off there. Reporters want a server off in
one project while every other project keeps loading it.

For a project under mcp.projects, the switch now writes the global
server's command, or its url without the query, with enabled: false to
the project's .pi/mcp.json. A disabled server never starts, so args, env
and headers stay out of a file that may be committed, and every sync
rewrites the entry from the global server. A project's own config cannot
see the global server, so pi there is still refused. The migration that
dropped pi from switch-only entries is gone.

Refs #305
This commit is contained in:
Willie
2026-10-01 16:08:23 +08:00
parent 886e3672a2
commit f837f0e94d
27 changed files with 175 additions and 124 deletions
+12 -5
View File
@@ -367,14 +367,14 @@ defined in the global file therefore loads in every project. To stop it loading
one project, add an entry **with the same name the Agent's global file uses** and
mark it `disabled`.
This works with three clients only:
This works with four clients only:
| Client | Supported | What Skillshare writes |
|---|---|---|
| Claude Code | Yes | `~/.claude.json`: the name, in this project's `disabledMcpServers` list |
| OpenCode | Yes | `opencode.json`: `"NAME": {"enabled": false}` |
| Kilo Code | Yes | `kilo.jsonc`: `"NAME": {"enabled": false}` |
| Pi | No | Requires a complete entry: use `piOptions: {enabled: false}` on a server with command/url |
| Pi | Yes, from `mcp.projects` | `.pi/mcp.json`: `"NAME": {"command": "...", "enabled": false}`, see below |
| Codex | No | See below |
| Every other client | No | Selecting one is an error; nothing is written |
@@ -391,6 +391,14 @@ no `command` or `url`, and Codex then fails to load its whole configuration with
could stop Codex from starting for another. Turn the server off per machine instead,
with `enabled = false` in `~/.codex/config.toml`.
Pi replaces a global entry with the project entry of the same name, and skips an entry
without a `command` or `url`. So for Pi, Skillshare writes the global server's `command`,
or its `url` without the query, next to `enabled: false`. A disabled server is never
started, so args, env and headers stay out of the project file, and other projects keep
the server. Every sync rewrites the entry from the global server. This needs the global
server, so it works for a project under `mcp.projects` in the global config; a project's
own config cannot see the global one, and `pi` in a `disabled` entry there is an error.
### OpenCode and Kilo Code
```bash
@@ -959,8 +967,8 @@ file; add `-l` for a project. `pi mcp list` checks connections by starting every
server; `pi mcp login NAME` requires user approval.
Pi server names allow only letters, digits, `_` and `-`. A Pi project entry replaces the
global entry of the same name, so Pi cannot take a switch-only `disabled` entry. To turn
off a global server in one project, use `piOptions: {enabled: false}` on a complete entry.
global entry of the same name; to turn off a global server in one project, see
[Turn off a global server in one project](#turn-off-a-global-server-in-one-project).
### Other Pi settings {#pi-options}
@@ -1051,7 +1059,6 @@ What the next sync does:
| `mcp.directTools`, or a project's `directTools` under `mcp.projects` | The default is written into each server that reaches Pi and has no value of its own, as above. A project's `false` overrides the global value |
| `piOptions.includeTools` / `excludeTools` | `tools.allow` / `tools.deny`; a `directTools` next to them still becomes `piOptions.exposure` |
| Other `pi-mcp-adapter` fields in `piOptions`: `approveTools`, `auth`, `bearerToken`, `bearerTokenEnv`, `bearerTokenStore`, `caFile`, `debug`, `exposeResources`, `idleTimeout`, `inheritEnv`, `lifecycle`, `protocolVersion`, `requestHeadersCommand`, `requestTimeoutMs`, `searchKeywords`, `socket`, `tasks`, `toolPrefix`, `trace` | Removed, because Pi's built-in MCP does not read them |
| `pi` in the `targets` of a `disabled` entry | `pi` is removed from that list. Pi cannot take a switch-only entry, so that server is on again there; to keep it off, add a complete entry with `piOptions: {enabled: false}` |
A `directTools`, `includeTools` or `excludeTools` that would overwrite an exposure the
server already sets, or that is not a list of tool names, is dropped with its own
@@ -274,14 +274,14 @@ Agent は自身の global MCP ファイルと project のファイルを合わ
ファイルで定義されたサーバーはすべての project で読み込まれます。1 つの project だけでそれを読み込まれないようにするには、**Agent の global ファイルが使っているのと同じ名前**のエントリを追加し、
`disabled` を指定します。
これは以下の 3 つのクライアントでのみ機能します。
これは以下の 4 つのクライアントでのみ機能します。
| クライアント | 対応 | Skillshare が書き込む内容 |
|---|---|---|
| Claude Code | Yes | `~/.claude.json`: この project の `disabledMcpServers` リストにその名前を追加 |
| OpenCode | Yes | `opencode.json`: `"NAME": {"enabled": false}` |
| Kilo Code | Yes | `kilo.jsonc`: `"NAME": {"enabled": false}` |
| Pi | No | 完全なエントリが必要:command/url を持つサーバーに `piOptions: {enabled: false}` を設定 |
| Pi | Yes(`mcp.projects` から) | `.pi/mcp.json`: `"NAME": {"command": "...", "enabled": false}`、下記参照 |
| Codex | No | 下記参照 |
| その他すべてのクライアント | No | 選択するとエラー。何も書き込まれない |
@@ -293,6 +293,13 @@ global config がそのサーバーを定義しているマシンでは `enabled
別のメンバーの Codex の起動を止めてしまう可能性があります。代わりに、マシンごとに `~/.codex/config.toml` で
`enabled = false` を指定してサーバーをオフにしてください。
Pi は project の同名エントリで global エントリを丸ごと置き換え、`command` も `url` もないエントリは読み飛ばします。
そのため Pi には、global サーバーの `command`、またはクエリを除いた `url` を `enabled: false` と一緒に書き込みます。
オフにしたサーバーは起動しないので、args、env、headers は project ファイルに書き込まれず、他の project では
そのサーバーがそのまま使われます。sync のたびにエントリは global サーバーから書き直されます。global サーバーが
必要なので、これは global config の `mcp.projects` 配下の project でのみ機能します。project 自身の config からは
global サーバーが見えないため、そこで `disabled` エントリに `pi` を指定するとエラーになります。
### OpenCode と Kilo Code
```bash
@@ -819,9 +826,8 @@ Pi だけの簡単な設定なら、`pi mcp add` でグローバルファイル
ユーザーの承認が必要です。
Pi のサーバー名には英数字、`_`、`-` のみを使えます。Pi では project のエントリが同名の global
エントリを丸ごと置き換えるため、スイッチだけの `disabled` エントリは Pi を対象にできません。
1 つの project で global サーバーをオフにするには、完全なエントリに `piOptions: {enabled: false}`
を設定してください。
エントリを丸ごと置き換えます。1 つの project で global サーバーをオフにするには、
[1 つの project だけで global サーバーをオフにする](#turn-off-a-global-server-in-one-project)を参照してください。
### その他の Pi 設定 {#pi-options}
@@ -906,7 +912,6 @@ sync がサーバーをこれらの extension から移すとき、`sync mcp --d
| `mcp.directTools`、または `mcp.projects` 配下の project の `directTools` | 既定値が、Pi に届き自身の値を持たない各サーバーに上記のとおり書き込まれる。project の `false` はグローバルの値より優先される |
| `piOptions.includeTools` / `excludeTools` | `tools.allow` / `tools.deny`。一緒に設定した `directTools` は引き続き `piOptions.exposure` になる |
| `piOptions` 内のその他の `pi-mcp-adapter` フィールド: `approveTools`、`auth`、`bearerToken`、`bearerTokenEnv`、`bearerTokenStore`、`caFile`、`debug`、`exposeResources`、`idleTimeout`、`inheritEnv`、`lifecycle`、`protocolVersion`、`requestHeadersCommand`、`requestTimeoutMs`、`searchKeywords`、`socket`、`tasks`、`toolPrefix`、`trace` | Pi の内蔵 MCP が読まないため削除される |
| `disabled` エントリの `targets` 内の `pi` | そのリストから `pi` が削除される。Pi はスイッチだけのエントリを受け付けないため、そのサーバーはその project で再びオンになる。オフのままにするには、`piOptions: {enabled: false}` を持つ完全なエントリを追加する |
サーバーがすでに設定している exposure を上書きしてしまう `directTools`、`includeTools`、`excludeTools`、
またはツール名のリストではないものは、それぞれ独自の warning とともに破棄されます。
@@ -360,14 +360,14 @@ Agent는 자체 global MCP 파일과 프로젝트 파일을 함께 읽습니다.
막으려면, **Agent의 global 파일이 사용하는 것과 동일한 이름**으로 항목을 추가하고
`disabled`로 표시하세요.
이는 다음 세 client에서만 동작합니다.
이는 다음 네 client에서만 동작합니다.
| Client | Supported | What Skillshare writes |
|---|---|---|
| Claude Code | 예 | `~/.claude.json`: 이름을 이 프로젝트의 `disabledMcpServers` 목록에 추가 |
| OpenCode | 예 | `opencode.json`: `"NAME": {"enabled": false}` |
| Kilo Code | 예 | `kilo.jsonc`: `"NAME": {"enabled": false}` |
| Pi | 아니요 | 완전한 항목 필요: command/url이 있는 서버에 `piOptions: {enabled: false}` 사용 |
| Pi | 예, `mcp.projects`에서 | `.pi/mcp.json`: `"NAME": {"command": "...", "enabled": false}`, 아래 참조 |
| Codex | 아니요 | 아래 참고 |
| Every other client | 아니요 | 하나를 선택하면 오류가 발생하며 아무것도 작성되지 않음 |
@@ -384,6 +384,14 @@ Codex는 다른 이유로 거부됩니다. Codex는 `.codex/config.toml`을 필
Codex 시작을 막을 수 있습니다. 대신 `~/.codex/config.toml`에서 `enabled = false`로
머신별로 서버를 끄세요.
Pi는 같은 이름의 프로젝트 항목으로 global 항목을 통째로 대체하고, `command`나 `url`이 없는 항목은
건너뜁니다. 그래서 Pi에는 global 서버의 `command`, 또는 query를 뺀 `url`을 `enabled: false`와 함께
씁니다. 꺼진 서버는 시작되지 않으므로 args, env, headers는 프로젝트 파일에 쓰지 않으며, 다른
프로젝트는 그 서버를 그대로 사용합니다. sync할 때마다 이 항목은 global 서버를 기준으로 다시
작성됩니다. global 서버가 필요하므로 global 구성의 `mcp.projects` 아래 프로젝트에서만 동작합니다.
프로젝트 자체 구성에서는 global 서버를 볼 수 없으므로, 그곳의 `disabled` 항목에 `pi`를 쓰면
오류가 납니다.
### OpenCode and Kilo Code
```bash
@@ -934,9 +942,8 @@ project에는 `-l`을 추가하세요. `pi mcp list`는 활성 서버를 모두
`pi mcp login NAME`은 사용자 승인이 필요합니다.
Pi 서버 이름에는 영문자, 숫자, `_`, `-`만 쓸 수 있습니다. Pi에서는 프로젝트 항목이 같은 이름의
global 항목을 통째로 대체하므로 스위치만 있는 `disabled` 항목은 Pi를 target으로 삼을 수
없습니다. 한 프로젝트에서 global 서버를 끄려면 완전한 항목에 `piOptions: {enabled: false}`를
사용하세요.
global 항목을 통째로 대체합니다. 한 프로젝트에서 global 서버를 끄려면
[Turn off a global server in one project](#turn-off-a-global-server-in-one-project)를 참고하세요.
### 기타 Pi 설정 {#pi-options}
@@ -1025,7 +1032,6 @@ config도 그대로 로드됩니다. `sync mcp --dry-run`과 `sync mcp`는 발
| `mcp.directTools`, 또는 `mcp.projects` 아래 프로젝트의 `directTools` | Pi에 전달되고 자체 값이 없는 각 서버에 기본값이 위와 같이 작성됩니다. 프로젝트의 `false`는 global 값을 재정의합니다 |
| `piOptions.includeTools` / `excludeTools` | `tools.allow` / `tools.deny`가 되며, 함께 설정한 `directTools`는 여전히 `piOptions.exposure`가 됩니다 |
| `piOptions`의 그 밖의 `pi-mcp-adapter` 필드: `approveTools`, `auth`, `bearerToken`, `bearerTokenEnv`, `bearerTokenStore`, `caFile`, `debug`, `exposeResources`, `idleTimeout`, `inheritEnv`, `lifecycle`, `protocolVersion`, `requestHeadersCommand`, `requestTimeoutMs`, `searchKeywords`, `socket`, `tasks`, `toolPrefix`, `trace` | Pi 내장 MCP가 읽지 않으므로 제거됩니다 |
| `disabled` 항목의 `targets`에 있는 `pi` | 그 목록에서 `pi`가 제거됩니다. Pi는 스위치만 있는 항목을 받지 않으므로, 그 서버는 해당 프로젝트에서 다시 켜집니다. 계속 끄려면 `piOptions: {enabled: false}`가 있는 완전한 항목을 추가하세요 |
서버가 이미 설정한 exposure를 덮어쓰게 되거나 도구 이름 목록이 아닌 `directTools`,
`includeTools`, `excludeTools`는 별도의 warning과 함께 버려집니다.
@@ -362,14 +362,14 @@ mcp:
某个项目中加载,请添加一个**名称与该 Agent 的 global 文件所用名称相同**的条目,
并将其标记为 `disabled`。
这个方法仅适用于三个 client:
这个方法仅适用于四个 client:
| Client | 是否支持 | Skillshare 写入的内容 |
|---|---|---|
| Claude Code | 是 | `~/.claude.json`:在此项目的 `disabledMcpServers` 列表中写入名称 |
| OpenCode | 是 | `opencode.json`:`"NAME": {"enabled": false}` |
| Kilo Code | 是 | `kilo.jsonc`:`"NAME": {"enabled": false}` |
| Pi | 否 | 需要完整条目:在有 command/url 的 server 上使用 `piOptions: {enabled: false}` |
| Pi | 是,从 `mcp.projects` | `.pi/mcp.json`: `"NAME": {"command": "...", "enabled": false}`,见下文 |
| Codex | 否 | 见下文 |
| 其他所有 client | 否 | 选择其中任何一个都会报错;不会写入任何内容 |
@@ -386,6 +386,13 @@ Codex 因不同的原因被拒绝。它确实会将 `.codex/config.toml` 逐字
可能会导致另一位队友的 Codex 无法启动。请改为在每台机器上单独
关闭该 server,在 `~/.codex/config.toml` 中设置 `enabled = false`。
Pi 会用项目中的同名条目整条替换 global 条目,并跳过没有 `command` 或 `url` 的条目。
因此对 Pi,Skillshare 会写入 global server 的 `command`,或去掉 query 的 `url`,再加上
`enabled: false`。被关闭的 server 不会启动,所以 args、env 和 headers 都不会写进项目文件,
其他项目也照常使用该 server。每次同步都会根据 global server 重写这个条目。这需要 global
server,所以只适用于 global 配置中 `mcp.projects` 下的项目;项目自己的配置看不到 global
server,在那里的 `disabled` 条目中使用 `pi` 会报错。
### OpenCode 和 Kilo Code
```bash
@@ -911,8 +918,8 @@ mcp:
`pi mcp list` 会启动每个已启用的 server 来检查连接;`pi mcp login NAME` 需要用户批准。
Pi 的 server 名称只允许字母、数字、`_` 和 `-`。Pi 的项目条目会整条替换 global
中的同名条目,因此 Pi 不接受只有开关的 `disabled` 条目。要在单个项目中关闭
global server,请改为在完整条目上使用 `piOptions: {enabled: false}`。
中的同名条目;要在单个项目中关闭 global server,请参阅
[在单个项目中关闭一个 global server](#turn-off-a-global-server-in-one-project)。
### 其他 Pi 设置 {#pi-options}
@@ -996,7 +1003,6 @@ pi-mcp-adapter` 或 `pi-mcp-extension`、`directTools`,以及下方列出的 `
| `mcp.directTools`,或 `mcp.projects` 下某个项目的 `directTools` | 该默认值会写入每个送往 Pi 且没有自身值的 server,转换方式同上。项目的 `false` 会覆盖 global 值 |
| `piOptions.includeTools` / `excludeTools` | `tools.allow` / `tools.deny`;同时设置的 `directTools` 仍会转为 `piOptions.exposure` |
| `piOptions` 中其他 `pi-mcp-adapter` 字段:`approveTools`、`auth`、`bearerToken`、`bearerTokenEnv`、`bearerTokenStore`、`caFile`、`debug`、`exposeResources`、`idleTimeout`、`inheritEnv`、`lifecycle`、`protocolVersion`、`requestHeadersCommand`、`requestTimeoutMs`、`searchKeywords`、`socket`、`tasks`、`toolPrefix`、`trace` | 移除,因为 Pi 的内置 MCP 不会读取它们 |
| `disabled` 条目 `targets` 中的 `pi` | 从该列表中移除 `pi`。Pi 不接受只有开关的条目,因此该 server 在那个 project 中会重新启用;要保持关闭,请添加带有 `piOptions: {enabled: false}` 的完整条目 |
如果 `directTools`、`includeTools` 或 `excludeTools` 会覆盖该 server 已设置的
exposure,或者不是工具名称列表,就会被丢弃,并给出单独的 warning。
@@ -328,14 +328,14 @@ global 檔案中的 server 會在每個 project 中載入。若要讓它在某
project 中不要載入,請新增一個**使用該 Agent 的 global 檔案中相同名稱**的項目,
並標記為 `disabled`。
這只適用於三種 clients:
這只適用於四種 clients:
| Client | 是否支援 | Skillshare 會寫入什麼 |
|---|---|---|
| Claude Code | 是 | `~/.claude.json`:名稱會加入這個 project 的 `disabledMcpServers` 清單 |
| OpenCode | 是 | `opencode.json`:`"NAME": {"enabled": false}` |
| Kilo Code | 是 | `kilo.jsonc`:`"NAME": {"enabled": false}` |
| Pi | 否 | 需要完整 entry:在有 command/url 的 server 上使用 `piOptions: {enabled: false}` |
| Pi | 是,從 `mcp.projects` | `.pi/mcp.json`: `"NAME": {"command": "...", "enabled": false}`,見下方 |
| Codex | 否 | 見下方說明 |
| 其他所有 client | 否 | 選擇它會是錯誤;不會寫入任何內容 |
@@ -352,6 +352,13 @@ global 檔案之上,所以在 global config 有定義該 server 的機器上
可能導致另一個隊友的 Codex 無法啟動。請改為逐機器關閉該 server,
在 `~/.codex/config.toml` 中設定 `enabled = false`。
Pi 會用 project 中的同名項目整筆取代 global 項目,並略過沒有 `command` 或 `url` 的項目。
因此對 Pi,Skillshare 會寫入 global server 的 `command`,或去掉 query 的 `url`,再加上
`enabled: false`。被關閉的 server 不會啟動,所以 args、env 和 headers 都不會寫進 project
檔案,其他 project 也照常使用該 server。每次同步都會依 global server 重寫這個項目。這需要
global server,所以只適用於 global config 中 `mcp.projects` 底下的 project;project 自己的
config 看不到 global server,在那裡的 `disabled` 項目中使用 `pi` 會報錯。
### OpenCode and Kilo Code
```bash
@@ -873,8 +880,8 @@ mcp:
server 檢查連線;`pi mcp login NAME` 需要使用者授權。
Pi 的 server 名稱只接受字母、數字、`_` 和 `-`。Pi 的 project 項目會整筆取代 global
中的同名項目,因此 Pi 無法接受只有開關的 `disabled` 項目。要在單一 project 中關閉
global server,請改在完整的項目上使用 `piOptions: {enabled: false}`。
中的同名項目;要在單一 project 中關閉 global server,請見
[Turn off a global server in one project](#turn-off-a-global-server-in-one-project)。
### 其他 Pi 設定 {#pi-options}
@@ -958,7 +965,6 @@ servers,例如:
| `mcp.directTools`,或 `mcp.projects` 下某個 project 的 `directTools` | 預設值會依上述方式,寫入每個送往 Pi 且沒有自己值的 server。project 的 `false` 會覆寫 global 的值 |
| `piOptions.includeTools` / `excludeTools` | `tools.allow` / `tools.deny`;同時設定的 `directTools` 仍會轉為 `piOptions.exposure` |
| `piOptions` 中其他 `pi-mcp-adapter` 欄位:`approveTools`、`auth`、`bearerToken`、`bearerTokenEnv`、`bearerTokenStore`、`caFile`、`debug`、`exposeResources`、`idleTimeout`、`inheritEnv`、`lifecycle`、`protocolVersion`、`requestHeadersCommand`、`requestTimeoutMs`、`searchKeywords`、`socket`、`tasks`、`toolPrefix`、`trace` | 移除,因為 Pi 內建 MCP 不會讀取它們 |
| `disabled` 項目 `targets` 中的 `pi` | 從該清單中移除 `pi`。Pi 無法接受只有開關的項目,所以該 server 在那個 project 會重新啟用;要繼續關閉,請加上帶有 `piOptions: {enabled: false}` 的完整項目 |
若 `directTools`、`includeTools` 或 `excludeTools` 會覆寫 server 已設定的曝光模式,或不是
工具名稱清單,就會被捨棄,並顯示各自的 warning。