stylegallery 0.1.0 → 0.1.2

package/scripts/agent-native/v2/material-context.mjs

@@ -0,0 +1,251 @@
+import { hashCanonical, canonicalize, deepFreeze } from "../canonical-json.mjs";
+import { materialAdmissionPolicy } from "./material-admission.mjs";
+import {
+  captureMaterialQuerySnapshot,
+  MATERIAL_GET_MAX_BYTES,
+  materialGet,
+  materialSearch,
+  rethrowMaterialQuerySnapshotError,
+  verifyMaterialQuerySnapshot,
+} from "./material-queries.mjs";
+
+export const MATERIAL_CONTEXT_DEFAULT_TOKENS = 8192;
+export const MATERIAL_CONTEXT_MIN_TOKENS = 256;
+export const MATERIAL_CONTEXT_MAX_TOKENS = 32768;
+export const MATERIAL_CONTEXT_OPERATION_VERSION = "material-context@1";
+export const MATERIAL_CONTEXT_TOKEN_CONTRACT = "ceil(canonical UTF-8 response bytes / 4)";
+export const MATERIAL_CONTEXT_CACHE_CONTRACT = "material-context-cache@1";
+
+const TRUST_INPUTS = new Set([
+  "claim", "claims", "evidence", "evidence_links", "governance", "governance_decisions",
+  "merge", "merge_flags", "merge_trust", "policy_dispositions", "trust_records", "validations",
+]);
+const PATH_INPUTS = new Set(["path", "repository_path", "repository_paths", "repository_root"]);
+const MANIFEST_INPUTS = new Set(["manifest", "manifest_head", "manifest_override", "manifest_version_id"]);
+
+export class MaterialContextError extends TypeError {
+  constructor(code, message) {
+    super(message);
+    this.name = "MaterialContextError";
+    this.code = code;
+  }
+}
+
+function fail(code, message) { throw new MaterialContextError(code, message); }
+function unsafeInput() { fail("material_context_input_unsafe", "material context input must be plain JSON data"); }
+function snapshotOwnData(value, seen = new WeakSet()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) unsafeInput();
+    return value;
+  }
+  if (!value || typeof value !== "object" || seen.has(value)) unsafeInput();
+  const array = Array.isArray(value);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== (array ? Array.prototype : Object.prototype) && prototype !== null) unsafeInput();
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== "string" || key === "__proto__" || key === "prototype" || key === "constructor")) unsafeInput();
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  if (keys.some((key) => !Object.hasOwn(descriptors[key], "value") || (descriptors[key].enumerable !== true && !(array && key === "length")))) unsafeInput();
+  if (array && (keys.some((key) => key !== "length" && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length))
+    || descriptors.length?.enumerable !== false)) unsafeInput();
+  seen.add(value);
+  const clone = array ? [] : Object.create(null);
+  for (const key of keys) {
+    if (array && key === "length") continue;
+    clone[key] = snapshotOwnData(descriptors[key].value, seen);
+  }
+  seen.delete(value);
+  return clone;
+}
+function assertInput(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) fail("material_input_invalid", "input must be an object");
+  const snapshot = snapshotOwnData(input);
+  const keys = Object.keys(snapshot);
+  if (keys.some((key) => TRUST_INPUTS.has(key) || /^(claim|evidence|governance|policy|trust|validation)(?:_|$)/.test(key) || key.includes("merge"))) {
+    fail("material_context_trust_merge_forbidden", "trust records cannot be merged into material retrieval");
+  }
+  if (keys.some((key) => PATH_INPUTS.has(key) || /^(repository|source)_paths?$/.test(key))) {
+    fail("material_context_repository_path_forbidden", "repository paths are not caller inputs");
+  }
+  if (keys.some((key) => MANIFEST_INPUTS.has(key) || key.startsWith("manifest_"))) {
+    fail("material_context_manifest_override_forbidden", "the material manifest cannot be overridden");
+  }
+  if (keys.some((key) => key !== "query" && key !== "budget_tokens")) fail("material_input_unknown", "input contains an unsupported field");
+  const budgetTokens = snapshot.budget_tokens ?? MATERIAL_CONTEXT_DEFAULT_TOKENS;
+  if (!Number.isInteger(budgetTokens) || budgetTokens < MATERIAL_CONTEXT_MIN_TOKENS || budgetTokens > MATERIAL_CONTEXT_MAX_TOKENS) {
+    fail("material_context_budget_invalid", "budget_tokens must be an integer from 256 to 32768");
+  }
+  return { budgetTokens, query: snapshot.query };
+}
+
+function withoutCacheKey(context) {
+  const value = structuredClone(context);
+  delete value.cache_key;
+  return value;
+}
+
+/** Recompute the canonical cache key. The key binds every output field except itself. */
+export function materialContextCacheKey(context) {
+  return hashCanonical({ contract: MATERIAL_CONTEXT_CACHE_CONTRACT, output: withoutCacheKey(context) });
+}
+
+/** Count the complete successful operation response, not only excerpt bodies. */
+export function countMaterialContextTokens(context) {
+  const response = { ok: true, operation: "material-context", result: context };
+  return Math.ceil(Buffer.byteLength(canonicalize(response), "utf8") / 4);
+}
+
+function finalizeContext(value) {
+  const context = structuredClone(value);
+  context.cache_key = "sha256:" + "0".repeat(64);
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    context.cache_key = materialContextCacheKey(context);
+    const count = countMaterialContextTokens(context);
+    if (context.budget.used_tokens === count) {
+      context.cache_key = materialContextCacheKey(context);
+      return deepFreeze(context);
+    }
+    context.budget.used_tokens = count;
+  }
+  fail("material_context_accounting_failed", "material context accounting did not converge");
+}
+
+function contextValue({ normalizedQuery, tokens, manifestVersionId, totalMatches, budgetTokens, excerpts }) {
+  const truncated = excerpts.length < totalMatches || excerpts.some((excerpt) => excerpt.truncated);
+  return finalizeContext({
+    schema_version: "2.0",
+    record_kind: "material_context",
+    operation_version: MATERIAL_CONTEXT_OPERATION_VERSION,
+    normalized_query: normalizedQuery,
+    query_tokens: tokens,
+    heads: {
+      manifest_ref: "sg:manifest/material-admission-v2",
+      manifest_version_id: manifestVersionId,
+      policy_ref: materialAdmissionPolicy.stable_ref,
+      policy_version_id: materialAdmissionPolicy.version_id,
+    },
+    member_manifest: excerpts.map(({ source }) => ({
+      stable_ref: source.stable_ref,
+      version_id: source.version_id,
+      sha256: source.sha256,
+    })),
+    budget: {
+      limit_tokens: budgetTokens,
+      used_tokens: 0,
+      token_count_contract: MATERIAL_CONTEXT_TOKEN_CONTRACT,
+    },
+    untrusted_retrieval: {
+      classification: "untrusted_material_excerpts",
+      retrieval_only: true,
+      total_matches: totalMatches,
+      truncated,
+      excerpts,
+    },
+  });
+}
+
+function excerptOf(page, content) {
+  const bytes = Buffer.from(content, "utf8");
+  return {
+    material_ref: page.identity.stable_ref,
+    source: {
+      stable_ref: page.source.stable_ref,
+      version_id: page.source.version_id,
+      sha256: page.source.source_sha256,
+      byte_offset: page.offset,
+      byte_length: bytes.byteLength,
+    },
+    truncated: page.offset + bytes.byteLength < page.source.byte_length,
+    content,
+  };
+}
+
+function codePointPrefixes(content) {
+  const prefixes = [""];
+  let current = "";
+  for (const point of content) {
+    current += point;
+    prefixes.push(current);
+  }
+  return prefixes;
+}
+
+/** Build a closed, read-only v2 material retrieval package. No source body cache is retained. */
+export function materialContext({ repositoryRoot, input, fileSystem, sourceReader, gitRunner }) {
+  const { budgetTokens, query } = assertInput(input);
+  const transaction = captureMaterialQuerySnapshot({ repositoryRoot, fileSystem, gitRunner });
+  let search;
+  try {
+    search = materialSearch({
+      repositoryRoot,
+      input: { query, limit: 100 },
+      fileSystem,
+      sourceReader,
+      gitRunner,
+      snapshot: transaction,
+    });
+  } catch (error) {
+    rethrowMaterialQuerySnapshotError({ snapshot: transaction, error, fileSystem });
+  }
+  const normalizedQuery = search.scoring_tokens.join(" ");
+  const pages = [];
+  let excerpts = [];
+
+  // Membership is a maximal rank-ordered prefix at one code point per source.
+  // It is therefore deterministic and monotonic as the caller budget grows.
+  for (const result of search.results) {
+    const current = contextValue({ normalizedQuery, tokens: search.scoring_tokens, manifestVersionId: search.manifest_version_id, totalMatches: search.total_matches, budgetTokens, excerpts });
+    const remainingBytes = Math.max(4, (budgetTokens - current.budget.used_tokens) * 4);
+    let page;
+    try {
+      page = materialGet({
+        repositoryRoot,
+        input: { reference: result.source.stable_ref, offset: 0, length: Math.min(result.source.byte_length, MATERIAL_GET_MAX_BYTES, remainingBytes) },
+        fileSystem,
+        sourceReader,
+        gitRunner,
+        snapshot: transaction,
+        contextUtf8SafeEnd: true,
+      });
+    } catch (error) {
+      rethrowMaterialQuerySnapshotError({ snapshot: transaction, error, fileSystem });
+    }
+    const prefixes = codePointPrefixes(page.content);
+    const minimum = prefixes[Math.min(1, prefixes.length - 1)];
+    const candidate = [...excerpts, excerptOf(page, minimum)];
+    const packaged = contextValue({ normalizedQuery, tokens: search.scoring_tokens, manifestVersionId: search.manifest_version_id, totalMatches: search.total_matches, budgetTokens, excerpts: candidate });
+    if (packaged.budget.used_tokens > budgetTokens) break;
+    excerpts = candidate;
+    pages.push({ result, page, prefixes });
+  }
+
+  // Spend remaining budget in rank order without changing membership.
+  for (let index = 0; index < pages.length; index += 1) {
+    const { page, prefixes } = pages[index];
+    let low = 1;
+    let high = prefixes.length - 1;
+    let best = excerpts[index].content;
+    while (low <= high) {
+      const middle = Math.floor((low + high) / 2);
+      const candidateExcerpts = excerpts.slice();
+      candidateExcerpts[index] = excerptOf(page, prefixes[middle]);
+      const packaged = contextValue({ normalizedQuery, tokens: search.scoring_tokens, manifestVersionId: search.manifest_version_id, totalMatches: search.total_matches, budgetTokens, excerpts: candidateExcerpts });
+      if (packaged.budget.used_tokens <= budgetTokens) { best = prefixes[middle]; low = middle + 1; }
+      else high = middle - 1;
+    }
+    excerpts[index] = excerptOf(page, best);
+  }
+
+  const context = contextValue({ normalizedQuery, tokens: search.scoring_tokens, manifestVersionId: search.manifest_version_id, totalMatches: search.total_matches, budgetTokens, excerpts });
+  if (context.budget.used_tokens > budgetTokens) fail("material_context_budget_too_small", "budget cannot contain the material context envelope");
+  verifyMaterialQuerySnapshot({
+    repositoryRoot,
+    snapshot: transaction,
+    selectedSourceRefs: excerpts.map((excerpt) => excerpt.source.stable_ref),
+    fileSystem,
+    sourceReader,
+    gitRunner,
+  });
+  return context;
+}

package/scripts/agent-native/v2/material-identity.mjs

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+
+import { deepFreeze } from "../canonical-json.mjs";
+
+export const MATERIAL_STABLE_REF_KINDS = Object.freeze(["domain", "page", "pattern", "material"]);
+const KIND_SET = new Set(MATERIAL_STABLE_REF_KINDS);
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const PATH_ID = /^path-sha256-[a-f0-9]{64}$/;
+const DOMAIN_IDS = new Set(["layout", "motion", "design-engineering", "game-ui", "platform-guides"]);
+const MATERIAL_ID = PATH_ID;
+
+export class MaterialIdentityError extends TypeError {
+  constructor(code, message) {
+    super(message);
+    this.name = "MaterialIdentityError";
+    this.code = code;
+  }
+}
+
+function fail(code, message) { throw new MaterialIdentityError(code, message); }
+function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+function referenceOf(input) {
+  if (typeof input === "string") return input;
+  if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+  return input.stable_ref ?? input.reference;
+}
+
+/** Parse only the closed v2 material identity grammar. This is deliberately not part of v1 identity.mjs. */
+export function parseMaterialStableRef(input) {
+  if (input && typeof input === "object" && Object.hasOwn(input, "schema_version") && input.schema_version !== "2.0") {
+    fail("material_identity_version_invalid", "material identities require schema_version 2.0");
+  }
+  const reference = referenceOf(input);
+  if (typeof reference !== "string") fail("material_stable_ref_required", "v2 StableRef must be a string");
+  const match = /^sg:(domain|page|pattern|material)\/([a-z0-9]+(?:-[a-z0-9]+)*)$/.exec(reference);
+  if (!match || !KIND_SET.has(match[1])) fail("material_stable_ref_invalid", "reference is not a v2 material StableRef");
+  const [, kind, id] = match;
+  if ((kind === "domain" && !DOMAIN_IDS.has(id))
+    || ((kind === "page" || kind === "pattern" || kind === "material") && !PATH_ID.test(id))) {
+    fail("material_stable_ref_invalid", "reference is outside the closed v2 material identity grammar");
+  }
+  return deepFreeze({ schema_version: "2.0", stable_ref: reference, kind, id });
+}
+
+export function createMaterialStableRef({ kind, id }) {
+  if (!KIND_SET.has(kind)) fail("material_stable_ref_kind_invalid", "unsupported v2 material StableRef kind");
+  if (typeof id !== "string" || !KEBAB.test(id)) fail("material_stable_ref_id_invalid", "v2 material StableRef id must be kebab-case");
+  return parseMaterialStableRef(`sg:${kind}/${id}`).stable_ref;
+}
+
+export function materialIdentityForRecord(record) {
+  if (!record || typeof record !== "object" || !MATERIAL_ID.test(record.stable_ref?.replace(/^sg:material\//, "") ?? "")) {
+    fail("material_record_identity_invalid", "record does not carry a v2 material source identity");
+  }
+  const repositoryPath = record.repository_path;
+  if (typeof repositoryPath !== "string") fail("material_record_identity_invalid", "record has no bound source path");
+  let kind = "page";
+  let id = `path-sha256-${sha256(Buffer.from(repositoryPath, "utf8"))}`;
+  const domainMatch = /^(layout|motion|design-engineering|game-ui|platform-guides)\/index\.md$/.exec(repositoryPath);
+  if (domainMatch) { kind = "domain"; id = domainMatch[1]; }
+  else if (/^patterns\/[^/]+\/[^/]+\.md$/.test(repositoryPath)) kind = "pattern";
+  return deepFreeze({
+    schema_version: "2.0",
+    stable_ref: createMaterialStableRef({ kind, id }),
+    kind,
+    source_ref: record.stable_ref,
+    source_version_id: record.version_id,
+  });
+}
+
+export const parseV2StableRef = parseMaterialStableRef;

package/scripts/agent-native/v2/material-mcp-adapter.mjs

@@ -0,0 +1,253 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { types as utilTypes } from "node:util";
+
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolRequestSchema, ErrorCode, McpError, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+import { canonicalize } from "../canonical-json.mjs";
+import { parseMaterialStableRef } from "./material-identity.mjs";
+import { createMaterialOperationRegistry, materialOperationSpecs } from "./material-operation-registry.mjs";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+const manifestPath = path.join(repositoryRoot, "consumer-reference", "agent-native", "v2", "material-registry.json");
+const exposedNames = new Set(["material-context", "material-discover", "material-get", "material-search"]);
+const descriptions = Object.freeze({
+  "material-context": "Build a deterministic, provenance-bound material context within a token budget.",
+  "material-discover": "Discover the five governed StyleGallery domain entries.",
+  "material-get": "Read bounded UTF-8 bytes for one canonical v2 material StableRef.",
+  "material-search": "Search admitted material deterministically using normalized Unicode terms.",
+});
+const inputSchemas = Object.freeze({
+  "material-context": z.strictObject({ query: z.string(), budget_tokens: z.number().int().min(256).max(32768).default(8192) }),
+  "material-discover": z.strictObject({}),
+  "material-get": z.strictObject({ reference: z.string(), offset: z.number().int().min(0).optional(), length: z.number().int().min(1).max(65536).optional() }),
+  "material-search": z.strictObject({ query: z.string(), limit: z.number().int().min(1).max(100).optional() }),
+});
+const outputSchema = z.strictObject({
+  ok: z.boolean(),
+  operation: z.string().nullable(),
+  result: z.looseObject({}).optional(),
+  failures: z.array(z.looseObject({})).optional(),
+});
+const safeCallToolRequestSchema = CallToolRequestSchema.extend({
+  params: CallToolRequestSchema.shape.params.extend({ arguments: z.unknown().optional() }),
+});
+const unsafeInputMarker = Object.freeze({ __stylegallery_unsafe_material_input__: true });
+
+function packagedInventoryRunner(root) {
+  return () => {
+    try {
+      const manifest = JSON.parse(fs.readFileSync(path.join(root, "consumer-reference", "agent-native", "v2", "material-registry.json"), "utf8"));
+      return {
+        error: undefined,
+        status: 0,
+        stderr: Buffer.alloc(0),
+        stdout: Buffer.from(manifest.materials.map((record) => `100644 ${record.source_sha256} 0\t${record.repository_path}\0`).join(""), "utf8"),
+      };
+    } catch {
+      return { error: undefined, status: 1, stderr: Buffer.alloc(0), stdout: Buffer.alloc(0) };
+    }
+  };
+}
+
+function runtimeRegistry() {
+  return createMaterialOperationRegistry({
+    repositoryRoot,
+    ...(fs.existsSync(path.join(repositoryRoot, ".git")) ? {} : { gitRunner: packagedInventoryRunner(repositoryRoot) }),
+  });
+}
+
+function loadManifest() {
+  return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+}
+
+function assertRegistry(registry) {
+  if (!registry || typeof registry.invoke !== "function" || !Array.isArray(registry.operations)) {
+    throw new TypeError("material MCP registry must expose invoke and operations");
+  }
+  const names = registry.operations.map(({ name }) => name).sort();
+  if (names.length !== exposedNames.size || names.some((name) => !exposedNames.has(name))) {
+    throw new TypeError("material MCP registry must contain exactly four v2 read operations");
+  }
+  for (const operation of registry.operations) {
+    if (operation.read_only !== true || operation.effect_class !== "NONE") {
+      throw new TypeError("material MCP operations must be read-only with NONE effects");
+    }
+  }
+}
+
+export function normalizeMaterialMcpInput(input) {
+  if (input === undefined) return {};
+  if (input === null || typeof input !== "object" || utilTypes.isProxy(input) || Array.isArray(input)) {
+    throw new McpError(ErrorCode.InvalidParams, "operation input must contain only own plain data");
+  }
+  let prototype;
+  let keys;
+  try {
+    prototype = Object.getPrototypeOf(input);
+    keys = Reflect.ownKeys(input);
+  } catch {
+    throw new McpError(ErrorCode.InvalidParams, "operation input must contain only own plain data");
+  }
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new McpError(ErrorCode.InvalidParams, "operation input must contain only own plain data");
+  }
+  const normalized = {};
+  for (const key of keys) {
+    if (typeof key !== "string") throw new McpError(ErrorCode.InvalidParams, "operation input must contain only own plain data");
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    if (!descriptor || descriptor.enumerable !== true || !("value" in descriptor)) {
+      throw new McpError(ErrorCode.InvalidParams, "operation input must contain only own plain data");
+    }
+    const value = descriptor.value;
+    if (!["string", "number", "boolean"].includes(typeof value) && value !== null) {
+      throw new McpError(ErrorCode.InvalidParams, "operation input must contain only own scalar data");
+    }
+    normalized[key] = value;
+  }
+  return normalized;
+}
+
+function sanitizedToolCallMessage(message) {
+  if (!message || typeof message !== "object" || message.method !== "tools/call" || !message.params || typeof message.params !== "object") return message;
+  const descriptor = Object.getOwnPropertyDescriptor(message.params, "arguments");
+  let normalized;
+  try {
+    normalized = descriptor && "value" in descriptor ? normalizeMaterialMcpInput(descriptor.value) : {};
+  } catch {
+    normalized = unsafeInputMarker;
+  }
+  const params = Object.create(Object.getPrototypeOf(message.params), Object.getOwnPropertyDescriptors(message.params));
+  Object.defineProperty(params, "arguments", { configurable: true, enumerable: true, value: normalized, writable: true });
+  const sanitized = Object.create(Object.getPrototypeOf(message), Object.getOwnPropertyDescriptors(message));
+  Object.defineProperty(sanitized, "params", { configurable: true, enumerable: true, value: params, writable: true });
+  return sanitized;
+}
+
+class OwnDataTransport {
+  onclose;
+  onerror;
+  onmessage;
+
+  constructor(transport) { this.transport = transport; }
+  get sessionId() { return this.transport.sessionId; }
+  async start() {
+    this.transport.onmessage = (message, extra) => this.onmessage?.(sanitizedToolCallMessage(message), extra);
+    this.transport.onerror = (error) => this.onerror?.(error);
+    this.transport.onclose = () => this.onclose?.();
+    await this.transport.start();
+  }
+  close() { return this.transport.close(); }
+  send(message, options) { return this.transport.send(message, options); }
+  setProtocolVersion(version) { return this.transport.setProtocolVersion?.(version); }
+}
+
+function toolResponse(value) {
+  return {
+    content: [{ type: "text", text: canonicalize(value) }],
+    ...(value.ok ? {} : { isError: true }),
+    structuredContent: value,
+  };
+}
+
+function resourceContents(uri, value) {
+  return { contents: [{ uri, mimeType: "application/json", text: canonicalize(value) }] };
+}
+
+export function materialResourceUri(stableRef) {
+  return `sg://v2/material/${encodeURIComponent(parseMaterialStableRef(stableRef).stable_ref)}`;
+}
+
+function materialReference(encoded) {
+  if (typeof encoded !== "string" || encoded.length === 0 || encoded.length > 256) {
+    throw new McpError(ErrorCode.InvalidParams, "material resource reference must be one canonical encoded StableRef");
+  }
+  let decoded;
+  try { decoded = decodeURIComponent(encoded); } catch {
+    throw new McpError(ErrorCode.InvalidParams, "material resource reference has invalid percent encoding");
+  }
+  if (encodeURIComponent(decoded) !== encoded) {
+    throw new McpError(ErrorCode.InvalidParams, "material resource reference is not canonically encoded once");
+  }
+  try { return parseMaterialStableRef(decoded).stable_ref; } catch {
+    throw new McpError(ErrorCode.InvalidParams, "material resource reference must decode to one canonical v2 StableRef");
+  }
+}
+
+function resourceEnvelope(registry, encoded) {
+  const result = registry.invoke("material-get", { reference: materialReference(encoded) });
+  if (result.ok) return result;
+  const failure = result.failures?.[0] ?? { code: "material_operation_failed", message: "v2 material operation failed" };
+  throw new McpError(ErrorCode.InvalidParams, `${failure.code}: ${failure.message}`);
+}
+
+function materialReferenceFromUri(uri) {
+  const prefix = "sg://v2/material/";
+  if (typeof uri !== "string" || !uri.startsWith(prefix) || uri.length > prefix.length + 256) {
+    throw new McpError(ErrorCode.InvalidParams, "material resource URI must use the canonical v2 authority and path");
+  }
+  const encoded = uri.slice(prefix.length);
+  const reference = materialReference(encoded);
+  if (materialResourceUri(reference) !== uri) {
+    throw new McpError(ErrorCode.InvalidParams, "material resource URI is not canonical");
+  }
+  return reference;
+}
+
+export function createMaterialMcpServer({ registry = runtimeRegistry(), manifest = loadManifest() } = {}) {
+  assertRegistry(registry);
+  if (!manifest || !Array.isArray(manifest.materials)) throw new TypeError("material MCP manifest is unavailable");
+  const server = new McpServer({ name: "StyleGallery Material", version: "2.0.0" });
+  const operations = materialOperationSpecs.filter(({ name }) => exposedNames.has(name));
+  const operationByName = new Map(operations.map((operation) => [operation.name, operation]));
+
+  for (const operation of operations) {
+    server.registerTool(operation.name, {
+      description: descriptions[operation.name],
+      inputSchema: inputSchemas[operation.name],
+      outputSchema,
+      annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false, readOnlyHint: true },
+      _meta: { effect_class: "NONE" },
+    }, async (input) => toolResponse(registry.invoke(operation.name, normalizeMaterialMcpInput(input))));
+  }
+  server.server.setRequestHandler(safeCallToolRequestSchema, async (request) => {
+    const operation = operationByName.get(request.params.name);
+    if (!operation) throw new McpError(ErrorCode.InvalidParams, `Tool ${request.params.name} not found`);
+    if (request.params.arguments?.__stylegallery_unsafe_material_input__ === true) {
+      throw new McpError(ErrorCode.InvalidParams, "operation input must contain only own plain data");
+    }
+    const normalized = normalizeMaterialMcpInput(request.params.arguments);
+    const parsed = await inputSchemas[operation.name].safeParseAsync(normalized);
+    if (!parsed.success) throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for tool ${operation.name}`);
+    return toolResponse(registry.invoke(operation.name, parsed.data));
+  });
+
+  server.registerResource(
+    "stylegallery-v2-material",
+    new ResourceTemplate("sg://v2/material/{reference}", {
+      list: async () => ({
+        resources: manifest.materials.map((record) => ({
+          name: record.stable_ref,
+          description: "Canonical admitted StyleGallery v2 material.",
+          mimeType: "application/json",
+          uri: materialResourceUri(record.stable_ref),
+        })),
+      }),
+    }),
+    { description: "Read one canonically encoded v2 material StableRef.", mimeType: "application/json" },
+    async (uri, variables) => resourceContents(uri.toString(), resourceEnvelope(registry, variables.reference)),
+  );
+  server.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    const reference = materialReferenceFromUri(uri);
+    return resourceContents(uri, resourceEnvelope(registry, encodeURIComponent(reference)));
+  });
+  const connect = server.connect.bind(server);
+  server.connect = (transport) => connect(new OwnDataTransport(transport));
+  return server;
+}
+
+export const createMcpServer = createMaterialMcpServer;