@contractspec/bundle.library 3.8.2 → 3.8.5

package/src/application/mcp/docsMcp.tools.ts

@@ -0,0 +1,183 @@
+import {
+	defineCommand,
+	defineSchemaModel,
+	installOp,
+	OperationSpecRegistry,
+} from '@contractspec/lib.contracts-spec';
+import type { DocPresentationRoute } from '@contractspec/lib.contracts-spec/docs';
+import {
+	ContractReferenceInput,
+	ContractReferenceOutput,
+	DocsIndexInput,
+	DocsIndexOutput,
+} from '@contractspec/lib.contracts-spec/docs';
+import { ScalarTypeEnum } from '@contractspec/lib.schema';
+import {
+	getDocById,
+	getDocByRoute,
+	listDocFacets,
+	searchDocs,
+} from './docsMcp.data';
+import { resolveContractReference } from './docsMcp.reference';
+
+const DOC_OWNERS = ['@contractspec'];
+const DOC_TAGS = ['docs', 'mcp'];
+
+const DocsGetInput = defineSchemaModel({
+	name: 'DocsGetInput',
+	fields: {
+		id: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+	},
+});
+
+const DocsGetOutput = defineSchemaModel({
+	name: 'DocsGetOutput',
+	fields: {
+		doc: { type: ScalarTypeEnum.JSON(), isOptional: false },
+		content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+	},
+});
+
+const DocsResolveRouteInput = defineSchemaModel({
+	name: 'DocsResolveRouteInput',
+	fields: {
+		route: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+	},
+});
+
+const DocsResolveRouteOutput = defineSchemaModel({
+	name: 'DocsResolveRouteOutput',
+	fields: {
+		doc: { type: ScalarTypeEnum.JSON(), isOptional: false },
+		content: { type: ScalarTypeEnum.String_unsecure(), isOptional: false },
+	},
+});
+
+const DocsFacetsInput = defineSchemaModel({
+	name: 'DocsFacetsInput',
+	fields: {},
+});
+
+const DocsFacetsOutput = defineSchemaModel({
+	name: 'DocsFacetsOutput',
+	fields: {
+		facets: { type: ScalarTypeEnum.JSON(), isOptional: false },
+	},
+});
+
+export function buildDocOps(routes: DocPresentationRoute[]) {
+	const registry = new OperationSpecRegistry();
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'docs.search',
+				version: '1.0.0',
+				stability: 'beta',
+				owners: DOC_OWNERS,
+				tags: DOC_TAGS,
+				description:
+					'Search ContractSpec docs by query, tag, kind, or visibility.',
+				goal: 'Find the most relevant DocBlocks without browsing the full corpus.',
+				context: 'Read-only docs MCP search surface.',
+			},
+			io: { input: DocsIndexInput, output: DocsIndexOutput },
+			policy: { auth: 'anonymous' },
+			transport: { mcp: { toolName: 'docs_search-v1_0_0' } },
+		}),
+		async (args) => searchDocs(routes, args)
+	);
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'docs.get',
+				version: '1.0.0',
+				stability: 'beta',
+				owners: DOC_OWNERS,
+				tags: DOC_TAGS,
+				description: 'Read a single DocBlock by id.',
+				goal: 'Fetch the exact markdown content and metadata for a known doc id.',
+				context: 'Read-only docs MCP surface.',
+			},
+			io: { input: DocsGetInput, output: DocsGetOutput },
+			policy: { auth: 'anonymous' },
+			transport: { mcp: { toolName: 'docs_get-v1_0_0' } },
+		}),
+		async ({ id }) => {
+			const found = getDocById(id);
+			if (!found) throw new Error(`DocBlock not found: ${id}`);
+			return found;
+		}
+	);
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'docs.resolveRoute',
+				version: '1.0.0',
+				stability: 'beta',
+				owners: DOC_OWNERS,
+				tags: DOC_TAGS,
+				description: 'Resolve a docs route to the matching DocBlock.',
+				goal: 'Turn a route or URL path into a canonical doc id and markdown body.',
+				context: 'Read-only docs MCP surface.',
+			},
+			io: { input: DocsResolveRouteInput, output: DocsResolveRouteOutput },
+			policy: { auth: 'anonymous' },
+			transport: { mcp: { toolName: 'docs_resolve_route-v1_0_0' } },
+		}),
+		async ({ route }) => {
+			const found = getDocByRoute(routes, route);
+			if (!found) throw new Error(`Doc route not found: ${route}`);
+			return found;
+		}
+	);
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'docs.contract.lookup',
+				version: '1.0.0',
+				stability: 'beta',
+				owners: DOC_OWNERS,
+				tags: DOC_TAGS,
+				description:
+					'Resolve a ContractSpec surface into a docs-ready reference payload.',
+				goal: 'Get canonical docs metadata, route, and optional schema for a spec key.',
+				context: 'Read-only docs MCP surface.',
+			},
+			io: { input: ContractReferenceInput, output: ContractReferenceOutput },
+			policy: { auth: 'anonymous' },
+			transport: { mcp: { toolName: 'docs_contract_reference-v1_0_0' } },
+		}),
+		async (args) => resolveContractReference(args)
+	);
+
+	installOp(
+		registry,
+		defineCommand({
+			meta: {
+				key: 'docs.list.facets',
+				version: '1.0.0',
+				stability: 'beta',
+				owners: DOC_OWNERS,
+				tags: DOC_TAGS,
+				description:
+					'List docs taxonomy facets such as tags, kinds, and visibilities.',
+				goal: 'Help agents browse the docs corpus before making targeted reads.',
+				context: 'Read-only docs MCP surface.',
+			},
+			io: { input: DocsFacetsInput, output: DocsFacetsOutput },
+			policy: { auth: 'anonymous' },
+			transport: { mcp: { toolName: 'docs_list_facets-v1_0_0' } },
+		}),
+		async () => ({ facets: listDocFacets(routes) })
+	);
+
+	return registry;
+}

package/src/application/mcp/docsMcp.ts

@@ -1,184 +1,18 @@
-import {
-	definePrompt,
-	defineResourceTemplate,
-	installOp,
-	OperationSpecRegistry,
-	PromptRegistry,
-	ResourceRegistry,
-} from '@contractspec/lib.contracts-spec';
-import type { DocPresentationRoute } from '@contractspec/lib.contracts-spec/docs';
 import { defaultDocRegistry } from '@contractspec/lib.contracts-spec/docs';
-import z from 'zod';
-import { docsSearchSpec } from '../../features/docs';
 import { appLogger } from '../../infrastructure/elysia/logger';
 import { createMcpElysiaHandler } from './common';
+import { buildDocPrompts } from './docsMcp.prompts';
+import { buildDocResources } from './docsMcp.resources';
+import { buildDocOps } from './docsMcp.tools';
 
-const DOC_OWNERS = ['@contractspec'];
-const DOC_TAGS = ['docs', 'mcp'];
-
-function buildDocResources(routes: DocPresentationRoute[]) {
-	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' as const,
-						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' as const,
-						uri: 'docs://list',
-						title: 'DocBlocks index',
-					},
-				];
-				return parts;
-			},
-		})
-	);
-
-	return prompts;
-}
-
-function buildDocOps(routes: DocPresentationRoute[]) {
-	const registry = new OperationSpecRegistry();
-
-	// Use the module-level spec from docs.contracts.ts
-	installOp(registry, docsSearchSpec, 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;
+interface DocsMcpHandlerOptions {
+	includePresentations?: boolean;
 }
 
-export function createDocsMcpHandler(path = '/api/mcp/docs') {
+export function createDocsMcpHandler(
+	path = '/api/mcp/docs',
+	options: DocsMcpHandlerOptions = {}
+) {
 	const routes = defaultDocRegistry.list();
 
 	return createMcpElysiaHandler({
@@ -187,7 +21,9 @@ export function createDocsMcpHandler(path = '/api/mcp/docs') {
 		serverName: 'contractspec-docs-mcp',
 		ops: buildDocOps(routes),
 		resources: buildDocResources(routes),
-		prompts: buildDocPrompts(),
-		presentations: routes.map(({ descriptor }) => descriptor),
+		prompts: buildDocPrompts(routes),
+		presentations: options.includePresentations
+			? routes.map(({ descriptor }) => descriptor)
+			: undefined,
 	});
 }

package/src/application/mcp/normalizeMcpRequest.ts

@@ -0,0 +1,30 @@
+const REQUIRED_ACCEPT_TYPES = ['application/json', 'text/event-stream'];
+
+function canNormalizeAcceptHeader(acceptHeader: string | null) {
+	return (
+		!acceptHeader ||
+		acceptHeader.includes('*/*') ||
+		acceptHeader.includes('application/*') ||
+		REQUIRED_ACCEPT_TYPES.some((value) => acceptHeader.includes(value))
+	);
+}
+
+export function normalizeMcpRequest(request: Request) {
+	if (request.method !== 'POST') return request;
+
+	const acceptHeader = request.headers.get('accept');
+	if (!canNormalizeAcceptHeader(acceptHeader)) return request;
+
+	const missingTypes = REQUIRED_ACCEPT_TYPES.filter(
+		(value) => !acceptHeader?.includes(value)
+	);
+	if (missingTypes.length === 0) return request;
+
+	const headers = new Headers(request.headers);
+	headers.set(
+		'accept',
+		[acceptHeader, ...missingTypes].filter(Boolean).join(', ')
+	);
+
+	return new Request(request, { headers });
+}

package/src/components/docs/generated/docs-index._common.json

@@ -1399,7 +1399,7 @@
 	{
 		"id": "docs.tech.presentation-runtime",
 		"title": "Presentation Runtime",
-		"summary": "Cross-platform runtime for list pages and presentation flows.",
+		"summary": "Cross-platform runtime for list pages, presentation flows, and headless ContractSpec tables.",
 		"route": "/docs/tech/presentation-runtime",
 		"source": "docblock",
 		"contentPath": "docblocks/docs/tech/presentation-runtime.md",

package/src/components/docs/generated/docs-index.ai-chat-assistant.json

@@ -1,4 +1,12 @@
 [
+	{
+		"id": "ai-chat-assistant/ai-chat-assistant",
+		"title": "ai-chat-assistant",
+		"summary": "Focused assistant example with chat UX and search-backed retrieval.\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: beta\n- **Owners**: @platform.core\n- **Tags**: ai, chat, assistant, example\n- **File**: `packages/examples/ai-chat-assistant/src/ai-chat-assistant.feature.ts`",
+		"route": "/docs/reference/ai-chat-assistant/ai-chat-assistant",
+		"source": "generated",
+		"contentPath": "ai-chat-assistant/ai-chat-assistant.md"
+	},
 	{
 		"id": "ai-chat-assistant/assistant.search",
 		"title": "assistant.search",

package/src/components/docs/generated/docs-index.artisan-knowledge-product.json

@@ -0,0 +1,18 @@
+[
+	{
+		"id": "artisan.knowledge.product/artisan.knowledge.product",
+		"title": "artisan.knowledge.product",
+		"summary": "Blueprint that surfaces canonical product knowledge to agents and workflows.\n- **Type**: app-config (app-config)\n- **Version**: 1.0.0\n- **Tags**: knowledge, product-canon\n- **File**: `packages/examples/knowledge-canon/src/blueprint.ts`",
+		"route": "/docs/reference/artisan.knowledge.product/artisan.knowledge.product",
+		"source": "generated",
+		"contentPath": "artisan.knowledge.product/artisan.knowledge.product.md"
+	},
+	{
+		"id": "artisan.knowledge.product/knowledge-canon",
+		"title": "knowledge-canon",
+		"summary": "Curated product knowledge space with blueprint, tenant config, and FAQ workflow\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: experimental\n- **Owners**: @examples\n- **Tags**: knowledge, canon, faq",
+		"route": "/docs/reference/artisan.knowledge.product/knowledge-canon",
+		"source": "generated",
+		"contentPath": "artisan.knowledge.product/knowledge-canon.md"
+	}
+]

package/src/components/docs/generated/docs-index.artisan-payments-stripe.json

@@ -0,0 +1,34 @@
+[
+	{
+		"id": "artisan.payments.stripe/artisan.payments.stripe",
+		"title": "artisan.payments.stripe",
+		"summary": "Blueprint enabling card payments for ArtisanOS merchants via the Stripe integration.\n- **Type**: app-config (app-config)\n- **Version**: 1.0.0\n- **Tags**: stripe, payments\n- **File**: `packages/examples/integration-stripe/src/blueprint.ts`",
+		"route": "/docs/reference/artisan.payments.stripe/artisan.payments.stripe",
+		"source": "generated",
+		"contentPath": "artisan.payments.stripe/artisan.payments.stripe.md"
+	},
+	{
+		"id": "artisan.payments.stripe/integration-stripe",
+		"title": "integration-stripe",
+		"summary": "Stripe payments integration with blueprint, workflow, and tenant configuration\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: experimental\n- **Owners**: @integration-team\n- **Tags**: integration, stripe, payments",
+		"route": "/docs/reference/artisan.payments.stripe/integration-stripe",
+		"source": "generated",
+		"contentPath": "artisan.payments.stripe/integration-stripe.md"
+	},
+	{
+		"id": "artisan.payments.stripe/integration-stripe.integration.psp",
+		"title": "integration-stripe.integration.psp",
+		"summary": "Integration contract for managed or BYOK Stripe card processing.\n- **Type**: integration (integration)\n- **Version**: 1.0.0\n- **Tags**: stripe, payments\n- **File**: `packages/examples/integration-stripe/src/integration.ts`",
+		"route": "/docs/reference/artisan.payments.stripe/integration-stripe.integration.psp",
+		"source": "generated",
+		"contentPath": "artisan.payments.stripe/integration-stripe.integration.psp.md"
+	},
+	{
+		"id": "artisan.payments.stripe/integration-stripe.workflow.payment",
+		"title": "integration-stripe.workflow.payment",
+		"summary": "Charge a customer using the tenant Stripe connection and record settlement details.\n- **Type**: workflow (workflow)\n- **Version**: 1.0.0\n- **Tags**: stripe\n- **File**: `packages/examples/integration-stripe/src/workflow.ts`",
+		"route": "/docs/reference/artisan.payments.stripe/integration-stripe.workflow.payment",
+		"source": "generated",
+		"contentPath": "artisan.payments.stripe/integration-stripe.workflow.payment.md"
+	}
+]

package/src/components/docs/generated/docs-index.data-grid-showcase.json

@@ -0,0 +1,18 @@
+[
+	{
+		"id": "data-grid-showcase/data-grid-showcase",
+		"title": "data-grid-showcase",
+		"summary": "Focused ContractSpec table example covering client mode, server mode, and DataView adapter paths.\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: experimental\n- **Owners**: @platform.core\n- **Tags**: table, data-grid, ui, tanstack",
+		"route": "/docs/reference/data-grid-showcase/data-grid-showcase",
+		"source": "generated",
+		"contentPath": "data-grid-showcase/data-grid-showcase.md"
+	},
+	{
+		"id": "data-grid-showcase/examples.data-grid-showcase.rows.list",
+		"title": "examples.data-grid-showcase.rows.list",
+		"summary": "Lists the demo rows used by the data-grid showcase.\n- **Type**: operation (query)\n- **Version**: 1.0.0\n- **Stability**: experimental\n- **Owners**: @platform.core\n- **Tags**: examples, table, data-grid\n- **File**: `packages/examples/data-grid-showcase/src/contracts/data-grid-showcase.operation.ts`",
+		"route": "/docs/reference/data-grid-showcase/examples.data-grid-showcase.rows.list",
+		"source": "generated",
+		"contentPath": "data-grid-showcase/examples.data-grid-showcase.rows.list.md"
+	}
+]

package/src/components/docs/generated/docs-index.generated.ts

@@ -1,6 +1,6 @@
 export type DocsIndexSource = 'generated' | 'docblock';
 
-export interface DocsIndexEntry {
+export type DocsIndexEntry = {
 	id: string;
 	title: string;
 	summary?: string;
@@ -12,20 +12,20 @@ export interface DocsIndexEntry {
 	visibility?: string;
 	version?: string;
 	owners?: string[];
-}
+};
 
-export interface DocsIndexChunk {
+export type DocsIndexChunk = {
 	key: string;
 	file: string;
 	total: number;
-}
+};
 
-export interface DocsIndexManifest {
+export type DocsIndexManifest = {
 	generatedAt: string;
 	total: number;
 	version: string | null;
 	contentRoot: string | null;
 	chunks: DocsIndexChunk[];
-}
+};
 
 export const DOCS_INDEX_MANIFEST = 'docs-index.manifest.json';

package/src/components/docs/generated/docs-index.harness-lab.json

@@ -0,0 +1,10 @@
+[
+	{
+		"id": "harness-lab/harness-lab",
+		"title": "harness-lab",
+		"summary": "Focused harness example for deterministic sandbox and browser evaluation flows.\n- **Type**: feature\n- **Version**: 1.0.0\n- **Stability**: experimental\n- **Owners**: @examples\n- **Tags**: harness, runtime, evaluation",
+		"route": "/docs/reference/harness-lab/harness-lab",
+		"source": "generated",
+		"contentPath": "harness-lab/harness-lab.md"
+	}
+]

package/src/components/docs/generated/docs-index.locale-jurisdiction-gate.json

@@ -46,5 +46,13 @@
 		"route": "/docs/reference/locale-jurisdiction-gate/locale-jurisdiction-gate",
 		"source": "generated",
 		"contentPath": "locale-jurisdiction-gate/locale-jurisdiction-gate.md"
+	},
+	{
+		"id": "locale-jurisdiction-gate/locale-jurisdiction-gate.policy.gate",
+		"title": "locale-jurisdiction-gate.policy.gate",
+		"summary": "Requires explicit locale, jurisdiction, knowledge snapshot, and allowed scope before assistant requests may proceed.\n- **Type**: policy (policy)\n- **Version**: 1.0.0\n- **Tags**: assistant, policy, jurisdiction",
+		"route": "/docs/reference/locale-jurisdiction-gate/locale-jurisdiction-gate.policy.gate",
+		"source": "generated",
+		"contentPath": "locale-jurisdiction-gate/locale-jurisdiction-gate.policy.gate.md"
 	}
 ]