@contractspec/bundle.library 3.8.4 → 3.8.7

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

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'bun:test';
+import { Elysia } from 'elysia';
+import { createDocsMcpHandler } from './docsMcp';
+
+function createTestApp() {
+	return new Elysia().use(createDocsMcpHandler('/mcp/docs'));
+}
+
+async function mcpRequest(
+	method: string,
+	params: Record<string, unknown> = {}
+) {
+	return createTestApp().handle(
+		new Request('http://localhost/mcp/docs', {
+			method: 'POST',
+			headers: {
+				accept: 'application/json',
+				'content-type': 'application/json',
+			},
+			body: JSON.stringify({
+				jsonrpc: '2.0',
+				id: 1,
+				method,
+				params,
+			}),
+		})
+	);
+}
+
+async function initialize() {
+	const response = await mcpRequest('initialize', {
+		protocolVersion: '2024-11-05',
+		capabilities: {},
+		clientInfo: { name: 'docs-mcp-test', version: '1.0.0' },
+	});
+	expect(response.status).toBe(200);
+}
+
+describe('docs MCP handler', () => {
+	it('exposes curated tools, prompts, and resources', async () => {
+		await initialize();
+
+		const toolsResponse = await mcpRequest('tools/list');
+		const toolsBody = await toolsResponse.json();
+		const toolNames = toolsBody.result.tools.map(
+			(tool: { name: string }) => tool.name
+		);
+		expect(toolNames).toContain('docs_search-v1_0_0');
+		expect(toolNames).toContain('docs_get-v1_0_0');
+		expect(toolNames).toContain('docs_resolve_route-v1_0_0');
+		expect(toolNames).toContain('docs_contract_reference-v1_0_0');
+		expect(toolNames).toContain('docs_list_facets-v1_0_0');
+
+		const promptsResponse = await mcpRequest('prompts/list');
+		const promptsBody = await promptsResponse.json();
+		const promptNames = promptsBody.result.prompts.map(
+			(prompt: { name: string }) => prompt.name
+		);
+		expect(promptNames).toContain('docs_navigator');
+		expect(promptNames).toContain('docs_reference_guide');
+
+		const listedResourcesResponse = await mcpRequest('resources/list');
+		const listedResourcesBody = await listedResourcesResponse.json();
+		const listedResources = listedResourcesBody.result.resources ?? [];
+		const listedResourceUris = listedResources.map(
+			(resource: { uri?: string; uriTemplate?: string }) =>
+				resource.uriTemplate ?? resource.uri
+		);
+		expect(listedResourceUris).toContain('docs://index');
+		expect(listedResourceUris).toContain('docs://list');
+		expect(listedResourceUris).toContain('docs://facets');
+
+		const templatesResponse = await mcpRequest('resources/templates/list');
+		const templatesBody = await templatesResponse.json();
+		const templates = templatesBody.result.resourceTemplates ?? [];
+		const templateUris = templates.map(
+			(resource: { uri?: string; uriTemplate?: string }) =>
+				resource.uriTemplate ?? resource.uri
+		);
+		expect(templateUris).toContain(
+			'docs://index{?query,tag,kind,visibility,limit,offset}'
+		);
+		expect(templateUris).toContain(
+			'docs://contract-reference/{key}{?version,type,includeSchema}'
+		);
+		expect(
+			listedResourceUris.some((uri: string) =>
+				uri.startsWith('presentation://')
+			)
+		).toBeFalse();
+	});
+
+	it('supports paginated docs search and contract reference lookup', async () => {
+		await initialize();
+
+		const searchResponse = await mcpRequest('tools/call', {
+			name: 'docs_search-v1_0_0',
+			arguments: {
+				query: 'docs',
+				kind: 'how',
+				limit: 1,
+			},
+		});
+		const searchBody = await searchResponse.json();
+		const searchResult = JSON.parse(searchBody.result.content[0].text);
+		expect(searchResult.docs).toBeArray();
+		expect(searchResult.docs.length).toBe(1);
+		expect(searchResult.total).toBeGreaterThan(1);
+		expect(searchResult.nextOffset).toBe(1);
+
+		const referenceResponse = await mcpRequest('tools/call', {
+			name: 'docs_contract_reference-v1_0_0',
+			arguments: {
+				key: 'docs.generate',
+				type: 'command',
+				includeSchema: true,
+			},
+		});
+		const referenceBody = await referenceResponse.json();
+		const referenceResult = JSON.parse(referenceBody.result.content[0].text);
+		expect(referenceResult.reference.type).toBe('command');
+		expect(referenceResult.reference.route).toBe('/docs/tech/docs/generator');
+		expect(referenceResult.reference.schema.meta.key).toBe('docs.generate');
+	});
+
+	it('keeps markdown doc resources and richer prompts usable', async () => {
+		await initialize();
+
+		const docResponse = await mcpRequest('resources/read', {
+			uri: 'docs://doc/docs.tech.docs-generator',
+		});
+		const docBody = await docResponse.json();
+		expect(docBody.result.contents[0].text).toContain('# Docs generator');
+
+		const promptResponse = await mcpRequest('prompts/get', {
+			name: 'docs_reference_guide',
+			arguments: {
+				key: 'docs.generate',
+				type: 'command',
+			},
+		});
+		const promptBody = await promptResponse.json();
+		const text = promptBody.result.messages[0].content.text;
+		expect(text).toContain('docs_contract_reference-v1_0_0');
+		expect(text).toContain('docs.generate');
+		expect(text).toContain('docs://contract-reference/docs.generate');
+	});
+});

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 });
+}