@contractspec/bundle.library 3.0.0 → 3.2.0

package/src/application/context-storage/index.ts

@@ -0,0 +1,58 @@
+import type {
+  DatabaseProvider,
+  EmbeddingProvider,
+  VectorStoreProvider,
+} from '@contractspec/lib.contracts-integrations';
+import {
+  DocumentProcessor,
+  EmbeddingService,
+  VectorIndexer,
+  type VectorIndexConfig,
+} from '@contractspec/lib.knowledge/ingestion';
+import {
+  ContextSnapshotPipeline,
+  PostgresContextStorage,
+} from '@contractspec/module.context-storage';
+
+export interface ContextStorageServiceOptions {
+  database: DatabaseProvider;
+  schema?: string;
+  createTablesIfMissing?: boolean;
+  documentProcessor?: DocumentProcessor;
+  embeddingProvider?: EmbeddingProvider;
+  embeddingBatchSize?: number;
+  vectorStoreProvider?: VectorStoreProvider;
+  vectorIndex?: VectorIndexConfig;
+}
+
+export interface ContextStorageService {
+  store: PostgresContextStorage;
+  pipeline: ContextSnapshotPipeline;
+}
+
+export function createContextStorageService(
+  options: ContextStorageServiceOptions
+): ContextStorageService {
+  const store = new PostgresContextStorage({
+    database: options.database,
+    schema: options.schema,
+    createTablesIfMissing: options.createTablesIfMissing,
+  });
+  const embeddingService = options.embeddingProvider
+    ? new EmbeddingService(
+        options.embeddingProvider,
+        options.embeddingBatchSize
+      )
+    : undefined;
+  const vectorIndexer =
+    options.vectorStoreProvider && options.vectorIndex
+      ? new VectorIndexer(options.vectorStoreProvider, options.vectorIndex)
+      : undefined;
+  const pipeline = new ContextSnapshotPipeline({
+    store,
+    documentProcessor: options.documentProcessor,
+    embeddingService,
+    vectorIndexer,
+  });
+  return { store, pipeline };
+}

package/src/application/index.ts

@@ -1 +1,2 @@
 export * from './mcp';
+export * from './context-storage';

package/src/application/mcp/common.ts

@@ -11,6 +11,13 @@ import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/
 import { Elysia } from 'elysia';
 import { Logger } from '@contractspec/lib.logger';
 import { randomUUID } from 'node:crypto';
+import type { IntegrationAuthType } from '@contractspec/lib.contracts-integrations/integrations';
+
+export interface McpAuthValidationResult {
+  valid: boolean;
+  actor?: string;
+  reason?: string;
+}
 
 interface McpHttpHandlerConfig {
   path: string;
@@ -20,6 +27,10 @@ interface McpHttpHandlerConfig {
   prompts: PromptRegistry;
   presentations?: PresentationSpec[];
   logger: Logger;
+  /** Callback to validate auth credentials from the incoming request. */
+  validateAuth?: (request: Request) => Promise<McpAuthValidationResult>;
+  /** Auth methods this MCP handler requires callers to present. */
+  requiredAuthMethods?: IntegrationAuthType[];
 }
 
 const baseCtx = {
@@ -116,8 +127,12 @@ export function createMcpElysiaHandler({
   resources,
   prompts,
   presentations,
+  validateAuth,
+  requiredAuthMethods,
 }: McpHttpHandlerConfig) {
-  logger.info('Setting up MCP handler...');
+  logger.info('Setting up MCP handler...', {
+    requiredAuthMethods: requiredAuthMethods ?? [],
+  });
 
   const isStateful = process.env.CONTRACTSPEC_MCP_STATEFUL === '1';
   const sessions = new Map<string, McpSessionState>();
@@ -200,6 +215,18 @@ export function createMcpElysiaHandler({
     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);
         }

package/src/application/mcp/contractsMcp.ts

@@ -0,0 +1,34 @@
+/**
+ * Contracts MCP server.
+ *
+ * Exposes contract management operations (list, get, create, update,
+ * delete, validate, build) as MCP tools, resources, and prompts.
+ *
+ * Services are injected at creation time so this bundle stays
+ * decoupled from bundle.workspace — the app layer provides real impls.
+ */
+
+import { createMcpElysiaHandler } from './common';
+import { appLogger } from '../../infrastructure/elysia/logger';
+import { buildContractsOps } from './contractsMcpTools';
+import {
+  buildContractsResources,
+  buildContractsPrompts,
+} from './contractsMcpResources';
+import type { ContractsMcpServices } from './contractsMcpTypes';
+
+export type { ContractsMcpServices, ContractInfo } from './contractsMcpTypes';
+
+export function createContractsMcpHandler(
+  path = '/api/mcp/contracts',
+  services: ContractsMcpServices
+) {
+  return createMcpElysiaHandler({
+    logger: appLogger,
+    path,
+    serverName: 'contractspec-contracts-mcp',
+    ops: buildContractsOps(services),
+    resources: buildContractsResources(services),
+    prompts: buildContractsPrompts(),
+  });
+}

package/src/application/mcp/contractsMcpResources.ts

@@ -0,0 +1,142 @@
+/**
+ * Contract management MCP resource and prompt definitions.
+ */
+
+import {
+  definePrompt,
+  defineResourceTemplate,
+  PromptRegistry,
+  ResourceRegistry,
+} from '@contractspec/lib.contracts-spec';
+import z from 'zod';
+import type { ContractsMcpServices } from './contractsMcpTypes';
+
+const OWNERS = ['@contractspec'];
+const TAGS = ['contracts', 'mcp'];
+
+export function buildContractsResources(services: ContractsMcpServices) {
+  const resources = new ResourceRegistry();
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'contracts://list',
+        title: 'Contract specs list',
+        description: 'JSON list of all contract specs in the workspace.',
+        mimeType: 'application/json',
+        tags: TAGS,
+      },
+      input: z.object({}),
+      resolve: async () => {
+        const specs = await services.listSpecs();
+        return {
+          uri: 'contracts://list',
+          mimeType: 'application/json',
+          data: JSON.stringify(specs, null, 2),
+        };
+      },
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'contracts://spec/{path}',
+        title: 'Contract spec content',
+        description: 'Read a single contract spec file by path.',
+        mimeType: 'text/plain',
+        tags: TAGS,
+      },
+      input: z.object({ path: z.string() }),
+      resolve: async ({ path }) => {
+        const result = await services.getSpec(path);
+        if (!result) {
+          return {
+            uri: `contracts://spec/${encodeURIComponent(path)}`,
+            mimeType: 'text/plain',
+            data: `Spec not found: ${path}`,
+          };
+        }
+        return {
+          uri: `contracts://spec/${encodeURIComponent(path)}`,
+          mimeType: 'text/plain',
+          data: result.content,
+        };
+      },
+    })
+  );
+
+  resources.register(
+    defineResourceTemplate({
+      meta: {
+        uriTemplate: 'contracts://registry/manifest',
+        title: 'Remote registry manifest',
+        description: 'Contract registry manifest from the remote server.',
+        mimeType: 'application/json',
+        tags: TAGS,
+      },
+      input: z.object({}),
+      resolve: async () => {
+        const manifest = await services.fetchRegistryManifest();
+        return {
+          uri: 'contracts://registry/manifest',
+          mimeType: 'application/json',
+          data: JSON.stringify(manifest, null, 2),
+        };
+      },
+    })
+  );
+
+  return resources;
+}
+
+export function buildContractsPrompts() {
+  const prompts = new PromptRegistry();
+
+  prompts.register(
+    definePrompt({
+      meta: {
+        key: 'contracts.editor',
+        version: '1.0.0',
+        title: 'Contract editing guide',
+        description:
+          'Guide AI agents through reading, editing, and validating contracts.',
+        tags: TAGS,
+        stability: 'beta',
+        owners: OWNERS,
+      },
+      args: [
+        {
+          name: 'goal',
+          description: 'What the agent wants to achieve with the contract.',
+          required: false,
+          schema: z.string().optional(),
+        },
+      ],
+      input: z.object({ goal: z.string().optional() }),
+      render: async ({ goal }) => [
+        {
+          type: 'text' as const,
+          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('\n'),
+        },
+        {
+          type: 'resource' as const,
+          uri: 'contracts://list',
+          title: 'Available contracts',
+        },
+      ],
+    })
+  );
+
+  return prompts;
+}

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';