@contractspec/bundle.library 3.8.4 → 3.8.7

package/dist/node/application/mcp/index.js

@@ -25,6 +25,25 @@ var authLogger = new Logger({
   enableContext: true,
   enableColors: false
 });
+// src/application/mcp/normalizeMcpRequest.ts
+var REQUIRED_ACCEPT_TYPES = ["application/json", "text/event-stream"];
+function canNormalizeAcceptHeader(acceptHeader) {
+  return !acceptHeader || acceptHeader.includes("*/*") || acceptHeader.includes("application/*") || REQUIRED_ACCEPT_TYPES.some((value) => acceptHeader.includes(value));
+}
+function normalizeMcpRequest(request) {
+  if (request.method !== "POST")
+    return request;
+  const acceptHeader = request.headers.get("accept");
+  if (!canNormalizeAcceptHeader(acceptHeader))
+    return request;
+  const missingTypes = REQUIRED_ACCEPT_TYPES.filter((value) => !acceptHeader?.includes(value));
+  if (missingTypes.length === 0)
+    return request;
+  const headers = new Headers(request.headers);
+  headers.set("accept", [acceptHeader, ...missingTypes].filter(Boolean).join(", "));
+  return new Request(request, { headers });
+}
+
 // src/application/mcp/common.ts
 import { randomUUID } from "node:crypto";
 import { createMcpServer } from "@contractspec/lib.contracts-runtime-server-mcp/provider-mcp";
@@ -120,7 +139,7 @@ function createMcpElysiaHandler({
       stateful: false
     });
     try {
-      return await state.transport.handleRequest(request);
+      return await state.transport.handleRequest(normalizeMcpRequest(request));
     } finally {
       await closeSessionState(state);
     }
@@ -156,7 +175,7 @@ function createMcpElysiaHandler({
       createdState = true;
     }
     try {
-      const response = await state.transport.handleRequest(request);
+      const response = await state.transport.handleRequest(normalizeMcpRequest(request));
       const activeSessionId = state.transport.sessionId;
       if (activeSessionId && !sessions.has(activeSessionId)) {
         sessions.set(activeSessionId, state);
@@ -763,90 +782,393 @@ function createContractsMcpHandler(path2 = "/api/mcp/contracts", services) {
   });
 }
 
-// src/features/docs/docs.contracts.ts
+// src/application/mcp/docsMcp.data.ts
+import { defaultDocRegistry } from "@contractspec/lib.contracts-spec/docs";
+var DEFAULT_LIMIT = 20;
+var MAX_LIMIT = 100;
+function normalizeText(value) {
+  return value?.trim().toLowerCase() ?? "";
+}
+function normalizeRoute(route) {
+  const decoded = decodeURIComponent(route).trim();
+  if (!decoded)
+    return "/";
+  return decoded.startsWith("/") ? decoded : `/${decoded}`;
+}
+function normalizeTags(value) {
+  const tags = Array.isArray(value) ? value : value ? [value] : [];
+  return tags.map((tag) => normalizeText(tag)).filter(Boolean);
+}
+function clampLimit(limit) {
+  if (!limit || Number.isNaN(limit))
+    return DEFAULT_LIMIT;
+  return Math.min(Math.max(limit, 1), MAX_LIMIT);
+}
+function clampOffset(offset) {
+  if (!offset || Number.isNaN(offset))
+    return 0;
+  return Math.max(offset, 0);
+}
+function toDocSummary({ block, route }) {
+  return {
+    id: block.id,
+    title: block.title,
+    summary: block.summary ?? "",
+    route,
+    visibility: block.visibility ?? "public",
+    kind: block.kind ?? "reference",
+    version: block.version ?? "1.0.0",
+    tags: block.tags ?? []
+  };
+}
+function scoreDoc(route, query) {
+  if (!query)
+    return 1;
+  const tokens = query.split(/\s+/).filter(Boolean);
+  const title = normalizeText(route.block.title);
+  const id = normalizeText(route.block.id);
+  const summary = normalizeText(route.block.summary);
+  const body = normalizeText(route.block.body);
+  const path2 = normalizeText(route.route);
+  const tags = (route.block.tags ?? []).map((tag) => normalizeText(tag));
+  const haystack = [title, id, summary, body, path2, ...tags].join(" ");
+  if (tokens.some((token) => !haystack.includes(token)))
+    return 0;
+  let score = 0;
+  for (const token of tokens) {
+    if (id.includes(token))
+      score += 8;
+    if (title.includes(token))
+      score += 7;
+    if (tags.some((tag) => tag.includes(token)))
+      score += 5;
+    if (summary.includes(token))
+      score += 4;
+    if (path2.includes(token))
+      score += 3;
+    if (body.includes(token))
+      score += 2;
+  }
+  return score;
+}
+function searchDocs(routes, args) {
+  const query = normalizeText(typeof args.query === "string" ? args.query : undefined);
+  const tags = normalizeTags(args.tag);
+  const visibility = normalizeText(typeof args.visibility === "string" ? args.visibility : undefined);
+  const kind = normalizeText(typeof args.kind === "string" ? args.kind : undefined);
+  const limit = clampLimit(typeof args.limit === "number" ? args.limit : undefined);
+  const offset = clampOffset(typeof args.offset === "number" ? args.offset : undefined);
+  const ranked = routes.map((route) => ({
+    doc: toDocSummary(route),
+    score: scoreDoc(route, query)
+  })).filter(({ doc, score }) => {
+    const matchesQuery = query ? score > 0 : true;
+    const matchesTags = tags.length ? tags.every((tag) => doc.tags.some((docTag) => normalizeText(docTag).includes(tag))) : true;
+    const matchesVisibility = visibility ? normalizeText(doc.visibility) === visibility : true;
+    const matchesKind = kind ? normalizeText(doc.kind) === kind : true;
+    return matchesQuery && matchesTags && matchesVisibility && matchesKind;
+  }).sort((left, right) => {
+    if (right.score !== left.score)
+      return right.score - left.score;
+    return left.doc.title.localeCompare(right.doc.title);
+  });
+  const docs = ranked.slice(offset, offset + limit).map(({ doc }) => doc);
+  const nextOffset = offset + docs.length < ranked.length ? offset + docs.length : undefined;
+  return {
+    docs,
+    items: docs,
+    total: ranked.length,
+    ...nextOffset != null ? { nextOffset } : {}
+  };
+}
+function getDocById(id) {
+  const normalizedId = decodeURIComponent(id);
+  const found = defaultDocRegistry.get(normalizedId);
+  if (!found)
+    return;
+  return {
+    doc: toDocSummary(found),
+    content: String(found.block.body ?? "")
+  };
+}
+function getDocByRoute(routes, routePath) {
+  const normalizedPath = normalizeRoute(routePath);
+  const found = routes.find((route) => normalizeRoute(route.route) === normalizedPath);
+  if (!found)
+    return;
+  return {
+    doc: toDocSummary(found),
+    content: String(found.block.body ?? "")
+  };
+}
+function listDocFacets(routes) {
+  const tags = new Map;
+  const kinds = new Map;
+  const visibilities = new Map;
+  for (const route of routes) {
+    const kind = route.block.kind ?? "reference";
+    const visibility = route.block.visibility ?? "public";
+    kinds.set(kind, (kinds.get(kind) ?? 0) + 1);
+    visibilities.set(visibility, (visibilities.get(visibility) ?? 0) + 1);
+    for (const tag of route.block.tags ?? []) {
+      tags.set(tag, (tags.get(tag) ?? 0) + 1);
+    }
+  }
+  const toEntries = (values, key) => [...values.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).map(([value, count]) => ({ [key]: value, count }));
+  return {
+    totalDocs: routes.length,
+    tags: toEntries(tags, "tag"),
+    kinds: toEntries(kinds, "kind"),
+    visibilities: toEntries(visibilities, "visibility")
+  };
+}
+
+// src/features/contracts-registry.ts
+import {
+  EventRegistry,
+  OperationSpecRegistry as OperationSpecRegistry3
+} from "@contractspec/lib.contracts-spec";
 import {
+  DataViewRegistry
+} from "@contractspec/lib.contracts-spec/data-views";
+import {
+  ContractReferenceDataView,
   ContractReferenceQuery,
-  DocSummaryModel,
-  DocsIndexInput,
-  DocsIndexOutput,
+  DocsGenerateCommand,
+  DocsGeneratedEvent,
+  DocsIndexDataView,
   DocsIndexQuery,
-  DocsIndexQuery as DocsIndexQuery2
+  DocsLayoutPresentation,
+  DocsPublishCommand,
+  DocsPublishedEvent,
+  DocsReferencePagePresentation,
+  DocsSearchForm,
+  ExampleCatalogDataView
 } from "@contractspec/lib.contracts-spec/docs";
-// src/application/mcp/docsMcp.ts
+import { FormRegistry } from "@contractspec/lib.contracts-spec/forms";
 import {
-  definePrompt as definePrompt3,
-  defineResourceTemplate as defineResourceTemplate3,
-  installOp as installOp3,
-  OperationSpecRegistry as OperationSpecRegistry3,
-  PromptRegistry as PromptRegistry3,
-  ResourceRegistry as ResourceRegistry3
-} from "@contractspec/lib.contracts-spec";
-import { defaultDocRegistry } from "@contractspec/lib.contracts-spec/docs";
-import z3 from "zod";
-var DOC_OWNERS = ["@contractspec"];
-var DOC_TAGS = ["docs", "mcp"];
-function buildDocResources(routes) {
-  const resources = new ResourceRegistry3;
-  resources.register(defineResourceTemplate3({
-    meta: {
-      uriTemplate: "docs://list",
-      title: "DocBlocks index",
-      description: "All registered DocBlocks with route, visibility, tags, and summary.",
-      mimeType: "application/json",
-      tags: DOC_TAGS
+  PresentationRegistry as PresentationRegistry2
+} from "@contractspec/lib.contracts-spec/presentations";
+import {
+  serializeDataViewSpec,
+  serializeEventSpec,
+  serializeFormSpec,
+  serializeOperationSpec,
+  serializePresentationSpec
+} from "@contractspec/lib.contracts-spec/serialization";
+var operationRegistry = null;
+function createContractSpecOperationRegistry() {
+  const registry = new OperationSpecRegistry3;
+  registry.register(DocsIndexQuery).register(ContractReferenceQuery).register(DocsGenerateCommand).register(DocsPublishCommand);
+  return registry;
+}
+function getContractSpecOperationRegistry() {
+  if (!operationRegistry) {
+    operationRegistry = createContractSpecOperationRegistry();
+  }
+  return operationRegistry;
+}
+function resolveOperationSpec(key, version) {
+  return getContractSpecOperationRegistry().get(key, version);
+}
+var eventRegistry = null;
+function createContractSpecEventRegistry() {
+  const registry = new EventRegistry;
+  registry.register(DocsGeneratedEvent).register(DocsPublishedEvent);
+  return registry;
+}
+function getContractSpecEventRegistry() {
+  if (!eventRegistry) {
+    eventRegistry = createContractSpecEventRegistry();
+  }
+  return eventRegistry;
+}
+function resolveEventSpec(key, version) {
+  return getContractSpecEventRegistry().get(key, version);
+}
+var presentationRegistry = null;
+function createContractSpecPresentationRegistry() {
+  const registry = new PresentationRegistry2;
+  registry.register(DocsLayoutPresentation).register(DocsReferencePagePresentation);
+  return registry;
+}
+function getContractSpecPresentationRegistry() {
+  if (!presentationRegistry) {
+    presentationRegistry = createContractSpecPresentationRegistry();
+  }
+  return presentationRegistry;
+}
+function resolvePresentationSpec(key, version) {
+  return getContractSpecPresentationRegistry().get(key, version);
+}
+var dataViewRegistry = null;
+function createContractSpecDataViewRegistry() {
+  const registry = new DataViewRegistry;
+  registry.register(DocsIndexDataView).register(ContractReferenceDataView).register(ExampleCatalogDataView);
+  return registry;
+}
+function getContractSpecDataViewRegistry() {
+  if (!dataViewRegistry) {
+    dataViewRegistry = createContractSpecDataViewRegistry();
+  }
+  return dataViewRegistry;
+}
+function resolveDataViewSpec(key, version) {
+  return getContractSpecDataViewRegistry().get(key, version);
+}
+var formRegistry = null;
+function createContractSpecFormRegistry() {
+  const registry = new FormRegistry;
+  registry.register(DocsSearchForm);
+  return registry;
+}
+function getContractSpecFormRegistry() {
+  if (!formRegistry) {
+    formRegistry = createContractSpecFormRegistry();
+  }
+  return formRegistry;
+}
+function resolveFormSpec(key, _version) {
+  return getContractSpecFormRegistry().get(key);
+}
+function resolveSerializedOperationSpec(key, version) {
+  const spec = resolveOperationSpec(key, version);
+  return serializeOperationSpec(spec) ?? undefined;
+}
+function resolveSerializedEventSpec(key, version) {
+  const spec = resolveEventSpec(key, version);
+  return serializeEventSpec(spec) ?? undefined;
+}
+function resolveSerializedPresentationSpec(key, version) {
+  const spec = resolvePresentationSpec(key, version);
+  return serializePresentationSpec(spec) ?? undefined;
+}
+function resolveSerializedDataViewSpec(key, version) {
+  const spec = resolveDataViewSpec(key, version);
+  return serializeDataViewSpec(spec) ?? undefined;
+}
+function resolveSerializedFormSpec(key, version) {
+  const spec = resolveFormSpec(key, version);
+  return serializeFormSpec(spec) ?? undefined;
+}
+function resetContractSpecOperationRegistry() {
+  operationRegistry = null;
+}
+function resetContractSpecEventRegistry() {
+  eventRegistry = null;
+}
+function resetContractSpecPresentationRegistry() {
+  presentationRegistry = null;
+}
+function resetContractSpecDataViewRegistry() {
+  dataViewRegistry = null;
+}
+function resetContractSpecFormRegistry() {
+  formRegistry = null;
+}
+function resetAllContractSpecRegistries() {
+  resetContractSpecOperationRegistry();
+  resetContractSpecEventRegistry();
+  resetContractSpecPresentationRegistry();
+  resetContractSpecDataViewRegistry();
+  resetContractSpecFormRegistry();
+}
+
+// src/application/mcp/docsMcp.reference.ts
+import { defaultDocRegistry as defaultDocRegistry2 } from "@contractspec/lib.contracts-spec/docs";
+function normalizeText2(value) {
+  return value?.trim().toLowerCase() ?? "";
+}
+function routeFromDocIds(docIds) {
+  for (const docId of docIds ?? []) {
+    const doc = defaultDocRegistry2.get(docId);
+    if (doc)
+      return doc.route;
+  }
+  return;
+}
+function toReference(spec, type, schema, policy) {
+  const title = spec.meta.title ?? spec.meta.key;
+  const route = routeFromDocIds(spec.meta.docId);
+  const description = spec.meta.description;
+  return {
+    key: spec.meta.key,
+    version: spec.meta.version,
+    type,
+    title,
+    description,
+    markdown: [
+      `# ${title}`,
+      `- Key: ${spec.meta.key}`,
+      `- Type: ${type}`,
+      `- Version: ${spec.meta.version}`,
+      route ? `- Docs route: ${route}` : "",
+      description ? `
+${description}` : ""
+    ].filter(Boolean).join(`
+`),
+    ...route ? { route } : {},
+    ...schema ? { schema } : {},
+    ...policy ? { policy } : {},
+    tags: spec.meta.tags ?? [],
+    owners: spec.meta.owners ?? [],
+    stability: spec.meta.stability
+  };
+}
+function resolveContractReference(args) {
+  const includeSchema = args.includeSchema ?? false;
+  const requestedType = normalizeText2(args.type);
+  const operation = resolveOperationSpec(args.key, args.version);
+  if (operation && (!requestedType || requestedType === "operation" || requestedType === operation.meta.kind)) {
+    return {
+      reference: toReference(operation, operation.meta.kind, includeSchema ? resolveSerializedOperationSpec(args.key, args.version) : undefined, operation.policy)
+    };
+  }
+  const resolvers = [
+    {
+      type: "data-view",
+      spec: resolveDataViewSpec(args.key, args.version),
+      schema: includeSchema ? resolveSerializedDataViewSpec(args.key, args.version) : undefined
     },
-    input: z3.object({}),
-    resolve: async () => {
-      const docs = routes.map(({ block, route }) => ({
-        id: block.id,
-        title: block.title,
-        summary: block.summary ?? "",
-        tags: block.tags ?? [],
-        visibility: block.visibility ?? "public",
-        route
-      }));
-      return {
-        uri: "docs://list",
-        mimeType: "application/json",
-        data: JSON.stringify(docs, null, 2)
-      };
-    }
-  }));
-  resources.register(defineResourceTemplate3({
-    meta: {
-      uriTemplate: "docs://doc/{id}",
-      title: "DocBlock markdown",
-      description: "Fetch DocBlock body by id as markdown.",
-      mimeType: "text/markdown",
-      tags: DOC_TAGS
+    {
+      type: "form",
+      spec: resolveFormSpec(args.key, args.version),
+      schema: includeSchema ? resolveSerializedFormSpec(args.key, args.version) : undefined
     },
-    input: z3.object({ id: z3.string() }),
-    resolve: async ({ id }) => {
-      const found = defaultDocRegistry.get(id);
-      if (!found) {
-        return {
-          uri: `docs://doc/${encodeURIComponent(id)}`,
-          mimeType: "text/plain",
-          data: `DocBlock not found: ${id}`
-        };
-      }
+    {
+      type: "presentation",
+      spec: resolvePresentationSpec(args.key, args.version),
+      schema: includeSchema ? resolveSerializedPresentationSpec(args.key, args.version) : undefined
+    },
+    {
+      type: "event",
+      spec: resolveEventSpec(args.key, args.version),
+      schema: includeSchema ? resolveSerializedEventSpec(args.key, args.version) : undefined
+    }
+  ];
+  for (const candidate of resolvers) {
+    if (candidate.spec && (!requestedType || requestedType === candidate.type)) {
       return {
-        uri: `docs://doc/${encodeURIComponent(id)}`,
-        mimeType: "text/markdown",
-        data: String(found.block.body ?? "")
+        reference: toReference(candidate.spec, candidate.type, candidate.schema)
       };
     }
-  }));
-  return resources;
+  }
+  throw new Error(`Contract reference not found: ${args.key}`);
 }
-function buildDocPrompts() {
+
+// src/application/mcp/docsMcp.prompts.ts
+import { definePrompt as definePrompt3, PromptRegistry as PromptRegistry3 } from "@contractspec/lib.contracts-spec";
+import z3 from "zod";
+var DOC_OWNERS = ["@contractspec"];
+var DOC_TAGS = ["docs", "mcp"];
+function buildDocPrompts(routes) {
   const prompts = new PromptRegistry3;
   prompts.register(definePrompt3({
     meta: {
       key: "docs.navigator",
       version: "1.0.0",
       title: "Find relevant ContractSpec docs",
-      description: "Guide agents to pick the right DocBlock by topic or tag.",
+      description: "Guide agents to search, filter, and open the right ContractSpec docs.",
       tags: DOC_TAGS,
       stability: "beta",
       owners: DOC_OWNERS
@@ -858,6 +1180,12 @@ function buildDocPrompts() {
         required: false,
         schema: z3.string().optional()
       },
+      {
+        name: "kind",
+        description: "Optional doc kind filter.",
+        required: false,
+        schema: z3.string().optional()
+      },
       {
         name: "tag",
         description: "Optional tag filter.",
@@ -867,82 +1195,429 @@ function buildDocPrompts() {
     ],
     input: z3.object({
       topic: z3.string().optional(),
+      kind: z3.string().optional(),
       tag: z3.string().optional()
     }),
-    render: async ({ topic, tag }) => {
-      const parts = [
+    render: async ({ topic, kind, tag }) => {
+      const matches = searchDocs(routes, {
+        query: topic,
+        kind,
+        tag,
+        limit: 3
+      });
+      const suggestedDocs = matches.docs.length ? matches.docs.map((doc) => `- ${doc.title} (${doc.id}) -> ${doc.route}`).join(`
+`) : "- No direct pre-match. Use docs_list_facets-v1_0_0 to browse tags and kinds.";
+      return [
         {
           type: "text",
-          text: `Use the docs index to choose DocBlocks. If a specific topic is provided, prefer docs whose id/title/summary match it.${topic ? ` Topic: ${topic}.` : ""}${tag ? ` Tag: ${tag}.` : ""}`
+          text: [
+            "Use docs_search-v1_0_0 first, then read docs://doc/{id} for the strongest matches.",
+            "Use docs_resolve_route-v1_0_0 when the user already gives you a docs URL or route.",
+            "Use docs_list_facets-v1_0_0 or docs://facets to browse the docs taxonomy before guessing.",
+            topic ? `Topic: ${topic}` : "",
+            kind ? `Kind: ${kind}` : "",
+            tag ? `Tag: ${tag}` : "",
+            "Suggested starting docs:",
+            suggestedDocs
+          ].filter(Boolean).join(`
+`)
         },
         {
           type: "resource",
-          uri: "docs://list",
+          uri: "docs://index",
           title: "DocBlocks index"
+        },
+        {
+          type: "resource",
+          uri: "docs://facets",
+          title: "Docs facets"
+        }
+      ];
+    }
+  }));
+  prompts.register(definePrompt3({
+    meta: {
+      key: "docs.reference.guide",
+      version: "1.0.0",
+      title: "Resolve a ContractSpec reference",
+      description: "Guide agents to fetch the canonical reference payload for a ContractSpec surface.",
+      tags: DOC_TAGS,
+      stability: "beta",
+      owners: DOC_OWNERS
+    },
+    args: [
+      {
+        name: "key",
+        description: "ContractSpec key to resolve.",
+        required: true,
+        schema: z3.string()
+      },
+      {
+        name: "version",
+        description: "Optional version override.",
+        required: false,
+        schema: z3.string().optional()
+      },
+      {
+        name: "type",
+        description: "Optional surface type: command, query, form, data-view, presentation, event.",
+        required: false,
+        schema: z3.string().optional()
+      }
+    ],
+    input: z3.object({
+      key: z3.string(),
+      version: z3.string().optional(),
+      type: z3.string().optional()
+    }),
+    render: async ({ key, version, type }) => {
+      const reference = resolveContractReference({
+        key,
+        version,
+        type,
+        includeSchema: true
+      }).reference;
+      return [
+        {
+          type: "text",
+          text: [
+            "Use docs_contract_reference-v1_0_0 when you need the canonical docs payload for a ContractSpec surface.",
+            "Use docs_get-v1_0_0 only when you already know the exact DocBlock id and need raw markdown.",
+            `Resolved key: ${reference.key}`,
+            `Resolved type: ${reference.type}`,
+            reference.route ? `Docs route: ${reference.route}` : "",
+            `Resource URI: docs://contract-reference/${encodeURIComponent(key)}`
+          ].filter(Boolean).join(`
+`)
+        },
+        {
+          type: "resource",
+          uri: `docs://contract-reference/${encodeURIComponent(key)}`,
+          title: "Contract reference"
         }
       ];
-      return parts;
     }
   }));
   return prompts;
 }
+
+// src/application/mcp/docsMcp.resources.ts
+import {
+  defineResourceTemplate as defineResourceTemplate3,
+  ResourceRegistry as ResourceRegistry3
+} from "@contractspec/lib.contracts-spec";
+import z4 from "zod";
+var DOC_TAGS2 = ["docs", "mcp"];
+function buildDocResources(routes) {
+  const resources = new ResourceRegistry3;
+  const readDocIndex = (input) => searchDocs(routes, input);
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "docs://index",
+      title: "DocBlocks index",
+      description: "Default ContractSpec docs index resource.",
+      mimeType: "application/json",
+      tags: DOC_TAGS2
+    },
+    input: z4.object({}),
+    resolve: async () => ({
+      uri: "docs://index",
+      mimeType: "application/json",
+      data: JSON.stringify(readDocIndex({}), null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "docs://index{?query,tag,kind,visibility,limit,offset}",
+      title: "DocBlocks index",
+      description: "Search and paginate ContractSpec docs by query, tag, kind, or visibility.",
+      mimeType: "application/json",
+      tags: DOC_TAGS2
+    },
+    input: z4.object({
+      query: z4.string().optional(),
+      tag: z4.string().optional(),
+      kind: z4.string().optional(),
+      visibility: z4.string().optional(),
+      limit: z4.coerce.number().optional(),
+      offset: z4.coerce.number().optional()
+    }),
+    resolve: async (input) => ({
+      uri: "docs://index",
+      mimeType: "application/json",
+      data: JSON.stringify(readDocIndex(input), null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "docs://list",
+      title: "DocBlocks index (legacy alias)",
+      description: "Compatibility alias for the docs index resource.",
+      mimeType: "application/json",
+      tags: DOC_TAGS2
+    },
+    input: z4.object({}),
+    resolve: async () => ({
+      uri: "docs://list",
+      mimeType: "application/json",
+      data: JSON.stringify(readDocIndex({}), null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "docs://doc/{id}",
+      title: "Doc markdown",
+      description: "Fetch a single DocBlock body by id as markdown.",
+      mimeType: "text/markdown",
+      tags: DOC_TAGS2
+    },
+    input: z4.object({ id: z4.string() }),
+    resolve: async ({ id }) => {
+      const found = getDocById(id);
+      if (!found) {
+        return {
+          uri: `docs://doc/${encodeURIComponent(id)}`,
+          mimeType: "text/plain",
+          data: `DocBlock not found: ${id}`
+        };
+      }
+      return {
+        uri: `docs://doc/${encodeURIComponent(id)}`,
+        mimeType: "text/markdown",
+        data: found.content
+      };
+    }
+  }));
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "docs://route/{routePath}",
+      title: "Doc by route",
+      description: "Resolve a docs route to the matching DocBlock summary and body.",
+      mimeType: "application/json",
+      tags: DOC_TAGS2
+    },
+    input: z4.object({ routePath: z4.string() }),
+    resolve: async ({ routePath }) => ({
+      uri: `docs://route/${encodeURIComponent(routePath)}`,
+      mimeType: "application/json",
+      data: JSON.stringify(getDocByRoute(routes, routePath) ?? {
+        error: "not_found",
+        route: routePath
+      }, null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "docs://facets",
+      title: "Docs facets",
+      description: "Counts of available tags, kinds, and visibilities across docs.",
+      mimeType: "application/json",
+      tags: DOC_TAGS2
+    },
+    input: z4.object({}),
+    resolve: async () => ({
+      uri: "docs://facets",
+      mimeType: "application/json",
+      data: JSON.stringify(listDocFacets(routes), null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate3({
+    meta: {
+      uriTemplate: "docs://contract-reference/{key}{?version,type,includeSchema}",
+      title: "Contract reference",
+      description: "Resolve a ContractSpec surface into a docs-ready reference payload.",
+      mimeType: "application/json",
+      tags: DOC_TAGS2
+    },
+    input: z4.object({
+      key: z4.string(),
+      version: z4.string().optional(),
+      type: z4.string().optional(),
+      includeSchema: z4.coerce.boolean().optional()
+    }),
+    resolve: async ({ key, version, type, includeSchema }) => ({
+      uri: `docs://contract-reference/${encodeURIComponent(key)}`,
+      mimeType: "application/json",
+      data: JSON.stringify(resolveContractReference({ key, version, type, includeSchema }), null, 2)
+    })
+  }));
+  return resources;
+}
+
+// src/application/mcp/docsMcp.tools.ts
+import {
+  defineCommand as defineCommand3,
+  defineSchemaModel as defineSchemaModel3,
+  installOp as installOp3,
+  OperationSpecRegistry as OperationSpecRegistry4
+} from "@contractspec/lib.contracts-spec";
+import {
+  ContractReferenceInput,
+  ContractReferenceOutput,
+  DocsIndexInput,
+  DocsIndexOutput
+} from "@contractspec/lib.contracts-spec/docs";
+import { ScalarTypeEnum as ScalarTypeEnum3 } from "@contractspec/lib.schema";
+var DOC_OWNERS2 = ["@contractspec"];
+var DOC_TAGS3 = ["docs", "mcp"];
+var DocsGetInput = defineSchemaModel3({
+  name: "DocsGetInput",
+  fields: {
+    id: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false }
+  }
+});
+var DocsGetOutput = defineSchemaModel3({
+  name: "DocsGetOutput",
+  fields: {
+    doc: { type: ScalarTypeEnum3.JSON(), isOptional: false },
+    content: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false }
+  }
+});
+var DocsResolveRouteInput = defineSchemaModel3({
+  name: "DocsResolveRouteInput",
+  fields: {
+    route: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false }
+  }
+});
+var DocsResolveRouteOutput = defineSchemaModel3({
+  name: "DocsResolveRouteOutput",
+  fields: {
+    doc: { type: ScalarTypeEnum3.JSON(), isOptional: false },
+    content: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false }
+  }
+});
+var DocsFacetsInput = defineSchemaModel3({
+  name: "DocsFacetsInput",
+  fields: {}
+});
+var DocsFacetsOutput = defineSchemaModel3({
+  name: "DocsFacetsOutput",
+  fields: {
+    facets: { type: ScalarTypeEnum3.JSON(), isOptional: false }
+  }
+});
 function buildDocOps(routes) {
-  const registry = new OperationSpecRegistry3;
-  installOp3(registry, DocsIndexQuery, async (args) => {
-    const query = args.query?.toLowerCase().trim();
-    const tagsFilter = args.tag?.map((t) => t.toLowerCase().trim()) ?? [];
-    const visibility = args.visibility?.toLowerCase().trim();
-    const docs = routes.map(({ block, route }) => ({
-      id: block.id,
-      title: block.title,
-      summary: block.summary ?? "",
-      tags: block.tags ?? [],
-      visibility: (block.visibility ?? "public").toLowerCase(),
-      route
-    })).filter((doc) => {
-      const matchesQuery = query ? doc.id.toLowerCase().includes(query) || doc.title.toLowerCase().includes(query) || doc.summary.toLowerCase().includes(query) : true;
-      const matchesTags = tagsFilter.length ? tagsFilter.every((t) => doc.tags.some((tag) => tag.toLowerCase().includes(t))) : true;
-      const matchesVisibility = visibility ? doc.visibility === visibility : true;
-      return matchesQuery && matchesTags && matchesVisibility;
-    });
-    return {
-      docs,
-      items: docs,
-      total: docs.length
-    };
+  const registry = new OperationSpecRegistry4;
+  installOp3(registry, defineCommand3({
+    meta: {
+      key: "docs.search",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS2,
+      tags: DOC_TAGS3,
+      description: "Search ContractSpec docs by query, tag, kind, or visibility.",
+      goal: "Find the most relevant DocBlocks without browsing the full corpus.",
+      context: "Read-only docs MCP search surface."
+    },
+    io: { input: DocsIndexInput, output: DocsIndexOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_search-v1_0_0" } }
+  }), async (args) => searchDocs(routes, args));
+  installOp3(registry, defineCommand3({
+    meta: {
+      key: "docs.get",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS2,
+      tags: DOC_TAGS3,
+      description: "Read a single DocBlock by id.",
+      goal: "Fetch the exact markdown content and metadata for a known doc id.",
+      context: "Read-only docs MCP surface."
+    },
+    io: { input: DocsGetInput, output: DocsGetOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_get-v1_0_0" } }
+  }), async ({ id }) => {
+    const found = getDocById(id);
+    if (!found)
+      throw new Error(`DocBlock not found: ${id}`);
+    return found;
   });
+  installOp3(registry, defineCommand3({
+    meta: {
+      key: "docs.resolveRoute",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS2,
+      tags: DOC_TAGS3,
+      description: "Resolve a docs route to the matching DocBlock.",
+      goal: "Turn a route or URL path into a canonical doc id and markdown body.",
+      context: "Read-only docs MCP surface."
+    },
+    io: { input: DocsResolveRouteInput, output: DocsResolveRouteOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_resolve_route-v1_0_0" } }
+  }), async ({ route }) => {
+    const found = getDocByRoute(routes, route);
+    if (!found)
+      throw new Error(`Doc route not found: ${route}`);
+    return found;
+  });
+  installOp3(registry, defineCommand3({
+    meta: {
+      key: "docs.contract.lookup",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS2,
+      tags: DOC_TAGS3,
+      description: "Resolve a ContractSpec surface into a docs-ready reference payload.",
+      goal: "Get canonical docs metadata, route, and optional schema for a spec key.",
+      context: "Read-only docs MCP surface."
+    },
+    io: { input: ContractReferenceInput, output: ContractReferenceOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_contract_reference-v1_0_0" } }
+  }), async (args) => resolveContractReference(args));
+  installOp3(registry, defineCommand3({
+    meta: {
+      key: "docs.list.facets",
+      version: "1.0.0",
+      stability: "beta",
+      owners: DOC_OWNERS2,
+      tags: DOC_TAGS3,
+      description: "List docs taxonomy facets such as tags, kinds, and visibilities.",
+      goal: "Help agents browse the docs corpus before making targeted reads.",
+      context: "Read-only docs MCP surface."
+    },
+    io: { input: DocsFacetsInput, output: DocsFacetsOutput },
+    policy: { auth: "anonymous" },
+    transport: { mcp: { toolName: "docs_list_facets-v1_0_0" } }
+  }), async () => ({ facets: listDocFacets(routes) }));
   return registry;
 }
-function createDocsMcpHandler(path2 = "/api/mcp/docs") {
-  const routes = defaultDocRegistry.list();
+
+// src/application/mcp/docsMcp.ts
+import { defaultDocRegistry as defaultDocRegistry3 } from "@contractspec/lib.contracts-spec/docs";
+function createDocsMcpHandler(path2 = "/api/mcp/docs", options = {}) {
+  const routes = defaultDocRegistry3.list();
   return createMcpElysiaHandler({
     logger: appLogger,
     path: path2,
     serverName: "contractspec-docs-mcp",
     ops: buildDocOps(routes),
     resources: buildDocResources(routes),
-    prompts: buildDocPrompts(),
-    presentations: routes.map(({ descriptor }) => descriptor)
+    prompts: buildDocPrompts(routes),
+    presentations: options.includePresentations ? routes.map(({ descriptor }) => descriptor) : undefined
   });
 }
 
 // src/application/mcp/internalMcp.ts
 import {
-  defineCommand as defineCommand3,
+  defineCommand as defineCommand4,
   definePrompt as definePrompt4,
   defineResourceTemplate as defineResourceTemplate4,
   installOp as installOp4,
-  OperationSpecRegistry as OperationSpecRegistry4,
+  OperationSpecRegistry as OperationSpecRegistry5,
   PromptRegistry as PromptRegistry4,
   ResourceRegistry as ResourceRegistry4
 } from "@contractspec/lib.contracts-spec";
-import { defineSchemaModel as defineSchemaModel3, ScalarTypeEnum as ScalarTypeEnum3 } from "@contractspec/lib.schema";
+import { defineSchemaModel as defineSchemaModel4, ScalarTypeEnum as ScalarTypeEnum4 } from "@contractspec/lib.schema";
 import {
   getExample,
   listExamples,
   searchExamples
 } from "@contractspec/module.examples";
-import z4 from "zod";
+import z5 from "zod";
 var INTERNAL_TAGS = ["internal", "mcp"];
 var INTERNAL_OWNERS = ["@contractspec"];
 var ENDPOINTS = {
@@ -962,7 +1637,7 @@ function buildInternalResources() {
       mimeType: "application/json",
       tags: ["examples", ...INTERNAL_TAGS]
     },
-    input: z4.object({ q: z4.string().optional() }),
+    input: z5.object({ q: z5.string().optional() }),
     resolve: async ({ q }) => {
       const items = q ? searchExamples(q) : [...listExamples()];
       return {
@@ -980,7 +1655,7 @@ function buildInternalResources() {
       mimeType: "application/json",
       tags: ["examples", ...INTERNAL_TAGS]
     },
-    input: z4.object({ id: z4.string().min(1) }),
+    input: z5.object({ id: z5.string().min(1) }),
     resolve: async ({ id }) => {
       const example = getExample(id);
       if (!example) {
@@ -1005,7 +1680,7 @@ function buildInternalResources() {
       mimeType: "application/json",
       tags: INTERNAL_TAGS
     },
-    input: z4.object({}),
+    input: z5.object({}),
     resolve: async () => ({
       uri: "internal://endpoints",
       mimeType: "application/json",
@@ -1020,7 +1695,7 @@ function buildInternalResources() {
       mimeType: "text/markdown",
       tags: INTERNAL_TAGS
     },
-    input: z4.object({}),
+    input: z5.object({}),
     resolve: async () => ({
       uri: "internal://playbook",
       mimeType: "text/markdown",
@@ -1050,7 +1725,7 @@ function buildInternalPrompts() {
       stability: "beta"
     },
     args: [],
-    input: z4.object({}),
+    input: z5.object({}),
     render: async () => [
       {
         type: "text",
@@ -1066,18 +1741,18 @@ function buildInternalPrompts() {
   return prompts;
 }
 function buildInternalOps() {
-  const registry = new OperationSpecRegistry4;
-  const InternalDescribeOutput = defineSchemaModel3({
+  const registry = new OperationSpecRegistry5;
+  const InternalDescribeOutput = defineSchemaModel4({
     name: "InternalDescribeOutput",
     fields: {
       endpoints: {
-        type: ScalarTypeEnum3.JSONObject(),
+        type: ScalarTypeEnum4.JSONObject(),
         isOptional: false
       },
-      notes: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false }
+      notes: { type: ScalarTypeEnum4.String_unsecure(), isOptional: false }
     }
   });
-  const describeSpec = defineCommand3({
+  const describeSpec = defineCommand4({
     meta: {
       key: "internal_describe",
       version: "1.0.0",
@@ -1089,7 +1764,7 @@ function buildInternalOps() {
       context: "Used by internal MCP surface; read-only."
     },
     io: {
-      input: defineSchemaModel3({
+      input: defineSchemaModel4({
         name: "InternalDescribeInput",
         fields: {}
       }),
@@ -1122,7 +1797,7 @@ import {
   definePrompt as definePrompt5,
   defineResourceTemplate as defineResourceTemplate5,
   installOp as installOp5,
-  OperationSpecRegistry as OperationSpecRegistry5,
+  OperationSpecRegistry as OperationSpecRegistry6,
   PromptRegistry as PromptRegistry5,
   ResourceRegistry as ResourceRegistry5
 } from "@contractspec/lib.contracts-spec";
@@ -1137,9 +1812,9 @@ import {
   computeModelRankings,
   normalizeBenchmarkResults
 } from "@contractspec/lib.provider-ranking/scoring";
-import z5 from "zod";
-var TransportFilterSchema = z5.enum(["rest", "mcp", "webhook", "sdk"]).optional();
-var AuthFilterSchema = z5.enum([
+import z6 from "zod";
+var TransportFilterSchema = z6.enum(["rest", "mcp", "webhook", "sdk"]).optional();
+var AuthFilterSchema = z6.enum([
   "api-key",
   "oauth2",
   "bearer",
@@ -1167,7 +1842,7 @@ function buildRankingResources() {
       mimeType: "application/json",
       tags: RANKING_TAGS
     },
-    input: z5.object({
+    input: z6.object({
       transport: TransportFilterSchema,
       authMethod: AuthFilterSchema
     }),
@@ -1193,8 +1868,8 @@ function buildRankingResources() {
       mimeType: "application/json",
       tags: RANKING_TAGS
     },
-    input: z5.object({
-      dimension: z5.string(),
+    input: z6.object({
+      dimension: z6.string(),
       transport: TransportFilterSchema,
       authMethod: AuthFilterSchema
     }),
@@ -1221,7 +1896,7 @@ function buildRankingResources() {
       mimeType: "application/json",
       tags: RANKING_TAGS
     },
-    input: z5.object({ modelId: z5.string() }),
+    input: z6.object({ modelId: z6.string() }),
     resolve: async ({ modelId }) => {
       const store = getStore();
       const profile = await store.getModelProfile(modelId);
@@ -1262,7 +1937,7 @@ function buildRankingResources() {
       mimeType: "application/json",
       tags: RANKING_TAGS
     },
-    input: z5.object({}),
+    input: z6.object({}),
     resolve: async () => {
       const store = getStore();
       const result = await store.listBenchmarkResults({ limit: 200 });
@@ -1292,13 +1967,13 @@ function buildRankingPrompts() {
         name: "task",
         description: "The task or use case to recommend a model for.",
         required: true,
-        schema: z5.string()
+        schema: z6.string()
       },
       {
         name: "priority",
         description: "Priority dimension (coding, reasoning, cost, latency, etc.).",
         required: false,
-        schema: z5.string().optional()
+        schema: z6.string().optional()
       },
       {
         name: "transport",
@@ -1313,9 +1988,9 @@ function buildRankingPrompts() {
         schema: AuthFilterSchema
       }
     ],
-    input: z5.object({
-      task: z5.string(),
-      priority: z5.string().optional(),
+    input: z6.object({
+      task: z6.string(),
+      priority: z6.string().optional(),
       transport: TransportFilterSchema,
       authMethod: AuthFilterSchema
     }),
@@ -1343,7 +2018,7 @@ function buildRankingPrompts() {
   return prompts;
 }
 function buildRankingOps() {
-  const registry = new OperationSpecRegistry5;
+  const registry = new OperationSpecRegistry6;
   const ingesterRegistry = createDefaultIngesterRegistry();
   installOp5(registry, BenchmarkIngestCommand, async (args) => {
     const store = getStore();