@clarify-labs/cli 0.11.0 → 0.11.2

package/output/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_engine = require("./engine-BfkoyVNo.cjs");
+const require_engine = require("./engine--5unu78V.cjs");
 exports.ClarifyEngine = require_engine.ClarifyEngine;
 exports.createClarifyEngine = require_engine.createClarifyEngine;
 exports.createViteAdapter = require_engine.createViteAdapter;

package/output/index.js

@@ -1,2 +1,2 @@
-import { c as defineConfig, n as createClarifyEngine, s as createViteAdapter, t as ClarifyEngine } from "./engine-DfF5RJjC.js";
+import { l as createViteAdapter, n as createClarifyEngine, t as ClarifyEngine, u as defineConfig } from "./engine-DI8Nd3v0.js";
 export { ClarifyEngine, createClarifyEngine, createViteAdapter, defineConfig };

package/output/parsers/routes/routes.d.ts

@@ -1,19 +1,15 @@
-import { ContentRoute, ContentSection, ClarifyNavigationNode, ClarifyPagesConfig, ClarifyPagesGroup, ClarifyPagesItem, ClarifyRouteIntent, ClarifyLocalizedText, ClarifyTabsConfig, LocalizedNavigation, LocalizedTabbedNavigation, ResolvedClarifyLocalesConfig, TabbedNavigation } from '../../types.js';
+import { ContentRoute, ClarifyNavigationNode, ClarifyPagesConfig, ClarifyPagesGroup, ClarifyPagesItem, ClarifyRouteIntent, ClarifyTabsConfig, LocalizedNavigation, LocalizedTabbedNavigation, ResolvedClarifyLocalesConfig, TabbedNavigation } from '../../types.js';
 import { ContentProcessor } from '../content/content.js';
 export type FindContentRoutesOptions = {
     contentProcessor?: ContentProcessor;
 };
 export declare function kebabToTitle(str: string): string;
-/** 从 MDX/Markdown 内容中提取 H2/H3 章节 */
-export declare function extractMdxSections(content: string): ContentSection[];
 export declare function normalizePath(path: string): string;
-export declare function openAPITagsPathSegment(tags: string[]): string;
 export declare function basePathFromRef(ref: string): string;
 export declare function openAPIPagePathFromRef(ref: string, tagFilter?: string[], explicitPath?: string): string;
 export declare function routePathFromRef(ref: string, explicitPath?: string): string;
 export declare function virtualModuleIdFromRef(ref: string): string;
 export declare function localizedRoutePath(basePath: string, locale: string, _i18n: ResolvedClarifyLocalesConfig): string;
-export declare function resolveLocalizedText(text: ClarifyLocalizedText | undefined, locale: string, fallbackLocale?: string): string | undefined;
 export declare function findContentRoutes(dir: string, base?: string, options?: FindContentRoutesOptions): Promise<ContentRoute[]>;
 export declare function withAlternates(route: ContentRoute, routes: ContentRoute[], locales: ResolvedClarifyLocalesConfig): ContentRoute;
 export declare function findLocalizedContentRoutes(contentRoot: string, locales?: ResolvedClarifyLocalesConfig, options?: FindContentRoutesOptions): Promise<ContentRoute[]>;

package/output/plugins/content-artifacts/artifacts.d.ts

@@ -1,6 +1,4 @@
 import { ContentRoute, ResolvedProjectConfig } from '../../types.js';
-export declare function routeToMarkdownArtifactUrl(routePath: string): string;
-export declare function routeToOpenAPIArtifactUrl(routePath: string): string;
 export declare function attachContentArtifactUrls(routes: ContentRoute[]): void;
 export declare function readRouteContent(route: ContentRoute): string;
 export declare function readRouteArtifactContent(route: ContentRoute): string;

package/output/plugins/mcp-search/index.d.ts

@@ -0,0 +1,15 @@
+import { ClarifyPlugin } from '../../types.js';
+/**
+ * MCP search index plugin.
+ *
+ * Generates the Orama binary index (`mcp-search.msp`) and the MCP site
+ * descriptor (`mcp.json`) as build assets consumed by the `clarify mcp`
+ * command to serve documentation search to MCP-aware clients (e.g. AI coding
+ * assistants).
+ *
+ * This plugin is independent of `clarify:page-search` (Pagefind), which
+ * powers in-browser search. The MCP server runs in Node and needs a
+ * self-contained, compact index with CJK-aware tokenization that doesn't
+ * depend on the browser-only Pagefind runtime.
+ */
+export declare function createMcpSearchPlugin(): ClarifyPlugin;

package/output/plugins/mcp-search/mcp-config.d.ts

@@ -0,0 +1,75 @@
+import { ResolvedProjectConfig } from '../../types.js';
+/**
+ * Descriptor for a single MCP capability surfaced by a Clarify site.
+ *
+ * Capabilities are intentionally open-ended so future versions can add
+ * `resources`, `prompts`, etc. without reshaping the top-level file. Each
+ * capability carries its own metadata block; the CLI selects the block(s)
+ * it understands and ignores the rest.
+ */
+export type McpCapability = McpSearchCapability;
+/**
+ * Full-text search capability backed by an Orama binary index.
+ */
+export type McpSearchCapability = {
+    /** Capability discriminator. */
+    type: 'search';
+    /**
+     * Root-relative path to the Orama binary index (`.msp`) produced at build
+     * time. Always served from the site root, so it already includes the
+     * routePrefix when one is configured.
+     */
+    indexPath: string;
+    /** SHA-256 hash of the index payload at indexPath, for cache freshness checks. */
+    indexHash?: string;
+    /** Locale used when the caller does not specify one. Drives tokenizer. */
+    defaultLocale?: string;
+    /** Number of documents stored in the index. */
+    documentCount: number;
+    /** Locales present in the index, for surfacing in tool descriptions. */
+    locales: string[];
+};
+/**
+ * MCP server descriptor emitted to `<output>/mcp.json` during build.
+ *
+ * Consumed by `clarify mcp <url>` to bootstrap a local MCP server that
+ * exposes site capabilities (currently full-text search) to LLM clients.
+ * The descriptor points the CLI at the Orama binary index (`.msp`) written
+ * alongside `mcp.json` and carries the locale metadata needed to reconstruct
+ * the tokenizer at runtime.
+ */
+export type McpSiteConfig = {
+    /** Schema version of this file. Bumped on breaking shape changes. */
+    version: 3;
+    site: {
+        title?: string;
+        description?: string;
+        /** Canonical public site URL, if `siteUrl` is configured. */
+        url?: string;
+        /** Route prefix where the site is mounted. Default: '/'. */
+        routePrefix: string;
+    };
+    /**
+     * Capability map keyed by capability id. The id is stable across builds so
+     * clients can address a specific capability (e.g. `search`) even as new
+     * ones are added. Only capabilities actually emitted by the build are
+     * present; an absent key means the site does not provide that capability.
+     */
+    capabilities: {
+        search?: McpSearchCapability;
+    };
+};
+export type CreateMcpSiteConfigOptions = {
+    documentCount: number;
+    locales: string[];
+    indexHash: string;
+};
+/**
+ * Assemble the MCP site config from build-time metadata.
+ *
+ * Unlike the previous pagefind-based descriptor, this no longer reads an
+ * entry JSON file - the Orama index is a single binary blob, so the caller
+ * supplies the document count and locale list directly from the build step
+ * that produced the index.
+ */
+export declare function createMcpSiteConfig(projectConfig: ResolvedProjectConfig, options: CreateMcpSiteConfigOptions): McpSiteConfig;

package/output/plugins/mcp-search/orama-index.d.ts

@@ -0,0 +1,153 @@
+import { AnyOrama } from '@orama/orama';
+import { ContentRoute } from '../../types.js';
+/**
+ * Orama schema for the MCP search index.
+ *
+ * - `path`, `title`, `description`, `content` are full-text searchable strings.
+ * - `locale` is an `enum` so we can use `where: { locale: { eq } }` filters at
+ *   query time. (`string` fields cannot be filtered in Orama.)
+ * - `keywords` is a `string[]` also indexed for full-text matching.
+ */
+export declare const mcpSearchSchema: {
+    readonly path: "string";
+    readonly title: "string";
+    readonly description: "string";
+    readonly locale: "enum";
+    readonly content: "string";
+    readonly keywords: "string[]";
+};
+export type McpSearchDocument = {
+    path: string;
+    title: string;
+    description: string;
+    locale: string;
+    content: string;
+    keywords: string[];
+};
+/**
+ * Tokenize text for Orama indexing and querying.
+ *
+ * CJK locales use `Intl.Segmenter` (word granularity), which splits
+ * spaceless scripts into words and individual characters. Latin/whitespace
+ * locales fall back to a Unicode-aware split on spaces and punctuation.
+ *
+ * All tokens are lowercased so queries match regardless of case.
+ */
+export declare function tokenizeForSearch(text: string, locale?: string): string[];
+/**
+ * Build an Orama tokenizer component bound to a specific default locale.
+ *
+ * The tokenizer receives the raw field value and the per-field language hint
+ * from Orama (which we don't set per-field, so it falls back to the default
+ * language). We resolve the segmenter locale from the default locale at
+ * construction time so the same tokenizer handles all documents in a
+ * predominantly single-locale index.
+ *
+ * For multi-locale indexes, the tokenizer is also used at query time. Since
+ * the query locale is not known to Orama's tokenizer callback, we use the
+ * index's default locale - this is acceptable because:
+ *   - CJK queries get CJK segmentation (correct)
+ *   - Latin queries against a CJK-default index still work because Latin
+ *     text has no word boundaries for CJK segmenters to mis-split; the
+ *     segmenter passes through Latin words as-is.
+ */
+export declare function createMcpTokenizer(defaultLocale?: string): {
+    language: string;
+    normalizationCache: Map<string, string>;
+    tokenize(raw: unknown, language?: string): string[];
+};
+/**
+ * Compose the searchable text for a route. Shared between the Pagefind
+ * (browser) and Orama (MCP) indexing paths so both backends see the same
+ * field order and content.
+ */
+export declare function routeSearchContent(route: ContentRoute): string;
+/**
+ * Convert a `ContentRoute` into the document shape stored in the Orama index.
+ */
+export declare function routeToSearchDocument(route: ContentRoute, defaultLocale?: string): McpSearchDocument | null;
+/**
+ * Create an Orama index pre-configured with the MCP schema and CJK-aware
+ * tokenizer. Both the build step and the runtime loader use this so the
+ * tokenizer is guaranteed to match between indexing and querying.
+ *
+ * Annotated as `AnyOrama` (Orama's exported base type) rather than inferred
+ * via `ReturnType<typeof create>` because the inference would pull in
+ * Orama's internal component types (`DocumentsStore`, `Index`, `Sorter`)
+ * which are not exported and break `.d.ts` generation (TS2883).
+ */
+export declare function createMcpSearchIndex(defaultLocale?: string): McpSearchDb;
+/** Orama index instance type for the MCP search schema. */
+export type McpSearchDb = AnyOrama<typeof mcpSearchSchema>;
+/**
+ * Insert search documents into an Orama index.
+ */
+export declare function indexSearchDocuments(db: McpSearchDb, documents: McpSearchDocument[]): void;
+/**
+ * Build a ready-to-search Orama index from content routes.
+ *
+ * Filters out bare aliases and empty routes. Returns the populated db.
+ */
+export declare function buildSearchIndex(routes: ContentRoute[], defaultLocale?: string): {
+    db: McpSearchDb;
+    documentCount: number;
+};
+/**
+ * Collect the distinct locale codes that will be present in the Orama index,
+ * in stable insertion order. Bare aliases are skipped (they duplicate the
+ * default-locale route). Locales with no code fall back to the project
+ * default so single-locale sites still surface one locale.
+ */
+export declare function collectIndexedLocales(routes: ContentRoute[], defaultLocale?: string): string[];
+export type McpSearchParams = {
+    query: string;
+    locale?: string;
+    limit?: number;
+};
+export type McpSearchHit = {
+    path: string;
+    title: string;
+    description: string;
+    locale: string;
+    score: number;
+    excerpt: string;
+    keywords: string[];
+};
+export type McpSearchResult = {
+    hits: McpSearchHit[];
+    count: number;
+};
+/**
+ * Search an Orama MCP index.
+ *
+ * Applies an optional locale filter (via the `enum` field) and returns a
+ * compact, LLM-friendly hit shape. Excerpts are derived from the matched
+ * content: Orama does not return highlighted excerpts, so we synthesize a
+ * short window around the first query term occurrence.
+ */
+export declare function searchMcpIndex(db: McpSearchDb, params: McpSearchParams): McpSearchResult;
+/**
+ * Serialize an Orama index to a msgpack binary buffer.
+ *
+ * Uses `save()` to extract the raw index data, then msgpack-encodes it for a
+ * compact binary representation. The same schema + tokenizer must be supplied
+ * when loading so query-time tokenization matches indexing-time tokenization.
+ */
+export declare function serializeSearchIndex(db: McpSearchDb): Uint8Array;
+/**
+ * Deserialize a msgpack binary buffer into a ready-to-search Orama index.
+ *
+ * The caller must supply the same `defaultLocale` used when the index was
+ * built, so the tokenizer matches. A mismatch would not corrupt data but
+ * would cause CJK query terms to be tokenized incorrectly (e.g. "文档" left
+ * as a single token instead of split into "文" + "档").
+ */
+export declare function deserializeSearchIndex(buffer: Uint8Array, defaultLocale?: string): McpSearchDb;
+/**
+ * Write an Orama index to a `.msp` (msgpack) file on disk.
+ */
+export declare function writeSearchIndex(db: McpSearchDb, filePath: string): void;
+/**
+ * Read an Orama index from a `.msp` (msgpack) file on disk.
+ */
+export declare function readSearchIndex(filePath: string, defaultLocale?: string): McpSearchDb;

package/output/plugins/openapi/virtual-modules.d.ts

@@ -1,7 +1,6 @@
 import { OpenAPISpec } from '../../types.js';
 export declare const openApiRegistryModuleId = "virtual:clarify/openapi";
 export declare const openApiServerRegistryModuleId = "virtual:clarify/openapi/server";
-export declare const OPENAPI_SPEC_PREFIX = "virtual:clarify/openapi-spec/";
 export declare function specVirtualModuleId(specKey: string): string;
 export declare function generateOpenAPIRegistryModule(openApiSpecs: Record<string, string>): string;
 export declare function generateOpenAPIServerRegistryModule(openApiSpecs: Record<string, OpenAPISpec>): string;

package/output/plugins/page-search/index.d.ts

@@ -0,0 +1,2 @@
+import { ClarifyPlugin } from '../../types.js';
+export declare function createPageSearchPlugin(): ClarifyPlugin;

package/output/types.d.ts

@@ -185,7 +185,8 @@ export type ClarifyFeatureConfig<Options extends object = Record<never, never>>
 } & Options);
 export type ClarifyFeaturesConfig = {
     search?: ClarifyFeatureConfig<{
-        provider?: 'pagefind';
+        /** Whether to emit the MCP search index + descriptor for `clarify mcp`. Default: true. */
+        mcp?: boolean;
     }>;
     repository?: ClarifyFeatureConfig<ClarifyRepositoryConfig>;
     themeEditor?: ClarifyFeatureConfig;
@@ -196,7 +197,7 @@ export type ClarifyFeaturesConfig = {
 export type ResolvedClarifyFeaturesConfig = {
     search: {
         enabled: boolean;
-        provider: 'pagefind';
+        mcp: boolean;
     };
     repository: {
         enabled: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clarify-labs/cli",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "repository": {
@@ -39,10 +39,13 @@
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
-    "@clarify-labs/renderer": "0.11.0",
-    "@clarify-labs/templates": "0.11.0",
+    "@clarify-labs/renderer": "0.11.2",
+    "@clarify-labs/templates": "0.11.2",
     "@mdx-js/mdx": "^3.1.1",
     "@mdx-js/rollup": "^3.1.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@msgpack/msgpack": "^3.1.3",
+    "@orama/orama": "^3.1.18",
     "@shikijs/rehype": "^4.3.0",
     "@tailwindcss/vite": "^4.3.2",
     "@vitejs/plugin-react": "^6.0.3",
@@ -61,7 +64,6 @@
     "rehype-raw": "^7.0.0",
     "rehype-slug": "^6.0.0",
     "remark": "^15.0.1",
-    "remark-gfm": "^4.0.1",
     "shiki": "4.3.0",
     "unist-util-visit": "^5.1.0",
     "vite": "^8.1.4",