@contractspec/bundle.library 3.8.2 → 3.8.5

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

@@ -0,0 +1,165 @@
+import { definePrompt, PromptRegistry } from '@contractspec/lib.contracts-spec';
+import type { DocPresentationRoute } from '@contractspec/lib.contracts-spec/docs';
+import z from 'zod';
+import { searchDocs } from './docsMcp.data';
+import { resolveContractReference } from './docsMcp.reference';
+
+const DOC_OWNERS = ['@contractspec'];
+const DOC_TAGS = ['docs', 'mcp'];
+
+export function buildDocPrompts(routes: DocPresentationRoute[]) {
+	const prompts = new PromptRegistry();
+
+	prompts.register(
+		definePrompt({
+			meta: {
+				key: 'docs.navigator',
+				version: '1.0.0',
+				title: 'Find relevant ContractSpec docs',
+				description:
+					'Guide agents to search, filter, and open the right ContractSpec docs.',
+				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: 'kind',
+					description: 'Optional doc kind filter.',
+					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(),
+				kind: z.string().optional(),
+				tag: z.string().optional(),
+			}),
+			render: async ({ topic, kind, tag }) => {
+				const matches = searchDocs(routes, {
+					query: topic,
+					kind,
+					tag,
+					limit: 3,
+				});
+				const suggestedDocs = matches.docs.length
+					? matches.docs
+							.map((doc) => `- ${doc.title} (${doc.id}) -> ${doc.route}`)
+							.join('\n')
+					: '- No direct pre-match. Use docs_list_facets-v1_0_0 to browse tags and kinds.';
+
+				return [
+					{
+						type: 'text' as const,
+						text: [
+							'Use docs_search-v1_0_0 first, then read docs://doc/{id} for the strongest matches.',
+							'Use docs_resolve_route-v1_0_0 when the user already gives you a docs URL or route.',
+							'Use docs_list_facets-v1_0_0 or docs://facets to browse the docs taxonomy before guessing.',
+							topic ? `Topic: ${topic}` : '',
+							kind ? `Kind: ${kind}` : '',
+							tag ? `Tag: ${tag}` : '',
+							'Suggested starting docs:',
+							suggestedDocs,
+						]
+							.filter(Boolean)
+							.join('\n'),
+					},
+					{
+						type: 'resource' as const,
+						uri: 'docs://index',
+						title: 'DocBlocks index',
+					},
+					{
+						type: 'resource' as const,
+						uri: 'docs://facets',
+						title: 'Docs facets',
+					},
+				];
+			},
+		})
+	);
+
+	prompts.register(
+		definePrompt({
+			meta: {
+				key: 'docs.reference.guide',
+				version: '1.0.0',
+				title: 'Resolve a ContractSpec reference',
+				description:
+					'Guide agents to fetch the canonical reference payload for a ContractSpec surface.',
+				tags: DOC_TAGS,
+				stability: 'beta',
+				owners: DOC_OWNERS,
+			},
+			args: [
+				{
+					name: 'key',
+					description: 'ContractSpec key to resolve.',
+					required: true,
+					schema: z.string(),
+				},
+				{
+					name: 'version',
+					description: 'Optional version override.',
+					required: false,
+					schema: z.string().optional(),
+				},
+				{
+					name: 'type',
+					description:
+						'Optional surface type: command, query, form, data-view, presentation, event.',
+					required: false,
+					schema: z.string().optional(),
+				},
+			],
+			input: z.object({
+				key: z.string(),
+				version: z.string().optional(),
+				type: z.string().optional(),
+			}),
+			render: async ({ key, version, type }) => {
+				const reference = resolveContractReference({
+					key,
+					version,
+					type,
+					includeSchema: true,
+				}).reference;
+
+				return [
+					{
+						type: 'text' as const,
+						text: [
+							'Use docs_contract_reference-v1_0_0 when you need the canonical docs payload for a ContractSpec surface.',
+							'Use docs_get-v1_0_0 only when you already know the exact DocBlock id and need raw markdown.',
+							`Resolved key: ${reference.key}`,
+							`Resolved type: ${reference.type}`,
+							reference.route ? `Docs route: ${reference.route}` : '',
+							`Resource URI: docs://contract-reference/${encodeURIComponent(key)}`,
+						]
+							.filter(Boolean)
+							.join('\n'),
+					},
+					{
+						type: 'resource' as const,
+						uri: `docs://contract-reference/${encodeURIComponent(key)}`,
+						title: 'Contract reference',
+					},
+				];
+			},
+		})
+	);
+
+	return prompts;
+}

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

@@ -0,0 +1,152 @@
+import type {
+	AnyEventSpec,
+	AnyOperationSpec,
+	FormSpec,
+} from '@contractspec/lib.contracts-spec';
+import type { DataViewSpec } from '@contractspec/lib.contracts-spec/data-views';
+import { defaultDocRegistry } from '@contractspec/lib.contracts-spec/docs';
+import type { PresentationSpec } from '@contractspec/lib.contracts-spec/presentations';
+import {
+	resolveDataViewSpec,
+	resolveEventSpec,
+	resolveFormSpec,
+	resolveOperationSpec,
+	resolvePresentationSpec,
+	resolveSerializedDataViewSpec,
+	resolveSerializedEventSpec,
+	resolveSerializedFormSpec,
+	resolveSerializedOperationSpec,
+	resolveSerializedPresentationSpec,
+} from '../../features/contracts-registry';
+
+interface ContractReferenceArgs {
+	key: string;
+	version?: string;
+	type?: string;
+	format?: string;
+	includeSchema?: boolean;
+}
+
+function normalizeText(value: string | undefined | null) {
+	return value?.trim().toLowerCase() ?? '';
+}
+
+function routeFromDocIds(docIds: string[] | undefined) {
+	for (const docId of docIds ?? []) {
+		const doc = defaultDocRegistry.get(docId);
+		if (doc) return doc.route;
+	}
+	return undefined;
+}
+
+function toReference(
+	spec:
+		| AnyOperationSpec
+		| AnyEventSpec
+		| PresentationSpec
+		| DataViewSpec
+		| FormSpec,
+	type: string,
+	schema: unknown,
+	policy?: unknown
+) {
+	const title = spec.meta.title ?? spec.meta.key;
+	const route = routeFromDocIds(spec.meta.docId);
+	const description = spec.meta.description;
+
+	return {
+		key: spec.meta.key,
+		version: spec.meta.version,
+		type,
+		title,
+		description,
+		markdown: [
+			`# ${title}`,
+			`- Key: ${spec.meta.key}`,
+			`- Type: ${type}`,
+			`- Version: ${spec.meta.version}`,
+			route ? `- Docs route: ${route}` : '',
+			description ? `\n${description}` : '',
+		]
+			.filter(Boolean)
+			.join('\n'),
+		...(route ? { route } : {}),
+		...(schema ? { schema } : {}),
+		...(policy ? { policy } : {}),
+		tags: spec.meta.tags ?? [],
+		owners: spec.meta.owners ?? [],
+		stability: spec.meta.stability,
+	};
+}
+
+export function resolveContractReference(args: ContractReferenceArgs) {
+	const includeSchema = args.includeSchema ?? false;
+	const requestedType = normalizeText(args.type);
+
+	const operation = resolveOperationSpec(args.key, args.version);
+	if (
+		operation &&
+		(!requestedType ||
+			requestedType === 'operation' ||
+			requestedType === operation.meta.kind)
+	) {
+		return {
+			reference: toReference(
+				operation,
+				operation.meta.kind,
+				includeSchema
+					? resolveSerializedOperationSpec(args.key, args.version)
+					: undefined,
+				operation.policy
+			),
+		};
+	}
+
+	const resolvers = [
+		{
+			type: 'data-view',
+			spec: resolveDataViewSpec(args.key, args.version),
+			schema: includeSchema
+				? resolveSerializedDataViewSpec(args.key, args.version)
+				: undefined,
+		},
+		{
+			type: 'form',
+			spec: resolveFormSpec(args.key, args.version),
+			schema: includeSchema
+				? resolveSerializedFormSpec(args.key, args.version)
+				: undefined,
+		},
+		{
+			type: 'presentation',
+			spec: resolvePresentationSpec(args.key, args.version),
+			schema: includeSchema
+				? resolveSerializedPresentationSpec(args.key, args.version)
+				: undefined,
+		},
+		{
+			type: 'event',
+			spec: resolveEventSpec(args.key, args.version),
+			schema: includeSchema
+				? resolveSerializedEventSpec(args.key, args.version)
+				: undefined,
+		},
+	] as const;
+
+	for (const candidate of resolvers) {
+		if (
+			candidate.spec &&
+			(!requestedType || requestedType === candidate.type)
+		) {
+			return {
+				reference: toReference(
+					candidate.spec,
+					candidate.type,
+					candidate.schema
+				),
+			};
+		}
+	}
+
+	throw new Error(`Contract reference not found: ${args.key}`);
+}

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

@@ -0,0 +1,194 @@
+import {
+	defineResourceTemplate,
+	ResourceRegistry,
+} from '@contractspec/lib.contracts-spec';
+import type { DocPresentationRoute } from '@contractspec/lib.contracts-spec/docs';
+import z from 'zod';
+import {
+	getDocById,
+	getDocByRoute,
+	listDocFacets,
+	searchDocs,
+} from './docsMcp.data';
+import { resolveContractReference } from './docsMcp.reference';
+
+const DOC_TAGS = ['docs', 'mcp'];
+
+export function buildDocResources(routes: DocPresentationRoute[]) {
+	const resources = new ResourceRegistry();
+	const readDocIndex = (input: {
+		query?: string;
+		tag?: string;
+		kind?: string;
+		visibility?: string;
+		limit?: number;
+		offset?: number;
+	}) => searchDocs(routes, input);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'docs://index',
+				title: 'DocBlocks index',
+				description: 'Default ContractSpec docs index resource.',
+				mimeType: 'application/json',
+				tags: DOC_TAGS,
+			},
+			input: z.object({}),
+			resolve: async () => ({
+				uri: 'docs://index',
+				mimeType: 'application/json',
+				data: JSON.stringify(readDocIndex({}), null, 2),
+			}),
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'docs://index{?query,tag,kind,visibility,limit,offset}',
+				title: 'DocBlocks index',
+				description:
+					'Search and paginate ContractSpec docs by query, tag, kind, or visibility.',
+				mimeType: 'application/json',
+				tags: DOC_TAGS,
+			},
+			input: z.object({
+				query: z.string().optional(),
+				tag: z.string().optional(),
+				kind: z.string().optional(),
+				visibility: z.string().optional(),
+				limit: z.coerce.number().optional(),
+				offset: z.coerce.number().optional(),
+			}),
+			resolve: async (input) => ({
+				uri: 'docs://index',
+				mimeType: 'application/json',
+				data: JSON.stringify(readDocIndex(input), null, 2),
+			}),
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'docs://list',
+				title: 'DocBlocks index (legacy alias)',
+				description: 'Compatibility alias for the docs index resource.',
+				mimeType: 'application/json',
+				tags: DOC_TAGS,
+			},
+			input: z.object({}),
+			resolve: async () => ({
+				uri: 'docs://list',
+				mimeType: 'application/json',
+				data: JSON.stringify(readDocIndex({}), null, 2),
+			}),
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'docs://doc/{id}',
+				title: 'Doc markdown',
+				description: 'Fetch a single DocBlock body by id as markdown.',
+				mimeType: 'text/markdown',
+				tags: DOC_TAGS,
+			},
+			input: z.object({ id: z.string() }),
+			resolve: async ({ id }) => {
+				const found = getDocById(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: found.content,
+				};
+			},
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'docs://route/{routePath}',
+				title: 'Doc by route',
+				description:
+					'Resolve a docs route to the matching DocBlock summary and body.',
+				mimeType: 'application/json',
+				tags: DOC_TAGS,
+			},
+			input: z.object({ routePath: z.string() }),
+			resolve: async ({ routePath }) => ({
+				uri: `docs://route/${encodeURIComponent(routePath)}`,
+				mimeType: 'application/json',
+				data: JSON.stringify(
+					getDocByRoute(routes, routePath) ?? {
+						error: 'not_found',
+						route: routePath,
+					},
+					null,
+					2
+				),
+			}),
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate: 'docs://facets',
+				title: 'Docs facets',
+				description:
+					'Counts of available tags, kinds, and visibilities across docs.',
+				mimeType: 'application/json',
+				tags: DOC_TAGS,
+			},
+			input: z.object({}),
+			resolve: async () => ({
+				uri: 'docs://facets',
+				mimeType: 'application/json',
+				data: JSON.stringify(listDocFacets(routes), null, 2),
+			}),
+		})
+	);
+
+	resources.register(
+		defineResourceTemplate({
+			meta: {
+				uriTemplate:
+					'docs://contract-reference/{key}{?version,type,includeSchema}',
+				title: 'Contract reference',
+				description:
+					'Resolve a ContractSpec surface into a docs-ready reference payload.',
+				mimeType: 'application/json',
+				tags: DOC_TAGS,
+			},
+			input: z.object({
+				key: z.string(),
+				version: z.string().optional(),
+				type: z.string().optional(),
+				includeSchema: z.coerce.boolean().optional(),
+			}),
+			resolve: async ({ key, version, type, includeSchema }) => ({
+				uri: `docs://contract-reference/${encodeURIComponent(key)}`,
+				mimeType: 'application/json',
+				data: JSON.stringify(
+					resolveContractReference({ key, version, type, includeSchema }),
+					null,
+					2
+				),
+			}),
+		})
+	);
+
+	return resources;
+}

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