feat(mcp): mark the mcp serve skill tools read-only

Clients and gateways that gate tools by annotation treat a tool without
readOnlyHint as one that changes data. Executor v2 does, so every
list_skills or read_skill call could stop for approval even though both
only read the skills source. Marking them read-only lets those clients
call them without asking. Refs: #540.
This commit is contained in:
Willie
2026-10-15 21:34:45 +08:00
parent 750059af31
commit fdca87a1ff
8 changed files with 23 additions and 7 deletions
+7 -1
View File
@@ -187,9 +187,15 @@ func TestServer_ToolsListAndReadSkillsForClientsWithoutTheExtension(t *testing.T
writeFile(t, filepath.Join(src, "review", "SKILL.md"), skillMD("review"))
cs := connect(t, src)
if tools, err := cs.ListTools(context.Background(), nil); err != nil || len(tools.Tools) != 2 {
tools, err := cs.ListTools(context.Background(), nil)
if err != nil || len(tools.Tools) != 2 {
t.Fatalf("tools/list = %v, %v; want list_skills and read_skill", tools, err)
}
for _, tool := range tools.Tools {
if tool.Annotations == nil || !tool.Annotations.ReadOnlyHint {
t.Errorf("%s annotations = %+v, want readOnlyHint so clients do not ask to approve a read", tool.Name, tool.Annotations)
}
}
list, _ := callTool(t, cs, "list_skills", map[string]any{"query": "PDF"})
if !strings.Contains(list, "skill://pdf/SKILL.md") || strings.Contains(list, "review") {
t.Errorf("list_skills query=PDF:\n%s", list)
+6
View File
@@ -27,14 +27,20 @@ type readToolInput struct {
URI string `json:"uri" jsonschema:"A skill:// URI from list_skills, or one of the files read_skill lists for a skill"`
}
// readOnly marks both tools so clients that gate mutating tools behind approval
// call them without asking.
var readOnly = &mcp.ToolAnnotations{ReadOnlyHint: true}
func (s *service) addTools(srv *mcp.Server) {
mcp.AddTool(srv, &mcp.Tool{
Name: "list_skills",
Description: "List the available skills: name, when to use it, and its URI. Read a skill with read_skill before following it.",
Annotations: readOnly,
}, s.listTool)
mcp.AddTool(srv, &mcp.Tool{
Name: "read_skill",
Description: "Read a skill's SKILL.md, or one of its other files, by skill:// URI. Reading SKILL.md also lists the skill's other files.",
Annotations: readOnly,
}, s.readTool)
srv.AddReceivingMiddleware(hideToolsFromNativeClients)
}
+1 -1
View File
@@ -71,7 +71,7 @@ skillshare mcp serve --check [--target NAME] # List skills serve would s
remote `url` with `bearerToken: {fromEnv: SKILLSHARE_MCP_TOKEN}`. Agents with the Skills
extension load skills natively; as of October 2026 Codex, Cursor, VS Code, Goose and Pi
lack it and Claude Code's is off by default, so the server also offers `list_skills`
(`query` filters) and `read_skill` tools, hidden from clients that declare the extension. Verify the server with
(`query` filters) and `read_skill` tools, marked `readOnlyHint` and hidden from clients that declare the extension. Verify the server with
`npx @modelcontextprotocol/inspector --cli skillshare mcp serve --method skills/list --verify`.
- Noninteractive `import` without a name only lists candidates. Use `--replace` only
when replacing is intended.
+3 -2
View File
@@ -863,8 +863,9 @@ answer lists at most 200), and `read_skill` reads a `SKILL.md` or another file o
and for a `SKILL.md` lists the skill's other files. Any Agent that uses MCP tools can read
skills this way, including through a gateway that passes tools on. A client that declares
the Skills extension loads skills natively and is not offered the tools, so it does not
see each skill twice. Content read through a tool is ordinary text to the Agent: its own
skill approval does not apply.
see each skill twice. Both tools are marked `readOnlyHint`, so a client or gateway that
asks before tools that change data calls them without asking. Content read through a tool
is ordinary text to the Agent: its own skill approval does not apply.
- **Selection.** Without `--target`, every enabled skill is served. `--target NAME`
applies that target's `include`/`exclude` filters and frontmatter `targets`, whatever
@@ -695,7 +695,7 @@ SKILLSHARE_MCP_TOKEN=change-me skillshare mcp serve --http 0.0.0.0:8765 \
`mcp serve` は、Skill の同期先フォルダーにアクセスできない Agent(使い捨ての VM 上の Agent や MCP gateway の背後にある Agent など)向けの読み取り専用 MCP サーバーです。[Skills extension](https://modelcontextprotocol.io/seps/2640-skills-extension)
(`io.modelcontextprotocol/skills`、SEP-2640)の `skills/list`、`skills/get`、`resources/read` を実装しています。各 Skill は 1 つのエントリで、その URI は `skill://_team/tools/pdf/SKILL.md` のように source 内のパスに従います。エントリには frontmatter 全体と、`sha256` ダイジェストとサイズ付きのすべてのファイルが含まれます。自分のマシン上の Agent はすでに `sync` で Skill を受け取っているため、それらを `mcp serve` にも接続すると各 Skill が二重に表示されます。
ほとんどの Agent はまだ Skills extension に対応していないため(下記参照)、サーバーは 2 つのツールも提供します。`list_skills` は名前、説明、URI を一覧表示し(`query` で絞り込み可能。1 回の応答は最大 200 件)、`read_skill` は Skill の `SKILL.md` または他のファイルを読み、`SKILL.md` の場合はその Skill の他のファイルも一覧表示します。MCP ツールを使える Agent なら、ツールを中継する gateway 経由でも、この方法で Skill を読めます。Skills extension を宣言したクライアントは Skill をネイティブに読み込み、ツールは提供されないため、各 Skill が二重に表示されることはありません。ツール経由で読んだ内容は Agent にとって通常のテキストであり、Agent 自身の Skill 承認は適用されません。
ほとんどの Agent はまだ Skills extension に対応していないため(下記参照)、サーバーは 2 つのツールも提供します。`list_skills` は名前、説明、URI を一覧表示し(`query` で絞り込み可能。1 回の応答は最大 200 件)、`read_skill` は Skill の `SKILL.md` または他のファイルを読み、`SKILL.md` の場合はその Skill の他のファイルも一覧表示します。MCP ツールを使える Agent なら、ツールを中継する gateway 経由でも、この方法で Skill を読めます。Skills extension を宣言したクライアントは Skill をネイティブに読み込み、ツールは提供されないため、各 Skill が二重に表示されることはありません。両方のツールには `readOnlyHint` が付いているため、データを変更するツールの前に確認するクライアントや gateway も、確認なしで呼び出します。ツール経由で読んだ内容は Agent にとって通常のテキストであり、Agent 自身の Skill 承認は適用されません。
- **選択。** `--target` を指定しない場合、有効なすべての Skill が提供されます。`--target NAME`
は、sync mode にかかわらず、その target の `include`/`exclude` フィルターと frontmatter の `targets` を適用します。Skill は常に source から取得されます。Skill がオフになっている target を指定するとエラーになります。
@@ -818,6 +818,7 @@ SKILLSHARE_MCP_TOKEN=change-me skillshare mcp serve --http 0.0.0.0:8765 \
`read_skill`은 skill의 `SKILL.md`나 다른 파일을 읽고, `SKILL.md`를 읽을 때는 그 skill의 다른 파일 목록도 보여 줍니다.
MCP 도구를 사용하는 Agent라면 도구를 그대로 전달하는 게이트웨이를 거쳐도 이 방식으로 skill을 읽을 수 있습니다.
Skills extension을 선언한 client는 skill을 네이티브로 로드하며 도구를 제공받지 않으므로 각 skill이 두 번 보이지 않습니다.
두 도구 모두 `readOnlyHint`가 표시되어 있어, 데이터를 바꾸는 도구 앞에서 확인을 요청하는 client나 게이트웨이도 확인 없이 호출합니다.
도구로 읽은 내용은 Agent에게 일반 텍스트이며, Agent 자체의 skill 승인은 적용되지 않습니다.
- **선택.** `--target` 없이 실행하면 활성화된 모든 skill을 제공합니다. `--target NAME`은
@@ -801,7 +801,8 @@ SKILLSHARE_MCP_TOKEN=change-me skillshare mcp serve --http 0.0.0.0:8765 \
`read_skill` 读取某个 skill 的 `SKILL.md` 或其他文件,读取 `SKILL.md` 时还会列出该 skill 的
其他文件。任何使用 MCP 工具的 Agent 都能以这种方式读取 skill,包括通过会转发工具的 gateway。
声明了 Skills extension 的 client 会以原生方式加载 skill,不会得到这些工具,因此不会看到
两份 skill。通过工具读取的内容对 Agent 而言只是普通文本:Agent 自身的 skill 批准机制不适用。
两份 skill。两个工具都标记了 `readOnlyHint`,因此会在修改数据的工具前请求确认的 client 或
gateway 调用它们时不会请求确认。通过工具读取的内容对 Agent 而言只是普通文本:Agent 自身的 skill 批准机制不适用。
- **选择。** 不带 `--target` 时,会提供每一个已启用的 skill。`--target NAME`
会应用该 target 的 `include`/`exclude` 过滤器和 frontmatter `targets`,与其 sync 模式无关;
@@ -767,7 +767,8 @@ SKILLSHARE_MCP_TOKEN=change-me skillshare mcp serve --http 0.0.0.0:8765 \
`read_skill` 讀取某個 skill 的 `SKILL.md` 或其他檔案,讀取 `SKILL.md` 時也會列出該
skill 的其他檔案。任何會使用 MCP 工具的 Agent 都能這樣讀取 skills,包括透過會轉送工具的
gateway。宣告支援 Skills extension 的 client 會原生載入 skills,不會收到這些工具,因此
不會看到每個 skill 兩次。透過工具讀到的內容對 Agent 而言只是一般文字:Agent 本身的
不會看到每個 skill 兩次。兩個工具都標記了 `readOnlyHint`,所以會在修改資料的工具前要求
確認的 client 或 gateway,呼叫它們時不會要求確認。透過工具讀到的內容對 Agent 而言只是一般文字:Agent 本身的
skill 核准機制不適用。
- **選取。** 不帶 `--target` 時,會提供所有啟用的 skills。`--target NAME`