mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
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:
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`은
|
||||
|
||||
+2
-1
@@ -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 模式无关;
|
||||
|
||||
+2
-1
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user