Sep 2640 python sdk support

[vijaydeepsinha]

Fixes #3486

Summary

Adds Python SDK support for SEP-2640 (Skills Extension): skills/list, skills/get, and resources/directory/read as protocol primitives, SEP-2640 conformance validation, and capability negotiation. This SDK does not provide filesystem discovery, catalog indexing, or caching/refresh policy — those belong to a higher-level provider built on top of this.

Motivation and Context

SEP-2640 defines a convention for serving Agent Skills over MCP using the Resources primitive. The Python SDK has no support for it today. This PR adds the extension using the SDK's existing Extension/MethodBinding mechanism (the same one backing the shipped Apps extension, SEP-2133) — no schema or codegen changes, no new required dependencies.

What's included

• src/mcp/shared/skills.py — wire types (Skill, SkillResource, params/results), SEP-2640 conformance validation (name/URI/frontmatter consistency, digest format, resource-manifest completeness, the 512-entry/16 MiB limits), and verify_skill_resource (digest+size integrity check for content already read).
• src/mcp/server/skills.py — the Skills extension: handler-based (list_skills, get_skill, optional read_directory), validates results against SEP-2640 before they hit the wire, gates the SEP-2549 ttlMs/cacheScope fields to protocol version 2026-07-28+.
• src/mcp/client/skills.py — list_skills/get_skill/read_directory (auto-paginating, with cursor-repeat detection), read_skill_uri (a thin, discoverable resources/read alias), verify_skill_resource re-exported for client use.
• docs/advanced/skills.md + docs_src/skills/ — a new doc page with a runnable example, explicitly scoping what the SDK does and doesn't do.

Server usage

from mcp.server.skills import Skills
from mcp.shared.skills import ListSkillsResult, GetSkillResult

async def list_skills(ctx, params):
    return ListSkillsResult(skills=[...])

async def get_skill(ctx, params):
    if params.uri != "skill://git-workflow/SKILL.md":
        raise MCPError(code=INVALID_PARAMS, message="unknown skill")
    return GetSkillResult(skill=...)

mcp = MCPServer("catalog", extensions=[Skills(list_skills=list_skills, get_skill=get_skill)])
mcp.add_resource(TextResource(uri="skill://git-workflow/SKILL.md", ...))  # file content is served normally

Client usage

from mcp.client.skills import get_skill, list_skills, read_skill_uri, verify_skill_resource

skills = await list_skills(client.session)
skill = await get_skill(client.session, "skill://git-workflow/SKILL.md")
result = await read_skill_uri(client.session, skill.uri)
verify_skill_resource(skill, skill.uri, result.contents[0].text.encode())

Protocol version / compatibility notes

• capabilities.extensions (SEP-2133) and ttlMs/cacheScope (SEP-2549) are 2026-07-28+-only wire fields in this SDK's existing type surface — this is pre-existing, documented SDK behavior (docs/advanced/extensions.md), not something this PR changes. Skills gates its own cache fields to match.
• A JSON-RPC -32602 error returns HTTP 200 on the classic (pre-2026-07-28) wire and HTTP 400 on the modern (2026-07-28+) wire. This is existing, spec-mandated (SEP-2575) SDK-wide transport behavior — every handler in the SDK gets it automatically via the shared ERROR_CODE_HTTP_STATUS table; nothing Skills-specific.
• No breaking changes to any existing public API. All new files; the only touched existing file is mkdocs.yml (one nav entry).

How Has This Been Tested?

• tests/{shared,server,client,docs_src}/test_skills.py — 100% line+branch coverage on all three new modules (shared/skills.py, server/skills.py, client/skills.py), verified via coverage report --fail-under=0.
• Full suite: ./scripts/test → 6000+ passed, 0 failed, 100% total coverage, strict-no-cover clean.
• ruff format/ruff check, pyright, markdownlint, mkdocs build --strict (Zensical), README-snippet check: all clean.
• Cross-version: uv run --python 3.10 pytest tests/*/test_skills.py passes.

Conformance

Ran the modelcontextprotocol/conformance PR #330 SEP-2640 scenarios end-to-end against a real server and client built on this implementation (server scenarios exercise this PR's server; client scenarios exercise this PR's client against a hostile server the harness stands up):

Scenario	Checks	Result
sep-2640-skills-enumeration (skills/list + skills/get)	30	✅ 30/30
sep-2640-skills-manifest (SKILL.md resource metadata)	6	✅ 6/6
sep-2640-skills-directory (resources/directory/read)	7	✅ 7/7
sep-2640-client-no-prefetch	1	✅ PASS
sep-2640-client-verify-digest	1	✅ PASS
sep-2640-client-verify-size	1	✅ PASS
sep-2640-client-verify-frontmatter	1	✅ PASS
sep-2640-client-verify-unlisted	1	✅ PASS

43 wire checks + 5 client checks, 0 failures, 0 warnings.

Also manually verified via a live server against a Postman collection covering both the session-based (2025-11-25) and stateless (2026-07-28) wires.

Breaking Changes

None. New files only; no existing public API is modified.

Deliberate scope exclusions (and why)

• Filesystem discovery/indexing/caching: this SDK gives the protocol primitives only; a higher-level provider library (e.g. one that walks a directory tree and computes digests) builds on top of Skills, list_skills, and get_skill.
• Client-side frontmatter parsing: SEP-2640 requires hosts to parse a SKILL.md's YAML frontmatter and compare it field-by-field against the held entry. This SDK does not ship that comparison, to avoid adding a new required YAML dependency to the core SDK for a check any host already has the means to do with whatever YAML library it uses elsewhere. verify_skill_resource covers the digest/size half (no new dependency needed for that). Documented explicitly in docs/advanced/skills.md's "What this SDK doesn't do".
• Skills types living in mcp-types instead of mcp.shared: mcp-types is generated from the official, versioned MCP JSON Schema; SEP-2640 is an extension, not core spec vocabulary, so its types are hand-written and live alongside the extension code — the same placement the existing Apps extension (SEP-2133) uses.

Types of changes

• New feature (non-breaking change which adds functionality)
• Documentation update

Checklist

• I am assigned to the linked issue (or it is labeled help wanted, or I'm a maintainer) — N/A while targeting my own fork; will file/link before retargeting to upstream
• I have disclosed any AI assistance and can explain the change in my own words
• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[pja-ant]

Assigned #3486 to @vijaydeepsinha and re-opened

[cubic-dev-ai]

All reported issues were addressed across 12 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 9 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="tests/client/test_skills.py">

<violation number="1" location="tests/client/test_skills.py:299">
P2: The assertion checks `m.get("progress_token")`, but the wrapper only ever sets the camelCase key: `ListSkillsParams.model_validate({"_meta": {"progressToken": "t"}})`. Pydantic does not alias keys inside the `_meta` dict, and `send_request` dumps it with `model_dump(by_alias=True)`, so the server handler's `params.meta` contains `"progressToken"`, not `"progress_token"` — `m.get("progress_token")` is `None`, making `m.get(...) == "t"` always False and the test fail (or, if a transport layer renames keys, the check no longer verifies that the caller's token reached the server, contradicting the docstring). Assert on `"progressToken"` instead.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: The assertion checks m.get("progress_token"), but the wrapper only ever sets the camelCase key: ListSkillsParams.model_validate({"_meta": {"progressToken": "t"}}). Pydantic does not alias keys inside the _meta dict, and send_request dumps it with model_dump(by_alias=True), so the server handler's params.meta contains "progressToken", not "progress_token" — m.get("progress_token") is None, making m.get(...) == "t" always False and the test fail (or, if a transport layer renames keys, the check no longer verifies that the caller's token reached the server, contradicting the docstring). Assert on "progressToken" instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At tests/client/test_skills.py, line 299:

<comment>The assertion checks `m.get("progress_token")`, but the wrapper only ever sets the camelCase key: `ListSkillsParams.model_validate({"_meta": {"progressToken": "t"}})`. Pydantic does not alias keys inside the `_meta` dict, and `send_request` dumps it with `model_dump(by_alias=True)`, so the server handler's `params.meta` contains `"progressToken"`, not `"progress_token"` — `m.get("progress_token")` is `None`, making `m.get(...) == "t"` always False and the test fail (or, if a transport layer renames keys, the check no longer verifies that the caller's token reached the server, contradicting the docstring). Assert on `"progressToken"` instead.</comment>

<file context>
@@ -253,3 +253,47 @@ async def test_list_skills_starts_from_a_caller_supplied_cursor() -> None:
+    # The transport enriches `_meta` with its own keys; what matters is the caller's token
+    # reaching the server on both the first page and the cursor-following second one.
+    assert len(seen_meta) == 2
+    assert all(m is not None and m.get("progress_token") == "t" for m in seen_meta)
</file context>

Suggested change

	assert all(m is not None and m.get("progress_token") == "t" for m in seen_meta)
	assert all(m is not None and m.get("progressToken") == "t" for m in seen_meta)