@contractspec/bundle.library 3.8.10 → 3.8.11

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

@@ -1,1039 +1,6 @@
-// src/infrastructure/elysia/logger.ts
-import { Logger, LogLevel } from "@contractspec/lib.logger";
-var createAppLogger = () => new Logger({
-  level: LogLevel.INFO,
-  environment: "production",
-  enableTracing: true,
-  enableTiming: true,
-  enableContext: true,
-  enableColors: false
-});
-var appLogger = createAppLogger();
-var dbLogger = new Logger({
-  level: LogLevel.WARN,
-  environment: "production",
-  enableTracing: true,
-  enableTiming: true,
-  enableContext: true,
-  enableColors: false
-});
-var authLogger = new Logger({
-  level: LogLevel.INFO,
-  environment: "production",
-  enableTracing: true,
-  enableTiming: true,
-  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 { createMcpServer } from "@contractspec/lib.contracts-runtime-server-mcp/provider-mcp";
-import { PresentationRegistry } from "@contractspec/lib.contracts-spec/presentations";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-import { randomUUID } from "crypto";
-import { Elysia } from "elysia";
-var baseCtx = {
-  actor: "anonymous",
-  decide: async () => ({ effect: "allow" })
-};
-function createJsonRpcErrorResponse(status, code, message, data) {
-  return new Response(JSON.stringify({
-    jsonrpc: "2.0",
-    error: {
-      code,
-      message,
-      ...data ? { data } : {}
-    },
-    id: null
-  }), {
-    status,
-    headers: {
-      "content-type": "application/json"
-    }
-  });
-}
-function createSessionState({
-  logger,
-  serverName,
-  ops,
-  resources,
-  prompts,
-  presentations,
-  stateful
-}) {
-  const server = new McpServer({
-    name: serverName,
-    version: "1.0.0"
-  }, {
-    capabilities: {
-      tools: {},
-      resources: {},
-      prompts: {},
-      logging: {}
-    }
-  });
-  logger.info("Setting up MCP server...");
-  createMcpServer(server, ops, resources, prompts, {
-    logger,
-    toolCtx: () => baseCtx,
-    promptCtx: () => ({ locale: "en" }),
-    resourceCtx: () => ({ locale: "en" }),
-    presentations: new PresentationRegistry(presentations)
-  });
-  const transport = new WebStandardStreamableHTTPServerTransport({
-    sessionIdGenerator: stateful ? () => randomUUID() : undefined,
-    enableJsonResponse: true
-  });
-  return server.connect(transport).then(() => ({ server, transport }));
-}
-async function closeSessionState(state) {
-  await Promise.allSettled([state.transport.close(), state.server.close()]);
-}
-function toErrorMessage(error) {
-  return error instanceof Error ? error.stack ?? error.message : String(error);
-}
-function createMcpElysiaHandler({
-  logger,
-  path,
-  serverName,
-  ops,
-  resources,
-  prompts,
-  presentations,
-  validateAuth,
-  requiredAuthMethods
-}) {
-  logger.info("Setting up MCP handler...", {
-    requiredAuthMethods: requiredAuthMethods ?? []
-  });
-  const isStateful = process.env.CONTRACTSPEC_MCP_STATEFUL === "1";
-  const sessions = new Map;
-  async function handleStateless(request) {
-    const state = await createSessionState({
-      logger,
-      path,
-      serverName,
-      ops,
-      resources,
-      prompts,
-      presentations,
-      stateful: false
-    });
-    try {
-      return await state.transport.handleRequest(normalizeMcpRequest(request));
-    } finally {
-      await closeSessionState(state);
-    }
-  }
-  async function closeSession(sessionId) {
-    const state = sessions.get(sessionId);
-    if (!state)
-      return;
-    sessions.delete(sessionId);
-    await closeSessionState(state);
-  }
-  async function handleStateful(request) {
-    const requestedSessionId = request.headers.get("mcp-session-id");
-    let state;
-    let createdState = false;
-    if (requestedSessionId) {
-      const existing = sessions.get(requestedSessionId);
-      if (!existing) {
-        return createJsonRpcErrorResponse(404, -32001, "Session not found");
-      }
-      state = existing;
-    } else {
-      state = await createSessionState({
-        logger,
-        path,
-        serverName,
-        ops,
-        resources,
-        prompts,
-        presentations,
-        stateful: true
-      });
-      createdState = true;
-    }
-    try {
-      const response = await state.transport.handleRequest(normalizeMcpRequest(request));
-      const activeSessionId = state.transport.sessionId;
-      if (activeSessionId && !sessions.has(activeSessionId)) {
-        sessions.set(activeSessionId, state);
-      }
-      if (request.method === "DELETE" && activeSessionId) {
-        await closeSession(activeSessionId);
-      } else if (!activeSessionId && createdState) {
-        await closeSessionState(state);
-      }
-      return response;
-    } catch (error) {
-      if (createdState) {
-        await closeSessionState(state);
-      }
-      throw error;
-    }
-  }
-  return new Elysia({ name: `mcp-${serverName}` }).all(path, async ({ request }) => {
-    try {
-      if (validateAuth) {
-        const authResult = await validateAuth(request);
-        if (!authResult.valid) {
-          return createJsonRpcErrorResponse(401, -32002, "Authentication failed", authResult.reason);
-        }
-      }
-      if (isStateful) {
-        return await handleStateful(request);
-      }
-      return await handleStateless(request);
-    } catch (error) {
-      logger.error("Error handling MCP request", {
-        path,
-        method: request.method,
-        error: toErrorMessage(error)
-      });
-      return createJsonRpcErrorResponse(500, -32000, "Internal error");
-    }
-  });
-}
-
-// 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 path = normalizeText(route.route);
-  const tags = (route.block.tags ?? []).map((tag) => normalizeText(tag));
-  const haystack = [title, id, summary, body, path, ...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 (path.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
-} from "@contractspec/lib.contracts-spec";
-import {
-  DataViewRegistry
-} from "@contractspec/lib.contracts-spec/data-views";
-import {
-  ContractReferenceDataView,
-  ContractReferenceQuery,
-  DocsGenerateCommand,
-  DocsGeneratedEvent,
-  DocsIndexDataView,
-  DocsIndexQuery,
-  DocsLayoutPresentation,
-  DocsPublishCommand,
-  DocsPublishedEvent,
-  DocsReferencePagePresentation,
-  DocsSearchForm,
-  ExampleCatalogDataView
-} from "@contractspec/lib.contracts-spec/docs";
-import { FormRegistry } from "@contractspec/lib.contracts-spec/forms";
-import {
-  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 OperationSpecRegistry;
-  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
-    },
-    {
-      type: "form",
-      spec: resolveFormSpec(args.key, args.version),
-      schema: includeSchema ? resolveSerializedFormSpec(args.key, args.version) : undefined
-    },
-    {
-      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 {
-        reference: toReference(candidate.spec, candidate.type, candidate.schema)
-      };
-    }
-  }
-  throw new Error(`Contract reference not found: ${args.key}`);
-}
-
-// src/application/mcp/docsMcp.prompts.ts
-import { definePrompt, PromptRegistry } from "@contractspec/lib.contracts-spec";
-import z from "zod";
-var DOC_OWNERS = ["@contractspec"];
-var DOC_TAGS = ["docs", "mcp"];
-function buildDocPrompts(routes) {
-  const prompts = new PromptRegistry;
-  prompts.register(definePrompt({
-    meta: {
-      key: "docs.navigator",
-      version: "1.0.0",
-      title: "Find relevant ContractSpec docs",
-      description: "Guide agents to search, filter, and open the right ContractSpec docs.",
-      tags: DOC_TAGS,
-      stability: "beta",
-      owners: DOC_OWNERS
-    },
-    args: [
-      {
-        name: "topic",
-        description: "Goal or subject to search for.",
-        required: false,
-        schema: z.string().optional()
-      },
-      {
-        name: "kind",
-        description: "Optional doc kind filter.",
-        required: false,
-        schema: z.string().optional()
-      },
-      {
-        name: "tag",
-        description: "Optional tag filter.",
-        required: false,
-        schema: z.string().optional()
-      }
-    ],
-    input: z.object({
-      topic: z.string().optional(),
-      kind: z.string().optional(),
-      tag: z.string().optional()
-    }),
-    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 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://index",
-          title: "DocBlocks index"
-        },
-        {
-          type: "resource",
-          uri: "docs://facets",
-          title: "Docs facets"
-        }
-      ];
-    }
-  }));
-  prompts.register(definePrompt({
-    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: z.string()
-      },
-      {
-        name: "version",
-        description: "Optional version override.",
-        required: false,
-        schema: z.string().optional()
-      },
-      {
-        name: "type",
-        description: "Optional surface type: command, query, form, data-view, presentation, event.",
-        required: false,
-        schema: z.string().optional()
-      }
-    ],
-    input: z.object({
-      key: z.string(),
-      version: z.string().optional(),
-      type: z.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 prompts;
-}
-
-// src/application/mcp/docsMcp.resources.ts
-import {
-  defineResourceTemplate,
-  ResourceRegistry
-} from "@contractspec/lib.contracts-spec";
-import z2 from "zod";
-var DOC_TAGS2 = ["docs", "mcp"];
-function buildDocResources(routes) {
-  const resources = new ResourceRegistry;
-  const readDocIndex = (input) => searchDocs(routes, input);
-  resources.register(defineResourceTemplate({
-    meta: {
-      uriTemplate: "docs://index",
-      title: "DocBlocks index",
-      description: "Default ContractSpec docs index resource.",
-      mimeType: "application/json",
-      tags: DOC_TAGS2
-    },
-    input: z2.object({}),
-    resolve: async () => ({
-      uri: "docs://index",
-      mimeType: "application/json",
-      data: JSON.stringify(readDocIndex({}), null, 2)
-    })
-  }));
-  resources.register(defineResourceTemplate({
-    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: z2.object({
-      query: z2.string().optional(),
-      tag: z2.string().optional(),
-      kind: z2.string().optional(),
-      visibility: z2.string().optional(),
-      limit: z2.coerce.number().optional(),
-      offset: z2.coerce.number().optional()
-    }),
-    resolve: async (input) => ({
-      uri: "docs://index",
-      mimeType: "application/json",
-      data: JSON.stringify(readDocIndex(input), null, 2)
-    })
-  }));
-  resources.register(defineResourceTemplate({
-    meta: {
-      uriTemplate: "docs://list",
-      title: "DocBlocks index (legacy alias)",
-      description: "Compatibility alias for the docs index resource.",
-      mimeType: "application/json",
-      tags: DOC_TAGS2
-    },
-    input: z2.object({}),
-    resolve: async () => ({
-      uri: "docs://list",
-      mimeType: "application/json",
-      data: JSON.stringify(readDocIndex({}), null, 2)
-    })
-  }));
-  resources.register(defineResourceTemplate({
-    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: z2.object({ id: z2.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(defineResourceTemplate({
-    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: z2.object({ routePath: z2.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(defineResourceTemplate({
-    meta: {
-      uriTemplate: "docs://facets",
-      title: "Docs facets",
-      description: "Counts of available tags, kinds, and visibilities across docs.",
-      mimeType: "application/json",
-      tags: DOC_TAGS2
-    },
-    input: z2.object({}),
-    resolve: async () => ({
-      uri: "docs://facets",
-      mimeType: "application/json",
-      data: JSON.stringify(listDocFacets(routes), null, 2)
-    })
-  }));
-  resources.register(defineResourceTemplate({
-    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: z2.object({
-      key: z2.string(),
-      version: z2.string().optional(),
-      type: z2.string().optional(),
-      includeSchema: z2.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,
-  defineSchemaModel,
-  installOp,
-  OperationSpecRegistry as OperationSpecRegistry2
-} from "@contractspec/lib.contracts-spec";
-import {
-  ContractReferenceInput,
-  ContractReferenceOutput,
-  DocsIndexInput,
-  DocsIndexOutput
-} from "@contractspec/lib.contracts-spec/docs";
-import { ScalarTypeEnum } from "@contractspec/lib.schema";
-var DOC_OWNERS2 = ["@contractspec"];
-var DOC_TAGS3 = ["docs", "mcp"];
-var DocsGetInput = defineSchemaModel({
-  name: "DocsGetInput",
-  fields: {
-    id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
-  }
-});
-var DocsGetOutput = defineSchemaModel({
-  name: "DocsGetOutput",
-  fields: {
-    doc: { type: ScalarTypeEnum.JSON(), isOptional: false },
-    content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
-  }
-});
-var DocsResolveRouteInput = defineSchemaModel({
-  name: "DocsResolveRouteInput",
-  fields: {
-    route: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
-  }
-});
-var DocsResolveRouteOutput = defineSchemaModel({
-  name: "DocsResolveRouteOutput",
-  fields: {
-    doc: { type: ScalarTypeEnum.JSON(), isOptional: false },
-    content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false }
-  }
-});
-var DocsFacetsInput = defineSchemaModel({
-  name: "DocsFacetsInput",
-  fields: {}
-});
-var DocsFacetsOutput = defineSchemaModel({
-  name: "DocsFacetsOutput",
-  fields: {
-    facets: { type: ScalarTypeEnum.JSON(), isOptional: false }
-  }
-});
-function buildDocOps(routes) {
-  const registry = new OperationSpecRegistry2;
-  installOp(registry, defineCommand({
-    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));
-  installOp(registry, defineCommand({
-    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;
-  });
-  installOp(registry, defineCommand({
-    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;
-  });
-  installOp(registry, defineCommand({
-    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));
-  installOp(registry, defineCommand({
-    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;
-}
-
-// src/application/mcp/docsMcp.ts
-import { defaultDocRegistry as defaultDocRegistry3 } from "@contractspec/lib.contracts-spec/docs";
-function createDocsMcpHandler(path = "/api/mcp/docs", options = {}) {
-  const routes = defaultDocRegistry3.list();
-  return createMcpElysiaHandler({
-    logger: appLogger,
-    path,
-    serverName: "contractspec-docs-mcp",
-    ops: buildDocOps(routes),
-    resources: buildDocResources(routes),
-    prompts: buildDocPrompts(routes),
-    presentations: options.includePresentations ? routes.map(({ descriptor }) => descriptor) : undefined
-  });
-}
-export {
-  createDocsMcpHandler
-};
+import{Logger as g,LogLevel as d}from"@contractspec/lib.logger";function u(){return"production"}var Gj=()=>new g({level:d.INFO,environment:u(),enableTracing:!0,enableTiming:!0,enableContext:!0,enableColors:!1}),e=Gj(),hw=new g({level:d.WARN,environment:u(),enableTracing:!0,enableTiming:!0,enableContext:!0,enableColors:!1}),kw=new g({level:d.INFO,environment:u(),enableTracing:!0,enableTiming:!0,enableContext:!0,enableColors:!1});var jj=["application/json","text/event-stream"];function Nj(j){return!j||j.includes("*/*")||j.includes("application/*")||jj.some((w)=>j.includes(w))}function n(j){if(j.method!=="POST")return j;let w=j.headers.get("accept");if(!Nj(w))return j;let Y=jj.filter((U)=>!w?.includes(U));if(Y.length===0)return j;let J=new Headers(j.headers);return J.set("accept",[w,...Y].filter(Boolean).join(", ")),new Request(j,{headers:J})}import{createMcpServer as Lj}from"@contractspec/lib.contracts-runtime-server-mcp/provider-mcp";import{PresentationRegistry as Ej}from"@contractspec/lib.contracts-spec/presentations";import{McpServer as xj}from"@modelcontextprotocol/sdk/server/mcp.js";import{WebStandardStreamableHTTPServerTransport as Mj}from"@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";import{randomUUID as _j}from"crypto";import{Elysia as Aj}from"elysia";var Cj={actor:"anonymous",decide:async()=>({effect:"allow"})};function i(j,w,Y,J){return new Response(JSON.stringify({jsonrpc:"2.0",error:{code:w,message:Y,...J?{data:J}:{}},id:null}),{status:j,headers:{"content-type":"application/json"}})}function wj({logger:j,serverName:w,ops:Y,resources:J,prompts:U,presentations:Q,stateful:K}){let Z=new xj({name:w,version:"1.0.0"},{capabilities:{tools:{},resources:{},prompts:{},logging:{}}});j.info("Setting up MCP server..."),Lj(Z,Y,J,U,{logger:j,toolCtx:()=>Cj,promptCtx:()=>({locale:"en"}),resourceCtx:()=>({locale:"en"}),presentations:new Ej(Q)});let V=new Mj({sessionIdGenerator:K?()=>_j():void 0,enableJsonResponse:!0});return Z.connect(V).then(()=>({server:Z,transport:V}))}async function T(j){await Promise.allSettled([j.transport.close(),j.server.close()])}function Ij(j){return j instanceof Error?j.stack??j.message:String(j)}function Yj({logger:j,path:w,serverName:Y,ops:J,resources:U,prompts:Q,presentations:K,validateAuth:Z,requiredAuthMethods:V}){j.info("Setting up MCP handler...",{requiredAuthMethods:V??[]});let L=process.env.CONTRACTSPEC_MCP_STATEFUL==="1",H=new Map;async function $(B){let F=await wj({logger:j,path:w,serverName:Y,ops:J,resources:U,prompts:Q,presentations:K,stateful:!1});try{return await F.transport.handleRequest(n(B))}finally{await T(F)}}async function G(B){let F=H.get(B);if(!F)return;H.delete(B),await T(F)}async function p(B){let F=B.headers.get("mcp-session-id"),N,q=!1;if(F){let E=H.get(F);if(!E)return i(404,-32001,"Session not found");N=E}else N=await wj({logger:j,path:w,serverName:Y,ops:J,resources:U,prompts:Q,presentations:K,stateful:!0}),q=!0;try{let E=await N.transport.handleRequest(n(B)),A=N.transport.sessionId;if(A&&!H.has(A))H.set(A,N);if(B.method==="DELETE"&&A)await G(A);else if(!A&&q)await T(N);return E}catch(E){if(q)await T(N);throw E}}return new Aj({name:`mcp-${Y}`}).all(w,async({request:B})=>{try{if(Z){let F=await Z(B);if(!F.valid)return i(401,-32002,"Authentication failed",F.reason)}if(L)return await p(B);return await $(B)}catch(F){return j.error("Error handling MCP request",{path:w,method:B.method,error:Ij(F)}),i(500,-32000,"Internal error")}})}import{defaultDocRegistry as Rj}from"@contractspec/lib.contracts-spec/docs";var qj=20,bj=100;function P(j){return j?.trim().toLowerCase()??""}function Jj(j){let w=decodeURIComponent(j).trim();if(!w)return"/";return w.startsWith("/")?w:`/${w}`}function Oj(j){return(Array.isArray(j)?j:j?[j]:[]).map((Y)=>P(Y)).filter(Boolean)}function Dj(j){if(!j||Number.isNaN(j))return qj;return Math.min(Math.max(j,1),bj)}function zj(j){if(!j||Number.isNaN(j))return 0;return Math.max(j,0)}function c({block:j,route:w}){return{id:j.id,title:j.title,summary:j.summary??"",route:w,visibility:j.visibility??"public",kind:j.kind??"reference",version:j.version??"1.0.0",tags:j.tags??[]}}function Tj(j,w){if(!w)return 1;let Y=w.split(/\s+/).filter(Boolean),J=P(j.block.title),U=P(j.block.id),Q=P(j.block.summary),K=P(j.block.body),Z=P(j.route),V=(j.block.tags??[]).map(($)=>P($)),L=[J,U,Q,K,Z,...V].join(" ");if(Y.some(($)=>!L.includes($)))return 0;let H=0;for(let $ of Y){if(U.includes($))H+=8;if(J.includes($))H+=7;if(V.some((G)=>G.includes($)))H+=5;if(Q.includes($))H+=4;if(Z.includes($))H+=3;if(K.includes($))H+=2}return H}function C(j,w){let Y=P(typeof w.query==="string"?w.query:void 0),J=Oj(w.tag),U=P(typeof w.visibility==="string"?w.visibility:void 0),Q=P(typeof w.kind==="string"?w.kind:void 0),K=Dj(typeof w.limit==="number"?w.limit:void 0),Z=zj(typeof w.offset==="number"?w.offset:void 0),V=j.map(($)=>({doc:c($),score:Tj($,Y)})).filter(({doc:$,score:G})=>{let p=Y?G>0:!0,B=J.length?J.every((q)=>$.tags.some((E)=>P(E).includes(q))):!0,F=U?P($.visibility)===U:!0,N=Q?P($.kind)===Q:!0;return p&&B&&F&&N}).sort(($,G)=>{if(G.score!==$.score)return G.score-$.score;return $.doc.title.localeCompare(G.doc.title)}),L=V.slice(Z,Z+K).map(({doc:$})=>$),H=Z+L.length<V.length?Z+L.length:void 0;return{docs:L,items:L,total:V.length,...H!=null?{nextOffset:H}:{}}}function S(j){let w=decodeURIComponent(j),Y=Rj.get(w);if(!Y)return;return{doc:c(Y),content:String(Y.block.body??"")}}function h(j,w){let Y=Jj(w),J=j.find((U)=>Jj(U.route)===Y);if(!J)return;return{doc:c(J),content:String(J.block.body??"")}}function k(j){let w=new Map,Y=new Map,J=new Map;for(let Q of j){let K=Q.block.kind??"reference",Z=Q.block.visibility??"public";Y.set(K,(Y.get(K)??0)+1),J.set(Z,(J.get(Z)??0)+1);for(let V of Q.block.tags??[])w.set(V,(w.get(V)??0)+1)}let U=(Q,K)=>[...Q.entries()].sort((Z,V)=>V[1]-Z[1]||Z[0].localeCompare(V[0])).map(([Z,V])=>({[K]:Z,count:V}));return{totalDocs:j.length,tags:U(w,"tag"),kinds:U(Y,"kind"),visibilities:U(J,"visibility")}}import{EventRegistry as Sj,OperationSpecRegistry as hj}from"@contractspec/lib.contracts-spec";import{DataViewRegistry as kj}from"@contractspec/lib.contracts-spec/data-views";import{ContractReferenceDataView as fj,ContractReferenceQuery as vj,DocsGenerateCommand as yj,DocsGeneratedEvent as mj,DocsIndexDataView as lj,DocsIndexQuery as pj,DocsLayoutPresentation as gj,DocsPublishCommand as dj,DocsPublishedEvent as uj,DocsReferencePagePresentation as nj,DocsSearchForm as ij,ExampleCatalogDataView as cj}from"@contractspec/lib.contracts-spec/docs";import{FormRegistry as aj}from"@contractspec/lib.contracts-spec/forms";import{PresentationRegistry as oj}from"@contractspec/lib.contracts-spec/presentations";import{serializeDataViewSpec as tj,serializeEventSpec as rj,serializeFormSpec as sj,serializeOperationSpec as ej,serializePresentationSpec as jw}from"@contractspec/lib.contracts-spec/serialization";var f=null;function ww(){let j=new hj;return j.register(pj).register(vj).register(yj).register(dj),j}function Yw(){if(!f)f=ww();return f}function a(j,w){return Yw().get(j,w)}var v=null;function Jw(){let j=new Sj;return j.register(mj).register(uj),j}function Qw(){if(!v)v=Jw();return v}function o(j,w){return Qw().get(j,w)}var y=null;function Uw(){let j=new oj;return j.register(gj).register(nj),j}function Zw(){if(!y)y=Uw();return y}function t(j,w){return Zw().get(j,w)}var m=null;function $w(){let j=new kj;return j.register(lj).register(fj).register(cj),j}function Kw(){if(!m)m=$w();return m}function r(j,w){return Kw().get(j,w)}var l=null;function Vw(){let j=new aj;return j.register(ij),j}function Xw(){if(!l)l=Vw();return l}function s(j,w){return Xw().get(j)}function Qj(j,w){let Y=a(j,w);return ej(Y)??void 0}function Uj(j,w){let Y=o(j,w);return rj(Y)??void 0}function Zj(j,w){let Y=t(j,w);return jw(Y)??void 0}function $j(j,w){let Y=r(j,w);return tj(Y)??void 0}function Kj(j,w){let Y=s(j,w);return sj(Y)??void 0}function Hw(){f=null}function Bw(){v=null}function Fw(){y=null}function Ww(){m=null}function Pw(){l=null}function jY(){Hw(),Bw(),Fw(),Ww(),Pw()}import{defaultDocRegistry as Gw}from"@contractspec/lib.contracts-spec/docs";function Nw(j){return j?.trim().toLowerCase()??""}function Lw(j){for(let w of j??[]){let Y=Gw.get(w);if(Y)return Y.route}return}function Vj(j,w,Y,J){let U=j.meta.title??j.meta.key,Q=Lw(j.meta.docId),K=j.meta.description;return{key:j.meta.key,version:j.meta.version,type:w,title:U,description:K,markdown:[`# ${U}`,`- Key: ${j.meta.key}`,`- Type: ${w}`,`- Version: ${j.meta.version}`,Q?`- Docs route: ${Q}`:"",K?`
+${K}`:""].filter(Boolean).join(`
+`),...Q?{route:Q}:{},...Y?{schema:Y}:{},...J?{policy:J}:{},tags:j.meta.tags??[],owners:j.meta.owners??[],stability:j.meta.stability}}function I(j){let w=j.includeSchema??!1,Y=Nw(j.type),J=a(j.key,j.version);if(J&&(!Y||Y==="operation"||Y===J.meta.kind))return{reference:Vj(J,J.meta.kind,w?Qj(j.key,j.version):void 0,J.policy)};let U=[{type:"data-view",spec:r(j.key,j.version),schema:w?$j(j.key,j.version):void 0},{type:"form",spec:s(j.key,j.version),schema:w?Kj(j.key,j.version):void 0},{type:"presentation",spec:t(j.key,j.version),schema:w?Zj(j.key,j.version):void 0},{type:"event",spec:o(j.key,j.version),schema:w?Uj(j.key,j.version):void 0}];for(let Q of U)if(Q.spec&&(!Y||Y===Q.type))return{reference:Vj(Q.spec,Q.type,Q.schema)};throw Error(`Contract reference not found: ${j.key}`)}import{definePrompt as Xj,PromptRegistry as Ew}from"@contractspec/lib.contracts-spec";import W from"zod";var Hj=["@contractspec"],Bj=["docs","mcp"];function Fj(j){let w=new Ew;return w.register(Xj({meta:{key:"docs.navigator",version:"1.0.0",title:"Find relevant ContractSpec docs",description:"Guide agents to search, filter, and open the right ContractSpec docs.",tags:Bj,stability:"beta",owners:Hj},args:[{name:"topic",description:"Goal or subject to search for.",required:!1,schema:W.string().optional()},{name:"kind",description:"Optional doc kind filter.",required:!1,schema:W.string().optional()},{name:"tag",description:"Optional tag filter.",required:!1,schema:W.string().optional()}],input:W.object({topic:W.string().optional(),kind:W.string().optional(),tag:W.string().optional()}),render:async({topic:Y,kind:J,tag:U})=>{let Q=C(j,{query:Y,kind:J,tag:U,limit:3}),K=Q.docs.length?Q.docs.map((Z)=>`- ${Z.title} (${Z.id}) -> ${Z.route}`).join(`
+`):"- No direct pre-match. Use docs_list_facets-v1_0_0 to browse tags and kinds.";return[{type:"text",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.",Y?`Topic: ${Y}`:"",J?`Kind: ${J}`:"",U?`Tag: ${U}`:"","Suggested starting docs:",K].filter(Boolean).join(`
+`)},{type:"resource",uri:"docs://index",title:"DocBlocks index"},{type:"resource",uri:"docs://facets",title:"Docs facets"}]}})),w.register(Xj({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:Bj,stability:"beta",owners:Hj},args:[{name:"key",description:"ContractSpec key to resolve.",required:!0,schema:W.string()},{name:"version",description:"Optional version override.",required:!1,schema:W.string().optional()},{name:"type",description:"Optional surface type: command, query, form, data-view, presentation, event.",required:!1,schema:W.string().optional()}],input:W.object({key:W.string(),version:W.string().optional(),type:W.string().optional()}),render:async({key:Y,version:J,type:U})=>{let Q=I({key:Y,version:J,type:U,includeSchema:!0}).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: ${Q.key}`,`Resolved type: ${Q.type}`,Q.route?`Docs route: ${Q.route}`:"",`Resource URI: docs://contract-reference/${encodeURIComponent(Y)}`].filter(Boolean).join(`
+`)},{type:"resource",uri:`docs://contract-reference/${encodeURIComponent(Y)}`,title:"Contract reference"}]}})),w}import{defineResourceTemplate as x,ResourceRegistry as xw}from"@contractspec/lib.contracts-spec";import X from"zod";var M=["docs","mcp"];function Wj(j){let w=new xw,Y=(J)=>C(j,J);return w.register(x({meta:{uriTemplate:"docs://index",title:"DocBlocks index",description:"Default ContractSpec docs index resource.",mimeType:"application/json",tags:M},input:X.object({}),resolve:async()=>({uri:"docs://index",mimeType:"application/json",data:JSON.stringify(Y({}),null,2)})})),w.register(x({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:M},input:X.object({query:X.string().optional(),tag:X.string().optional(),kind:X.string().optional(),visibility:X.string().optional(),limit:X.coerce.number().optional(),offset:X.coerce.number().optional()}),resolve:async(J)=>({uri:"docs://index",mimeType:"application/json",data:JSON.stringify(Y(J),null,2)})})),w.register(x({meta:{uriTemplate:"docs://list",title:"DocBlocks index (legacy alias)",description:"Compatibility alias for the docs index resource.",mimeType:"application/json",tags:M},input:X.object({}),resolve:async()=>({uri:"docs://list",mimeType:"application/json",data:JSON.stringify(Y({}),null,2)})})),w.register(x({meta:{uriTemplate:"docs://doc/{id}",title:"Doc markdown",description:"Fetch a single DocBlock body by id as markdown.",mimeType:"text/markdown",tags:M},input:X.object({id:X.string()}),resolve:async({id:J})=>{let U=S(J);if(!U)return{uri:`docs://doc/${encodeURIComponent(J)}`,mimeType:"text/plain",data:`DocBlock not found: ${J}`};return{uri:`docs://doc/${encodeURIComponent(J)}`,mimeType:"text/markdown",data:U.content}}})),w.register(x({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:M},input:X.object({routePath:X.string()}),resolve:async({routePath:J})=>({uri:`docs://route/${encodeURIComponent(J)}`,mimeType:"application/json",data:JSON.stringify(h(j,J)??{error:"not_found",route:J},null,2)})})),w.register(x({meta:{uriTemplate:"docs://facets",title:"Docs facets",description:"Counts of available tags, kinds, and visibilities across docs.",mimeType:"application/json",tags:M},input:X.object({}),resolve:async()=>({uri:"docs://facets",mimeType:"application/json",data:JSON.stringify(k(j),null,2)})})),w.register(x({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:M},input:X.object({key:X.string(),version:X.string().optional(),type:X.string().optional(),includeSchema:X.coerce.boolean().optional()}),resolve:async({key:J,version:U,type:Q,includeSchema:K})=>({uri:`docs://contract-reference/${encodeURIComponent(J)}`,mimeType:"application/json",data:JSON.stringify(I({key:J,version:U,type:Q,includeSchema:K}),null,2)})})),w}import{defineCommand as b,defineSchemaModel as R,installOp as O,OperationSpecRegistry as Mw}from"@contractspec/lib.contracts-spec";import{ContractReferenceInput as _w,ContractReferenceOutput as Aw,DocsIndexInput as Cw,DocsIndexOutput as Iw}from"@contractspec/lib.contracts-spec/docs";import{ScalarTypeEnum as _}from"@contractspec/lib.schema";var D=["@contractspec"],z=["docs","mcp"],Rw=R({name:"DocsGetInput",fields:{id:{type:_.String_unsecure(),isOptional:!1}}}),qw=R({name:"DocsGetOutput",fields:{doc:{type:_.JSON(),isOptional:!1},content:{type:_.String_unsecure(),isOptional:!1}}}),bw=R({name:"DocsResolveRouteInput",fields:{route:{type:_.String_unsecure(),isOptional:!1}}}),Ow=R({name:"DocsResolveRouteOutput",fields:{doc:{type:_.JSON(),isOptional:!1},content:{type:_.String_unsecure(),isOptional:!1}}}),Dw=R({name:"DocsFacetsInput",fields:{}}),zw=R({name:"DocsFacetsOutput",fields:{facets:{type:_.JSON(),isOptional:!1}}});function Pj(j){let w=new Mw;return O(w,b({meta:{key:"docs.search",version:"1.0.0",stability:"beta",owners:D,tags:z,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:Cw,output:Iw},policy:{auth:"anonymous"},transport:{mcp:{toolName:"docs_search-v1_0_0"}}}),async(Y)=>C(j,Y)),O(w,b({meta:{key:"docs.get",version:"1.0.0",stability:"beta",owners:D,tags:z,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:Rw,output:qw},policy:{auth:"anonymous"},transport:{mcp:{toolName:"docs_get-v1_0_0"}}}),async({id:Y})=>{let J=S(Y);if(!J)throw Error(`DocBlock not found: ${Y}`);return J}),O(w,b({meta:{key:"docs.resolveRoute",version:"1.0.0",stability:"beta",owners:D,tags:z,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:bw,output:Ow},policy:{auth:"anonymous"},transport:{mcp:{toolName:"docs_resolve_route-v1_0_0"}}}),async({route:Y})=>{let J=h(j,Y);if(!J)throw Error(`Doc route not found: ${Y}`);return J}),O(w,b({meta:{key:"docs.contract.lookup",version:"1.0.0",stability:"beta",owners:D,tags:z,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:_w,output:Aw},policy:{auth:"anonymous"},transport:{mcp:{toolName:"docs_contract_reference-v1_0_0"}}}),async(Y)=>I(Y)),O(w,b({meta:{key:"docs.list.facets",version:"1.0.0",stability:"beta",owners:D,tags:z,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:Dw,output:zw},policy:{auth:"anonymous"},transport:{mcp:{toolName:"docs_list_facets-v1_0_0"}}}),async()=>({facets:k(j)})),w}import{defaultDocRegistry as Tw}from"@contractspec/lib.contracts-spec/docs";function qY(j="/api/mcp/docs",w={}){let Y=Tw.list();return Yj({logger:e,path:j,serverName:"contractspec-docs-mcp",ops:Pj(Y),resources:Wj(Y),prompts:Fj(Y),presentations:w.includePresentations?Y.map(({descriptor:J})=>J):void 0})}export{qY as createDocsMcpHandler};