feat(sep-2640): skills server conformance against the Accepted SEP, enumeration + manifest + directory

src/scenarios/client/skills/no-prefetch.ts

@@ -0,0 +1,172 @@
+/**
+ * SEP-2640 client scenario: hosts MUST NOT retrieve a skill's files ahead of
+ * need.
+ *
+ * This is a `Scenario` rather than a `ClientScenario`: the harness stands up
+ * the server and the client is the system under test. The rule reduces to
+ * "did a request arrive", which makes it one of the most wire-observable
+ * obligations in the SEP despite the first traceability pass filing it as an
+ * unobservable host obligation.
+ *
+ * Contract for the client under test, keyed on MCP_CONFORMANCE_SCENARIO:
+ * connect, call `skills/list`, then exit. Do not load a skill. A client that
+ * prefetches will read `SKILL.md` or a supporting file during that window and
+ * fail the check.
+ */
+
+import http from 'http';
+import { ConformanceCheck } from '../../../types.js';
+import { BaseHttpScenario } from '../http-base.js';
+
+const SPEC_REFERENCE = {
+  id: 'SEP-2640-Lazy-Retrieval',
+  url: 'https://modelcontextprotocol.io/seps/2640-skills-extension#integrity-and-verification'
+};
+
+const SKILLS_EXTENSION_ID = 'io.modelcontextprotocol/skills';
+
+/** One skill with a supporting file, so a prefetch has something to grab. */
+const SKILL_URI = 'skill://pdf-processing/SKILL.md';
+const SUPPORTING_URI = 'skill://pdf-processing/references/FORMS.md';
+
+const SKILL_MD = `---
+name: pdf-processing
+description: Extract, fill, and assemble PDF documents
+---
+
+Body the client has no business fetching yet.
+`;
+
+const SUPPORTING =
+  'Supporting content the client has no business fetching yet.\n';
+
+/** sha256 of the two bodies, computed at module load so the entry is honest. */
+import { createHash } from 'crypto';
+const digestOf = (s: string) =>
+  'sha256:' + createHash('sha256').update(s, 'utf8').digest('hex');
+
+export class SkillsNoPrefetchScenario extends BaseHttpScenario {
+  name = 'sep-2640-client-no-prefetch';
+  description =
+    'A client MUST NOT retrieve a skill file before the skill is loaded';
+  readonly source = { extensionId: SKILLS_EXTENSION_ID } as const;
+
+  /** Every resources/read URI the client asked for, in order. */
+  private readsRequested: string[] = [];
+  private listCalled = false;
+
+  protected handlePost(
+    _req: http.IncomingMessage,
+    res: http.ServerResponse,
+    request: any
+  ): void {
+    switch (request.method) {
+      case 'initialize':
+        this.sendInitialize(res, request, {
+          resources: { listChanged: false },
+          extensions: { [SKILLS_EXTENSION_ID]: {} }
+        });
+        return;
+
+      case 'skills/list':
+        this.listCalled = true;
+        this.sendJson(res, {
+          jsonrpc: '2.0',
+          id: request.id,
+          result: {
+            resultType: 'complete',
+            skills: [
+              {
+                uri: SKILL_URI,
+                frontmatter: {
+                  name: 'pdf-processing',
+                  description: 'Extract, fill, and assemble PDF documents'
+                },
+                resources: [
+                  {
+                    uri: SKILL_URI,
+                    digest: digestOf(SKILL_MD),
+                    size: Buffer.byteLength(SKILL_MD)
+                  },
+                  {
+                    uri: SUPPORTING_URI,
+                    digest: digestOf(SUPPORTING),
+                    size: Buffer.byteLength(SUPPORTING)
+                  }
+                ]
+              }
+            ]
+          }
+        });
+        return;
+
+      // Served, but reaching it during this scenario is the failure.
+      case 'resources/read': {
+        const uri = request.params?.uri;
+        if (typeof uri === 'string') this.readsRequested.push(uri);
+        const body = uri === SUPPORTING_URI ? SUPPORTING : SKILL_MD;
+        this.sendJson(res, {
+          jsonrpc: '2.0',
+          id: request.id,
+          result: {
+            resultType: 'complete',
+            contents: [{ uri, mimeType: 'text/markdown', text: body }]
+          }
+        });
+        return;
+      }
+
+      default:
+        if (request.id === undefined) {
+          this.sendNotificationAck(res);
+          return;
+        }
+        this.sendGenericResult(res, request);
+    }
+  }
+
+  getChecks(): ConformanceCheck[] {
+    const DESC =
+      "Hosts MUST NOT retrieve a skill's files ahead of need, not on connection, not on listing, and not at approval.";
+
+    // Without a listing there is no window in which prefetching is even
+    // possible, so the run proves nothing rather than passing.
+    if (!this.listCalled) {
+      return [
+        {
+          id: 'sep-2640-host-no-prefetch',
+          name: 'SkillsClientNoPrefetch',
+          description: DESC,
+          status: 'SKIPPED',
+          timestamp: new Date().toISOString(),
+          errorMessage:
+            'the client never called skills/list, so no retrieval window was opened',
+          specReferences: [SPEC_REFERENCE]
+        }
+      ];
+    }
+
+    const prefetched = this.readsRequested.filter(
+      (u) => u === SKILL_URI || u === SUPPORTING_URI
+    );
+
+    return [
+      {
+        id: 'sep-2640-host-no-prefetch',
+        name: 'SkillsClientNoPrefetch',
+        description: DESC,
+        status: prefetched.length === 0 ? 'SUCCESS' : 'FAILURE',
+        timestamp: new Date().toISOString(),
+        errorMessage:
+          prefetched.length === 0
+            ? undefined
+            : `client read ${prefetched.length} skill file(s) without loading a skill: ${prefetched.join(', ')}`,
+        specReferences: [SPEC_REFERENCE],
+        details: {
+          skillsListCalled: true,
+          fileReads: prefetched.length
+        }
+      }
+    ];
+  }
+}

src/scenarios/index.ts

@@ -10,6 +10,7 @@ import {
   DRAFT_PROTOCOL_VERSION
 } from '../types';
 import { InitializeScenario } from './client/initialize';
+import { SkillsNoPrefetchScenario } from './client/skills/no-prefetch';
 import { ToolsCallScenario } from './client/tools_call';
 import { ElicitationClientDefaultsScenario } from './client/elicitation-defaults';
 import { SSERetryScenario } from './client/sse-retry';
@@ -58,6 +59,10 @@ import {
   ResourcesNotFoundErrorScenario
 } from './server/resources';
 
+import { SkillsDirectoryReadScenario } from './server/skills/directory';
+import { SkillsEnumerationScenario } from './server/skills/enumeration';
+import { SkillsManifestScenario } from './server/skills/manifest';
+
 import {
   PromptsListScenario,
   PromptsGetSimpleScenario,
@@ -151,7 +156,15 @@ const pendingClientScenariosList: ClientScenario[] = [
   new TasksDispatchScenario(),
   new TasksStatusNotificationsScenario(),
   new TasksRequiredTaskErrorScenario(),
-  new TasksMrtrCompositionScenario()
+  new TasksMrtrCompositionScenario(),
+
+  // SEP-2640 Skills extension. Pending because the everything-server does not
+  // implement io.modelcontextprotocol/skills; targeted runs point at a
+  // SEP-2640-conformant fixture via
+  // `npm start -- server --scenario sep-2640-skills-* --url <fixture>`.
+  new SkillsDirectoryReadScenario(),
+  new SkillsEnumerationScenario(),
+  new SkillsManifestScenario()
 ];
 
 // All client scenarios
@@ -203,6 +216,12 @@ const allClientScenariosList: ClientScenario[] = [
   // Resources error handling (SEP-2164)
   new ResourcesNotFoundErrorScenario(),
 
+  // Skills extension (SEP-2640). Fixture-dependent (needs a SEP-2640 server);
+  // each scenario SKIPs cleanly when the extension is not declared.
+  new SkillsDirectoryReadScenario(),
+  new SkillsEnumerationScenario(),
+  new SkillsManifestScenario(),
+
   // Prompts scenarios
   new PromptsListScenario(),
   new PromptsGetSimpleScenario(),
@@ -317,7 +336,12 @@ const scenariosList: Scenario[] = [
   new JsonSchemaRefDerefScenario(),
 
   // JSON Schema 2020-12 client-side keyword preservation (SEP-1613, SEP-2106)
-  new JsonSchema2020_12PreservationScenario()
+  new JsonSchema2020_12PreservationScenario(),
+
+  // SEP-2640 skills, client side. The harness is the server and grades what
+  // the client requests, which is how the retrieval-policy MUSTs become
+  // observable at all.
+  new SkillsNoPrefetchScenario()
 ];
 
 // Core scenarios (tier 1 requirements)