@farming-labs/theme 0.1.22 → 0.1.23

package/dist/docs-api.d.mts

@@ -43,6 +43,8 @@ interface DocsAPIOptions {
   search?: boolean | DocsSearchConfig;
   /** Feedback configuration */
   feedback?: boolean | FeedbackConfig;
+  /** MCP configuration used for the agent discovery spec. */
+  mcp?: boolean | DocsMcpConfig;
 }
 interface DocsMCPAPIOptions {
   rootDir?: string;

package/dist/docs-api.mjs

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
 import { performDocsSearch, resolveChangelogConfig, resolveDocsI18n, resolveDocsLocale, resolveSearchRequestConfig } from "@farming-labs/docs";
-import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource } from "@farming-labs/docs/server";
+import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
 /**
@@ -32,6 +32,8 @@ const FILE_EXTS = [
 	"jsx",
 	"js"
 ];
+const DEFAULT_DOCS_API_ROUTE = "/api/docs";
+const DEFAULT_AGENT_SPEC_ROUTE = "/api/docs/agent/spec";
 const DEFAULT_AGENT_FEEDBACK_ROUTE = "/api/docs/agent/feedback";
 const DEFAULT_AGENT_FEEDBACK_PAYLOAD_SCHEMA = {
 	type: "object",
@@ -143,6 +145,54 @@ function resolveAgentFeedbackRequest(url, feedback) {
 	if (pathname === feedback.route) return { kind: "submit" };
 	return null;
 }
+function resolveAgentSpecRequest(url) {
+	if (url.searchParams.get("agent")?.trim() === "spec") return true;
+	return normalizeUrlPath(url.pathname) === DEFAULT_AGENT_SPEC_ROUTE;
+}
+function buildAgentSpec({ origin, entry, mcp, feedback }) {
+	const normalizedEntry = normalizePathSegment(entry) || "docs";
+	return {
+		version: "1",
+		name: "@farming-labs/docs",
+		baseUrl: origin,
+		api: {
+			docs: DEFAULT_DOCS_API_ROUTE,
+			agentSpec: DEFAULT_AGENT_SPEC_ROUTE,
+			agentSpecQuery: `${DEFAULT_DOCS_API_ROUTE}?agent=spec`
+		},
+		markdown: {
+			enabled: true,
+			pagePattern: `/${normalizedEntry}/{slug}.md`,
+			rootPage: `/${normalizedEntry}.md`,
+			apiPattern: `${DEFAULT_DOCS_API_ROUTE}?format=markdown&path={slug}`,
+			resolutionOrder: [
+				"agent.md",
+				"Agent blocks",
+				"page markdown"
+			]
+		},
+		mcp: {
+			enabled: mcp.enabled,
+			endpoint: mcp.route,
+			name: mcp.name,
+			version: mcp.version,
+			tools: mcp.tools
+		},
+		feedback: {
+			enabled: feedback.enabled,
+			schema: feedback.schemaRoute,
+			submit: feedback.route,
+			schemaQuery: `${DEFAULT_DOCS_API_ROUTE}?feedback=agent&schema=1`,
+			submitQuery: `${DEFAULT_DOCS_API_ROUTE}?feedback=agent`
+		},
+		instructions: {
+			preferMarkdownRoutes: true,
+			useMcpWhenAvailable: true,
+			readFeedbackSchemaBeforeSubmitting: true,
+			doNotAssumeFeedbackPayloadShape: true
+		}
+	};
+}
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -808,6 +858,7 @@ function createDocsAPI(options) {
 	const aiConfig = options?.ai ?? readAIConfig(root);
 	const searchConfig = options?.search;
 	const llmsConfig = readLlmsTxtConfig(root);
+	const mcpConfig = resolveDocsMcpConfig(options?.mcp ?? readMcpConfig(root), { defaultName: llmsConfig.siteTitle ?? "Documentation" });
 	function resolveDocsDirCandidates(locale) {
 		const relativeCandidates = /* @__PURE__ */ new Set();
 		if (path.isAbsolute(contentDir)) return [locale ? path.join(contentDir, locale) : contentDir];
@@ -927,6 +978,15 @@ function createDocsAPI(options) {
 		async GET(request) {
 			const ctx = resolveContextFromRequest(request);
 			const url = new URL(request.url);
+			if (resolveAgentSpecRequest(url)) return Response.json(buildAgentSpec({
+				origin: url.origin,
+				entry,
+				mcp: mcpConfig,
+				feedback: agentFeedbackConfig
+			}), { headers: {
+				"Cache-Control": "public, max-age=0, s-maxage=3600",
+				"X-Robots-Tag": "noindex"
+			} });
 			const agentFeedbackRequest = resolveAgentFeedbackRequest(url, agentFeedbackConfig);
 			if (agentFeedbackRequest) {
 				if (agentFeedbackRequest.kind === "submit") return Response.json({ error: "Method Not Allowed" }, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -133,7 +133,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@farming-labs/docs": "0.1.22"
+    "@farming-labs/docs": "0.1.23"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",