simt-dev 0.2.1 → 0.2.2

package/src/mcp/schema.mjs

@@ -0,0 +1,139 @@
+// A JSON Schema checker, for the subset these schemas use.
+//
+// Written here rather than taken from npm because a tool that validates a payload has
+// to keep working on a machine where nothing was installed (ADR-012), and because the
+// schemas it checks are in this file: a dependency would be a second place for the same
+// rules to live, and the one thing a validator must not be is quietly out of date.
+//
+// The subset is deliberately small and deliberately loud. A keyword this file does not
+// understand is reported as an error rather than skipped, because a keyword silently
+// ignored turns a schema into decoration - the check passes, the payload does not match,
+// and nobody can say which of the two was wrong. `assertValid` is the only entry point
+// the tests use, and it names the failing path.
+//
+// Supported: type (including union arrays), properties, required, items, enum,
+// additionalProperties (boolean or a schema), anyOf.
+
+/**
+ * Check a value against a schema.
+ *
+ * @param {unknown} value
+ * @param {object} schema
+ * @param {string} [path] JSON pointer-ish location, for the message
+ * @returns {string|null} the first failure, or null when it validates
+ */
+export function check(value, schema, path = '$') {
+  if (schema === true || schema === undefined) return null;
+  if (schema === false) return `${path}: no value is allowed here`;
+  if (typeof schema !== 'object' || schema === null) return `${path}: schema must be an object`;
+
+  for (const keyword of Object.keys(schema)) {
+    if (!SUPPORTED.has(keyword)) {
+      // Loud on purpose: see the header. A keyword nobody implements is a promise the
+      // schema does not keep, and this is the only place that can notice.
+      throw new Error(`schema at ${path} uses "${keyword}", which this checker does not implement`);
+    }
+  }
+
+  if (schema.type !== undefined && !typeMatches(value, schema.type)) {
+    return `${path}: expected ${describe(schema.type)}, got ${describeValue(value)}`;
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((allowed) => same(allowed, value))) {
+    return `${path}: ${JSON.stringify(value)} is not one of ${JSON.stringify(schema.enum)}`;
+  }
+  if (Array.isArray(schema.anyOf)) {
+    const matched = schema.anyOf.some((option) => check(value, option, path) === null);
+    if (!matched) return `${path}: matched none of the ${schema.anyOf.length} allowed shapes`;
+  }
+
+  if (schema.type === 'object' || schema.properties !== undefined || schema.required !== undefined) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+    for (const key of schema.required ?? []) {
+      if (!(key in value)) return `${path}: missing required property "${key}"`;
+    }
+    for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+      if (!(key in value)) continue;
+      const failure = check(value[key], sub, `${path}.${key}`);
+      if (failure !== null) return failure;
+    }
+    if (schema.additionalProperties !== undefined) {
+      const known = new Set(Object.keys(schema.properties ?? {}));
+      for (const [key, sub] of Object.entries(value)) {
+        if (known.has(key)) continue;
+        if (schema.additionalProperties === false) return `${path}: unexpected property "${key}"`;
+        if (schema.additionalProperties !== true) {
+          const failure = check(sub, schema.additionalProperties, `${path}.${key}`);
+          if (failure !== null) return failure;
+        }
+      }
+    }
+  }
+
+  if (schema.items !== undefined && Array.isArray(value)) {
+    for (const [index, item] of value.entries()) {
+      const failure = check(item, schema.items, `${path}[${index}]`);
+      if (failure !== null) return failure;
+    }
+  }
+  return null;
+}
+
+/** Throws with the first failure, named. The shape a test wants. */
+export function assertValid(value, schema, what = 'value') {
+  const failure = check(value, schema);
+  if (failure !== null) throw new Error(`${what} does not match its schema: ${failure}`);
+  return true;
+}
+
+const SUPPORTED = new Set([
+  'type',
+  'properties',
+  'required',
+  'items',
+  'enum',
+  'additionalProperties',
+  'anyOf',
+  'description',
+  '$schema',
+]);
+
+function typeMatches(value, type) {
+  const types = Array.isArray(type) ? type : [type];
+  return types.some((t) => singleTypeMatches(value, t));
+}
+
+function singleTypeMatches(value, type) {
+  switch (type) {
+    case 'object':
+      return value !== null && typeof value === 'object' && !Array.isArray(value);
+    case 'array':
+      return Array.isArray(value);
+    case 'string':
+      return typeof value === 'string';
+    case 'number':
+      return typeof value === 'number' && Number.isFinite(value);
+    case 'integer':
+      return Number.isInteger(value);
+    case 'boolean':
+      return typeof value === 'boolean';
+    case 'null':
+      return value === null;
+    default:
+      return false;
+  }
+}
+
+function describe(type) {
+  return Array.isArray(type) ? type.join('|') : type;
+}
+
+/** What a value IS, for the failure message. Distinct from `describe(type)`. */
+function describeValue(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+}
+
+function same(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}

package/src/mcp/server.mjs

@@ -22,7 +22,24 @@
 import { createInterface } from 'node:readline';
 import { CLI } from '../name.mjs';
 
-export const PROTOCOL_VERSION = '2025-06-18';
+/**
+ * Every protocol revision this server speaks, newest first.
+ *
+ * The list is a claim about revisions that were read, not about ones that exist: each
+ * entry names a published revision and the behaviour this file implements for it, and
+ * ADR-068 records what changed. A revision not in this list is answered with
+ * `UnsupportedProtocolVersionError` rather than an optimistic guess, because the failure
+ * mode of guessing is a client that believes a feature is on and watches it misbehave.
+ */
+export const SUPPORTED_VERSIONS = ['2026-07-28', '2025-11-25', '2025-06-18'];
+
+/**
+ * The revision this server answers with when the client has not asked for one.
+ *
+ * Named the way every caller has always named it, and it is the newest supported
+ * revision rather than the only one: a client that asks for an older one gets it.
+ */
+export const PROTOCOL_VERSION = SUPPORTED_VERSIONS[0];
 
 /** JSON-RPC codes. -32700/-32600/-32601 are the spec's parse/request/method set. */
 export const RPC = {
@@ -30,16 +47,60 @@ export const RPC = {
   REQUEST: -32600,
   METHOD: -32601,
   INTERNAL: -32603,
+  /**
+   * `UnsupportedProtocolVersionError`, renumbered to -32022 in 2026-07-28. The spec
+   * reserves -32000..-32019 for implementations and -32020..-32099 for itself, so the
+   * older -32004 would now be an implementation-defined code in the wrong range.
+   */
+  UNSUPPORTED_VERSION: -32022,
+  /** Resource not found: -32002 in every revision up to 2025-11-25, -32602 after. */
+  RESOURCE_NOT_FOUND_LEGACY: -32002,
+  RESOURCE_NOT_FOUND: -32602,
+};
+
+/** The `_meta` keys 2026-07-28 puts on a request and in a result. */
+export const META = {
+  PROTOCOL_VERSION: 'io.modelcontextprotocol/protocolVersion',
+  CLIENT_INFO: 'io.modelcontextprotocol/clientInfo',
+  CLIENT_CAPABILITIES: 'io.modelcontextprotocol/clientCapabilities',
+  SERVER_INFO: 'io.modelcontextprotocol/serverInfo',
 };
 
+/** Revisions that removed `ping`, per the 2026-07-28 changelog (SEP-2575). */
+const PING_REMOVED_IN = '2026-07-28';
+
 const SERVER_INFO = { name: 'simt-dev', title: 'SIMT developer and agent tooling' };
 
+/**
+ * One hour, and the reason it is a number rather than an omission.
+ *
+ * `ttlMs` and `cacheScope` are required on list results from 2026-07-28, and the value
+ * is a fact about this server rather than a courtesy: the tool list changes when the
+ * release changes and not otherwise, so an hour is long enough to spare a client the
+ * round trip and short enough that a client started from a stale one re-reads it within
+ * a working day. `private`, because the list names the reader's own repository and no
+ * intermediary may hold it.
+ */
+const LIST_CACHE = { ttlMs: 3600000, cacheScope: 'private' };
+
 /**
  * Handle one parsed request. Pure with respect to the process: returns the response
  * object or null (for a notification), and never writes anywhere. Testable without a
  * pipe, which is the only way to test a line protocol honestly.
+ *
+ * `state` is the negotiated revision, and it is the only thing this function mutates.
+ * 2026-07-28 removed the handshake and made every request carry its own version, so a
+ * session is not part of the protocol any more - but a client on an older revision
+ * negotiates once and then sends bare requests, and answering those at the newest
+ * revision would hand it fields it did not ask for. So the version is read from the
+ * request when there is one and remembered only for the clients that need it.
+ *
+ * @param {object|null} request a parsed JSON-RPC message
+ * @param {object[]} tools
+ * @param {{packageVersion?: string, state?: {version: string|null}}} options
+ * @returns {Promise<object|null>}
  */
-export async function handle(request, tools, { version } = {}) {
+export async function handle(request, tools, { packageVersion, state } = {}) {
   if (request === null || typeof request !== 'object' || Array.isArray(request)) {
     return error(null, RPC.REQUEST, 'request must be a JSON object');
   }
@@ -54,25 +115,68 @@ export async function handle(request, tools, { version } = {}) {
   }
   if (isNotification) return null;
 
+  const asked = params?._meta?.[META.PROTOCOL_VERSION];
+  if (typeof asked === 'string' && !SUPPORTED_VERSIONS.includes(asked)) {
+    // The one place a client checks whether it got what it asked for, so this is where
+    // an unsupported version has to fail. The message names the revisions that do work,
+    // because "unsupported" alone leaves the client to guess between the two answers a
+    // server can give.
+    return error(
+      id,
+      RPC.UNSUPPORTED_VERSION,
+      `protocol version ${asked} is not supported; this server speaks ${SUPPORTED_VERSIONS.join(', ')}`,
+    );
+  }
+  const negotiated =
+    typeof asked === 'string' ? asked : method === 'initialize' ? negotiate(params?.protocolVersion) : state?.version;
+  // A caller that passes no `state` gets one request with no memory: `serve` threads one
+  // through the stream, and a test that calls this directly usually wants exactly that.
+  const session = state ?? { version: null };
+  if (method === 'initialize') session.version = negotiated;
+  const v = negotiated ?? PROTOCOL_VERSION;
+
+  const reply = (value) => result(id, decorate(value, v, { packageVersion, tools }));
+
   switch (method) {
     case 'initialize':
-      return result(id, {
-        protocolVersion: negotiate(params?.protocolVersion),
-        capabilities: { tools: { listChanged: false } },
-        serverInfo: { ...SERVER_INFO, version: version ?? '0.0.0' },
-        instructions:
-          `Read-only. Every answer is JSON. \`${CLI} skills brief\` is the one to call first: it returns the pre-assembled set for a task, plus what it deliberately left out and why.`,
+      return reply({
+        protocolVersion: v,
+        capabilities: capabilities(tools),
+        // `serverInfo` stays in the body here even on 2026-07-28: a client that has just
+        // called a method the newest revision removed is by definition an older client,
+        // and the field is where it looks.
+        serverInfo: serverInfo(packageVersion),
+        instructions: INSTRUCTIONS,
       });
 
     case 'notifications/initialized':
     case 'initialized':
       return null;
 
+    // MUST, from 2026-07-28 on. Cheap, stateless, and the stdio way for a client that
+    // supports both shapes to find out which one it is talking to before it commits.
+    case 'server/discover':
+      return reply({
+        supportedVersions: [...SUPPORTED_VERSIONS],
+        capabilities: capabilities(tools),
+        instructions: INSTRUCTIONS,
+        ...(cacheable(v) ? LIST_CACHE : {}),
+      });
+
     case 'ping':
-      return result(id, {});
+      // Removed in 2026-07-28, and kept before it: a client that speaks an older
+      // revision and probes liveness gets an answer, and one that speaks the newest
+      // gets told the method is gone rather than a success it would read as support.
+      if (atLeast(v, PING_REMOVED_IN)) {
+        return error(id, RPC.METHOD, `ping was removed in ${PING_REMOVED_IN}; this session negotiated ${v}`);
+      }
+      return reply({});
 
     case 'tools/list':
-      return result(id, { tools: tools.map(describe) });
+      return reply({
+        tools: tools.map((t) => describe(t, v)),
+        ...(cacheable(v) ? LIST_CACHE : {}),
+      });
 
     case 'tools/call': {
       const name = params?.name;
@@ -85,12 +189,21 @@ export async function handle(request, tools, { version } = {}) {
       const args = params?.arguments ?? {};
       try {
         const payload = await tool.run(args);
-        return result(id, { content: [contentOf(payload)], isError: false });
-      } catch (failure) {
-        return result(id, {
-          content: [contentOf({ error: failure.message, remedy: failure.remedy ?? null })],
-          isError: true,
+        // Both blocks, always. `structuredContent` is what a client validates against
+        // `outputSchema` and what it can index; the text block is what a client that
+        // predates structured output reads. Emitting one without the other leaves half
+        // the clients guessing, which is the state this release was filed for.
+        return reply({
+          content: [contentOf(payload)],
+          structuredContent: payload,
+          isError: false,
         });
+      } catch (failure) {
+        // An error is a result too, and it carries the same two shapes: the remedy is
+        // the part a model needs to act on, and it has to survive in whichever block the
+        // client reads.
+        const payload = { error: failure.message, remedy: failure.remedy ?? null };
+        return reply({ content: [contentOf(payload)], structuredContent: payload, isError: true });
       }
     }
 
@@ -99,6 +212,22 @@ export async function handle(request, tools, { version } = {}) {
   }
 }
 
+const INSTRUCTIONS =
+  `Read-only. Every answer is JSON. \`${CLI} skills brief\` is the one to call first: it returns the pre-assembled set for a task, plus what it deliberately left out and why.`;
+
+function serverInfo(packageVersion) {
+  return { ...SERVER_INFO, version: packageVersion ?? '0.0.0' };
+}
+
+function capabilities(tools) {
+  return {
+    tools: { listChanged: false },
+    // Declared only when there is something to read. A capability with no method behind
+    // it is a promise a client will keep waiting on.
+    ...(tools.resources ? { resources: { listChanged: false, subscribe: false } } : {}),
+  };
+}
+
 /**
  * Echo the client's protocol version when it is one this server implements.
  *
@@ -107,16 +236,58 @@ export async function handle(request, tools, { version } = {}) {
  * fails loudly at the one place the client checks.
  */
 function negotiate(requested) {
-  const SUPPORTED = new Set([PROTOCOL_VERSION]);
-  return typeof requested === 'string' && SUPPORTED.has(requested) ? requested : PROTOCOL_VERSION;
+  return typeof requested === 'string' && SUPPORTED_VERSIONS.includes(requested)
+    ? requested
+    : PROTOCOL_VERSION;
 }
 
-function describe(tool) {
+/** Revision ordering. These are dates, so lexicographic is chronological - stated here
+ *  because "sort a version string" is the kind of helper that gets rewritten by someone
+ *  who thinks it is a number, and this one is right. */
+function atLeast(version, floor) {
+  return version >= floor;
+}
+
+/** 2026-07-28 requires `ttlMs` and `cacheScope` on list results; earlier ones ignore them. */
+function cacheable(version) {
+  return atLeast(version, '2026-07-28');
+}
+
+/**
+ * What the newest revision adds to every result.
+ *
+ * `resultType` is required from 2026-07-28 and is absent before it — clients on older
+ * revisions treat it as an unknown field, and clients MUST read a missing one as
+ * `complete`, so emitting it unconditionally is the compatible half and omitting it on
+ * the new revision is not. `_meta.serverInfo` is a SHOULD, and it is how a stateless
+ * client learns who it is talking to now that `initialize` is gone.
+ */
+function decorate(value, version, { packageVersion }) {
+  if (!atLeast(version, '2026-07-28')) return value;
   return {
+    resultType: 'complete',
+    ...value,
+    _meta: { [META.SERVER_INFO]: serverInfo(packageVersion) },
+  };
+}
+
+function describe(tool, version) {
+  const entry = {
     name: tool.name,
     description: tool.description,
     inputSchema: tool.inputSchema,
+    // Every tool here is a reader: none writes, and none writes twice. Saying so lets a
+    // client cache the answer and, where it offers, let the model call without a
+    // confirmation step. The declaration is per tool rather than global because the next
+    // tool this file gains may not be one.
+    annotations: { readOnlyHint: true, idempotentHint: true, ...(tool.annotations ?? {}) },
   };
+  // `outputSchema` exists in all three revisions, and a tool that declares its input
+  // shape but not its output shape leaves the client guessing what a successful answer
+  // looks like - which is the same defect as a returned value nothing can be checked
+  // against.
+  if (tool.outputSchema) entry.outputSchema = tool.outputSchema;
+  return entry;
 }
 
 /** Content is one text block. Bounded, and truncation is announced in the text itself -
@@ -146,15 +317,21 @@ function error(id, code, message) {
  * Lines are processed strictly in order. A server that interleaves responses would let a
  * client match the wrong answer to the wrong question, and the tools here are already
  * sequential and cheap - parallelising them would buy nothing and cost correctness.
+ *
+ * One `state` for the whole stream, holding the revision a client negotiated through
+ * `initialize`. That is the residue of a handshake the 2026-07-28 revision removed, kept
+ * only because a client on an older revision sends bare requests afterwards and expects
+ * the answers it agreed to.
  */
-export async function serve(tools, { input = process.stdin, output = process.stdout, version, onError } = {}) {
+export async function serve(tools, { input = process.stdin, output = process.stdout, packageVersion, onError } = {}) {
   const rl = createInterface({ input, crlfDelay: Infinity });
+  const state = { version: null };
   for await (const line of rl) {
     if (line.trim() === '') continue;
 
     let response;
     try {
-      response = await handle(JSON.parse(line), tools, { version });
+      response = await handle(JSON.parse(line), tools, { packageVersion, state });
     } catch (parseFailure) {
       response = error(null, RPC.PARSE, `invalid JSON: ${parseFailure.message}`);
     }