@contractspec/bundle.library 2.9.1 → 3.1.1

package/src/application/mcp/contractsMcpTools.ts

@@ -0,0 +1,246 @@
+/**
+ * Contract management MCP tool definitions.
+ *
+ * Each tool delegates to an injected service so the bundle stays
+ * decoupled from bundle.workspace (apps layer does the wiring).
+ */
+
+import {
+  defineCommand,
+  installOp,
+  OperationSpecRegistry,
+} from '@contractspec/lib.contracts-spec';
+import { defineSchemaModel, ScalarTypeEnum } from '@contractspec/lib.schema';
+import type { ContractsMcpServices } from './contractsMcpTypes';
+
+const OWNERS = ['@contractspec'];
+const TAGS = ['contracts', 'mcp'];
+
+export function buildContractsOps(services: ContractsMcpServices) {
+  const registry = new OperationSpecRegistry();
+
+  // -- contracts.list --
+  const ListInput = defineSchemaModel({
+    name: 'ContractsListInput',
+    fields: {
+      pattern: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+      type: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+    },
+  });
+  const ListOutput = defineSchemaModel({
+    name: 'ContractsListOutput',
+    fields: {
+      specs: { type: ScalarTypeEnum.JSON(), isOptional: false },
+      total: { type: ScalarTypeEnum.Int_unsecure(), isOptional: false },
+    },
+  });
+  installOp(
+    registry,
+    defineCommand({
+      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 };
+    }
+  );
+
+  // -- contracts.get --
+  const GetInput = defineSchemaModel({
+    name: 'ContractsGetInput',
+    fields: {
+      path: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    },
+  });
+  const GetOutput = defineSchemaModel({
+    name: 'ContractsGetOutput',
+    fields: {
+      content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      info: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    },
+  });
+  installOp(
+    registry,
+    defineCommand({
+      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.',
+      },
+      io: { input: GetInput, output: GetOutput },
+      policy: { auth: 'anonymous' },
+    }),
+    async ({ path }) => {
+      const result = await services.getSpec(path);
+      if (!result) throw new Error(`Spec not found: ${path}`);
+      return result;
+    }
+  );
+
+  // -- contracts.validate --
+  const ValidateInput = defineSchemaModel({
+    name: 'ContractsValidateInput',
+    fields: {
+      path: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+    },
+  });
+  const ValidateOutput = defineSchemaModel({
+    name: 'ContractsValidateOutput',
+    fields: {
+      valid: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+      errors: { type: ScalarTypeEnum.JSON(), isOptional: false },
+      warnings: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    },
+  });
+  installOp(
+    registry,
+    defineCommand({
+      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.',
+      },
+      io: { input: ValidateInput, output: ValidateOutput },
+      policy: { auth: 'anonymous' },
+    }),
+    async ({ path }) => services.validateSpec(path)
+  );
+
+  // -- contracts.build --
+  const BuildInput = defineSchemaModel({
+    name: 'ContractsBuildInput',
+    fields: {
+      path: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      dryRun: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    },
+  });
+  const BuildOutput = defineSchemaModel({
+    name: 'ContractsBuildOutput',
+    fields: {
+      results: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    },
+  });
+  installOp(
+    registry,
+    defineCommand({
+      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.',
+      },
+      io: { input: BuildInput, output: BuildOutput },
+      policy: { auth: 'user' },
+    }),
+    async ({ path, dryRun }) => services.buildSpec(path, { dryRun })
+  );
+
+  registerMutationTools(registry, services);
+
+  return registry;
+}
+
+function registerMutationTools(
+  registry: OperationSpecRegistry,
+  services: ContractsMcpServices
+) {
+  // -- contracts.update --
+  const UpdateInput = defineSchemaModel({
+    name: 'ContractsUpdateInput',
+    fields: {
+      path: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      content: { type: ScalarTypeEnum.String_unsecure(), isOptional: true },
+      fields: { type: ScalarTypeEnum.JSON(), isOptional: true },
+    },
+  });
+  const UpdateOutput = defineSchemaModel({
+    name: 'ContractsUpdateOutput',
+    fields: {
+      updated: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+      errors: { type: ScalarTypeEnum.JSON(), isOptional: false },
+      warnings: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    },
+  });
+  installOp(
+    registry,
+    defineCommand({
+      meta: {
+        key: 'contracts.update',
+        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.',
+      },
+      io: { input: UpdateInput, output: UpdateOutput },
+      policy: { auth: 'user' },
+    }),
+    async ({ path, content, fields }) =>
+      services.updateSpec(path, {
+        content,
+        fields: Array.isArray(fields) ? (fields as unknown[]) : undefined,
+      })
+  );
+
+  // -- contracts.delete --
+  const DeleteInput = defineSchemaModel({
+    name: 'ContractsDeleteInput',
+    fields: {
+      path: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+      clean: { type: ScalarTypeEnum.Boolean(), isOptional: true },
+    },
+  });
+  const DeleteOutput = defineSchemaModel({
+    name: 'ContractsDeleteOutput',
+    fields: {
+      deleted: { type: ScalarTypeEnum.Boolean(), isOptional: false },
+      cleanedFiles: { type: ScalarTypeEnum.JSON(), isOptional: false },
+      errors: { type: ScalarTypeEnum.JSON(), isOptional: false },
+    },
+  });
+  installOp(
+    registry,
+    defineCommand({
+      meta: {
+        key: 'contracts.delete',
+        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.',
+      },
+      io: { input: DeleteInput, output: DeleteOutput },
+      policy: { auth: 'user' },
+    }),
+    async ({ path, clean }) => services.deleteSpec(path, { clean })
+  );
+}

package/src/application/mcp/contractsMcpTypes.ts

@@ -0,0 +1,47 @@
+/**
+ * Contracts MCP service interface.
+ *
+ * Defines the dependency-injection boundary so `bundle.library` stays
+ * decoupled from `bundle.workspace`. The app layer wires real impls.
+ */
+
+export interface ContractInfo {
+  specType: string;
+  filePath: string;
+  key?: string;
+  version?: string;
+  kind?: string;
+  description?: string;
+}
+
+export interface ContractsMcpServices {
+  listSpecs(options?: {
+    pattern?: string;
+    type?: string;
+  }): Promise<ContractInfo[]>;
+
+  getSpec(
+    path: string
+  ): Promise<{ content: string; info: ContractInfo } | null>;
+
+  validateSpec(
+    path: string
+  ): Promise<{ valid: boolean; errors: string[]; warnings: string[] }>;
+
+  buildSpec(
+    path: string,
+    options?: { dryRun?: boolean }
+  ): Promise<{ results: unknown[] }>;
+
+  updateSpec(
+    path: string,
+    options: { content?: string; fields?: unknown[] }
+  ): Promise<{ updated: boolean; errors: string[]; warnings: string[] }>;
+
+  deleteSpec(
+    path: string,
+    options?: { clean?: boolean }
+  ): Promise<{ deleted: boolean; cleanedFiles: string[]; errors: string[] }>;
+
+  fetchRegistryManifest(): Promise<unknown>;
+}

package/src/application/mcp/index.ts

@@ -1,3 +1,5 @@
 export * from './docsMcp';
 export * from './cliMcp';
 export * from './internalMcp';
+export * from './providerRankingMcp';
+export * from './contractsMcp';

package/src/application/mcp/providerRankingMcp.ts

@@ -0,0 +1,380 @@
+import {
+  definePrompt,
+  defineResourceTemplate,
+  installOp,
+  OperationSpecRegistry,
+  PromptRegistry,
+  ResourceRegistry,
+} from '@contractspec/lib.contracts-spec';
+import {
+  BenchmarkIngestCommand,
+  BenchmarkRunCustomCommand,
+  RankingRefreshCommand,
+} from '@contractspec/lib.contracts-spec/provider-ranking';
+import z from 'zod';
+import { createMcpElysiaHandler } from './common';
+import { appLogger } from '../../infrastructure/elysia/logger';
+import type { ProviderRankingStore } from '@contractspec/lib.provider-ranking/store';
+import type {
+  ProviderTransportSupport,
+  ProviderAuthSupport,
+} from '@contractspec/lib.provider-ranking/types';
+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';
+
+const TransportFilterSchema = z
+  .enum(['rest', 'mcp', 'webhook', 'sdk'])
+  .optional();
+const AuthFilterSchema = z
+  .enum([
+    'api-key',
+    'oauth2',
+    'bearer',
+    'header',
+    'basic',
+    'webhook-signing',
+    'service-account',
+  ])
+  .optional();
+
+const RANKING_TAGS = ['ranking', 'mcp', 'ai'];
+const RANKING_OWNERS = ['platform.ai'];
+
+let sharedStore: ProviderRankingStore | null = null;
+
+function getStore(): ProviderRankingStore {
+  if (!sharedStore) {
+    sharedStore = new InMemoryProviderRankingStore();
+  }
+  return sharedStore;
+}
+
+function buildRankingResources() {
+  const resources = new ResourceRegistry();
+
+  resources.register(
+    defineResourceTemplate({
+      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,
+      },
+      input: z.object({
+        transport: TransportFilterSchema,
+        authMethod: AuthFilterSchema,
+      }),
+      resolve: async ({ transport, authMethod }) => {
+        const store = getStore();
+        const result = await store.listModelRankings({
+          limit: 100,
+          requiredTransport: transport as ProviderTransportSupport | undefined,
+          requiredAuthMethod: authMethod as ProviderAuthSupport | undefined,
+        });
+        return {
+          uri: 'ranking://leaderboard',
+          mimeType: 'application/json',
+          data: JSON.stringify(result, null, 2),
+        };
+      },
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      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,
+      },
+      input: z.object({
+        dimension: z.string(),
+        transport: TransportFilterSchema,
+        authMethod: AuthFilterSchema,
+      }),
+      resolve: async ({ dimension, transport, authMethod }) => {
+        const store = getStore();
+        const result = await store.listModelRankings({
+          dimension: dimension as
+            | 'coding'
+            | 'reasoning'
+            | 'agentic'
+            | 'cost'
+            | 'latency'
+            | 'context'
+            | 'safety'
+            | 'custom',
+          limit: 100,
+          requiredTransport: transport as ProviderTransportSupport | undefined,
+          requiredAuthMethod: authMethod as ProviderAuthSupport | undefined,
+        });
+        return {
+          uri: `ranking://leaderboard/${encodeURIComponent(dimension)}`,
+          mimeType: 'application/json',
+          data: JSON.stringify(result, null, 2),
+        };
+      },
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        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: z.object({ modelId: z.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 }),
+          };
+        }
+        return {
+          uri: `ranking://model/${encodeURIComponent(modelId)}`,
+          mimeType: 'application/json',
+          data: JSON.stringify(profile, null, 2),
+        };
+      },
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'ranking://results',
+        title: 'Benchmark Results',
+        description: 'List of raw benchmark results from all ingested sources.',
+        mimeType: 'application/json',
+        tags: RANKING_TAGS,
+      },
+      input: z.object({}),
+      resolve: async () => {
+        const store = getStore();
+        const result = await store.listBenchmarkResults({ limit: 200 });
+        return {
+          uri: 'ranking://results',
+          mimeType: 'application/json',
+          data: JSON.stringify(result, null, 2),
+        };
+      },
+    })
+  );
+
+  return resources;
+}
+
+function buildRankingPrompts() {
+  const prompts = new PromptRegistry();
+
+  prompts.register(
+    definePrompt({
+      meta: {
+        key: 'ranking.advisor',
+        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,
+        stability: 'beta',
+        owners: RANKING_OWNERS,
+      },
+      args: [
+        {
+          name: 'task',
+          description: 'The task or use case to recommend a model for.',
+          required: true,
+          schema: z.string(),
+        },
+        {
+          name: 'priority',
+          description:
+            'Priority dimension (coding, reasoning, cost, latency, etc.).',
+          required: false,
+          schema: z.string().optional(),
+        },
+        {
+          name: 'transport',
+          description: 'Required transport type (rest, mcp, webhook, sdk).',
+          required: false,
+          schema: TransportFilterSchema,
+        },
+        {
+          name: 'authMethod',
+          description: 'Required auth method (api-key, oauth2, bearer, etc.).',
+          required: false,
+          schema: AuthFilterSchema,
+        },
+      ],
+      input: z.object({
+        task: z.string(),
+        priority: z.string().optional(),
+        transport: TransportFilterSchema,
+        authMethod: AuthFilterSchema,
+      }),
+      render: async ({ task, priority, transport, authMethod }) => {
+        const constraints: string[] = [];
+        if (priority) constraints.push(`Prioritize: ${priority}.`);
+        if (transport) constraints.push(`Required transport: ${transport}.`);
+        if (authMethod) constraints.push(`Required auth: ${authMethod}.`);
+
+        return [
+          {
+            type: 'text' as const,
+            text: `Recommend the best AI model for: "${task}".${constraints.length ? ` ${constraints.join(' ')}` : ''} Use the leaderboard data to justify your recommendation.`,
+          },
+          {
+            type: 'resource' as const,
+            uri: priority
+              ? `ranking://leaderboard/${priority}`
+              : 'ranking://leaderboard',
+            title: 'Leaderboard',
+          },
+        ];
+      },
+    })
+  );
+
+  return prompts;
+}
+
+function buildRankingOps() {
+  const registry = new OperationSpecRegistry();
+  const ingesterRegistry = createDefaultIngesterRegistry();
+
+  installOp(registry, BenchmarkIngestCommand, async (args) => {
+    const store = getStore();
+    const source = args.source as string;
+    const ingester = ingesterRegistry.get(
+      source as Parameters<typeof ingesterRegistry.get>[0]
+    );
+    if (!ingester) {
+      throw new Error(`No ingester registered for source: ${source}`);
+    }
+
+    const rawResults = await ingester.ingest({
+      sourceUrl: args.sourceUrl as string | undefined,
+      dimensions: args.dimensions as string[] | undefined as Parameters<
+        typeof ingester.ingest
+      >[0] extends undefined
+        ? never
+        : NonNullable<Parameters<typeof ingester.ingest>[0]>['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(),
+    };
+  });
+
+  installOp(registry, BenchmarkRunCustomCommand, async (args) => {
+    return {
+      runId: `custom-${Date.now()}`,
+      evalSuiteKey: args.evalSuiteKey,
+      modelId: args.modelId,
+      status: 'started',
+      startedAt: new Date(),
+    };
+  });
+
+  installOp(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: 10000 })).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: weightOverrides as Parameters<
+              typeof computeModelRankings
+            >[1] extends undefined
+              ? never
+              : NonNullable<
+                  Parameters<typeof computeModelRankings>[1]
+                >['weightOverrides'],
+          }
+        : undefined,
+      existingRankings
+    );
+
+    for (const ranking of newRankings) {
+      await store.upsertModelRanking(ranking);
+    }
+
+    return {
+      modelsRanked: newRankings.length,
+      updatedAt: new Date(),
+      status: 'completed',
+    };
+  });
+
+  return registry;
+}
+
+export function createProviderRankingMcpHandler(path = '/api/mcp/ranking') {
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path,
+    serverName: 'contractspec-ranking-mcp',
+    ops: buildRankingOps(),
+    resources: buildRankingResources(),
+    prompts: buildRankingPrompts(),
+  });
+}
+
+/**
+ * Allows external callers to inject a custom store
+ * (e.g. PostgresProviderRankingStore from the module layer).
+ */
+export function setProviderRankingStore(store: ProviderRankingStore): void {
+  sharedStore = store;
+}

package/src/components/docs/DocsIndexPage.tsx

@@ -195,7 +195,8 @@ bun contractspec build src/contracts/mySpec.ts`}
             },
             {
               title: 'Ecosystem',
-              description: 'Plugin API, templates, and integrations',
+              description:
+                'Cursor marketplace plugins, templates, manifest, and integrations',
               href: '/docs/ecosystem/plugins',
             },
             {