fluidcad 0.0.32 → 0.0.34

package/mcp/dist/docs-index.js

@@ -0,0 +1,261 @@
+// In-memory index over `llm-docs/`.
+//
+// Loaded once at MCP startup. Resolves the on-disk docs root (either the
+// published `node_modules/fluidcad/llm-docs/` or the in-repo `<root>/llm-docs/`
+// during dev), reads the two manifests written by `scripts/build-llm-docs.ts`,
+// and builds an inverted index for `search_docs`.
+//
+// Bodies are loaded lazily on first read and cached. The seed set is small
+// (single-digit MB at most) so we don't bother with any external search dep
+// or LRU bookkeeping — a Map is plenty.
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+const FIELD_WEIGHT = {
+    title: 5,
+    summary: 3,
+    tags: 4,
+    body: 1,
+};
+// Small fixed stopword set. Kept tiny on purpose — the corpus is small and we
+// want exact lookups like "z" or "ts" to still work for users.
+const STOPWORDS = new Set([
+    'a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'for', 'from', 'has',
+    'have', 'in', 'into', 'is', 'it', 'its', 'of', 'on', 'or', 'that', 'the', 'to',
+    'was', 'were', 'will', 'with',
+]);
+export class DocsIndex {
+    /** Absolute path to the docs root directory. */
+    root;
+    /** Every doc record, in the order they were emitted by the build script. */
+    docs;
+    /** Symbol -> docId (from `llm-docs/api/index.json`). */
+    symbols;
+    /**
+     * Type-name -> docId, restricted to docs under `api/types/`. Populated by
+     * filtering `symbols` so the same symbol map drives both `get_api_signature`
+     * and `get_type_definition`, but the latter rejects function symbols with a
+     * clear "not a type" error rather than returning a feature signature.
+     */
+    types;
+    byId;
+    bodyCache = new Map();
+    /** token -> docId -> per-field hit counts. */
+    inverted;
+    constructor(root, index, apiIndex) {
+        this.root = root;
+        this.docs = index.docs;
+        this.symbols = apiIndex.symbols;
+        this.types = Object.fromEntries(Object.entries(apiIndex.symbols).filter(([, docId]) => docId.startsWith('api/types/')));
+        this.byId = new Map(index.docs.map((d) => [d.id, d]));
+        this.inverted = this.buildInverted();
+    }
+    /** All docs, optionally filtered to those carrying a given tag. */
+    list(tag) {
+        if (!tag) {
+            return [...this.docs];
+        }
+        return this.docs.filter((d) => (d.tags ?? []).includes(tag));
+    }
+    get(id) {
+        return this.byId.get(id) ?? null;
+    }
+    /**
+     * Load the markdown body for a doc id, stripping the YAML frontmatter so
+     * callers see the same text the docs author wrote (no metadata clutter).
+     */
+    body(id) {
+        const cached = this.bodyCache.get(id);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const doc = this.byId.get(id);
+        if (!doc) {
+            return null;
+        }
+        const raw = fs.readFileSync(path.join(this.root, doc.file), 'utf8');
+        const body = stripFrontmatter(raw);
+        this.bodyCache.set(id, body);
+        return body;
+    }
+    /** Keyword search. Returns ranked hits with an ~80-char snippet per result. */
+    search(query, limit = 10) {
+        const tokens = tokenize(query);
+        if (tokens.length === 0) {
+            return [];
+        }
+        const scores = new Map();
+        for (const token of tokens) {
+            const postings = this.inverted.get(token);
+            if (!postings) {
+                continue;
+            }
+            for (const [docId, hits] of postings) {
+                let local = 0;
+                local += hits.title * FIELD_WEIGHT.title;
+                local += hits.summary * FIELD_WEIGHT.summary;
+                local += hits.tags * FIELD_WEIGHT.tags;
+                local += hits.body * FIELD_WEIGHT.body;
+                scores.set(docId, (scores.get(docId) ?? 0) + local);
+            }
+        }
+        // Exact-symbol boost — agents often type the bare function name.
+        for (const token of tokens) {
+            const docId = this.symbols[token];
+            if (docId) {
+                scores.set(docId, (scores.get(docId) ?? 0) + 10);
+            }
+        }
+        const ranked = [...scores.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, limit);
+        return ranked.map(([docId, score]) => {
+            const doc = this.byId.get(docId);
+            return {
+                id: doc.id,
+                title: doc.title,
+                snippet: this.snippet(doc.id, tokens),
+                score,
+            };
+        });
+    }
+    /** First fenced code block in the body, used as a symbol's signature surface. */
+    firstCodeBlock(id) {
+        const body = this.body(id);
+        if (!body) {
+            return null;
+        }
+        const match = body.match(/```[a-zA-Z0-9_-]*\n([\s\S]*?)```/);
+        return match ? match[1].trimEnd() : null;
+    }
+    buildInverted() {
+        const inverted = new Map();
+        const add = (token, docId, field) => {
+            let perDoc = inverted.get(token);
+            if (!perDoc) {
+                perDoc = new Map();
+                inverted.set(token, perDoc);
+            }
+            let hits = perDoc.get(docId);
+            if (!hits) {
+                hits = { title: 0, summary: 0, tags: 0, body: 0 };
+                perDoc.set(docId, hits);
+            }
+            hits[field] += 1;
+        };
+        for (const doc of this.docs) {
+            for (const t of tokenize(doc.title)) {
+                add(t, doc.id, 'title');
+            }
+            for (const t of tokenize(doc.summary)) {
+                add(t, doc.id, 'summary');
+            }
+            for (const tag of doc.tags ?? []) {
+                for (const t of tokenize(tag)) {
+                    add(t, doc.id, 'tags');
+                }
+            }
+            const body = this.body(doc.id);
+            if (body) {
+                for (const t of tokenize(body)) {
+                    add(t, doc.id, 'body');
+                }
+            }
+        }
+        return inverted;
+    }
+    snippet(docId, tokens) {
+        const body = this.body(docId);
+        if (!body) {
+            return '';
+        }
+        const lower = body.toLowerCase();
+        let bestIdx = -1;
+        for (const token of tokens) {
+            const i = lower.indexOf(token);
+            if (i !== -1 && (bestIdx === -1 || i < bestIdx)) {
+                bestIdx = i;
+            }
+        }
+        if (bestIdx === -1) {
+            return body.slice(0, 160).replace(/\s+/g, ' ').trim();
+        }
+        const start = Math.max(0, bestIdx - 40);
+        const end = Math.min(body.length, bestIdx + 120);
+        const prefix = start > 0 ? '…' : '';
+        const suffix = end < body.length ? '…' : '';
+        return prefix + body.slice(start, end).replace(/\s+/g, ' ').trim() + suffix;
+    }
+}
+/**
+ * Locate the on-disk `llm-docs/` directory.
+ *
+ * Resolution order:
+ *   1. The installed package — `require.resolve('fluidcad/package.json')` gives
+ *      us the consumer's `node_modules/fluidcad/`, and `llm-docs/` sits next to
+ *      that `package.json`.
+ *   2. The in-repo path — walk up from this file (`mcp/src/` or `mcp/dist/`)
+ *      until we hit a sibling `llm-docs/` directory.
+ *
+ * We never trust `process.cwd()`: the MCP process is launched by an external
+ * client (Claude Desktop, etc.) so its CWD is whatever they happen to be in.
+ */
+export function resolveDocsRoot() {
+    const here = fileURLToPath(import.meta.url);
+    const require_ = createRequire(here);
+    try {
+        const pkg = require_.resolve('fluidcad/package.json');
+        const candidate = path.join(path.dirname(pkg), 'llm-docs');
+        if (fs.existsSync(path.join(candidate, 'index.json'))) {
+            return candidate;
+        }
+    }
+    catch {
+        // Falls through to the dev-walkup path below.
+    }
+    let dir = path.dirname(here);
+    for (let i = 0; i < 8; i++) {
+        const candidate = path.join(dir, 'llm-docs');
+        if (fs.existsSync(path.join(candidate, 'index.json'))) {
+            return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    throw new Error(`Could not locate llm-docs/ from ${here}. ` +
+        `Run \`npm run build:llm-docs\` to generate the manifest, ` +
+        `or ensure the package is installed.`);
+}
+/**
+ * Load the manifests from `<root>/index.json` and `<root>/api/index.json` and
+ * construct the in-memory index. Throws (with a helpful message) if either
+ * manifest is missing — that almost always means `build:llm-docs` was skipped.
+ */
+export function loadDocsIndex(root) {
+    const resolved = root ?? resolveDocsRoot();
+    const indexPath = path.join(resolved, 'index.json');
+    const apiIndexPath = path.join(resolved, 'api', 'index.json');
+    if (!fs.existsSync(indexPath)) {
+        throw new Error(`llm-docs manifest missing at ${indexPath}. Run \`npm run build:llm-docs\`.`);
+    }
+    if (!fs.existsSync(apiIndexPath)) {
+        throw new Error(`llm-docs api manifest missing at ${apiIndexPath}. Run \`npm run build:llm-docs\`.`);
+    }
+    const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    const apiIndex = JSON.parse(fs.readFileSync(apiIndexPath, 'utf8'));
+    return new DocsIndex(resolved, index, apiIndex);
+}
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/)
+        .filter((t) => t.length > 0 && !STOPWORDS.has(t));
+}
+function stripFrontmatter(raw) {
+    const match = raw.match(/^---\n[\s\S]*?\n---\n?([\s\S]*)$/);
+    return match ? match[1] : raw;
+}

package/mcp/dist/resources.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { DocsIndex } from './docs-index.ts';
+export declare const URI_OVERVIEW = "fluidcad-docs://overview";
+export declare function registerDocResources(server: McpServer, index: DocsIndex): void;

package/mcp/dist/resources.js

@@ -0,0 +1,115 @@
+// MCP resource registrations for `fluidcad-docs://*`.
+//
+// Resources are a bonus surface — clients that auto-attach them (e.g. Claude
+// Desktop) get the docs for free without burning tool calls. Clients that
+// ignore resources fall back to the `list_docs` / `read_doc` tools, so the
+// two surfaces are designed to be self-sufficient.
+//
+// Every resource is registered statically. The seed set is small (under a
+// dozen entries) so we trade the template machinery for a simple per-doc
+// `registerResource` call — the resulting list shows up explicitly in the
+// MCP client's resource picker.
+export const URI_OVERVIEW = 'fluidcad-docs://overview';
+export function registerDocResources(server, index) {
+    server.registerResource('fluidcad-docs-overview', URI_OVERVIEW, {
+        title: 'FluidCAD docs — overview',
+        description: 'Single-document aggregate of the FluidCAD doc set: titles, summaries, and tags for every API symbol and concept.',
+        mimeType: 'text/markdown',
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: renderOverview(index),
+            },
+        ],
+    }));
+    // One static resource per API symbol. We use the symbol map (not the doc
+    // list) so a single doc that documents multiple symbols still appears under
+    // each. The doc body is identical across symbol resources — that's fine,
+    // clients dedupe by content.
+    for (const [symbol, docId] of Object.entries(index.symbols)) {
+        const doc = index.get(docId);
+        if (!doc) {
+            continue;
+        }
+        server.registerResource(`fluidcad-docs-api-${symbol}`, `fluidcad-docs://api/${symbol}`, {
+            title: doc.title,
+            description: doc.summary,
+            mimeType: 'text/markdown',
+        }, async (uri) => ({
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'text/markdown',
+                    text: index.body(doc.id) ?? '',
+                },
+            ],
+        }));
+    }
+    // One static resource per non-API doc, exposed as `guide/<slug>`. Slug is
+    // the doc id stripped of any leading category prefix (e.g.
+    // `concepts/scene-graph` → `scene-graph`). If two ids collide on slug, we
+    // keep the first and skip the rest — collisions are flagged here rather
+    // than during manifest validation since slug uniqueness is a resource-layer
+    // concern, not a doc-content concern.
+    const seenSlugs = new Set();
+    for (const doc of index.docs) {
+        if (isApiDoc(doc)) {
+            continue;
+        }
+        const slug = guideSlug(doc.id);
+        if (seenSlugs.has(slug)) {
+            continue;
+        }
+        seenSlugs.add(slug);
+        server.registerResource(`fluidcad-docs-guide-${slug}`, `fluidcad-docs://guide/${slug}`, {
+            title: doc.title,
+            description: doc.summary,
+            mimeType: 'text/markdown',
+        }, async (uri) => ({
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'text/markdown',
+                    text: index.body(doc.id) ?? '',
+                },
+            ],
+        }));
+    }
+}
+function isApiDoc(doc) {
+    return doc.id.startsWith('api/');
+}
+function guideSlug(id) {
+    const slash = id.indexOf('/');
+    return slash === -1 ? id : id.slice(slash + 1);
+}
+function renderOverview(index) {
+    const lines = [];
+    lines.push('# FluidCAD docs');
+    lines.push('');
+    lines.push('Generated from `llm-docs/`. Each entry lists a doc id, its title, and a one-line summary.');
+    lines.push('');
+    const apiDocs = index.docs.filter(isApiDoc);
+    const otherDocs = index.docs.filter((d) => !isApiDoc(d));
+    if (apiDocs.length > 0) {
+        lines.push('## API');
+        lines.push('');
+        for (const doc of apiDocs) {
+            lines.push(`- **${doc.id}** — ${doc.title}`);
+            lines.push(`  ${doc.summary}`);
+        }
+        lines.push('');
+    }
+    if (otherDocs.length > 0) {
+        lines.push('## Concepts and guides');
+        lines.push('');
+        for (const doc of otherDocs) {
+            lines.push(`- **${doc.id}** — ${doc.title}`);
+            lines.push(`  ${doc.summary}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}

package/mcp/dist/server.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { type DocsIndex } from './docs-index.ts';
+export declare const SERVER_NAME = "FluidCAD";
+export declare const SERVER_VERSION: string;
+export type BuildServerOptions = {
+    /** Pre-built docs index. Tests use this to inject a custom docs root. */
+    docsIndex?: DocsIndex;
+};
+export declare function buildServer(options?: BuildServerOptions): McpServer;
+export declare function runStdio(): Promise<void>;
+export { z };