@farming-labs/docs 0.2.52 → 0.2.54

package/dist/mcp.d.mts

@@ -1,4 +1,4 @@
-import { Ct as DocsTelemetryConfig, J as DocsMcpConfig, Kt as OrderingItem, Ot as DocsTelemetryFramework, Q as DocsObservabilityConfig, bt as DocsSearchSourcePage, mt as DocsSearchConfig, v as DocsAnalyticsConfig } from "./types-XqGLsmOD.mjs";
+import { Ft as DocsSearchSourcePage, Rt as DocsTelemetryConfig, T as DocsAnalyticsConfig, Ut as DocsTelemetryFramework, fn as PageAgentFrontmatter, kt as DocsSearchConfig, nt as DocsMcpAuthPrincipal, ot as DocsMcpConfig, pt as DocsObservabilityConfig, rt as DocsMcpAuthenticate, sn as OrderingItem, tt as DocsMcpAllowedOrigins } from "./types-BVgucdVm.mjs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 //#region src/mcp.d.ts
@@ -8,9 +8,14 @@ interface DocsMcpPage {
   title: string;
   description?: string;
   related?: DocsSearchSourcePage["related"];
+  agent?: PageAgentFrontmatter;
   icon?: string;
   sourcePath?: string;
   lastModified?: string;
+  locale?: string;
+  framework?: string;
+  version?: string;
+  tags?: string[];
   content: string;
   rawContent?: string;
   agentContent?: string;
@@ -41,10 +46,26 @@ interface DocsMcpDocsPageSummary {
   url: string;
   title: string;
   description?: string;
+  agent?: DocsMcpAgentContractSummary;
   icon?: string;
   sourcePath?: string;
   lastModified?: string;
 }
+interface DocsMcpAgentContractSummary {
+  hasContract: boolean;
+  task?: string;
+  outcome?: string;
+  appliesTo?: PageAgentFrontmatter["appliesTo"];
+}
+interface DocsMcpTaskSummary {
+  slug: string;
+  url: string;
+  title: string;
+  description?: string;
+  task?: string;
+  outcome?: string;
+  appliesTo?: PageAgentFrontmatter["appliesTo"];
+}
 interface DocsMcpDocsSection {
   slug: string;
   title: string;
@@ -70,8 +91,8 @@ interface DocsMcpConfigSchemaOption {
   default?: string | boolean | number | null;
   description: string;
   docs?: string;
-  values?: string[];
-  children?: DocsMcpConfigSchemaOption[];
+  values?: readonly string[];
+  children?: readonly DocsMcpConfigSchemaOption[];
 }
 interface DocsMcpConfigSchema {
   schemaVersion: 1;
@@ -88,6 +109,62 @@ interface DocsMcpConfigSchema {
     code: string;
   }>;
 }
+interface DocsMcpContextSource {
+  id: string;
+  title: string;
+  /** Page URL without a fragment. */
+  pageUrl: string;
+  /** Source URL for this exact context chunk, including its heading anchor when available. */
+  url: string;
+  section?: string;
+  anchor?: string;
+  sourcePath?: string;
+  lastModified?: string;
+  locale?: string;
+  framework?: string;
+  version?: string;
+  tags?: string[];
+  score?: number;
+  content: string;
+  /** JavaScript string length for this source's content only. */
+  chars: number;
+  /** Encoded UTF-8 bytes for this source's content only. */
+  utf8Bytes: number;
+  truncated: boolean;
+}
+interface DocsMcpContextResult {
+  query: string;
+  filters: {
+    framework?: string;
+    version?: string;
+    locale?: string;
+  };
+  budget: {
+    /** Caller-provided token target; retained as the stable input contract. */requestedTokens: number; /** Dependency-free conservative accounting strategy. */
+    strategy: "utf8-bytes"; /** Hard UTF-8 byte ceiling for the complete assembled `context`. */
+    maxUtf8Bytes: number; /** Exact UTF-8 bytes used by the complete assembled `context`. */
+    usedUtf8Bytes: number; /** Conservative token-count upper bound derived from `usedUtf8Bytes`. */
+    conservativeTokenUpperBound: number;
+    remainingUtf8Bytes: number;
+    truncated: boolean;
+  };
+  resultCount: number;
+  candidateCount: number;
+  context: string;
+  sources: DocsMcpContextSource[];
+}
+interface DocsMcpContextOptions {
+  pages: readonly DocsMcpPage[];
+  query: string;
+  framework?: string;
+  version?: string;
+  locale?: string;
+  tokenBudget: number;
+  entry?: string;
+  siteTitle?: string;
+  /** Maximum number of ranked, deduplicated candidates to render. Defaults to 50. */
+  maxResults?: number;
+}
 interface DocsMcpPageNode {
   type: "page";
   name: string;
@@ -110,8 +187,27 @@ interface DocsMcpNavigationTree {
 interface DocsMcpSource {
   entry?: string;
   siteTitle?: string;
-  getPages(locale?: string): DocsMcpPage[] | Promise<DocsMcpPage[]>;
-  getNavigation(locale?: string): DocsMcpNavigationTree | Promise<DocsMcpNavigationTree>;
+  getPages(locale?: string, context?: DocsMcpRequestContext): DocsMcpPage[] | Promise<DocsMcpPage[]>;
+  getNavigation(locale?: string, context?: DocsMcpRequestContext): DocsMcpNavigationTree | Promise<DocsMcpNavigationTree>;
+}
+/** Request-scoped identity available to custom MCP sources. */
+interface DocsMcpRequestContext {
+  transport: "http" | "stdio";
+  request?: Request;
+  auth?: DocsMcpAuthPrincipal;
+}
+interface DocsMcpResolvedSecurityConfig {
+  allowedOrigins: DocsMcpAllowedOrigins;
+  authenticate?: DocsMcpAuthenticate;
+  maxBodyBytes: number;
+  cors: DocsMcpResolvedCorsConfig;
+}
+interface DocsMcpResolvedCorsConfig {
+  enabled: boolean;
+  allowedHeaders: string[];
+  exposedHeaders: string[];
+  allowCredentials: boolean;
+  maxAgeSeconds: number;
 }
 interface DocsMcpResolvedConfig {
   enabled: boolean;
@@ -122,11 +218,16 @@ interface DocsMcpResolvedConfig {
     listDocs: boolean;
     listPages: boolean;
     readPage: boolean;
+    listTasks?: boolean;
+    readTask?: boolean;
     searchDocs: boolean;
     getNavigation: boolean;
     getCodeExamples: boolean;
     getConfigSchema: boolean;
+    getContext: boolean;
   };
+  /** Resolved HTTP-only security policy. Omitted on manually constructed legacy values. */
+  security?: DocsMcpResolvedSecurityConfig;
 }
 interface DocsMcpHttpHandlers {
   GET: (context: {
@@ -138,6 +239,9 @@ interface DocsMcpHttpHandlers {
   DELETE: (context: {
     request: Request;
   }) => Promise<Response>;
+  OPTIONS: (context: {
+    request: Request;
+  }) => Promise<Response>;
 }
 interface CreateDocsMcpServerOptions {
   source: DocsMcpSource;
@@ -149,6 +253,8 @@ interface CreateDocsMcpServerOptions {
   observability?: boolean | DocsObservabilityConfig;
   defaultName?: string;
   defaultVersion?: string;
+  /** Internal request context used to expose an authenticated principal to custom sources. */
+  requestContext?: DocsMcpRequestContext;
 }
 interface CreateFilesystemDocsMcpSourceOptions {
   rootDir?: string;
@@ -157,6 +263,11 @@ interface CreateFilesystemDocsMcpSourceOptions {
   siteTitle?: string;
   ordering?: "alphabetical" | "numeric" | OrderingItem[];
 }
+declare const DEFAULT_DOCS_MCP_MAX_BODY_BYTES: number;
+declare const DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS = 600;
+declare const DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS: readonly string[];
+declare const DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS: readonly string[];
+declare const DOCS_CONFIG_SCHEMA_OPTIONS: readonly DocsMcpConfigSchemaOption[];
 declare function normalizeDocsMcpRoute(route?: string): string;
 declare function resolveDocsMcpConfig(mcp?: boolean | DocsMcpConfig, defaults?: {
   defaultName?: string;
@@ -167,5 +278,10 @@ declare function createFilesystemDocsMcpSource(options?: CreateFilesystemDocsMcp
 declare function createDocsMcpServer(options: CreateDocsMcpServerOptions): Promise<McpServer>;
 declare function createDocsMcpHttpHandler(options: CreateDocsMcpServerOptions): DocsMcpHttpHandlers;
 declare function runDocsMcpStdio(options: CreateDocsMcpServerOptions): Promise<void>;
+declare function getDocsConfigSchema(filters?: {
+  option?: string;
+  query?: string;
+}): DocsMcpConfigSchema;
+declare function buildDocsMcpContext(options: DocsMcpContextOptions): Promise<DocsMcpContextResult>;
 //#endregion
-export { DocsMcpCodeExample, DocsMcpConfigSchema, DocsMcpConfigSchemaOption, DocsMcpDocsList, DocsMcpDocsPageSummary, DocsMcpDocsSection, DocsMcpFolderNode, DocsMcpHttpHandlers, DocsMcpNavigationNode, DocsMcpNavigationTree, DocsMcpPage, DocsMcpPageNode, DocsMcpResolvedConfig, DocsMcpSource, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio };
+export { CreateDocsMcpServerOptions, DEFAULT_DOCS_MCP_CORS_ALLOWED_HEADERS, DEFAULT_DOCS_MCP_CORS_EXPOSED_HEADERS, DEFAULT_DOCS_MCP_CORS_MAX_AGE_SECONDS, DEFAULT_DOCS_MCP_MAX_BODY_BYTES, DOCS_CONFIG_SCHEMA_OPTIONS, DocsMcpAgentContractSummary, DocsMcpCodeExample, DocsMcpConfigSchema, DocsMcpConfigSchemaOption, DocsMcpContextOptions, DocsMcpContextResult, DocsMcpContextSource, DocsMcpDocsList, DocsMcpDocsPageSummary, DocsMcpDocsSection, DocsMcpFolderNode, DocsMcpHttpHandlers, DocsMcpNavigationNode, DocsMcpNavigationTree, DocsMcpPage, DocsMcpPageNode, DocsMcpRequestContext, DocsMcpResolvedConfig, DocsMcpResolvedCorsConfig, DocsMcpResolvedSecurityConfig, DocsMcpSource, DocsMcpTaskSummary, buildDocsMcpContext, createDocsMcpHttpHandler, createDocsMcpServer, createFilesystemDocsMcpSource, getDocsConfigSchema, normalizeDocsMcpRoute, resolveDocsMcpConfig, runDocsMcpStdio };