@contractspec/bundle.library 3.8.4 → 3.8.7

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

@@ -0,0 +1,196 @@
+import type { DocPresentationRoute } from '@contractspec/lib.contracts-spec/docs';
+import { defaultDocRegistry } from '@contractspec/lib.contracts-spec/docs';
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+
+type DocsSearchArgs = {
+	query?: string;
+	tag?: string | string[];
+	visibility?: string;
+	kind?: string;
+	limit?: number;
+	offset?: number;
+};
+
+function normalizeText(value: string | undefined | null) {
+	return value?.trim().toLowerCase() ?? '';
+}
+
+function normalizeRoute(route: string) {
+	const decoded = decodeURIComponent(route).trim();
+	if (!decoded) return '/';
+	return decoded.startsWith('/') ? decoded : `/${decoded}`;
+}
+
+function normalizeTags(value: string | string[] | undefined) {
+	const tags = Array.isArray(value) ? value : value ? [value] : [];
+	return tags.map((tag) => normalizeText(tag)).filter(Boolean);
+}
+
+function clampLimit(limit: number | undefined) {
+	if (!limit || Number.isNaN(limit)) return DEFAULT_LIMIT;
+	return Math.min(Math.max(limit, 1), MAX_LIMIT);
+}
+
+function clampOffset(offset: number | undefined) {
+	if (!offset || Number.isNaN(offset)) return 0;
+	return Math.max(offset, 0);
+}
+
+export function toDocSummary({ block, route }: DocPresentationRoute) {
+	return {
+		id: block.id,
+		title: block.title,
+		summary: block.summary ?? '',
+		route,
+		visibility: block.visibility ?? 'public',
+		kind: block.kind ?? 'reference',
+		version: block.version ?? '1.0.0',
+		tags: block.tags ?? [],
+	};
+}
+
+function scoreDoc(route: DocPresentationRoute, query: string) {
+	if (!query) return 1;
+
+	const tokens = query.split(/\s+/).filter(Boolean);
+	const title = normalizeText(route.block.title);
+	const id = normalizeText(route.block.id);
+	const summary = normalizeText(route.block.summary);
+	const body = normalizeText(route.block.body);
+	const path = normalizeText(route.route);
+	const tags = (route.block.tags ?? []).map((tag) => normalizeText(tag));
+	const haystack = [title, id, summary, body, path, ...tags].join(' ');
+
+	if (tokens.some((token) => !haystack.includes(token))) return 0;
+
+	let score = 0;
+	for (const token of tokens) {
+		if (id.includes(token)) score += 8;
+		if (title.includes(token)) score += 7;
+		if (tags.some((tag) => tag.includes(token))) score += 5;
+		if (summary.includes(token)) score += 4;
+		if (path.includes(token)) score += 3;
+		if (body.includes(token)) score += 2;
+	}
+
+	return score;
+}
+
+export function searchDocs(
+	routes: DocPresentationRoute[],
+	args: DocsSearchArgs
+) {
+	const query = normalizeText(
+		typeof args.query === 'string' ? args.query : undefined
+	);
+	const tags = normalizeTags(args.tag as string | string[] | undefined);
+	const visibility = normalizeText(
+		typeof args.visibility === 'string' ? args.visibility : undefined
+	);
+	const kind = normalizeText(
+		typeof args.kind === 'string' ? args.kind : undefined
+	);
+	const limit = clampLimit(
+		typeof args.limit === 'number' ? args.limit : undefined
+	);
+	const offset = clampOffset(
+		typeof args.offset === 'number' ? args.offset : undefined
+	);
+
+	const ranked = routes
+		.map((route) => ({
+			doc: toDocSummary(route),
+			score: scoreDoc(route, query),
+		}))
+		.filter(({ doc, score }) => {
+			const matchesQuery = query ? score > 0 : true;
+			const matchesTags = tags.length
+				? tags.every((tag) =>
+						doc.tags.some((docTag) => normalizeText(docTag).includes(tag))
+					)
+				: true;
+			const matchesVisibility = visibility
+				? normalizeText(doc.visibility) === visibility
+				: true;
+			const matchesKind = kind ? normalizeText(doc.kind) === kind : true;
+			return matchesQuery && matchesTags && matchesVisibility && matchesKind;
+		})
+		.sort((left, right) => {
+			if (right.score !== left.score) return right.score - left.score;
+			return left.doc.title.localeCompare(right.doc.title);
+		});
+
+	const docs = ranked.slice(offset, offset + limit).map(({ doc }) => doc);
+	const nextOffset =
+		offset + docs.length < ranked.length ? offset + docs.length : undefined;
+
+	return {
+		docs,
+		items: docs,
+		total: ranked.length,
+		...(nextOffset != null ? { nextOffset } : {}),
+	};
+}
+
+export function getDocById(id: string) {
+	const normalizedId = decodeURIComponent(id);
+	const found = defaultDocRegistry.get(normalizedId);
+	if (!found) return undefined;
+
+	return {
+		doc: toDocSummary(found),
+		content: String(found.block.body ?? ''),
+	};
+}
+
+export function getDocByRoute(
+	routes: DocPresentationRoute[],
+	routePath: string
+) {
+	const normalizedPath = normalizeRoute(routePath);
+	const found = routes.find(
+		(route) => normalizeRoute(route.route) === normalizedPath
+	);
+	if (!found) return undefined;
+
+	return {
+		doc: toDocSummary(found),
+		content: String(found.block.body ?? ''),
+	};
+}
+
+export function listDocFacets(routes: DocPresentationRoute[]) {
+	const tags = new Map<string, number>();
+	const kinds = new Map<string, number>();
+	const visibilities = new Map<string, number>();
+
+	for (const route of routes) {
+		const kind = route.block.kind ?? 'reference';
+		const visibility = route.block.visibility ?? 'public';
+		kinds.set(kind, (kinds.get(kind) ?? 0) + 1);
+		visibilities.set(visibility, (visibilities.get(visibility) ?? 0) + 1);
+
+		for (const tag of route.block.tags ?? []) {
+			tags.set(tag, (tags.get(tag) ?? 0) + 1);
+		}
+	}
+
+	const toEntries = (
+		values: Map<string, number>,
+		key: 'tag' | 'kind' | 'visibility'
+	) =>
+		[...values.entries()]
+			.sort(
+				(left, right) => right[1] - left[1] || left[0].localeCompare(right[0])
+			)
+			.map(([value, count]) => ({ [key]: value, count }));
+
+	return {
+		totalDocs: routes.length,
+		tags: toEntries(tags, 'tag'),
+		kinds: toEntries(kinds, 'kind'),
+		visibilities: toEntries(visibilities, 'visibility'),
+	};
+}

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