molecule-mcp 0.0.0-stage → 0.3.0

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * CLI entry — connects the molecule MCP server over stdio. The server itself
+ * lives in server.ts so tests can import it without triggering a transport.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { moleculeServer } from './server.js';
+async function main() {
+    await moleculeServer.connect(new StdioServerTransport());
+    process.stderr.write('molecule-mcp ready\n');
+}
+main().catch((e) => {
+    process.stderr.write(`molecule-mcp failed to start: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+});

package/dist/package-doc-files.d.ts

@@ -0,0 +1,15 @@
+import * as fs from 'node:fs';
+import type { DocDeclaration } from './package-doc-search.js';
+/** Bounded declaration reader, also serialized into the sandbox; keep it self-contained. */
+export declare function readDocDeclarations(root: string, io: typeof fs): {
+    declarations: DocDeclaration[];
+    note?: string;
+};
+/** Read declarations beside the exact README selected by the existing doc resolver. */
+export declare function declarationsBesideReadme(readmePath?: string): ReturnType<typeof readDocDeclarations>;
+/** Local MCP resolution follows hoisted node_modules and never selects a different copy's types. */
+export declare function localPackageDoc(name: string, base: string): {
+    readme: string;
+    declarations: DocDeclaration[];
+    note?: string;
+} | null;

package/dist/package-doc-files.js

@@ -0,0 +1,121 @@
+import * as fs from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/** Bounded declaration reader, also serialized into the sandbox; keep it self-contained. */
+export function readDocDeclarations(root, io) {
+    const declarations = [];
+    let remaining = 524_288;
+    let visited = 0;
+    let cut = false;
+    function walk(relative, depth) {
+        if (depth > 12 || visited >= 1_024 || declarations.length >= 128 || remaining <= 0) {
+            cut = true;
+            return;
+        }
+        let entries;
+        try {
+            entries = io.readdirSync(root + '/' + relative, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                cut = true;
+            return;
+        }
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (++visited > 1_024 || declarations.length >= 128 || remaining <= 0) {
+                cut = true;
+                break;
+            }
+            const path = relative + '/' + entry.name;
+            if (entry.isSymbolicLink()) {
+                cut = true;
+                continue;
+            }
+            if (entry.isDirectory()) {
+                walk(path, depth + 1);
+                continue;
+            }
+            if (!entry.isFile() || !path.endsWith('.d.ts'))
+                continue;
+            let fd;
+            try {
+                fd = io.openSync(root + '/' + path, 'r');
+                const actual = io.realpathSync('/proc/self/fd/' + fd);
+                const before = io.fstatSync(fd);
+                if (!actual.startsWith(root + '/') ||
+                    !before.isFile() ||
+                    before.size > Math.min(262_144, remaining)) {
+                    cut = true;
+                    continue;
+                }
+                const bytes = Buffer.alloc(before.size + 1);
+                let length = 0;
+                while (length < bytes.length) {
+                    const n = io.readSync(fd, bytes, length, bytes.length - length, null);
+                    if (!n)
+                        break;
+                    length += n;
+                }
+                const after = io.fstatSync(fd);
+                if (length !== before.size ||
+                    after.size !== before.size ||
+                    after.mtimeMs !== before.mtimeMs) {
+                    cut = true;
+                    continue;
+                }
+                declarations.push({
+                    path,
+                    text: new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length)),
+                });
+                remaining -= length;
+            }
+            catch (_error) {
+                cut = true; // A partial scan must never establish declaration absence.
+            }
+            finally {
+                if (fd !== undefined)
+                    io.closeSync(fd);
+            }
+        }
+    }
+    walk('dist', 0);
+    return {
+        declarations,
+        ...(cut
+            ? {
+                note: 'Declaration scan incomplete (file/byte/depth cap or unreadable/unsafe path); no-hit terms do not establish absence.',
+            }
+            : {}),
+    };
+}
+/** Read declarations beside the exact README selected by the existing doc resolver. */
+export function declarationsBesideReadme(readmePath) {
+    if (!readmePath)
+        return { declarations: [] };
+    return readDocDeclarations(fs.realpathSync(dirname(readmePath)), fs);
+}
+/** Local MCP resolution follows hoisted node_modules and never selects a different copy's types. */
+export function localPackageDoc(name, base) {
+    let dir = resolve(base);
+    for (;;) {
+        const root = resolve(dir, 'node_modules', '@molecule', name);
+        for (const readme of ['README.md', 'dist/README.md']) {
+            try {
+                const realRoot = fs.realpathSync(root);
+                const path = fs.realpathSync(resolve(realRoot, readme));
+                if (!path.startsWith(realRoot + '/'))
+                    continue;
+                const stat = fs.statSync(path);
+                if (!stat.isFile() || stat.size > 1_048_576)
+                    continue;
+                return { readme: fs.readFileSync(path, 'utf8'), ...readDocDeclarations(realRoot, fs) };
+            }
+            catch (_error) {
+                // No installed doc at this node_modules level; continue the normal upward lookup.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/dist/package-doc-search.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+/** Literal, bounded README/type-reference search. Mirrored in molecule-mcp (no shared runtime dependency). */
+/** One installed declaration file; paths are relative to the package root. */
+export interface DocDeclaration {
+    path: string;
+    text: string;
+}
+/** Search output fits beneath the existing doc tool's transport budget. */
+export declare const DOC_SEARCH_TOTAL_CHARS = 24000;
+/** Validate the scalar/array input before opening any package files. */
+export declare function parseDocSearch(value: unknown): string[];
+/** Search README lines (one context line either side) and complete declaration blocks. */
+export declare function searchPackageDoc(readme: string, terms: readonly string[], declarations?: readonly DocDeclaration[], sourceNote?: string): {
+    doc: string;
+    search: readonly string[];
+    truncated?: boolean;
+    note?: string;
+};
+/** The same bounded search input on stdio and hosted MCP. */
+export declare const docSearchSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;

package/dist/package-doc-search.js

@@ -0,0 +1,199 @@
+import { z } from 'zod';
+/** Search output fits beneath the existing doc tool's transport budget. */
+export const DOC_SEARCH_TOTAL_CHARS = 24_000;
+const TERM_CHARS = 6_000;
+const SOURCE_CHARS = 2_600;
+const DECLARATION_CHARS = 1_800;
+/** Validate the scalar/array input before opening any package files. */
+export function parseDocSearch(value) {
+    const terms = typeof value === 'string' ? [value] : value;
+    if (!Array.isArray(terms) ||
+        terms.length < 1 ||
+        terms.length > 6 ||
+        terms.some((term) => typeof term !== 'string' || !term.trim() || term.length > 200))
+        throw new Error('`search` must be one non-empty string or 1–6 non-empty strings (max 200 characters each).');
+    return terms;
+}
+/** Locate top-level declaration starts without treating quoted/commented braces as structure. */
+function declarationRanges(lines) {
+    const masked = lines
+        .join('\n')
+        .replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*|"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`/g, (text) => text.replace(/[^\n]/g, ' '))
+        .split('\n');
+    const starts = [];
+    let depth = 0;
+    for (let i = 0; i < masked.length; i++) {
+        if (depth === 0 &&
+            /^\s*(?:(?:export|declare|default|abstract)\s+)*(?:interface|type|class|function|const|let|var|enum|namespace|module|global|import|export)\b/.test(masked[i])) {
+            // The preceding comment belongs to this declaration, not the previous export.
+            let start = i;
+            while (start > 0 && !masked[start - 1].trim())
+                start--;
+            while (start < i && !lines[start].trim())
+                start++;
+            starts.push(start);
+        }
+        for (const char of masked[i]) {
+            if ('{[('.includes(char))
+                depth++;
+            if ('}])'.includes(char))
+                depth = Math.max(0, depth - 1);
+        }
+    }
+    if (starts[0] !== 0)
+        starts.unshift(0);
+    return starts.map((start, i) => [start, (starts[i + 1] ?? lines.length) - 1]);
+}
+/** Retain the literal hit when a generated signature occupies one very long line. */
+function searchLine(line, needle, cap) {
+    if (line.length <= cap)
+        return line;
+    const match = line.toLowerCase().indexOf(needle);
+    const start = Math.max(0, match - 100);
+    return `${start ? '…' : ''}${line.slice(start, start + cap)}…(line truncated)`;
+}
+/** Search README lines (one context line either side) and complete declaration blocks. */
+export function searchPackageDoc(readme, terms, declarations = [], sourceNote) {
+    let truncated = false;
+    const readmeLines = readme.split(/\r?\n/);
+    const headings = [];
+    let heading = '(introduction)';
+    let fence = '';
+    for (const line of readmeLines) {
+        const marker = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+        if (marker) {
+            if (!fence)
+                fence = marker[1][0];
+            else if (marker[1][0] === fence)
+                fence = '';
+        }
+        const title = !fence && line.match(/^\s{0,3}#{1,6}\s+(.+?)(?:\s+#+)?\s*$/);
+        if (title)
+            heading = title[1];
+        headings.push(heading);
+    }
+    const files = declarations.map((file) => {
+        const lines = file.text.split(/\r?\n/);
+        return { ...file, lines, ranges: declarationRanges(lines) };
+    });
+    const output = [];
+    for (const [termIndex, term] of terms.entries()) {
+        const needle = term.toLowerCase();
+        const readmeHits = [];
+        const declarationHits = [];
+        let readmeCut = false;
+        let declarationCut = false;
+        let readmeSize = 0;
+        let declarationSize = 0;
+        let last = -1;
+        for (let i = 0; i < readmeLines.length; i++) {
+            if (!readmeLines[i].toLowerCase().includes(needle))
+                continue;
+            const start = Math.max(last + 1, i - 1, 0);
+            const end = Math.min(readmeLines.length - 1, i + 1);
+            if (start > end)
+                continue;
+            const hit = `README.md:${i + 1} — section ${JSON.stringify(headings[i])}\n` +
+                readmeLines
+                    .slice(start, end + 1)
+                    .map((line, j) => `${start + j + 1}: ${searchLine(line, needle, start + j === i ? 1_400 : 300)}`)
+                    .join('\n');
+            if (hit.includes('…(line truncated)'))
+                readmeCut = true;
+            if (readmeSize + hit.length > SOURCE_CHARS) {
+                readmeCut = true;
+                break;
+            }
+            readmeHits.push(hit);
+            readmeSize += hit.length;
+            last = end;
+        }
+        for (const file of files) {
+            for (const [start, end] of file.ranges) {
+                let match = start;
+                while (match <= end && !file.lines[match].toLowerCase().includes(needle))
+                    match++;
+                if (match > end)
+                    continue;
+                let text = file.lines
+                    .slice(start, end + 1)
+                    .join('\n')
+                    .trimEnd();
+                let at = start;
+                if (text.length > DECLARATION_CHARS) {
+                    // Keep the matching line visible even inside a very large interface.
+                    at = Math.max(start, match - 1);
+                    const before = at < match ? searchLine(file.lines[at], needle, 200) + '\n' : '';
+                    text = (before +
+                        searchLine(file.lines[match], needle, 1_400) +
+                        '\n' +
+                        file.lines.slice(match + 1, end + 1).join('\n')).slice(0, DECLARATION_CHARS);
+                    text += '\n…(declaration truncated; read this path for the complete declaration)';
+                    declarationCut = true;
+                }
+                const hit = `${file.path}:${at + 1}\n${text}`;
+                if (declarationSize + hit.length > SOURCE_CHARS) {
+                    declarationCut = true;
+                    break;
+                }
+                declarationHits.push(hit);
+                declarationSize += hit.length;
+            }
+        }
+        const chunks = [`### Search: ${JSON.stringify(term)}`, ...readmeHits, ...declarationHits];
+        if (readmeCut)
+            chunks.push('…(README matches truncated by the per-term cap)');
+        if (declarationCut)
+            chunks.push('…(declaration matches truncated by the per-term cap)');
+        if (!readmeHits.length && !declarationHits.length && !readmeCut && !declarationCut)
+            chunks.push('No matches in README.md or dist/**/*.d.ts.');
+        let block = chunks.join('\n\n');
+        if (block.length > TERM_CHARS) {
+            block = block.slice(0, TERM_CHARS - 100) + '\n…(per-term search cap reached)';
+            truncated = true;
+        }
+        const reserve = terms
+            .slice(termIndex + 1)
+            .reduce((size, value) => size + JSON.stringify(value).length + 100, 700);
+        if (output.join('\n\n').length + block.length > DOC_SEARCH_TOTAL_CHARS - reserve) {
+            output.push(`### Search: ${JSON.stringify(term)}\nOmitted — total search cap reached.`);
+            truncated = true;
+        }
+        else {
+            output.push(block);
+            truncated ||= readmeCut || declarationCut;
+        }
+    }
+    const note = [
+        !declarations.length ? 'No installed dist/**/*.d.ts declarations available.' : '',
+        sourceNote?.slice(0, 500),
+    ]
+        .filter(Boolean)
+        .join(' ');
+    if (note)
+        output.push(note);
+    return {
+        doc: output.join('\n\n'),
+        search: terms,
+        ...(truncated ? { truncated: true } : {}),
+        ...(note ? { note } : {}),
+    };
+}
+/** The same bounded search input on stdio and hosted MCP. */
+export const docSearchSchema = z
+    .union([
+    z
+        .string()
+        .min(1)
+        .max(200)
+        .refine((term) => !!term.trim()),
+    z
+        .array(z
+        .string()
+        .min(1)
+        .max(200)
+        .refine((term) => !!term.trim()))
+        .min(1)
+        .max(6),
+])
+    .describe('Case-insensitive literal string or up to 6 terms. Search README lines with context/headings and available installed dist/**/*.d.ts declarations; never implementation JS.');

package/dist/package-search.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The canonical package-search contract shared by `mlcl search` and the hosted
+ * MCP server.
+ *
+ * This module is PURE — registry-shaped data in, ranked hits out: no filesystem,
+ * no registry loader, no oclif/CLI, and no vendor or `@molecule/*` import. That
+ * is what lets the standalone hosted MCP (`mcp/src/package-search.ts`, which
+ * must build from the `mcp/` package alone — its Dockerfile and
+ * `scripts/deploy-remote.sh` ship no CLI or workspace) carry the SAME ranking,
+ * stack filtering and DTO instead of hand-maintaining a second scorer.
+ *
+ * The copy under `mcp/src/` is generated from this file by
+ * `scripts/generate-mcp-package-search.mjs`; `src/lib/__tests__/mcp-search-owner-drift.test.ts`
+ * fails when the two diverge. Edit this file, then regenerate — never the copy.
+ *
+ * Input is the loose registry-entry shape, because the two readers hold
+ * different views of one registry: the CLI adapts `loadRegistry()`'s
+ * `InferredPackage` (flattening its `molecule` metadata), and the hosted server
+ * passes the raw registry entry. Both therefore reach the same scorer.
+ *
+ * @module
+ */
+/**
+ * One package as either registry reader can hand it to the search contract.
+ *
+ * Every metadata field is optional because the hosted side reads an
+ * UNVALIDATED registry document: an entry missing a label, or carrying a
+ * non-array `exports`, must degrade to a score (or no match), never throw
+ * inside the tool handler.
+ */
+export interface SearchSourceEntry {
+    /** Full package name, e.g. `@molecule/api-payments-stripe`. */
+    name: string;
+    /** Declared stack. Absent only in a malformed/legacy registry entry. */
+    stack?: 'api' | 'app';
+    category?: string;
+    label?: string;
+    description?: string;
+    exports?: readonly string[];
+    /**
+     * The UI framework the package is written for (`react`, `vue`, `svelte`, `solid`,
+     * `angular`, `react-native`); absent for a framework-neutral package.
+     */
+    framework?: string;
+    /** Dependencies and peers, as sync-registry records them; {@link packageFramework} reads them. */
+    runtimeDependencies?: readonly string[];
+    intentHints?: readonly string[];
+    /** Optional package-authored decision guidance in the registry. */
+    decisionGuide?: {
+        configuration?: readonly string[];
+    };
+}
+/**
+ * One ranked discovery hit, as both transports return it.
+ *
+ * This is the shared DTO shape: transports add only their own `install`
+ * command, so a consumer reading `label` (or any other field) gets the same
+ * answer over the CLI, stdio MCP and hosted MCP.
+ */
+export interface SearchHit {
+    name: string;
+    stack: 'api' | 'app';
+    category: string;
+    label: string;
+    description: string;
+    /** Concrete common-shape configuration, when this package declares it. */
+    configuration?: string[];
+}
+/** What a caller may narrow before ranking and the limit cutoff. */
+export interface SearchOptions {
+    /**
+     * Restrict to one stack. Applied BEFORE scoring/ranking/truncation, so a
+     * crowded query cannot lose same-stack matches to the limit window being
+     * filled by higher-scoring packages of the other stack.
+     *
+     * Matches the registry's DECLARED `stack` (the rule `loadRegistry(stack)`
+     * applies), not the name-derived display fallback below.
+     */
+    stack?: 'api' | 'app';
+    /**
+     * The project's app framework (its `molecule.framework`). Applied BEFORE
+     * ranking, like `stack`: a package written for a framework the project cannot
+     * import is left out, framework-neutral packages stay. Every framework binding
+     * exports the same hook names (`useProfileForm`, …), so without it a symbol
+     * query returns each framework's package with the same score, and only the
+     * caller knows which one its project can import.
+     */
+    framework?: string;
+    /**
+     * The registry's `appFrameworks`, which say which package frameworks a project
+     * framework can import ({@link frameworksAcceptedBy}). Without them only
+     * packages declaring exactly `framework` are kept.
+     */
+    appFrameworks?: Record<string, AppFrameworkInstalls>;
+    /** Maximum number of hits. */
+    limit?: number;
+}
+/** What a registry `appFrameworks` entry says about the projects it scaffolds. */
+export interface AppFrameworkInstalls {
+    /** The UI package set its projects render with, when it is another framework's (react-native-web → react-native). */
+    uiFramework?: string;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+}
+/**
+ * The package frameworks a project of one app framework can import.
+ *
+ * Its own, the UI set it renders with (`uiFramework`), and every framework whose
+ * identifying runtime the project installs in full. A framework is identified by
+ * its `dependencies`, or by its `devDependencies` when it has none (the rule
+ * `getAppFrameworkDeps` reads). A framework that renders with another
+ * framework's UI set is identified by that set, so its packages are never
+ * accepted by runtime alone. So a react-native-web project (react, react-dom,
+ * react-router) imports React packages, a react-native one (no react-dom) does
+ * not, and a React project does not import react-native-web packages.
+ *
+ * @param project - The project's framework key (`molecule.framework`).
+ * @param appFrameworks - The registry's `appFrameworks`.
+ * @returns The accepted package frameworks, the project's own first; just the
+ *   project's key when the registry does not know it.
+ */
+export declare function frameworksAcceptedBy(project: string, appFrameworks: Record<string, AppFrameworkInstalls>): string[];
+/**
+ * The framework a package is written for: its registry `framework`, else the one
+ * its `runtimeDependencies` (dependencies and peers, as sync-registry records
+ * them) name.
+ *
+ * A dependency names a framework when it identifies a runtime framework (react,
+ * react-dom, vue, solid-js, svelte, …). The package is written for the framework
+ * with the fewest identifying dependencies that still has every one the package
+ * names: `react` alone is react, `react` with `react-native` is react-native.
+ * The registry `framework` covers a package whose dependencies name none, like a
+ * bond over `@react-native-clipboard/clipboard`.
+ *
+ * @param entry - The package's registry entry.
+ * @param appFrameworks - The registry's `appFrameworks`.
+ * @returns The framework key, or undefined for a framework-neutral package (and for
+ *   dependencies two frameworks fit equally, which the registry tests refuse).
+ */
+export declare function packageFramework(entry: {
+    stack?: unknown;
+    framework?: unknown;
+    runtimeDependencies?: unknown;
+}, appFrameworks: Record<string, AppFrameworkInstalls>): string | undefined;
+/** Result count both `mlcl search` and `search_packages` use when none is given. */
+export declare const DEFAULT_SEARCH_LIMIT = 20;
+/**
+ * Score a package against the query tokens. Higher = more relevant.
+ * Exact names, exported symbols and complete capability phrases outrank
+ * incidental name substrings ("form" in "formula"). The existing token scores
+ * remain useful for partial package names and broad category/provider queries.
+ *
+ * @param entry - A registry-shaped package.
+ * @param q - Package name, exported symbol or natural capability query.
+ * @returns Relevance score; zero means no match.
+ */
+export declare function scoreSearchEntry(entry: SearchSourceEntry, q: string): number;
+/**
+ * Rank a registry into the shared discovery DTO.
+ *
+ * The stack filter is applied to the SOURCE entries first — before any scoring,
+ * sorting or truncation — because the limit window is otherwise claimed by the
+ * highest-scoring packages of BOTH stacks and a stack-restricted caller can be
+ * left with none of its own.
+ *
+ * @param entries - Registry-shaped packages, from either reader.
+ * @param query - Package name, exported symbol or natural capability query.
+ * @param options - Optional stack and framework restrictions and result limit.
+ * @returns Ranked hits (score stripped), at most `limit` of them.
+ */
+export declare function searchPackages(entries: Iterable<SearchSourceEntry>, query: string, options?: SearchOptions): SearchHit[];