Add skill://index.json discovery and remove SEP-2093 dependencies

Align the reference implementation with PR #69's SEP spec, which defines
skill://index.json as the primary enumeration mechanism and requires zero
protocol dependencies beyond resources/read.

Added:
- skill://index.json well-known discovery index (Agent Skills format)
- generateSkillIndex() server-side, listSkillsFromIndex() client-side
- SkillIndex/SkillIndexEntry types and INDEX_JSON_URI constant
- 53 tests across URI utilities, index round-trip, and client parsing

Removed (SEP-2093 features not in the SEP):
- resources/metadata handler and fetchSkillMetadata()
- Scoped resources/list(uri=...) and listSkillsScoped()
- Per-resource _meta capabilities on all resource registrations
- ResourceCapabilities/ResourceMetadataResult types
- Zod schemas and RequestHandlerRegistrar interface

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: olaservo

examples/skills-client/typescript/src/index.ts

@@ -4,13 +4,12 @@
  *
  * Demonstrates client-side SDK usage for the Skills Extension SEP:
  *
- *   1. READ_RESOURCE_TOOL  — Host-provided tool for model-driven loading
- *   2. listSkills()        — Discover all skills, show prefix + name
- *   3. readSkillContent()  — Load a multi-segment skill by path
- *   4. readSkillManifest() — Get file inventory with SHA256 hashes
- *   5. readSkillDocument() — Load a supporting file via resource template
- *   6. fetchSkillMetadata()— SEP-2093: metadata without content
- *   7. listSkillsScoped()  — SEP-2093: URI-scoped listing
+ *   1. READ_RESOURCE_TOOL      — Host-provided tool for model-driven loading
+ *   2. listSkillsFromIndex()   — Discover skills via skill://index.json
+ *   3. listSkills()            — Discover all skills via resources/list
+ *   4. readSkillContent()      — Load a multi-segment skill by path
+ *   5. readSkillManifest()     — Get file inventory with SHA256 hashes
+ *   6. readSkillDocument()     — Load a supporting file via resource template
  *
  * Connects to the skills-server via stdio (spawns as child process).
  *
@@ -24,11 +23,10 @@ import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import {
   READ_RESOURCE_TOOL,
   listSkills,
+  listSkillsFromIndex,
   readSkillContent,
   readSkillManifest,
   readSkillDocument,
-  fetchSkillMetadata,
-  listSkillsScoped,
   buildSkillsSummary,
 } from "@modelcontextprotocol/ext-skills/client";
 import { buildSkillUri } from "@modelcontextprotocol/ext-skills";
@@ -88,9 +86,31 @@ async function main() {
     console.log(JSON.stringify(READ_RESOURCE_TOOL, null, 2));
 
     // -----------------------------------------------------------------------
-    // 2. List all skills — show multi-segment paths with prefix + name
+    // 2. Discover skills via skill://index.json (SEP enumeration)
     // -----------------------------------------------------------------------
-    header("2. listSkills() — Discover Skills");
+    header("2. listSkillsFromIndex() — skill://index.json Discovery");
+
+    console.log("Per the SEP, servers whose skill set is enumerable SHOULD expose");
+    console.log("a skill://index.json resource following the Agent Skills discovery format.\n");
+
+    const indexSkills = await listSkillsFromIndex(client);
+    if (indexSkills) {
+      console.log(`Found ${indexSkills.length} skill(s) in index:\n`);
+      for (const skill of indexSkills) {
+        console.log(`  Name:        ${skill.name}`);
+        console.log(`  Skill Path:  ${skill.skillPath}`);
+        console.log(`  URI:         ${skill.uri}`);
+        console.log(`  Description: ${skill.description}`);
+        console.log();
+      }
+    } else {
+      console.log("Server does not expose skill://index.json (enumeration is optional)");
+    }
+
+    // -----------------------------------------------------------------------
+    // 3. List all skills via resources/list — show multi-segment paths
+    // -----------------------------------------------------------------------
+    header("3. listSkills() — Discover Skills via resources/list");
 
     const skills = await listSkills(client);
     console.log(`Found ${skills.length} skill(s):\n`);
@@ -112,9 +132,9 @@ async function main() {
     console.log(buildSkillsSummary(skills));
 
     // -----------------------------------------------------------------------
-    // 3. Read a multi-segment skill
+    // 4. Read a multi-segment skill
     // -----------------------------------------------------------------------
-    header("3. readSkillContent() — Load Multi-Segment Skill");
+    header("4. readSkillContent() — Load Multi-Segment Skill");
 
     const refundSkill = skills.find((s) => s.skillPath === "acme/billing/refunds");
     if (refundSkill) {
@@ -131,9 +151,9 @@ async function main() {
     }
 
     // -----------------------------------------------------------------------
-    // 4. Read skill manifest
+    // 5. Read skill manifest
     // -----------------------------------------------------------------------
-    header("4. readSkillManifest() — File Inventory");
+    header("5. readSkillManifest() — File Inventory");
 
     if (refundSkill) {
       const manifest = await readSkillManifest(client, refundSkill.skillPath);
@@ -148,9 +168,9 @@ async function main() {
     }
 
     // -----------------------------------------------------------------------
-    // 5. Read a supporting file via resource template
+    // 6. Read a supporting file via resource template
     // -----------------------------------------------------------------------
-    header("5. readSkillDocument() — Supporting File");
+    header("6. readSkillDocument() — Supporting File");
 
     if (refundSkill) {
       const docPath = "templates/refund-email-template.md";
@@ -171,40 +191,6 @@ async function main() {
       }
     }
 
-    // -----------------------------------------------------------------------
-    // 6. SEP-2093: Fetch metadata without content
-    // -----------------------------------------------------------------------
-    header("6. fetchSkillMetadata() — SEP-2093 Metadata");
-
-    if (refundSkill) {
-      console.log(`Fetching metadata for: ${refundSkill.uri}\n`);
-      const metadata = await fetchSkillMetadata(client, refundSkill.uri);
-      if (metadata) {
-        console.log("Metadata (no content transferred):");
-        console.log(JSON.stringify(metadata, null, 2));
-      } else {
-        console.log("Server does not support resources/metadata (SEP-2093)");
-      }
-    }
-
-    // -----------------------------------------------------------------------
-    // 7. SEP-2093: Scoped listing
-    // -----------------------------------------------------------------------
-    header("7. listSkillsScoped() — resources/list with URI Scoping");
-
-    console.log('Listing skills under "skill://acme/" (SKILL.md entries only):\n');
-    const acmeSkills = await listSkillsScoped(client, "skill://acme/");
-    if (acmeSkills) {
-      console.log(`Found ${acmeSkills.length} skill(s) under acme/:\n`);
-      for (const skill of acmeSkills) {
-        console.log(`  ${skill.skillPath} (name: ${skill.name})`);
-      }
-    } else {
-      console.log(
-        "Server does not support skills/list",
-      );
-    }
-
     // -----------------------------------------------------------------------
     // Summary
     // -----------------------------------------------------------------------
@@ -213,10 +199,8 @@ async function main() {
     console.log("Features demonstrated:");
     console.log("  [SEP]      Skills Extension — skill:// resource convention");
     console.log("  [SEP]      Multi-segment paths (prefix + name = last segment)");
+    console.log("  [SEP]      skill://index.json — well-known discovery index");
     console.log("  [SEP-2133] Extension declaration: io.modelcontextprotocol/skills");
-    console.log("  [SEP-2093] resources/metadata — metadata without content");
-    console.log("  [SEP-2093] resources/list(uri=...) — URI-scoped listing");
-    console.log("  [SEP-2093] Per-resource capabilities via _meta");
     console.log();
   } finally {
     await client.close();

examples/skills-server/typescript/src/index.ts

@@ -5,13 +5,13 @@
  * Demonstrates the Skills Extension SEP with:
  *   - Extension declaration: io.modelcontextprotocol/skills (SEP-2133)
  *   - Multi-segment skill paths: prefix + name (final segment = frontmatter name)
- *   - SEP-2093 features: resources/metadata, scoped resources/list,
- *     per-resource capabilities via _meta
+ *   - skill://index.json — well-known discovery index
  *   - skill:// URI scheme with recursive discovery
  *
  * URI scheme:
  *   - skill://{skillPath}/SKILL.md     — Skill content (listed resource)
  *   - skill://{skillPath}/_manifest    — File manifest with SHA256 hashes
+ *   - skill://index.json               — Well-known discovery index (SEP enumeration)
  *   - skill://{+skillFilePath}         — Supporting files (resource template)
  *   - skill://prompt-xml               — XML for system prompt injection
  *
@@ -31,8 +31,6 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import {
   discoverSkills,
   registerSkillResources,
-  registerMetadataHandler,
-  overrideResourcesListWithScoping,
   declareSkillsExtension,
 } from "@modelcontextprotocol/ext-skills/server";
 import type { ServerInternals } from "@modelcontextprotocol/ext-skills/server";
@@ -70,10 +68,9 @@ const server = new McpServer(
   { capabilities: { resources: {} } },
 );
 
-// Cast to access low-level Server internals for SEP shims.
-// These workarounds can be removed if the SDK adds support for:
+// Cast to access low-level Server internals for extension declaration.
+// This workaround can be removed if the SDK adds support for:
 //   - extensions in capabilities (typescript-sdk#1630)
-//   - uri parameter on resources/list (SEP-2093)
 const lowLevelServer = server.server as unknown as ServerInternals;
 
 // --- Declare extension per SEP-2133 ---
@@ -89,20 +86,7 @@ registerSkillResources(server, skillMap, skillsDir, {
   promptXml: true,
 });
 
-// --- Override resources/list with URI scoping (SEP-2093) ---
-
-// Wraps the McpServer's built-in resources/list handler to add:
-//   resources/list(uri="skill://") → only SKILL.md entries under that prefix
-overrideResourcesListWithScoping(lowLevelServer);
-
-// --- Register resources/metadata (SEP-2093) ---
-
-registerMetadataHandler(lowLevelServer, skillMap);
-
 console.error("[skills-server] Extension: io.modelcontextprotocol/skills");
-console.error("[skills-server] SEP-2093 handlers:");
-console.error("  - resources/list with uri scoping");
-console.error("  - resources/metadata");
 
 // --- Connect via stdio transport ---
 

typescript/sdk/src/_client.ts

@@ -10,18 +10,17 @@
  * Key evolution from previous version:
  *   - Multi-segment skill paths: skillPath may have a prefix before name
  *     (per the SEP, the final segment of skillPath equals frontmatter name)
- *   - SEP-2093: fetchSkillMetadata() for metadata-only access
- *   - SDK wrappers per the SEP: listSkills(), readSkillUri()
+ *   - SDK wrappers per the SEP: listSkills(), listSkillsFromIndex(), readSkillUri()
  */
 
-import type { SkillManifest, SkillSummary } from "./types.js";
+import type { SkillManifest, SkillSummary, SkillIndex } from "./types.js";
 import {
   buildSkillUri,
   MANIFEST_PATH,
+  INDEX_JSON_URI,
   parseSkillUri,
   SKILL_FILENAME,
 } from "./uri.js";
-import { ResourcesMetadataResultSchema, ScopedListResultSchema } from "./resource-extensions.js";
 
 /**
  * Minimal structural interface for an MCP Client.
@@ -50,10 +49,6 @@ export interface SkillsClient {
       blob?: string;
     }>;
   }>;
-  request(
-    request: { method: string; params?: Record<string, unknown> },
-    schema: unknown,
-  ): Promise<unknown>;
 }
 
 /**
@@ -147,6 +142,48 @@ export async function listSkills(client: SkillsClient): Promise<SkillSummary[]>
   return skills;
 }
 
+/**
+ * List skills by reading the well-known skill://index.json resource.
+ *
+ * This is the SEP's primary enumeration mechanism, following the Agent Skills
+ * well-known URI discovery index format. Returns null if the server does not
+ * expose skill://index.json (enumeration is optional per the SEP).
+ *
+ * Hosts MUST NOT treat an absent or empty index as proof that a server has
+ * no skills — a skill:// URI is always directly readable via resources/read.
+ */
+export async function listSkillsFromIndex(
+  client: SkillsClient,
+): Promise<SkillSummary[] | null> {
+  try {
+    const result = await client.readResource({ uri: INDEX_JSON_URI });
+    const content = result.contents[0];
+    if (!content || !("text" in content) || !content.text) return null;
+
+    const index = JSON.parse(content.text) as SkillIndex;
+    if (!index.skills || !Array.isArray(index.skills)) return null;
+
+    return index.skills
+      .filter((entry) => entry.type === "skill-md")
+      .map((entry) => {
+        // Extract skillPath from the url field (strip "skill://" prefix and "/SKILL.md" suffix)
+        const parsed = parseSkillUri(entry.url);
+        const skillPath = parsed?.skillPath ?? entry.name;
+
+        return {
+          name: entry.name,
+          skillPath,
+          uri: entry.url,
+          description: entry.description,
+          mimeType: "text/markdown",
+        };
+      });
+  } catch {
+    // Server doesn't expose skill://index.json — not an error
+    return null;
+  }
+}
+
 /**
  * Read a resource by its full URI from an MCP server.
  *
@@ -262,72 +299,3 @@ export async function readSkillDocument(
   };
 }
 
-/**
- * SEP-2093: Fetch resource metadata without content.
- *
- * Tries the resources/metadata endpoint. Returns null if the server
- * doesn't support SEP-2093 (method not found).
- */
-export async function fetchSkillMetadata(
-  client: SkillsClient,
-  uri: string,
-): Promise<{ uri: string; name?: string; description?: string; mimeType?: string; capabilities?: { list?: boolean; subscribe?: boolean } } | null> {
-  try {
-    // SEP-2093: response shape is { resource: Resource }
-    const result = await client.request(
-      { method: "resources/metadata", params: { uri } },
-      ResourcesMetadataResultSchema,
-    ) as { resource: { uri: string; name?: string; description?: string; mimeType?: string; capabilities?: { list?: boolean; subscribe?: boolean }; [key: string]: unknown } };
-    return result.resource;
-  } catch {
-    // Server doesn't support resources/metadata — not an error
-    return null;
-  }
-}
-
-/**
- * List skills via resources/list with URI scoping (SEP-2093).
- *
- * When a `uriScope` is provided (e.g., "skill://acme/"), the server
- * filters to only SKILL.md entries under that prefix. Without a scope,
- * this is equivalent to a standard resources/list call.
- *
- * Returns null if the request fails (e.g., server doesn't support
- * the uri parameter on resources/list).
- */
-export async function listSkillsScoped(
-  client: SkillsClient,
-  uriScope?: string,
-): Promise<SkillSummary[] | null> {
-  try {
-    const result = await client.request(
-      {
-        method: "resources/list",
-        params: uriScope ? { uri: uriScope } : {},
-      },
-      ScopedListResultSchema,
-    ) as { resources: Array<{ uri: string; name?: string; description?: string; mimeType?: string }> };
-
-    const skills: SkillSummary[] = [];
-    for (const resource of result.resources) {
-      const parsed = parseSkillUri(resource.uri);
-      if (!parsed) continue;
-      if (
-        parsed.filePath !== SKILL_FILENAME &&
-        parsed.filePath.toLowerCase() !== "skill.md"
-      )
-        continue;
-
-      skills.push({
-        name: resource.name ?? parsed.skillPath,
-        skillPath: parsed.skillPath,
-        uri: resource.uri,
-        description: resource.description,
-        mimeType: resource.mimeType,
-      });
-    }
-    return skills;
-  } catch {
-    return null;
-  }
-}