@contractspec/bundle.library 3.7.6 → 3.8.2

package/dist/application/mcp/index.js

@@ -1,11 +1,38 @@
 // @bun
+// 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/common.ts
-import { PresentationRegistry } from "@contractspec/lib.contracts-spec/presentations";
+import { randomUUID } from "crypto";
 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 { Elysia } from "elysia";
-import { randomUUID } from "crypto";
 var baseCtx = {
   actor: "anonymous",
   decide: async () => ({ effect: "allow" })
@@ -171,44 +198,10 @@ function createMcpElysiaHandler({
   });
 }
 
-// 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/features/docs/docs.contracts.ts
-import {
-  DocSummaryModel,
-  DocsIndexInput,
-  DocsIndexOutput,
-  DocsIndexQuery,
-  DocsIndexQuery as DocsIndexQuery2,
-  ContractReferenceQuery
-} from "@contractspec/lib.contracts-spec/docs";
-// src/application/mcp/docsMcp.ts
+// src/application/mcp/cliMcp.ts
+import fs from "fs/promises";
 import {
+  defineCommand,
   definePrompt,
   defineResourceTemplate,
   installOp,
@@ -216,165 +209,9 @@ import {
   PromptRegistry,
   ResourceRegistry
 } from "@contractspec/lib.contracts-spec";
-import { defaultDocRegistry } from "@contractspec/lib.contracts-spec/docs";
-import z from "zod";
-var DOC_OWNERS = ["@contractspec"];
-var DOC_TAGS = ["docs", "mcp"];
-function buildDocResources(routes) {
-  const resources = new ResourceRegistry;
-  resources.register(defineResourceTemplate({
-    meta: {
-      uriTemplate: "docs://list",
-      title: "DocBlocks index",
-      description: "All registered DocBlocks with route, visibility, tags, and summary.",
-      mimeType: "application/json",
-      tags: DOC_TAGS
-    },
-    input: z.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(defineResourceTemplate({
-    meta: {
-      uriTemplate: "docs://doc/{id}",
-      title: "DocBlock markdown",
-      description: "Fetch DocBlock body by id as markdown.",
-      mimeType: "text/markdown",
-      tags: DOC_TAGS
-    },
-    input: z.object({ id: z.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}`
-        };
-      }
-      return {
-        uri: `docs://doc/${encodeURIComponent(id)}`,
-        mimeType: "text/markdown",
-        data: String(found.block.body ?? "")
-      };
-    }
-  }));
-  return resources;
-}
-function buildDocPrompts() {
-  const prompts = new PromptRegistry;
-  prompts.register(definePrompt({
-    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.",
-      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: "tag",
-        description: "Optional tag filter.",
-        required: false,
-        schema: z.string().optional()
-      }
-    ],
-    input: z.object({
-      topic: z.string().optional(),
-      tag: z.string().optional()
-    }),
-    render: async ({ topic, tag }) => {
-      const parts = [
-        {
-          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}.` : ""}`
-        },
-        {
-          type: "resource",
-          uri: "docs://list",
-          title: "DocBlocks index"
-        }
-      ];
-      return parts;
-    }
-  }));
-  return prompts;
-}
-function buildDocOps(routes) {
-  const registry = new OperationSpecRegistry;
-  installOp(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
-    };
-  });
-  return registry;
-}
-function createDocsMcpHandler(path = "/api/mcp/docs") {
-  const routes = defaultDocRegistry.list();
-  return createMcpElysiaHandler({
-    logger: appLogger,
-    path,
-    serverName: "contractspec-docs-mcp",
-    ops: buildDocOps(routes),
-    resources: buildDocResources(routes),
-    prompts: buildDocPrompts(),
-    presentations: routes.map(({ descriptor }) => descriptor)
-  });
-}
-
-// src/application/mcp/cliMcp.ts
-import fs from "fs/promises";
-import path from "path";
-import {
-  defineCommand,
-  definePrompt as definePrompt2,
-  defineResourceTemplate as defineResourceTemplate2,
-  installOp as installOp2,
-  OperationSpecRegistry as OperationSpecRegistry2,
-  PromptRegistry as PromptRegistry2,
-  ResourceRegistry as ResourceRegistry2
-} from "@contractspec/lib.contracts-spec";
 import { defineSchemaModel, ScalarTypeEnum } from "@contractspec/lib.schema";
-import z2 from "zod";
+import path from "path";
+import z from "zod";
 var __dirname = "/home/runner/work/contractspec/contractspec/packages/bundles/library/src/application/mcp";
 var CLI_DOC_PATHS = {
   quickstart: "packages/apps/cli-contractspec/QUICK_START.md",
@@ -427,8 +264,8 @@ async function loadCliDoc(key) {
   return fallback;
 }
 function buildCliResources() {
-  const resources = new ResourceRegistry2;
-  resources.register(defineResourceTemplate2({
+  const resources = new ResourceRegistry;
+  resources.register(defineResourceTemplate({
     meta: {
       uriTemplate: "cli://doc/{slug}",
       title: "CLI documentation",
@@ -436,8 +273,8 @@ function buildCliResources() {
       mimeType: "text/markdown",
       tags: CLI_DOC_TAGS
     },
-    input: z2.object({
-      slug: z2.enum(["quickstart", "reference", "readme"])
+    input: z.object({
+      slug: z.enum(["quickstart", "reference", "readme"])
     }),
     resolve: async ({ slug }) => {
       const data = await loadCliDoc(slug);
@@ -448,7 +285,7 @@ function buildCliResources() {
       };
     }
   }));
-  resources.register(defineResourceTemplate2({
+  resources.register(defineResourceTemplate({
     meta: {
       uriTemplate: "cli://commands",
       title: "CLI commands summary",
@@ -456,7 +293,7 @@ function buildCliResources() {
       mimeType: "application/json",
       tags: CLI_DOC_TAGS
     },
-    input: z2.object({}),
+    input: z.object({}),
     resolve: async () => {
       const commands = [
         {
@@ -485,8 +322,8 @@ function buildCliResources() {
   return resources;
 }
 function buildCliPrompts() {
-  const prompts = new PromptRegistry2;
-  prompts.register(definePrompt2({
+  const prompts = new PromptRegistry;
+  prompts.register(definePrompt({
     meta: {
       key: "cli.usage",
       version: "1.0.0",
@@ -501,10 +338,10 @@ function buildCliPrompts() {
         name: "goal",
         description: "Task the user wants to achieve.",
         required: false,
-        schema: z2.string().optional()
+        schema: z.string().optional()
       }
     ],
-    input: z2.object({ goal: z2.string().optional() }),
+    input: z.object({ goal: z.string().optional() }),
     render: async ({ goal }) => [
       {
         type: "text",
@@ -521,7 +358,7 @@ function buildCliPrompts() {
   return prompts;
 }
 function buildCliOps() {
-  const registry = new OperationSpecRegistry2;
+  const registry = new OperationSpecRegistry;
   const CliSuggestInput = defineSchemaModel({
     name: "CliSuggestInput",
     fields: {
@@ -556,7 +393,7 @@ function buildCliOps() {
       auth: "anonymous"
     }
   });
-  installOp2(registry, suggestSpec, async ({ goal, prefersAi }) => {
+  installOp(registry, suggestSpec, async ({ goal, prefersAi }) => {
     const lower = goal.toLowerCase();
     if (lower.includes("create") || lower.includes("new")) {
       return {
@@ -598,831 +435,996 @@ function createCliMcpHandler(path2 = "/api/mcp/cli") {
   });
 }
 
-// src/application/mcp/internalMcp.ts
+// src/application/mcp/contractsMcpResources.ts
 import {
-  defineCommand as defineCommand2,
-  definePrompt as definePrompt3,
-  defineResourceTemplate as defineResourceTemplate3,
-  installOp as installOp3,
-  OperationSpecRegistry as OperationSpecRegistry3,
-  PromptRegistry as PromptRegistry3,
-  ResourceRegistry as ResourceRegistry3
+  definePrompt as definePrompt2,
+  defineResourceTemplate as defineResourceTemplate2,
+  PromptRegistry as PromptRegistry2,
+  ResourceRegistry as ResourceRegistry2
 } from "@contractspec/lib.contracts-spec";
-import { defineSchemaModel as defineSchemaModel2, ScalarTypeEnum as ScalarTypeEnum2 } from "@contractspec/lib.schema";
-import z3 from "zod";
-import {
-  getExample,
-  listExamples,
-  searchExamples
-} from "@contractspec/module.examples";
-var INTERNAL_TAGS = ["internal", "mcp"];
-var INTERNAL_OWNERS = ["@contractspec"];
-var ENDPOINTS = {
-  docs: "/api/mcp/docs",
-  cli: "/api/mcp/cli",
-  internal: "/api/mcp/internal",
-  graphql: "/graphql",
-  health: "/health"
-};
-function buildInternalResources() {
-  const resources = new ResourceRegistry3;
-  resources.register(defineResourceTemplate3({
+import z2 from "zod";
+var OWNERS = ["@contractspec"];
+var TAGS = ["contracts", "mcp"];
+function buildContractsResources(services) {
+  const resources = new ResourceRegistry2;
+  resources.register(defineResourceTemplate2({
     meta: {
-      uriTemplate: "examples://list{?q}",
-      title: "ContractSpec examples registry",
-      description: "List available examples (templates, integrations, knowledge, scripts). Optional query `q` filters results.",
+      uriTemplate: "contracts://list",
+      title: "Contract specs list",
+      description: "JSON list of all contract specs in the workspace.",
       mimeType: "application/json",
-      tags: ["examples", ...INTERNAL_TAGS]
+      tags: TAGS
     },
-    input: z3.object({ q: z3.string().optional() }),
-    resolve: async ({ q }) => {
-      const items = q ? searchExamples(q) : [...listExamples()];
+    input: z2.object({}),
+    resolve: async () => {
+      const specs = await services.listSpecs();
       return {
-        uri: q ? `examples://list?q=${encodeURIComponent(q)}` : "examples://list",
+        uri: "contracts://list",
         mimeType: "application/json",
-        data: JSON.stringify(items, null, 2)
+        data: JSON.stringify(specs, null, 2)
       };
     }
   }));
-  resources.register(defineResourceTemplate3({
+  resources.register(defineResourceTemplate2({
     meta: {
-      uriTemplate: "examples://example/{id}",
-      title: "ContractSpec example (by id)",
-      description: "Fetch a single example manifest by id.",
-      mimeType: "application/json",
-      tags: ["examples", ...INTERNAL_TAGS]
+      uriTemplate: "contracts://spec/{path}",
+      title: "Contract spec content",
+      description: "Read a single contract spec file by path.",
+      mimeType: "text/plain",
+      tags: TAGS
     },
-    input: z3.object({ id: z3.string().min(1) }),
-    resolve: async ({ id }) => {
-      const example = getExample(id);
-      if (!example) {
+    input: z2.object({ path: z2.string() }),
+    resolve: async ({ path: path2 }) => {
+      const result = await services.getSpec(path2);
+      if (!result) {
         return {
-          uri: `examples://example/${encodeURIComponent(id)}`,
-          mimeType: "application/json",
-          data: JSON.stringify({ error: "not_found", id, message: `Unknown example id: ${id}` }, null, 2)
+          uri: `contracts://spec/${encodeURIComponent(path2)}`,
+          mimeType: "text/plain",
+          data: `Spec not found: ${path2}`
         };
       }
       return {
-        uri: `examples://example/${encodeURIComponent(id)}`,
-        mimeType: "application/json",
-        data: JSON.stringify(example, null, 2)
+        uri: `contracts://spec/${encodeURIComponent(path2)}`,
+        mimeType: "text/plain",
+        data: result.content
       };
     }
   }));
-  resources.register(defineResourceTemplate3({
+  resources.register(defineResourceTemplate2({
     meta: {
-      uriTemplate: "internal://endpoints",
-      title: "ContractSpec MCP endpoints",
-      description: "Endpoints for docs, CLI, internal MCP servers.",
-      mimeType: "application/json",
-      tags: INTERNAL_TAGS
-    },
-    input: z3.object({}),
-    resolve: async () => ({
-      uri: "internal://endpoints",
+      uriTemplate: "contracts://registry/manifest",
+      title: "Remote registry manifest",
+      description: "Contract registry manifest from the remote server.",
       mimeType: "application/json",
-      data: JSON.stringify(ENDPOINTS, null, 2)
-    })
-  }));
-  resources.register(defineResourceTemplate3({
-    meta: {
-      uriTemplate: "internal://playbook",
-      title: "Internal MCP usage playbook",
-      description: "How internal agents should discover docs, CLI usage, and endpoints.",
-      mimeType: "text/markdown",
-      tags: INTERNAL_TAGS
+      tags: TAGS
     },
-    input: z3.object({}),
-    resolve: async () => ({
-      uri: "internal://playbook",
-      mimeType: "text/markdown",
-      data: [
-        "# Internal MCP playbook",
-        "- Connect to docs MCP first for canonical specs.",
-        "- Use CLI MCP to surface quickstart/reference before running commands.",
-        "- Keep calls read-only unless explicitly approved.",
-        `- Endpoints: ${ENDPOINTS.docs}, ${ENDPOINTS.cli}, ${ENDPOINTS.internal}.`,
-        "- For API work, GraphQL at /graphql; health at /health."
-      ].join(`
-`)
-    })
+    input: z2.object({}),
+    resolve: async () => {
+      const manifest = await services.fetchRegistryManifest();
+      return {
+        uri: "contracts://registry/manifest",
+        mimeType: "application/json",
+        data: JSON.stringify(manifest, null, 2)
+      };
+    }
   }));
   return resources;
 }
-function buildInternalPrompts() {
-  const prompts = new PromptRegistry3;
-  prompts.register(definePrompt3({
+function buildContractsPrompts() {
+  const prompts = new PromptRegistry2;
+  prompts.register(definePrompt2({
     meta: {
-      key: "internal_bootstrap",
+      key: "contracts.editor",
       version: "1.0.0",
-      title: "Bootstrap internal ContractSpec agent",
-      description: "Points agents to the correct MCP endpoints and guardrails.",
-      tags: INTERNAL_TAGS,
-      owners: INTERNAL_OWNERS,
-      stability: "beta"
+      title: "Contract editing guide",
+      description: "Guide AI agents through reading, editing, and validating contracts.",
+      tags: TAGS,
+      stability: "beta",
+      owners: OWNERS
     },
-    args: [],
-    input: z3.object({}),
-    render: async () => [
+    args: [
+      {
+        name: "goal",
+        description: "What the agent wants to achieve with the contract.",
+        required: false,
+        schema: z2.string().optional()
+      }
+    ],
+    input: z2.object({ goal: z2.string().optional() }),
+    render: async ({ goal }) => [
       {
         type: "text",
-        text: "Start with internal://endpoints to pick the right MCP. Use docs MCP for specifications and CLI MCP for commands. Keep actions read-only unless explicitly approved."
+        text: [
+          "Contract editing workflow:",
+          "1. Use contracts.list to discover specs",
+          "2. Use contracts.get to read a spec",
+          "3. Edit content and call contracts.update",
+          "4. Run contracts.validate to verify changes",
+          "5. Run contracts.build to regenerate artifacts",
+          goal ? `Agent goal: ${goal}` : ""
+        ].filter(Boolean).join(`
+`)
       },
       {
         type: "resource",
-        uri: "internal://endpoints",
-        title: "Endpoints"
+        uri: "contracts://list",
+        title: "Available contracts"
       }
     ]
   }));
   return prompts;
 }
-function buildInternalOps() {
-  const registry = new OperationSpecRegistry3;
-  const InternalDescribeOutput = defineSchemaModel2({
-    name: "InternalDescribeOutput",
+
+// src/application/mcp/contractsMcpTools.ts
+import {
+  defineCommand as defineCommand2,
+  installOp as installOp2,
+  OperationSpecRegistry as OperationSpecRegistry2
+} from "@contractspec/lib.contracts-spec";
+import { defineSchemaModel as defineSchemaModel2, ScalarTypeEnum as ScalarTypeEnum2 } from "@contractspec/lib.schema";
+var OWNERS2 = ["@contractspec"];
+var TAGS2 = ["contracts", "mcp"];
+function buildContractsOps(services) {
+  const registry = new OperationSpecRegistry2;
+  const ListInput = defineSchemaModel2({
+    name: "ContractsListInput",
     fields: {
-      endpoints: {
-        type: ScalarTypeEnum2.JSONObject(),
-        isOptional: false
-      },
-      notes: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false }
+      pattern: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+      type: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true }
+    }
+  });
+  const ListOutput = defineSchemaModel2({
+    name: "ContractsListOutput",
+    fields: {
+      specs: { type: ScalarTypeEnum2.JSON(), isOptional: false },
+      total: { type: ScalarTypeEnum2.Int_unsecure(), isOptional: false }
     }
   });
-  const describeSpec = defineCommand2({
+  installOp2(registry, defineCommand2({
     meta: {
-      key: "internal_describe",
+      key: "contracts.list",
       version: "1.0.0",
-      stability: "stable",
-      owners: INTERNAL_OWNERS,
-      tags: INTERNAL_TAGS,
-      description: "Return MCP endpoints and guidance for internal ContractSpec agents.",
-      goal: "Speed up internal development with the correct MCP entrypoints.",
-      context: "Used by internal MCP surface; read-only."
+      stability: "beta",
+      owners: OWNERS2,
+      tags: TAGS2,
+      description: "List contract specs in the workspace.",
+      goal: "Discover available contracts by type, pattern, or owner.",
+      context: "Contracts MCP server."
     },
-    io: {
-      input: defineSchemaModel2({
-        name: "InternalDescribeInput",
-        fields: {}
-      }),
-      output: InternalDescribeOutput
+    io: { input: ListInput, output: ListOutput },
+    policy: { auth: "anonymous" }
+  }), async ({ pattern, type }) => {
+    const specs = await services.listSpecs({ pattern, type });
+    return { specs, total: specs.length };
+  });
+  const GetInput = defineSchemaModel2({
+    name: "ContractsGetInput",
+    fields: {
+      path: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false }
+    }
+  });
+  const GetOutput = defineSchemaModel2({
+    name: "ContractsGetOutput",
+    fields: {
+      content: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+      info: { type: ScalarTypeEnum2.JSON(), isOptional: false }
+    }
+  });
+  installOp2(registry, defineCommand2({
+    meta: {
+      key: "contracts.get",
+      version: "1.0.0",
+      stability: "beta",
+      owners: OWNERS2,
+      tags: TAGS2,
+      description: "Read a single contract spec file.",
+      goal: "Fetch spec content and parsed metadata.",
+      context: "Contracts MCP server."
     },
-    policy: {
-      auth: "anonymous"
+    io: { input: GetInput, output: GetOutput },
+    policy: { auth: "anonymous" }
+  }), async ({ path: path2 }) => {
+    const result = await services.getSpec(path2);
+    if (!result)
+      throw new Error(`Spec not found: ${path2}`);
+    return result;
+  });
+  const ValidateInput = defineSchemaModel2({
+    name: "ContractsValidateInput",
+    fields: {
+      path: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false }
     }
   });
-  installOp3(registry, describeSpec, async () => ({
-    endpoints: ENDPOINTS,
-    notes: "Use docs MCP for canonical specs, CLI MCP for contractspec commands, and keep side-effecting actions gated behind human review."
-  }));
-  return registry;
-}
-function createInternalMcpHandler(path2 = "/api/mcp/internal") {
-  return createMcpElysiaHandler({
-    logger: appLogger,
-    path: path2,
-    serverName: "contractspec-internal-mcp",
-    ops: buildInternalOps(),
-    resources: buildInternalResources(),
-    prompts: buildInternalPrompts()
+  const ValidateOutput = defineSchemaModel2({
+    name: "ContractsValidateOutput",
+    fields: {
+      valid: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+      errors: { type: ScalarTypeEnum2.JSON(), isOptional: false },
+      warnings: { type: ScalarTypeEnum2.JSON(), isOptional: false }
+    }
   });
-}
-
-// src/application/mcp/providerRankingMcp.ts
-import {
-  definePrompt as definePrompt4,
-  defineResourceTemplate as defineResourceTemplate4,
-  installOp as installOp4,
-  OperationSpecRegistry as OperationSpecRegistry4,
-  PromptRegistry as PromptRegistry4,
-  ResourceRegistry as ResourceRegistry4
-} from "@contractspec/lib.contracts-spec";
-import {
-  BenchmarkIngestCommand,
-  BenchmarkRunCustomCommand,
-  RankingRefreshCommand
-} from "@contractspec/lib.contracts-spec/provider-ranking";
-import z4 from "zod";
-import { getModelInfo } from "@contractspec/lib.ai-providers/models";
-import { InMemoryProviderRankingStore } from "@contractspec/lib.provider-ranking/in-memory-store";
-import { createDefaultIngesterRegistry } from "@contractspec/lib.provider-ranking/ingesters";
-import { computeModelRankings } from "@contractspec/lib.provider-ranking/scoring";
-import { normalizeBenchmarkResults } from "@contractspec/lib.provider-ranking/scoring";
-var TransportFilterSchema = z4.enum(["rest", "mcp", "webhook", "sdk"]).optional();
-var AuthFilterSchema = z4.enum([
-  "api-key",
-  "oauth2",
-  "bearer",
-  "header",
-  "basic",
-  "webhook-signing",
-  "service-account"
-]).optional();
-var RANKING_TAGS = ["ranking", "mcp", "ai"];
-var RANKING_OWNERS = ["platform.ai"];
-var sharedStore = null;
-function getStore() {
-  if (!sharedStore) {
-    sharedStore = new InMemoryProviderRankingStore;
-  }
-  return sharedStore;
-}
-function buildRankingResources() {
-  const resources = new ResourceRegistry4;
-  resources.register(defineResourceTemplate4({
+  installOp2(registry, defineCommand2({
     meta: {
-      uriTemplate: "ranking://leaderboard",
-      title: "AI Model Leaderboard",
-      description: "Current ranked list of AI models by composite score. Supports optional transport and authMethod query filters.",
-      mimeType: "application/json",
-      tags: RANKING_TAGS
+      key: "contracts.validate",
+      version: "1.0.0",
+      stability: "beta",
+      owners: OWNERS2,
+      tags: TAGS2,
+      description: "Validate a contract spec structure.",
+      goal: "Check spec for structural or policy issues.",
+      context: "Contracts MCP server."
     },
-    input: z4.object({
-      transport: TransportFilterSchema,
-      authMethod: AuthFilterSchema
-    }),
-    resolve: async ({ transport, authMethod }) => {
-      const store = getStore();
-      const result = await store.listModelRankings({
-        limit: 100,
-        requiredTransport: transport,
-        requiredAuthMethod: authMethod
-      });
-      return {
-        uri: "ranking://leaderboard",
-        mimeType: "application/json",
-        data: JSON.stringify(result, null, 2)
-      };
+    io: { input: ValidateInput, output: ValidateOutput },
+    policy: { auth: "anonymous" }
+  }), async ({ path: path2 }) => services.validateSpec(path2));
+  const BuildInput = defineSchemaModel2({
+    name: "ContractsBuildInput",
+    fields: {
+      path: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+      dryRun: { type: ScalarTypeEnum2.Boolean(), isOptional: true }
     }
-  }));
-  resources.register(defineResourceTemplate4({
+  });
+  const BuildOutput = defineSchemaModel2({
+    name: "ContractsBuildOutput",
+    fields: {
+      results: { type: ScalarTypeEnum2.JSON(), isOptional: false }
+    }
+  });
+  installOp2(registry, defineCommand2({
     meta: {
-      uriTemplate: "ranking://leaderboard/{dimension}",
-      title: "AI Model Leaderboard by Dimension",
-      description: "Ranked list of AI models filtered by a specific dimension. Supports optional transport and authMethod query filters.",
-      mimeType: "application/json",
-      tags: RANKING_TAGS
+      key: "contracts.build",
+      version: "1.0.0",
+      stability: "beta",
+      owners: OWNERS2,
+      tags: TAGS2,
+      description: "Generate implementation code from a contract spec.",
+      goal: "Produce handler, component, or test skeletons.",
+      context: "Contracts MCP server."
     },
-    input: z4.object({
-      dimension: z4.string(),
-      transport: TransportFilterSchema,
-      authMethod: AuthFilterSchema
-    }),
-    resolve: async ({ dimension, transport, authMethod }) => {
-      const store = getStore();
-      const result = await store.listModelRankings({
-        dimension,
-        limit: 100,
-        requiredTransport: transport,
-        requiredAuthMethod: authMethod
-      });
-      return {
-        uri: `ranking://leaderboard/${encodeURIComponent(dimension)}`,
-        mimeType: "application/json",
-        data: JSON.stringify(result, null, 2)
-      };
+    io: { input: BuildInput, output: BuildOutput },
+    policy: { auth: "user" }
+  }), async ({ path: path2, dryRun }) => services.buildSpec(path2, { dryRun }));
+  registerMutationTools(registry, services);
+  return registry;
+}
+function registerMutationTools(registry, services) {
+  const UpdateInput = defineSchemaModel2({
+    name: "ContractsUpdateInput",
+    fields: {
+      path: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+      content: { type: ScalarTypeEnum2.String_unsecure(), isOptional: true },
+      fields: { type: ScalarTypeEnum2.JSON(), isOptional: true }
+    }
+  });
+  const UpdateOutput = defineSchemaModel2({
+    name: "ContractsUpdateOutput",
+    fields: {
+      updated: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+      errors: { type: ScalarTypeEnum2.JSON(), isOptional: false },
+      warnings: { type: ScalarTypeEnum2.JSON(), isOptional: false }
     }
+  });
+  installOp2(registry, defineCommand2({
+    meta: {
+      key: "contracts.update",
+      version: "1.0.0",
+      stability: "beta",
+      owners: OWNERS2,
+      tags: TAGS2,
+      description: "Update an existing contract spec.",
+      goal: "Modify spec content or individual fields with validation.",
+      context: "Contracts MCP server."
+    },
+    io: { input: UpdateInput, output: UpdateOutput },
+    policy: { auth: "user" }
+  }), async ({ path: path2, content, fields }) => services.updateSpec(path2, {
+    content,
+    fields: Array.isArray(fields) ? fields : undefined
   }));
-  resources.register(defineResourceTemplate4({
+  const DeleteInput = defineSchemaModel2({
+    name: "ContractsDeleteInput",
+    fields: {
+      path: { type: ScalarTypeEnum2.String_unsecure(), isOptional: false },
+      clean: { type: ScalarTypeEnum2.Boolean(), isOptional: true }
+    }
+  });
+  const DeleteOutput = defineSchemaModel2({
+    name: "ContractsDeleteOutput",
+    fields: {
+      deleted: { type: ScalarTypeEnum2.Boolean(), isOptional: false },
+      cleanedFiles: { type: ScalarTypeEnum2.JSON(), isOptional: false },
+      errors: { type: ScalarTypeEnum2.JSON(), isOptional: false }
+    }
+  });
+  installOp2(registry, defineCommand2({
     meta: {
-      uriTemplate: "ranking://model/{modelId}",
-      title: "AI Model Profile",
-      description: "Detailed profile for a specific AI model including scores and benchmarks.",
+      key: "contracts.delete",
+      version: "1.0.0",
+      stability: "beta",
+      owners: OWNERS2,
+      tags: TAGS2,
+      description: "Delete a contract spec and optionally its artifacts.",
+      goal: "Remove a spec file and clean generated handlers/tests.",
+      context: "Contracts MCP server."
+    },
+    io: { input: DeleteInput, output: DeleteOutput },
+    policy: { auth: "user" }
+  }), async ({ path: path2, clean }) => services.deleteSpec(path2, { clean }));
+}
+
+// src/application/mcp/contractsMcp.ts
+function createContractsMcpHandler(path2 = "/api/mcp/contracts", services) {
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path: path2,
+    serverName: "contractspec-contracts-mcp",
+    ops: buildContractsOps(services),
+    resources: buildContractsResources(services),
+    prompts: buildContractsPrompts()
+  });
+}
+
+// src/features/docs/docs.contracts.ts
+import {
+  ContractReferenceQuery,
+  DocSummaryModel,
+  DocsIndexInput,
+  DocsIndexOutput,
+  DocsIndexQuery,
+  DocsIndexQuery as DocsIndexQuery2
+} from "@contractspec/lib.contracts-spec/docs";
+// src/application/mcp/docsMcp.ts
+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: RANKING_TAGS
+      tags: DOC_TAGS
     },
-    input: z4.object({ modelId: z4.string() }),
-    resolve: async ({ modelId }) => {
-      const store = getStore();
-      const profile = await store.getModelProfile(modelId);
-      if (!profile) {
-        return {
-          uri: `ranking://model/${encodeURIComponent(modelId)}`,
-          mimeType: "application/json",
-          data: JSON.stringify({ error: "not_found", modelId })
-        };
-      }
-      const enriched = profile.costPerMillion == null ? (() => {
-        const info = getModelInfo(profile.modelId);
-        return info?.costPerMillion ? {
-          ...profile,
-          costPerMillion: info.costPerMillion,
-          displayName: info.name,
-          contextWindow: info.contextWindow,
-          capabilities: [
-            ...info.capabilities.vision ? ["vision"] : [],
-            ...info.capabilities.tools ? ["tools"] : [],
-            ...info.capabilities.reasoning ? ["reasoning"] : [],
-            ...info.capabilities.streaming ? ["streaming"] : []
-          ]
-        } : profile;
-      })() : profile;
+    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: `ranking://model/${encodeURIComponent(modelId)}`,
+        uri: "docs://list",
         mimeType: "application/json",
-        data: JSON.stringify(enriched, null, 2)
+        data: JSON.stringify(docs, null, 2)
       };
     }
   }));
-  resources.register(defineResourceTemplate4({
+  resources.register(defineResourceTemplate3({
     meta: {
-      uriTemplate: "ranking://results",
-      title: "Benchmark Results",
-      description: "List of raw benchmark results from all ingested sources.",
-      mimeType: "application/json",
-      tags: RANKING_TAGS
+      uriTemplate: "docs://doc/{id}",
+      title: "DocBlock markdown",
+      description: "Fetch DocBlock body by id as markdown.",
+      mimeType: "text/markdown",
+      tags: DOC_TAGS
     },
-    input: z4.object({}),
-    resolve: async () => {
-      const store = getStore();
-      const result = await store.listBenchmarkResults({ limit: 200 });
+    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}`
+        };
+      }
       return {
-        uri: "ranking://results",
-        mimeType: "application/json",
-        data: JSON.stringify(result, null, 2)
+        uri: `docs://doc/${encodeURIComponent(id)}`,
+        mimeType: "text/markdown",
+        data: String(found.block.body ?? "")
       };
     }
   }));
   return resources;
 }
-function buildRankingPrompts() {
-  const prompts = new PromptRegistry4;
-  prompts.register(definePrompt4({
+function buildDocPrompts() {
+  const prompts = new PromptRegistry3;
+  prompts.register(definePrompt3({
     meta: {
-      key: "ranking.advisor",
+      key: "docs.navigator",
       version: "1.0.0",
-      title: "AI Model Advisor",
-      description: "Which AI model is best for a given task? Uses the leaderboard to recommend.",
-      tags: RANKING_TAGS,
+      title: "Find relevant ContractSpec docs",
+      description: "Guide agents to pick the right DocBlock by topic or tag.",
+      tags: DOC_TAGS,
       stability: "beta",
-      owners: RANKING_OWNERS
+      owners: DOC_OWNERS
     },
     args: [
       {
-        name: "task",
-        description: "The task or use case to recommend a model for.",
-        required: true,
-        schema: z4.string()
-      },
-      {
-        name: "priority",
-        description: "Priority dimension (coding, reasoning, cost, latency, etc.).",
-        required: false,
-        schema: z4.string().optional()
-      },
-      {
-        name: "transport",
-        description: "Required transport type (rest, mcp, webhook, sdk).",
+        name: "topic",
+        description: "Goal or subject to search for.",
         required: false,
-        schema: TransportFilterSchema
+        schema: z3.string().optional()
       },
       {
-        name: "authMethod",
-        description: "Required auth method (api-key, oauth2, bearer, etc.).",
+        name: "tag",
+        description: "Optional tag filter.",
         required: false,
-        schema: AuthFilterSchema
+        schema: z3.string().optional()
       }
     ],
-    input: z4.object({
-      task: z4.string(),
-      priority: z4.string().optional(),
-      transport: TransportFilterSchema,
-      authMethod: AuthFilterSchema
+    input: z3.object({
+      topic: z3.string().optional(),
+      tag: z3.string().optional()
     }),
-    render: async ({ task, priority, transport, authMethod }) => {
-      const constraints = [];
-      if (priority)
-        constraints.push(`Prioritize: ${priority}.`);
-      if (transport)
-        constraints.push(`Required transport: ${transport}.`);
-      if (authMethod)
-        constraints.push(`Required auth: ${authMethod}.`);
-      return [
+    render: async ({ topic, tag }) => {
+      const parts = [
         {
           type: "text",
-          text: `Recommend the best AI model for: "${task}".${constraints.length ? ` ${constraints.join(" ")}` : ""} Use the leaderboard data to justify your recommendation.`
+          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}.` : ""}`
         },
         {
           type: "resource",
-          uri: priority ? `ranking://leaderboard/${priority}` : "ranking://leaderboard",
-          title: "Leaderboard"
+          uri: "docs://list",
+          title: "DocBlocks index"
         }
       ];
+      return parts;
     }
   }));
   return prompts;
 }
-function buildRankingOps() {
-  const registry = new OperationSpecRegistry4;
-  const ingesterRegistry = createDefaultIngesterRegistry();
-  installOp4(registry, BenchmarkIngestCommand, async (args) => {
-    const store = getStore();
-    const source = args.source;
-    const ingester = ingesterRegistry.get(source);
-    if (!ingester) {
-      throw new Error(`No ingester registered for source: ${source}`);
-    }
-    const rawResults = await ingester.ingest({
-      sourceUrl: args.sourceUrl,
-      dimensions: args.dimensions
+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;
     });
-    const normalized = normalizeBenchmarkResults(rawResults);
-    for (const result of normalized) {
-      await store.upsertBenchmarkResult(result);
-    }
-    return {
-      ingestionId: `ingest-${source}-${Date.now()}`,
-      source,
-      resultsCount: normalized.length,
-      status: "completed",
-      ingestedAt: new Date
-    };
-  });
-  installOp4(registry, BenchmarkRunCustomCommand, async (args) => {
     return {
-      runId: `custom-${Date.now()}`,
-      evalSuiteKey: args.evalSuiteKey,
-      modelId: args.modelId,
-      status: "started",
-      startedAt: new Date
-    };
-  });
-  installOp4(registry, RankingRefreshCommand, async (args) => {
-    const store = getStore();
-    const allResults = [];
-    let offset = 0;
-    const pageSize = 500;
-    while (true) {
-      const page = await store.listBenchmarkResults({
-        limit: pageSize,
-        offset
-      });
-      allResults.push(...page.results);
-      if (allResults.length >= page.total || page.results.length < pageSize)
-        break;
-      offset += pageSize;
-    }
-    const existingRankings = new Map((await store.listModelRankings({ limit: 1e4 })).rankings.map((r) => [
-      r.modelId,
-      r
-    ]));
-    const weightOverrides = args.weightOverrides ? Array.isArray(args.weightOverrides) ? args.weightOverrides : [args.weightOverrides] : undefined;
-    const newRankings = computeModelRankings(allResults, weightOverrides ? {
-      weightOverrides
-    } : undefined, existingRankings);
-    for (const ranking of newRankings) {
-      await store.upsertModelRanking(ranking);
-    }
-    return {
-      modelsRanked: newRankings.length,
-      updatedAt: new Date,
-      status: "completed"
+      docs,
+      items: docs,
+      total: docs.length
     };
   });
   return registry;
 }
-function createProviderRankingMcpHandler(path2 = "/api/mcp/ranking") {
+function createDocsMcpHandler(path2 = "/api/mcp/docs") {
+  const routes = defaultDocRegistry.list();
   return createMcpElysiaHandler({
     logger: appLogger,
     path: path2,
-    serverName: "contractspec-ranking-mcp",
-    ops: buildRankingOps(),
-    resources: buildRankingResources(),
-    prompts: buildRankingPrompts()
+    serverName: "contractspec-docs-mcp",
+    ops: buildDocOps(routes),
+    resources: buildDocResources(routes),
+    prompts: buildDocPrompts(),
+    presentations: routes.map(({ descriptor }) => descriptor)
   });
 }
-function setProviderRankingStore(store) {
-  sharedStore = store;
-}
 
-// src/application/mcp/contractsMcpTools.ts
+// src/application/mcp/internalMcp.ts
 import {
   defineCommand as defineCommand3,
-  installOp as installOp5,
-  OperationSpecRegistry as OperationSpecRegistry5
+  definePrompt as definePrompt4,
+  defineResourceTemplate as defineResourceTemplate4,
+  installOp as installOp4,
+  OperationSpecRegistry as OperationSpecRegistry4,
+  PromptRegistry as PromptRegistry4,
+  ResourceRegistry as ResourceRegistry4
 } from "@contractspec/lib.contracts-spec";
 import { defineSchemaModel as defineSchemaModel3, ScalarTypeEnum as ScalarTypeEnum3 } from "@contractspec/lib.schema";
-var OWNERS = ["@contractspec"];
-var TAGS = ["contracts", "mcp"];
-function buildContractsOps(services) {
-  const registry = new OperationSpecRegistry5;
-  const ListInput = defineSchemaModel3({
-    name: "ContractsListInput",
-    fields: {
-      pattern: { type: ScalarTypeEnum3.String_unsecure(), isOptional: true },
-      type: { type: ScalarTypeEnum3.String_unsecure(), isOptional: true }
-    }
-  });
-  const ListOutput = defineSchemaModel3({
-    name: "ContractsListOutput",
-    fields: {
-      specs: { type: ScalarTypeEnum3.JSON(), isOptional: false },
-      total: { type: ScalarTypeEnum3.Int_unsecure(), isOptional: false }
-    }
-  });
-  installOp5(registry, defineCommand3({
-    meta: {
-      key: "contracts.list",
-      version: "1.0.0",
-      stability: "beta",
-      owners: OWNERS,
-      tags: TAGS,
-      description: "List contract specs in the workspace.",
-      goal: "Discover available contracts by type, pattern, or owner.",
-      context: "Contracts MCP server."
-    },
-    io: { input: ListInput, output: ListOutput },
-    policy: { auth: "anonymous" }
-  }), async ({ pattern, type }) => {
-    const specs = await services.listSpecs({ pattern, type });
-    return { specs, total: specs.length };
-  });
-  const GetInput = defineSchemaModel3({
-    name: "ContractsGetInput",
-    fields: {
-      path: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false }
-    }
-  });
-  const GetOutput = defineSchemaModel3({
-    name: "ContractsGetOutput",
-    fields: {
-      content: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false },
-      info: { type: ScalarTypeEnum3.JSON(), isOptional: false }
-    }
-  });
-  installOp5(registry, defineCommand3({
+import {
+  getExample,
+  listExamples,
+  searchExamples
+} from "@contractspec/module.examples";
+import z4 from "zod";
+var INTERNAL_TAGS = ["internal", "mcp"];
+var INTERNAL_OWNERS = ["@contractspec"];
+var ENDPOINTS = {
+  docs: "/api/mcp/docs",
+  cli: "/api/mcp/cli",
+  internal: "/api/mcp/internal",
+  graphql: "/graphql",
+  health: "/health"
+};
+function buildInternalResources() {
+  const resources = new ResourceRegistry4;
+  resources.register(defineResourceTemplate4({
     meta: {
-      key: "contracts.get",
-      version: "1.0.0",
-      stability: "beta",
-      owners: OWNERS,
-      tags: TAGS,
-      description: "Read a single contract spec file.",
-      goal: "Fetch spec content and parsed metadata.",
-      context: "Contracts MCP server."
+      uriTemplate: "examples://list{?q}",
+      title: "ContractSpec examples registry",
+      description: "List available examples (templates, integrations, knowledge, scripts). Optional query `q` filters results.",
+      mimeType: "application/json",
+      tags: ["examples", ...INTERNAL_TAGS]
     },
-    io: { input: GetInput, output: GetOutput },
-    policy: { auth: "anonymous" }
-  }), async ({ path: path2 }) => {
-    const result = await services.getSpec(path2);
-    if (!result)
-      throw new Error(`Spec not found: ${path2}`);
-    return result;
-  });
-  const ValidateInput = defineSchemaModel3({
-    name: "ContractsValidateInput",
-    fields: {
-      path: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false }
-    }
-  });
-  const ValidateOutput = defineSchemaModel3({
-    name: "ContractsValidateOutput",
-    fields: {
-      valid: { type: ScalarTypeEnum3.Boolean(), isOptional: false },
-      errors: { type: ScalarTypeEnum3.JSON(), isOptional: false },
-      warnings: { type: ScalarTypeEnum3.JSON(), isOptional: false }
+    input: z4.object({ q: z4.string().optional() }),
+    resolve: async ({ q }) => {
+      const items = q ? searchExamples(q) : [...listExamples()];
+      return {
+        uri: q ? `examples://list?q=${encodeURIComponent(q)}` : "examples://list",
+        mimeType: "application/json",
+        data: JSON.stringify(items, null, 2)
+      };
     }
-  });
-  installOp5(registry, defineCommand3({
+  }));
+  resources.register(defineResourceTemplate4({
     meta: {
-      key: "contracts.validate",
-      version: "1.0.0",
-      stability: "beta",
-      owners: OWNERS,
-      tags: TAGS,
-      description: "Validate a contract spec structure.",
-      goal: "Check spec for structural or policy issues.",
-      context: "Contracts MCP server."
+      uriTemplate: "examples://example/{id}",
+      title: "ContractSpec example (by id)",
+      description: "Fetch a single example manifest by id.",
+      mimeType: "application/json",
+      tags: ["examples", ...INTERNAL_TAGS]
     },
-    io: { input: ValidateInput, output: ValidateOutput },
-    policy: { auth: "anonymous" }
-  }), async ({ path: path2 }) => services.validateSpec(path2));
-  const BuildInput = defineSchemaModel3({
-    name: "ContractsBuildInput",
-    fields: {
-      path: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false },
-      dryRun: { type: ScalarTypeEnum3.Boolean(), isOptional: true }
-    }
-  });
-  const BuildOutput = defineSchemaModel3({
-    name: "ContractsBuildOutput",
-    fields: {
-      results: { type: ScalarTypeEnum3.JSON(), isOptional: false }
+    input: z4.object({ id: z4.string().min(1) }),
+    resolve: async ({ id }) => {
+      const example = getExample(id);
+      if (!example) {
+        return {
+          uri: `examples://example/${encodeURIComponent(id)}`,
+          mimeType: "application/json",
+          data: JSON.stringify({ error: "not_found", id, message: `Unknown example id: ${id}` }, null, 2)
+        };
+      }
+      return {
+        uri: `examples://example/${encodeURIComponent(id)}`,
+        mimeType: "application/json",
+        data: JSON.stringify(example, null, 2)
+      };
     }
-  });
-  installOp5(registry, defineCommand3({
+  }));
+  resources.register(defineResourceTemplate4({
     meta: {
-      key: "contracts.build",
-      version: "1.0.0",
-      stability: "beta",
-      owners: OWNERS,
-      tags: TAGS,
-      description: "Generate implementation code from a contract spec.",
-      goal: "Produce handler, component, or test skeletons.",
-      context: "Contracts MCP server."
+      uriTemplate: "internal://endpoints",
+      title: "ContractSpec MCP endpoints",
+      description: "Endpoints for docs, CLI, internal MCP servers.",
+      mimeType: "application/json",
+      tags: INTERNAL_TAGS
     },
-    io: { input: BuildInput, output: BuildOutput },
-    policy: { auth: "user" }
-  }), async ({ path: path2, dryRun }) => services.buildSpec(path2, { dryRun }));
-  registerMutationTools(registry, services);
-  return registry;
+    input: z4.object({}),
+    resolve: async () => ({
+      uri: "internal://endpoints",
+      mimeType: "application/json",
+      data: JSON.stringify(ENDPOINTS, null, 2)
+    })
+  }));
+  resources.register(defineResourceTemplate4({
+    meta: {
+      uriTemplate: "internal://playbook",
+      title: "Internal MCP usage playbook",
+      description: "How internal agents should discover docs, CLI usage, and endpoints.",
+      mimeType: "text/markdown",
+      tags: INTERNAL_TAGS
+    },
+    input: z4.object({}),
+    resolve: async () => ({
+      uri: "internal://playbook",
+      mimeType: "text/markdown",
+      data: [
+        "# Internal MCP playbook",
+        "- Connect to docs MCP first for canonical specs.",
+        "- Use CLI MCP to surface quickstart/reference before running commands.",
+        "- Keep calls read-only unless explicitly approved.",
+        `- Endpoints: ${ENDPOINTS.docs}, ${ENDPOINTS.cli}, ${ENDPOINTS.internal}.`,
+        "- For API work, GraphQL at /graphql; health at /health."
+      ].join(`
+`)
+    })
+  }));
+  return resources;
 }
-function registerMutationTools(registry, services) {
-  const UpdateInput = defineSchemaModel3({
-    name: "ContractsUpdateInput",
-    fields: {
-      path: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false },
-      content: { type: ScalarTypeEnum3.String_unsecure(), isOptional: true },
-      fields: { type: ScalarTypeEnum3.JSON(), isOptional: true }
-    }
-  });
-  const UpdateOutput = defineSchemaModel3({
-    name: "ContractsUpdateOutput",
-    fields: {
-      updated: { type: ScalarTypeEnum3.Boolean(), isOptional: false },
-      errors: { type: ScalarTypeEnum3.JSON(), isOptional: false },
-      warnings: { type: ScalarTypeEnum3.JSON(), isOptional: false }
-    }
-  });
-  installOp5(registry, defineCommand3({
+function buildInternalPrompts() {
+  const prompts = new PromptRegistry4;
+  prompts.register(definePrompt4({
     meta: {
-      key: "contracts.update",
+      key: "internal_bootstrap",
       version: "1.0.0",
-      stability: "beta",
-      owners: OWNERS,
-      tags: TAGS,
-      description: "Update an existing contract spec.",
-      goal: "Modify spec content or individual fields with validation.",
-      context: "Contracts MCP server."
+      title: "Bootstrap internal ContractSpec agent",
+      description: "Points agents to the correct MCP endpoints and guardrails.",
+      tags: INTERNAL_TAGS,
+      owners: INTERNAL_OWNERS,
+      stability: "beta"
     },
-    io: { input: UpdateInput, output: UpdateOutput },
-    policy: { auth: "user" }
-  }), async ({ path: path2, content, fields }) => services.updateSpec(path2, {
-    content,
-    fields: Array.isArray(fields) ? fields : undefined
+    args: [],
+    input: z4.object({}),
+    render: async () => [
+      {
+        type: "text",
+        text: "Start with internal://endpoints to pick the right MCP. Use docs MCP for specifications and CLI MCP for commands. Keep actions read-only unless explicitly approved."
+      },
+      {
+        type: "resource",
+        uri: "internal://endpoints",
+        title: "Endpoints"
+      }
+    ]
   }));
-  const DeleteInput = defineSchemaModel3({
-    name: "ContractsDeleteInput",
-    fields: {
-      path: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false },
-      clean: { type: ScalarTypeEnum3.Boolean(), isOptional: true }
-    }
-  });
-  const DeleteOutput = defineSchemaModel3({
-    name: "ContractsDeleteOutput",
+  return prompts;
+}
+function buildInternalOps() {
+  const registry = new OperationSpecRegistry4;
+  const InternalDescribeOutput = defineSchemaModel3({
+    name: "InternalDescribeOutput",
     fields: {
-      deleted: { type: ScalarTypeEnum3.Boolean(), isOptional: false },
-      cleanedFiles: { type: ScalarTypeEnum3.JSON(), isOptional: false },
-      errors: { type: ScalarTypeEnum3.JSON(), isOptional: false }
+      endpoints: {
+        type: ScalarTypeEnum3.JSONObject(),
+        isOptional: false
+      },
+      notes: { type: ScalarTypeEnum3.String_unsecure(), isOptional: false }
     }
   });
-  installOp5(registry, defineCommand3({
+  const describeSpec = defineCommand3({
     meta: {
-      key: "contracts.delete",
+      key: "internal_describe",
       version: "1.0.0",
-      stability: "beta",
-      owners: OWNERS,
-      tags: TAGS,
-      description: "Delete a contract spec and optionally its artifacts.",
-      goal: "Remove a spec file and clean generated handlers/tests.",
-      context: "Contracts MCP server."
+      stability: "stable",
+      owners: INTERNAL_OWNERS,
+      tags: INTERNAL_TAGS,
+      description: "Return MCP endpoints and guidance for internal ContractSpec agents.",
+      goal: "Speed up internal development with the correct MCP entrypoints.",
+      context: "Used by internal MCP surface; read-only."
     },
-    io: { input: DeleteInput, output: DeleteOutput },
-    policy: { auth: "user" }
-  }), async ({ path: path2, clean }) => services.deleteSpec(path2, { clean }));
+    io: {
+      input: defineSchemaModel3({
+        name: "InternalDescribeInput",
+        fields: {}
+      }),
+      output: InternalDescribeOutput
+    },
+    policy: {
+      auth: "anonymous"
+    }
+  });
+  installOp4(registry, describeSpec, async () => ({
+    endpoints: ENDPOINTS,
+    notes: "Use docs MCP for canonical specs, CLI MCP for contractspec commands, and keep side-effecting actions gated behind human review."
+  }));
+  return registry;
+}
+function createInternalMcpHandler(path2 = "/api/mcp/internal") {
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path: path2,
+    serverName: "contractspec-internal-mcp",
+    ops: buildInternalOps(),
+    resources: buildInternalResources(),
+    prompts: buildInternalPrompts()
+  });
 }
 
-// src/application/mcp/contractsMcpResources.ts
+// src/application/mcp/providerRankingMcp.ts
+import { getModelInfo } from "@contractspec/lib.ai-providers/models";
 import {
   definePrompt as definePrompt5,
   defineResourceTemplate as defineResourceTemplate5,
+  installOp as installOp5,
+  OperationSpecRegistry as OperationSpecRegistry5,
   PromptRegistry as PromptRegistry5,
   ResourceRegistry as ResourceRegistry5
 } from "@contractspec/lib.contracts-spec";
+import {
+  BenchmarkIngestCommand,
+  BenchmarkRunCustomCommand,
+  RankingRefreshCommand
+} from "@contractspec/lib.contracts-spec/provider-ranking";
+import { InMemoryProviderRankingStore } from "@contractspec/lib.provider-ranking/in-memory-store";
+import { createDefaultIngesterRegistry } from "@contractspec/lib.provider-ranking/ingesters";
+import {
+  computeModelRankings,
+  normalizeBenchmarkResults
+} from "@contractspec/lib.provider-ranking/scoring";
 import z5 from "zod";
-var OWNERS2 = ["@contractspec"];
-var TAGS2 = ["contracts", "mcp"];
-function buildContractsResources(services) {
+var TransportFilterSchema = z5.enum(["rest", "mcp", "webhook", "sdk"]).optional();
+var AuthFilterSchema = z5.enum([
+  "api-key",
+  "oauth2",
+  "bearer",
+  "header",
+  "basic",
+  "webhook-signing",
+  "service-account"
+]).optional();
+var RANKING_TAGS = ["ranking", "mcp", "ai"];
+var RANKING_OWNERS = ["platform.ai"];
+var sharedStore = null;
+function getStore() {
+  if (!sharedStore) {
+    sharedStore = new InMemoryProviderRankingStore;
+  }
+  return sharedStore;
+}
+function buildRankingResources() {
   const resources = new ResourceRegistry5;
   resources.register(defineResourceTemplate5({
     meta: {
-      uriTemplate: "contracts://list",
-      title: "Contract specs list",
-      description: "JSON list of all contract specs in the workspace.",
+      uriTemplate: "ranking://leaderboard",
+      title: "AI Model Leaderboard",
+      description: "Current ranked list of AI models by composite score. Supports optional transport and authMethod query filters.",
+      mimeType: "application/json",
+      tags: RANKING_TAGS
+    },
+    input: z5.object({
+      transport: TransportFilterSchema,
+      authMethod: AuthFilterSchema
+    }),
+    resolve: async ({ transport, authMethod }) => {
+      const store = getStore();
+      const result = await store.listModelRankings({
+        limit: 100,
+        requiredTransport: transport,
+        requiredAuthMethod: authMethod
+      });
+      return {
+        uri: "ranking://leaderboard",
+        mimeType: "application/json",
+        data: JSON.stringify(result, null, 2)
+      };
+    }
+  }));
+  resources.register(defineResourceTemplate5({
+    meta: {
+      uriTemplate: "ranking://leaderboard/{dimension}",
+      title: "AI Model Leaderboard by Dimension",
+      description: "Ranked list of AI models filtered by a specific dimension. Supports optional transport and authMethod query filters.",
       mimeType: "application/json",
-      tags: TAGS2
+      tags: RANKING_TAGS
     },
-    input: z5.object({}),
-    resolve: async () => {
-      const specs = await services.listSpecs();
+    input: z5.object({
+      dimension: z5.string(),
+      transport: TransportFilterSchema,
+      authMethod: AuthFilterSchema
+    }),
+    resolve: async ({ dimension, transport, authMethod }) => {
+      const store = getStore();
+      const result = await store.listModelRankings({
+        dimension,
+        limit: 100,
+        requiredTransport: transport,
+        requiredAuthMethod: authMethod
+      });
       return {
-        uri: "contracts://list",
+        uri: `ranking://leaderboard/${encodeURIComponent(dimension)}`,
         mimeType: "application/json",
-        data: JSON.stringify(specs, null, 2)
+        data: JSON.stringify(result, null, 2)
       };
     }
   }));
   resources.register(defineResourceTemplate5({
     meta: {
-      uriTemplate: "contracts://spec/{path}",
-      title: "Contract spec content",
-      description: "Read a single contract spec file by path.",
-      mimeType: "text/plain",
-      tags: TAGS2
+      uriTemplate: "ranking://model/{modelId}",
+      title: "AI Model Profile",
+      description: "Detailed profile for a specific AI model including scores and benchmarks.",
+      mimeType: "application/json",
+      tags: RANKING_TAGS
     },
-    input: z5.object({ path: z5.string() }),
-    resolve: async ({ path: path2 }) => {
-      const result = await services.getSpec(path2);
-      if (!result) {
+    input: z5.object({ modelId: z5.string() }),
+    resolve: async ({ modelId }) => {
+      const store = getStore();
+      const profile = await store.getModelProfile(modelId);
+      if (!profile) {
         return {
-          uri: `contracts://spec/${encodeURIComponent(path2)}`,
-          mimeType: "text/plain",
-          data: `Spec not found: ${path2}`
+          uri: `ranking://model/${encodeURIComponent(modelId)}`,
+          mimeType: "application/json",
+          data: JSON.stringify({ error: "not_found", modelId })
         };
       }
+      const enriched = profile.costPerMillion == null ? (() => {
+        const info = getModelInfo(profile.modelId);
+        return info?.costPerMillion ? {
+          ...profile,
+          costPerMillion: info.costPerMillion,
+          displayName: info.name,
+          contextWindow: info.contextWindow,
+          capabilities: [
+            ...info.capabilities.vision ? ["vision"] : [],
+            ...info.capabilities.tools ? ["tools"] : [],
+            ...info.capabilities.reasoning ? ["reasoning"] : [],
+            ...info.capabilities.streaming ? ["streaming"] : []
+          ]
+        } : profile;
+      })() : profile;
       return {
-        uri: `contracts://spec/${encodeURIComponent(path2)}`,
-        mimeType: "text/plain",
-        data: result.content
+        uri: `ranking://model/${encodeURIComponent(modelId)}`,
+        mimeType: "application/json",
+        data: JSON.stringify(enriched, null, 2)
       };
     }
   }));
   resources.register(defineResourceTemplate5({
     meta: {
-      uriTemplate: "contracts://registry/manifest",
-      title: "Remote registry manifest",
-      description: "Contract registry manifest from the remote server.",
+      uriTemplate: "ranking://results",
+      title: "Benchmark Results",
+      description: "List of raw benchmark results from all ingested sources.",
       mimeType: "application/json",
-      tags: TAGS2
+      tags: RANKING_TAGS
     },
     input: z5.object({}),
     resolve: async () => {
-      const manifest = await services.fetchRegistryManifest();
+      const store = getStore();
+      const result = await store.listBenchmarkResults({ limit: 200 });
       return {
-        uri: "contracts://registry/manifest",
+        uri: "ranking://results",
         mimeType: "application/json",
-        data: JSON.stringify(manifest, null, 2)
+        data: JSON.stringify(result, null, 2)
       };
     }
   }));
   return resources;
 }
-function buildContractsPrompts() {
+function buildRankingPrompts() {
   const prompts = new PromptRegistry5;
   prompts.register(definePrompt5({
     meta: {
-      key: "contracts.editor",
+      key: "ranking.advisor",
       version: "1.0.0",
-      title: "Contract editing guide",
-      description: "Guide AI agents through reading, editing, and validating contracts.",
-      tags: TAGS2,
+      title: "AI Model Advisor",
+      description: "Which AI model is best for a given task? Uses the leaderboard to recommend.",
+      tags: RANKING_TAGS,
       stability: "beta",
-      owners: OWNERS2
+      owners: RANKING_OWNERS
     },
     args: [
       {
-        name: "goal",
-        description: "What the agent wants to achieve with the contract.",
+        name: "task",
+        description: "The task or use case to recommend a model for.",
+        required: true,
+        schema: z5.string()
+      },
+      {
+        name: "priority",
+        description: "Priority dimension (coding, reasoning, cost, latency, etc.).",
         required: false,
         schema: z5.string().optional()
-      }
-    ],
-    input: z5.object({ goal: z5.string().optional() }),
-    render: async ({ goal }) => [
+      },
       {
-        type: "text",
-        text: [
-          "Contract editing workflow:",
-          "1. Use contracts.list to discover specs",
-          "2. Use contracts.get to read a spec",
-          "3. Edit content and call contracts.update",
-          "4. Run contracts.validate to verify changes",
-          "5. Run contracts.build to regenerate artifacts",
-          goal ? `Agent goal: ${goal}` : ""
-        ].filter(Boolean).join(`
-`)
+        name: "transport",
+        description: "Required transport type (rest, mcp, webhook, sdk).",
+        required: false,
+        schema: TransportFilterSchema
       },
       {
-        type: "resource",
-        uri: "contracts://list",
-        title: "Available contracts"
+        name: "authMethod",
+        description: "Required auth method (api-key, oauth2, bearer, etc.).",
+        required: false,
+        schema: AuthFilterSchema
       }
-    ]
+    ],
+    input: z5.object({
+      task: z5.string(),
+      priority: z5.string().optional(),
+      transport: TransportFilterSchema,
+      authMethod: AuthFilterSchema
+    }),
+    render: async ({ task, priority, transport, authMethod }) => {
+      const constraints = [];
+      if (priority)
+        constraints.push(`Prioritize: ${priority}.`);
+      if (transport)
+        constraints.push(`Required transport: ${transport}.`);
+      if (authMethod)
+        constraints.push(`Required auth: ${authMethod}.`);
+      return [
+        {
+          type: "text",
+          text: `Recommend the best AI model for: "${task}".${constraints.length ? ` ${constraints.join(" ")}` : ""} Use the leaderboard data to justify your recommendation.`
+        },
+        {
+          type: "resource",
+          uri: priority ? `ranking://leaderboard/${priority}` : "ranking://leaderboard",
+          title: "Leaderboard"
+        }
+      ];
+    }
   }));
   return prompts;
 }
-
-// src/application/mcp/contractsMcp.ts
-function createContractsMcpHandler(path2 = "/api/mcp/contracts", services) {
+function buildRankingOps() {
+  const registry = new OperationSpecRegistry5;
+  const ingesterRegistry = createDefaultIngesterRegistry();
+  installOp5(registry, BenchmarkIngestCommand, async (args) => {
+    const store = getStore();
+    const source = args.source;
+    const ingester = ingesterRegistry.get(source);
+    if (!ingester) {
+      throw new Error(`No ingester registered for source: ${source}`);
+    }
+    const rawResults = await ingester.ingest({
+      sourceUrl: args.sourceUrl,
+      dimensions: args.dimensions
+    });
+    const normalized = normalizeBenchmarkResults(rawResults);
+    for (const result of normalized) {
+      await store.upsertBenchmarkResult(result);
+    }
+    return {
+      ingestionId: `ingest-${source}-${Date.now()}`,
+      source,
+      resultsCount: normalized.length,
+      status: "completed",
+      ingestedAt: new Date
+    };
+  });
+  installOp5(registry, BenchmarkRunCustomCommand, async (args) => {
+    return {
+      runId: `custom-${Date.now()}`,
+      evalSuiteKey: args.evalSuiteKey,
+      modelId: args.modelId,
+      status: "started",
+      startedAt: new Date
+    };
+  });
+  installOp5(registry, RankingRefreshCommand, async (args) => {
+    const store = getStore();
+    const allResults = [];
+    let offset = 0;
+    const pageSize = 500;
+    while (true) {
+      const page = await store.listBenchmarkResults({
+        limit: pageSize,
+        offset
+      });
+      allResults.push(...page.results);
+      if (allResults.length >= page.total || page.results.length < pageSize)
+        break;
+      offset += pageSize;
+    }
+    const existingRankings = new Map((await store.listModelRankings({ limit: 1e4 })).rankings.map((r) => [
+      r.modelId,
+      r
+    ]));
+    const weightOverrides = args.weightOverrides ? Array.isArray(args.weightOverrides) ? args.weightOverrides : [args.weightOverrides] : undefined;
+    const newRankings = computeModelRankings(allResults, weightOverrides ? {
+      weightOverrides
+    } : undefined, existingRankings);
+    for (const ranking of newRankings) {
+      await store.upsertModelRanking(ranking);
+    }
+    return {
+      modelsRanked: newRankings.length,
+      updatedAt: new Date,
+      status: "completed"
+    };
+  });
+  return registry;
+}
+function createProviderRankingMcpHandler(path2 = "/api/mcp/ranking") {
   return createMcpElysiaHandler({
     logger: appLogger,
     path: path2,
-    serverName: "contractspec-contracts-mcp",
-    ops: buildContractsOps(services),
-    resources: buildContractsResources(services),
-    prompts: buildContractsPrompts()
+    serverName: "contractspec-ranking-mcp",
+    ops: buildRankingOps(),
+    resources: buildRankingResources(),
+    prompts: buildRankingPrompts()
   });
 }
+function setProviderRankingStore(store) {
+  sharedStore = store;
+}
 export {
   setProviderRankingStore,
   createProviderRankingMcpHandler,