From fdca87a1ffd46394435210c73550f0495226966f Mon Sep 17 00:00:00 2001 From: Willie Date: Thu, 15 Oct 2026 21:34:45 +0800 Subject: [PATCH] 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. --- internal/skillserve/server_test.go | 8 +++++++- internal/skillserve/tools.go | 6 ++++++ skills/skillshare/references/mcp.md | 2 +- website/docs/reference/commands/mcp.md | 5 +++-- .../current/reference/commands/mcp.md | 2 +- .../current/reference/commands/mcp.md | 1 + .../current/reference/commands/mcp.md | 3 ++- .../current/reference/commands/mcp.md | 3 ++- 8 files changed, 23 insertions(+), 7 deletions(-) diff --git a/internal/skillserve/server_test.go b/internal/skillserve/server_test.go index 4224a676a..29c5497c4 100644 --- a/internal/skillserve/server_test.go +++ b/internal/skillserve/server_test.go @@ -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) diff --git a/internal/skillserve/tools.go b/internal/skillserve/tools.go index 2b9fce820..78a060418 100644 --- a/internal/skillserve/tools.go +++ b/internal/skillserve/tools.go @@ -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) } diff --git a/skills/skillshare/references/mcp.md b/skills/skillshare/references/mcp.md index f1f7d9554..3a493d13d 100644 --- a/skills/skillshare/references/mcp.md +++ b/skills/skillshare/references/mcp.md @@ -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. diff --git a/website/docs/reference/commands/mcp.md b/website/docs/reference/commands/mcp.md index 3dbb03976..66a549f1c 100644 --- a/website/docs/reference/commands/mcp.md +++ b/website/docs/reference/commands/mcp.md @@ -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 diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/mcp.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/mcp.md index 5d8539913..a90c7ce39 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/mcp.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/mcp.md @@ -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 を指定するとエラーになります。 diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/mcp.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/mcp.md index cff0b8f56..691dfaf2b 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/mcp.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/mcp.md @@ -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`은 diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/mcp.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/mcp.md index 17b47d7da..0a506fb61 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/mcp.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/mcp.md @@ -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 模式无关; diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/mcp.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/mcp.md index 7da47b286..4d40ee068 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/mcp.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/mcp.md @@ -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`