@sammorrowdrums/mcpi-ext 0.2.1 → 1.0.0

package/dist/skills/sep2640/load.js

@@ -0,0 +1,90 @@
+import { base64ToBytes, SkillIntegrityError, textToBytes, verifyFrontmatter, verifyNamePath, verifyResourceRead, } from "./integrity.js";
+/**
+ * Tracks how many bytes a skill has actually pulled down.
+ *
+ * Only `"dynamic"` skills need this: a declared resource set is bounded before
+ * the first fetch, but a dynamic one can only be bounded by watching what
+ * arrives.
+ */
+export class SkillFetchBudget {
+    retrieved = 0;
+    get bytesRetrieved() {
+        return this.retrieved;
+    }
+    add(count) {
+        this.retrieved += count;
+    }
+}
+/**
+ * Read one resource belonging to a skill and verify it before returning it.
+ *
+ * Verification happens on the raw bytes, on every read, with no cached
+ * "already checked this" shortcut — a digest that was right last time says
+ * nothing about the bytes that just arrived.
+ *
+ * Callers receive content only if it verifies. There is deliberately no way to
+ * obtain the unverified bytes.
+ */
+export async function readSkillResource(options) {
+    const { policy, entry, serverName, uri, budget, signal } = options;
+    const result = await policy.readResource({
+        // SEP-2640 reads are authorized by exact membership in this entry's
+        // `resources` set, which the policy indexes per skill. Defaulting to the
+        // legacy `skill-load` source would consult the broader per-server skill
+        // index instead, which does not contain supporting files at all and is
+        // wider than the spec allows for the ones it does contain.
+        source: options.source ?? "skills-extension",
+        serverName,
+        uri,
+        skillUri: entry.uri,
+        ...(signal ? { signal } : {}),
+    });
+    const content = result.contents.find((item) => item.uri === uri) ?? result.contents[0];
+    if (!content) {
+        throw new SkillIntegrityError("no_text_content", `Read of ${uri} returned no content to verify.`, uri);
+    }
+    const bytes = contentBytes(content, uri);
+    verifyResourceRead(entry, uri, bytes, budget?.bytesRetrieved ?? 0);
+    budget?.add(bytes.length);
+    return { uri, bytes, text: new TextDecoder().decode(bytes) };
+}
+/**
+ * Load a skill's SKILL.md and prove it is the document the listing described.
+ *
+ * Three separate checks have to pass, and each catches something the others
+ * cannot: the digest proves the bytes are the advertised bytes, the
+ * field-by-field frontmatter comparison proves the listing did not describe the
+ * skill as one thing while serving another, and the name/path check proves the
+ * skill is not impersonating a different slot in the namespace.
+ *
+ * Returns the full document text; stripping frontmatter is the caller's job,
+ * because verification needs the document exactly as it was digested.
+ */
+export async function loadSkillDocument(options) {
+    const { policy, entry, serverName, budget, signal } = options;
+    verifyNamePath(entry);
+    const resource = await readSkillResource({
+        policy,
+        entry,
+        serverName,
+        uri: entry.uri,
+        ...(budget ? { budget } : {}),
+        ...(signal ? { signal } : {}),
+    });
+    verifyFrontmatter(entry, resource.text);
+    return resource;
+}
+/**
+ * Recover the raw bytes a resource content block represents.
+ *
+ * Text blocks are re-encoded as UTF-8 because that is what the digest covered;
+ * decoding and re-encoding is lossless for valid UTF-8 and any input that
+ * survives that round trip differently would have failed the digest anyway.
+ */
+function contentBytes(content, uri) {
+    if (typeof content.text === "string")
+        return textToBytes(content.text);
+    if (typeof content.blob === "string")
+        return base64ToBytes(content.blob);
+    throw new SkillIntegrityError("no_text_content", `Read of ${uri} returned neither text nor blob content.`, uri);
+}

package/dist/skills/sep2640/protocol.d.ts

@@ -0,0 +1,146 @@
+/**
+ * SEP-2640 wire schemas and entry-level validation.
+ *
+ * Everything here is pure: it turns an untrusted JSON-RPC result into a typed
+ * value, or refuses. No network, no filesystem, no policy decisions. The checks
+ * that SEP-2640 says are computable "from the listing alone, before any fetch"
+ * live here so they can run before a single byte is retrieved.
+ */
+import { z } from "zod";
+/**
+ * One declared supporting file. `digest` is the SHA-256 of the file's raw
+ * bytes; `size` is the count of those same bytes.
+ */
+export declare const SkillResourceRefSchema: z.ZodObject<{
+    uri: z.ZodString;
+    digest: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$loose>;
+/**
+ * A skill as advertised by `skills/list` / `skills/get`.
+ *
+ * `frontmatter` is the verbatim YAML-as-JSON the author wrote — not a curated
+ * subset — so it is typed as an open record and never narrowed on ingest.
+ * `resources` is either the complete declared set or the literal `"dynamic"`.
+ */
+export declare const SkillEntrySchema: z.ZodObject<{
+    uri: z.ZodString;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    resources: z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+        digest: z.ZodString;
+        size: z.ZodNumber;
+    }, z.core.$loose>>, z.ZodLiteral<"dynamic">]>;
+}, z.core.$loose>;
+export declare const SkillsListResultSchema: z.ZodObject<{
+    ttlMs: z.ZodOptional<z.ZodNumber>;
+    cacheScope: z.ZodOptional<z.ZodString>;
+    resultType: z.ZodOptional<z.ZodString>;
+    skills: z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+        frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        resources: z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+            uri: z.ZodString;
+            digest: z.ZodString;
+            size: z.ZodNumber;
+        }, z.core.$loose>>, z.ZodLiteral<"dynamic">]>;
+    }, z.core.$loose>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const SkillsGetResultSchema: z.ZodObject<{
+    ttlMs: z.ZodOptional<z.ZodNumber>;
+    cacheScope: z.ZodOptional<z.ZodString>;
+    resultType: z.ZodOptional<z.ZodString>;
+    skill: z.ZodObject<{
+        uri: z.ZodString;
+        frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        resources: z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+            uri: z.ZodString;
+            digest: z.ZodString;
+            size: z.ZodNumber;
+        }, z.core.$loose>>, z.ZodLiteral<"dynamic">]>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+export declare const DirectoryResourceSchema: z.ZodObject<{
+    uri: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    mimeType: z.ZodOptional<z.ZodString>;
+    size: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export declare const DirectoryReadResultSchema: z.ZodObject<{
+    resources: z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+        mimeType: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type SkillResourceRef = z.infer<typeof SkillResourceRefSchema>;
+export type SkillEntry = z.infer<typeof SkillEntrySchema>;
+export type SkillsListResult = z.infer<typeof SkillsListResultSchema>;
+export type SkillsGetResult = z.infer<typeof SkillsGetResultSchema>;
+export type DirectoryResource = z.infer<typeof DirectoryResourceSchema>;
+export type DirectoryReadResult = z.infer<typeof DirectoryReadResultSchema>;
+export type SkillValidationCode = "malformed_result" | "malformed_digest" | "resource_limit_exceeded" | "size_limit_exceeded" | "duplicate_resource_uri" | "skill_md_not_listed" | "missing_frontmatter_field" | "name_path_mismatch" | "dynamic_resources";
+/** A refusal to accept server-supplied skill metadata. Never a fetch failure. */
+export declare class SkillValidationError extends Error {
+    readonly code: SkillValidationCode;
+    readonly skillUri: string | undefined;
+    constructor(code: SkillValidationCode, message: string, skillUri?: string);
+}
+/** True only for exactly `sha256:` + 64 lowercase hex characters. */
+export declare function isValidDigest(digest: string): boolean;
+/** True when a `resources/directory/read` entry describes a directory. */
+export declare function isDirectoryResource(resource: DirectoryResource): boolean;
+/**
+ * The `<skill-path>` an entry URI addresses, i.e. everything up to but not
+ * including the trailing `/SKILL.md`. Returns `undefined` when the URI does not
+ * end in `/SKILL.md`.
+ */
+export declare function skillPathOf(uri: string): string | undefined;
+/** The final path segment of a skill path — the segment that must equal `frontmatter.name`. */
+export declare function finalPathSegment(skillPath: string): string;
+/**
+ * A skill's declared name, or `undefined` when frontmatter omits it or it is
+ * not a string. `name` and `description` are the two fields SEP-2640 requires.
+ */
+export declare function frontmatterName(entry: SkillEntry): string | undefined;
+export declare function frontmatterDescription(entry: SkillEntry): string | undefined;
+/**
+ * Validate one listing entry using only information the listing itself carries.
+ *
+ * This runs before any content is fetched, and every failure means the skill is
+ * not loadable — never that it should be silently downgraded or retried against
+ * a different contract.
+ *
+ * Checks, in order:
+ *  1. every declared digest is well-formed (`sha256:` + 64 lowercase hex);
+ *  2. no duplicate resource URIs within the entry (a duplicate would let one
+ *     declaration shadow another and make "which digest applies" ambiguous);
+ *  3. at most {@link MAX_SKILL_RESOURCE_ENTRIES} entries;
+ *  4. at most {@link MAX_SKILL_TOTAL_BYTES} declared bytes in total;
+ *  5. the entry's own `uri` appears in its `resources` (SKILL.md counts, and it
+ *     is the file we are about to fetch — it must carry a digest);
+ *  6. `name` and `description` are present;
+ *  7. the final `<skill-path>` segment equals `frontmatter.name`.
+ *
+ * `"dynamic"` resource sets skip 2–5: nothing is declared up front, so the
+ * ceilings are enforced against what is actually retrieved instead.
+ */
+export declare function validateSkillEntry(entry: SkillEntry): void;
+/**
+ * Total declared bytes for an entry, or `undefined` for a `"dynamic"` set where
+ * nothing is declared in advance.
+ */
+export declare function declaredTotalBytes(entry: SkillEntry): number | undefined;
+/** Look up an entry's declaration for one URI. `undefined` means "not listed". */
+export declare function findResourceRef(entry: SkillEntry, uri: string): SkillResourceRef | "dynamic" | undefined;
+/**
+ * A stable digest over an entry's declared resource set, used to bind an
+ * approval to exact content. Any rotation — a changed digest, an added file, a
+ * removed file, or a switch to/from `"dynamic"` — produces a different value,
+ * which is what makes a prior approval fall away instead of silently carrying
+ * over to different bytes.
+ */
+export declare function resourceSetFingerprint(entry: SkillEntry): string;

package/dist/skills/sep2640/protocol.js

@@ -0,0 +1,214 @@
+/**
+ * SEP-2640 wire schemas and entry-level validation.
+ *
+ * Everything here is pure: it turns an untrusted JSON-RPC result into a typed
+ * value, or refuses. No network, no filesystem, no policy decisions. The checks
+ * that SEP-2640 says are computable "from the listing alone, before any fetch"
+ * live here so they can run before a single byte is retrieved.
+ */
+import { z } from "zod";
+import { DIRECTORY_MIME_TYPE, MAX_SKILL_RESOURCE_ENTRIES, MAX_SKILL_TOTAL_BYTES, SKILL_DIGEST_PATTERN, } from "./spec.js";
+// -----------------------------------------------------------------------------
+// Wire schemas
+// -----------------------------------------------------------------------------
+/**
+ * One declared supporting file. `digest` is the SHA-256 of the file's raw
+ * bytes; `size` is the count of those same bytes.
+ */
+export const SkillResourceRefSchema = z.looseObject({
+    uri: z.string().min(1),
+    digest: z.string().min(1),
+    size: z.number().int().nonnegative(),
+});
+/**
+ * A skill as advertised by `skills/list` / `skills/get`.
+ *
+ * `frontmatter` is the verbatim YAML-as-JSON the author wrote — not a curated
+ * subset — so it is typed as an open record and never narrowed on ingest.
+ * `resources` is either the complete declared set or the literal `"dynamic"`.
+ */
+export const SkillEntrySchema = z.looseObject({
+    uri: z.string().min(1),
+    frontmatter: z.record(z.string(), z.unknown()),
+    resources: z.union([z.array(SkillResourceRefSchema), z.literal("dynamic")]),
+});
+/**
+ * SEP-2549 cache attributes. Advisory freshness metadata only — never an
+ * integrity property, and never a substitute for re-verifying bytes.
+ */
+const CacheAttributes = {
+    ttlMs: z.number().int().nonnegative().optional(),
+    cacheScope: z.string().optional(),
+};
+export const SkillsListResultSchema = z.looseObject({
+    // `resultType` appears in the proposal's examples but not its normative field
+    // table, so it is tolerated and never required.
+    resultType: z.string().optional(),
+    skills: z.array(SkillEntrySchema),
+    nextCursor: z.string().optional(),
+    ...CacheAttributes,
+});
+export const SkillsGetResultSchema = z.looseObject({
+    resultType: z.string().optional(),
+    // Note the singular key: `skills/get` returns `skill`, not `skills`.
+    skill: SkillEntrySchema,
+    ...CacheAttributes,
+});
+export const DirectoryResourceSchema = z.looseObject({
+    uri: z.string().min(1),
+    name: z.string().optional(),
+    mimeType: z.string().optional(),
+    size: z.number().int().nonnegative().optional(),
+});
+export const DirectoryReadResultSchema = z.looseObject({
+    resources: z.array(DirectoryResourceSchema),
+    nextCursor: z.string().optional(),
+});
+/** A refusal to accept server-supplied skill metadata. Never a fetch failure. */
+export class SkillValidationError extends Error {
+    code;
+    skillUri;
+    constructor(code, message, skillUri) {
+        super(message);
+        this.name = "SkillValidationError";
+        this.code = code;
+        this.skillUri = skillUri;
+    }
+}
+// -----------------------------------------------------------------------------
+// Entry validation
+// -----------------------------------------------------------------------------
+/** True only for exactly `sha256:` + 64 lowercase hex characters. */
+export function isValidDigest(digest) {
+    return SKILL_DIGEST_PATTERN.test(digest);
+}
+/** True when a `resources/directory/read` entry describes a directory. */
+export function isDirectoryResource(resource) {
+    return resource.mimeType === DIRECTORY_MIME_TYPE;
+}
+/**
+ * The `<skill-path>` an entry URI addresses, i.e. everything up to but not
+ * including the trailing `/SKILL.md`. Returns `undefined` when the URI does not
+ * end in `/SKILL.md`.
+ */
+export function skillPathOf(uri) {
+    const suffix = "/SKILL.md";
+    if (!uri.endsWith(suffix))
+        return undefined;
+    return uri.slice(0, -suffix.length);
+}
+/** The final path segment of a skill path — the segment that must equal `frontmatter.name`. */
+export function finalPathSegment(skillPath) {
+    const trimmed = skillPath.replace(/\/+$/, "");
+    const slash = trimmed.lastIndexOf("/");
+    return slash === -1 ? trimmed : trimmed.slice(slash + 1);
+}
+/**
+ * A skill's declared name, or `undefined` when frontmatter omits it or it is
+ * not a string. `name` and `description` are the two fields SEP-2640 requires.
+ */
+export function frontmatterName(entry) {
+    const value = entry.frontmatter["name"];
+    return typeof value === "string" ? value : undefined;
+}
+export function frontmatterDescription(entry) {
+    const value = entry.frontmatter["description"];
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * Validate one listing entry using only information the listing itself carries.
+ *
+ * This runs before any content is fetched, and every failure means the skill is
+ * not loadable — never that it should be silently downgraded or retried against
+ * a different contract.
+ *
+ * Checks, in order:
+ *  1. every declared digest is well-formed (`sha256:` + 64 lowercase hex);
+ *  2. no duplicate resource URIs within the entry (a duplicate would let one
+ *     declaration shadow another and make "which digest applies" ambiguous);
+ *  3. at most {@link MAX_SKILL_RESOURCE_ENTRIES} entries;
+ *  4. at most {@link MAX_SKILL_TOTAL_BYTES} declared bytes in total;
+ *  5. the entry's own `uri` appears in its `resources` (SKILL.md counts, and it
+ *     is the file we are about to fetch — it must carry a digest);
+ *  6. `name` and `description` are present;
+ *  7. the final `<skill-path>` segment equals `frontmatter.name`.
+ *
+ * `"dynamic"` resource sets skip 2–5: nothing is declared up front, so the
+ * ceilings are enforced against what is actually retrieved instead.
+ */
+export function validateSkillEntry(entry) {
+    const uri = entry.uri;
+    if (entry.resources !== "dynamic") {
+        const seen = new Set();
+        let totalBytes = 0;
+        for (const resource of entry.resources) {
+            if (!isValidDigest(resource.digest)) {
+                throw new SkillValidationError("malformed_digest", `Skill ${uri} declares resource ${resource.uri} with a non-conforming digest ` +
+                    `"${resource.digest}". SEP-2640 requires exactly "sha256:" followed by 64 lowercase hex characters.`, uri);
+            }
+            if (seen.has(resource.uri)) {
+                throw new SkillValidationError("duplicate_resource_uri", `Skill ${uri} declares resource ${resource.uri} more than once, so which digest applies is ambiguous.`, uri);
+            }
+            seen.add(resource.uri);
+            totalBytes += resource.size;
+        }
+        if (entry.resources.length > MAX_SKILL_RESOURCE_ENTRIES) {
+            throw new SkillValidationError("resource_limit_exceeded", `Skill ${uri} declares ${entry.resources.length} resources, above the SEP-2640 ceiling of ` +
+                `${MAX_SKILL_RESOURCE_ENTRIES}. The skill was not loaded and nothing was fetched.`, uri);
+        }
+        if (totalBytes > MAX_SKILL_TOTAL_BYTES) {
+            throw new SkillValidationError("size_limit_exceeded", `Skill ${uri} declares ${totalBytes} bytes across its resources, above the SEP-2640 ceiling of ` +
+                `${MAX_SKILL_TOTAL_BYTES} bytes (16 MiB). The skill was not loaded and nothing was fetched.`, uri);
+        }
+        if (!seen.has(uri)) {
+            throw new SkillValidationError("skill_md_not_listed", `Skill ${uri} does not list its own SKILL.md in its resources, so the content this host would ` +
+                `fetch carries no digest to verify against.`, uri);
+        }
+    }
+    const name = frontmatterName(entry);
+    if (!name) {
+        throw new SkillValidationError("missing_frontmatter_field", `Skill ${uri} has no string "name" in its frontmatter.`, uri);
+    }
+    if (!frontmatterDescription(entry)) {
+        throw new SkillValidationError("missing_frontmatter_field", `Skill ${uri} has no string "description" in its frontmatter.`, uri);
+    }
+    const skillPath = skillPathOf(uri);
+    if (skillPath === undefined) {
+        throw new SkillValidationError("name_path_mismatch", `Skill URI ${uri} does not address a SKILL.md, so its <skill-path> cannot be compared to "${name}".`, uri);
+    }
+    const segment = finalPathSegment(skillPath);
+    if (segment !== name) {
+        throw new SkillValidationError("name_path_mismatch", `Skill ${uri} declares name "${name}" but its final path segment is "${segment}". ` +
+            `SEP-2640 requires them to match.`, uri);
+    }
+}
+/**
+ * Total declared bytes for an entry, or `undefined` for a `"dynamic"` set where
+ * nothing is declared in advance.
+ */
+export function declaredTotalBytes(entry) {
+    if (entry.resources === "dynamic")
+        return undefined;
+    return entry.resources.reduce((total, resource) => total + resource.size, 0);
+}
+/** Look up an entry's declaration for one URI. `undefined` means "not listed". */
+export function findResourceRef(entry, uri) {
+    if (entry.resources === "dynamic")
+        return "dynamic";
+    return entry.resources.find((resource) => resource.uri === uri);
+}
+/**
+ * A stable digest over an entry's declared resource set, used to bind an
+ * approval to exact content. Any rotation — a changed digest, an added file, a
+ * removed file, or a switch to/from `"dynamic"` — produces a different value,
+ * which is what makes a prior approval fall away instead of silently carrying
+ * over to different bytes.
+ */
+export function resourceSetFingerprint(entry) {
+    if (entry.resources === "dynamic")
+        return "dynamic";
+    return [...entry.resources]
+        .map((resource) => `${resource.uri}\u0000${resource.digest}\u0000${resource.size}`)
+        .sort()
+        .join("\u0001");
+}

package/dist/skills/sep2640/spec.d.ts

@@ -0,0 +1,76 @@
+/**
+ * SEP-2640 "Skills Extension" — pinned Draft constants.
+ *
+ * ⚠️ DRAFT. SEP-2640 is an Extensions-Track proposal that has **not** been
+ * accepted into the MCP specification. Everything in this directory is written
+ * against one immutable revision of the proposal and is gated off by default so
+ * it can never be mistaken for final-spec support. See `docs/skills.md`.
+ *
+ * Source of truth for this implementation:
+ *   repo:   modelcontextprotocol/modelcontextprotocol
+ *   path:   docs/seps/2640-skills-extension.mdx
+ *   commit: 753b9f2be43e07fdd070e535d75f190cff14beea
+ *
+ * If the proposal moves, this file — not the call sites — is what changes, and
+ * the revision below is what makes the drift visible.
+ */
+/** The extension identifier negotiated in `initialize` capabilities (SEP-2133). */
+export declare const SKILLS_EXTENSION_NAME = "io.modelcontextprotocol/skills";
+/** Immutable Draft revision this client was written against. */
+export declare const SKILLS_EXTENSION_REVISION = "753b9f2be43e07fdd070e535d75f190cff14beea";
+/** Proposal status at the pinned revision. Never `"final"` while this reads `"draft"`. */
+export declare const SKILLS_EXTENSION_STATUS = "draft";
+/** JSON-RPC methods defined by the extension. */
+export declare const SKILLS_METHODS: {
+    readonly list: "skills/list";
+    readonly get: "skills/get";
+    readonly directoryRead: "resources/directory/read";
+};
+/**
+ * Maximum number of resource entries a single skill may declare, SKILL.md
+ * included. Hosts MUST support up to and including this; servers SHOULD NOT
+ * exceed it. Checkable from the listing alone, before any fetch.
+ */
+export declare const MAX_SKILL_RESOURCE_ENTRIES = 512;
+/**
+ * Maximum total declared byte size across one skill's resource entries
+ * (16 MiB). Also checkable before any fetch. For `"dynamic"` resource sets the
+ * same ceiling applies to what is actually retrieved.
+ */
+export declare const MAX_SKILL_TOTAL_BYTES: number;
+/**
+ * Digest wire format: exactly `sha256:` followed by 64 **lowercase** hex
+ * characters. Uppercase hex, a different prefix, or a different length is
+ * non-conforming and this client rejects it rather than normalising it.
+ */
+export declare const SKILL_DIGEST_PATTERN: RegExp;
+/** MIME type a directory entry carries in `resources/directory/read` results. */
+export declare const DIRECTORY_MIME_TYPE = "inode/directory";
+/**
+ * `cacheScope` values this client is willing to honour.
+ *
+ * SEP-2640 delegates `ttlMs`/`cacheScope` semantics to SEP-2549 and does not
+ * enumerate the legal scopes itself. Rather than guess the full vocabulary we
+ * honour only the two scopes that are unambiguously narrower than a shared
+ * cache, and treat every other value — including values we simply have not
+ * seen — as "do not cache". Caching is a freshness optimisation; being wrong
+ * in the conservative direction only costs a round trip.
+ */
+export declare const HONOURED_CACHE_SCOPES: ReadonlySet<string>;
+/** Upper bound applied to any server-supplied `ttlMs`, so a server cannot pin stale data. */
+export declare const MAX_CACHE_TTL_MS: number;
+/** Page cap for `skills/list` / `resources/directory/read` cursor pagination. */
+export declare const MAX_SKILL_LIST_PAGES = 64;
+/**
+ * A single human-readable line naming the proposal, its status, and the exact
+ * revision. Surfaced at discovery time so an operator can always tell that this
+ * is draft behaviour and which revision produced it.
+ */
+export declare function skillsExtensionDiagnostic(): string;
+/**
+ * One-line summary of what a server declared, for logs.
+ *
+ * Always names the draft status and revision so an operator reading a log can
+ * see they are looking at unratified behaviour rather than settled protocol.
+ */
+export declare function describeNegotiation(serverName: string, capability: Record<string, unknown> | undefined): string;

package/dist/skills/sep2640/spec.js

@@ -0,0 +1,88 @@
+/**
+ * SEP-2640 "Skills Extension" — pinned Draft constants.
+ *
+ * ⚠️ DRAFT. SEP-2640 is an Extensions-Track proposal that has **not** been
+ * accepted into the MCP specification. Everything in this directory is written
+ * against one immutable revision of the proposal and is gated off by default so
+ * it can never be mistaken for final-spec support. See `docs/skills.md`.
+ *
+ * Source of truth for this implementation:
+ *   repo:   modelcontextprotocol/modelcontextprotocol
+ *   path:   docs/seps/2640-skills-extension.mdx
+ *   commit: 753b9f2be43e07fdd070e535d75f190cff14beea
+ *
+ * If the proposal moves, this file — not the call sites — is what changes, and
+ * the revision below is what makes the drift visible.
+ */
+/** The extension identifier negotiated in `initialize` capabilities (SEP-2133). */
+export const SKILLS_EXTENSION_NAME = "io.modelcontextprotocol/skills";
+/** Immutable Draft revision this client was written against. */
+export const SKILLS_EXTENSION_REVISION = "753b9f2be43e07fdd070e535d75f190cff14beea";
+/** Proposal status at the pinned revision. Never `"final"` while this reads `"draft"`. */
+export const SKILLS_EXTENSION_STATUS = "draft";
+/** JSON-RPC methods defined by the extension. */
+export const SKILLS_METHODS = {
+    list: "skills/list",
+    get: "skills/get",
+    directoryRead: "resources/directory/read",
+};
+/**
+ * Maximum number of resource entries a single skill may declare, SKILL.md
+ * included. Hosts MUST support up to and including this; servers SHOULD NOT
+ * exceed it. Checkable from the listing alone, before any fetch.
+ */
+export const MAX_SKILL_RESOURCE_ENTRIES = 512;
+/**
+ * Maximum total declared byte size across one skill's resource entries
+ * (16 MiB). Also checkable before any fetch. For `"dynamic"` resource sets the
+ * same ceiling applies to what is actually retrieved.
+ */
+export const MAX_SKILL_TOTAL_BYTES = 16 * 1024 * 1024;
+/**
+ * Digest wire format: exactly `sha256:` followed by 64 **lowercase** hex
+ * characters. Uppercase hex, a different prefix, or a different length is
+ * non-conforming and this client rejects it rather than normalising it.
+ */
+export const SKILL_DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/** MIME type a directory entry carries in `resources/directory/read` results. */
+export const DIRECTORY_MIME_TYPE = "inode/directory";
+/**
+ * `cacheScope` values this client is willing to honour.
+ *
+ * SEP-2640 delegates `ttlMs`/`cacheScope` semantics to SEP-2549 and does not
+ * enumerate the legal scopes itself. Rather than guess the full vocabulary we
+ * honour only the two scopes that are unambiguously narrower than a shared
+ * cache, and treat every other value — including values we simply have not
+ * seen — as "do not cache". Caching is a freshness optimisation; being wrong
+ * in the conservative direction only costs a round trip.
+ */
+export const HONOURED_CACHE_SCOPES = new Set(["session", "connection"]);
+/** Upper bound applied to any server-supplied `ttlMs`, so a server cannot pin stale data. */
+export const MAX_CACHE_TTL_MS = 5 * 60_000;
+/** Page cap for `skills/list` / `resources/directory/read` cursor pagination. */
+export const MAX_SKILL_LIST_PAGES = 64;
+/**
+ * A single human-readable line naming the proposal, its status, and the exact
+ * revision. Surfaced at discovery time so an operator can always tell that this
+ * is draft behaviour and which revision produced it.
+ */
+export function skillsExtensionDiagnostic() {
+    return (`[skills] SEP-2640 Skills Extension support is DRAFT ` +
+        `(${SKILLS_EXTENSION_NAME}, status=${SKILLS_EXTENSION_STATUS}, ` +
+        `revision=${SKILLS_EXTENSION_REVISION.slice(0, 12)}). ` +
+        `Not final MCP specification; behaviour may change without notice.`);
+}
+/**
+ * One-line summary of what a server declared, for logs.
+ *
+ * Always names the draft status and revision so an operator reading a log can
+ * see they are looking at unratified behaviour rather than settled protocol.
+ */
+export function describeNegotiation(serverName, capability) {
+    const marker = `${SKILLS_EXTENSION_STATUS} ${SKILLS_EXTENSION_REVISION.slice(0, 12)}`;
+    if (!capability) {
+        return `skills extension (${marker}): "${serverName}" does not declare "${SKILLS_EXTENSION_NAME}" — using legacy skill:// discovery`;
+    }
+    const directoryRead = capability["directoryRead"] === true;
+    return `skills extension (${marker}): "${serverName}" declares "${SKILLS_EXTENSION_NAME}" (directoryRead=${String(directoryRead)})`;
+}