molecule-mcp 0.2.0 → 0.3.0

package/dist/package-search.js

@@ -0,0 +1,241 @@
+// GENERATED FILE — DO NOT EDIT.
+//
+// Byte-for-byte copy of `mlcl/src/lib/package-search.ts` (the canonical search
+// owner shared with `mlcl search` and the stdio MCP), made standalone so this
+// package keeps its own build/deploy closure: mcp/Dockerfile builds `mcp/`
+// alone and mcp/scripts/deploy-remote.sh ships only this package, so this file
+// must not import the CLI, oclif, node:fs or any @molecule/* package.
+//
+// Regenerate after ANY edit to the owner:
+//   node scripts/generate-mcp-package-search.mjs
+// Drift fails src/lib/__tests__/mcp-search-owner-drift.test.ts.
+/**
+ * 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 function frameworksAcceptedBy(project, appFrameworks) {
+    const own = appFrameworks[project];
+    // The hosted reader passes an unvalidated registry document.
+    if (!own || typeof own !== 'object')
+        return [project];
+    const installed = new Set([
+        ...Object.keys(own.dependencies ?? {}),
+        ...Object.keys(own.devDependencies ?? {}),
+    ]);
+    const accepted = [project];
+    if (own.uiFramework && own.uiFramework !== project)
+        accepted.push(own.uiFramework);
+    for (const [key, identifying] of runtimeFrameworks(appFrameworks)) {
+        if (accepted.includes(key))
+            continue;
+        if ([...identifying].every((dep) => installed.has(dep)))
+            accepted.push(key);
+    }
+    return accepted;
+}
+/**
+ * The frameworks that are a runtime of their own, each with the dependencies that
+ * identify it: its `dependencies`, or its `devDependencies` when it has none (the
+ * rule `getAppFrameworkDeps` reads). A framework that renders with another
+ * framework's UI set (react-native-web) is not one: it is identified by that set.
+ *
+ * @param appFrameworks - The registry's `appFrameworks` (unvalidated on the hosted side).
+ * @returns Framework key → identifying dependency names, frameworks with none left out.
+ */
+function runtimeFrameworks(appFrameworks) {
+    const runtimes = [];
+    for (const [key, fw] of Object.entries(appFrameworks)) {
+        if (!fw || typeof fw !== 'object')
+            continue;
+        if (fw.uiFramework && fw.uiFramework !== key)
+            continue;
+        const runtime = Object.keys(fw.dependencies ?? {});
+        const identifying = runtime.length > 0 ? runtime : Object.keys(fw.devDependencies ?? {});
+        if (identifying.length > 0)
+            runtimes.push([key, new Set(identifying)]);
+    }
+    return runtimes;
+}
+/**
+ * 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 function packageFramework(entry, appFrameworks) {
+    if (typeof entry.framework === 'string' && entry.framework)
+        return entry.framework;
+    // UI frameworks are the app stack's: an API package that peers react (to render an
+    // email, say) is not a React binding.
+    if (entry.stack === 'api' || !Array.isArray(entry.runtimeDependencies))
+        return undefined;
+    const runtimes = runtimeFrameworks(appFrameworks);
+    const named = entry.runtimeDependencies.filter((dep) => typeof dep === 'string' && runtimes.some(([, identifying]) => identifying.has(dep)));
+    if (named.length === 0)
+        return undefined;
+    const fits = runtimes
+        .filter(([, identifying]) => named.every((dep) => identifying.has(dep)))
+        .sort((a, b) => a[1].size - b[1].size);
+    if (fits.length === 0 || (fits.length > 1 && fits[1][1].size === fits[0][1].size))
+        return undefined;
+    return fits[0][0];
+}
+/** Result count both `mlcl search` and `search_packages` use when none is given. */
+export const DEFAULT_SEARCH_LIMIT = 20;
+/**
+ * The stack a hit reports. A declared stack wins; a legacy/malformed entry
+ * falls back to the package-name convention (the same rule both readers used
+ * before the contract was shared).
+ *
+ * @param entry - A registry-shaped package.
+ * @returns The stack to report on the hit.
+ */
+function resolveStack(entry) {
+    return entry.stack ?? (entry.name.includes('/app-') ? 'app' : 'api');
+}
+/**
+ * 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 function scoreSearchEntry(entry, q) {
+    const name = entry.name.replace('@molecule/', '');
+    const tokens = q.toLowerCase().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return 0;
+    let score = 0;
+    const phrase = (value) => value
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .trim();
+    const query = phrase(q);
+    const symbolQuery = q.trim().replace(/\(\)$/, '').toLowerCase();
+    // The hosted server scores an unvalidated document, so `exports` may not be
+    // the string[] the registry contract says: treat anything else as no export
+    // list rather than throwing inside the tool handler.
+    const exportsList = Array.isArray(entry.exports) ? entry.exports : [];
+    const exactSymbol = /^[\p{L}_$][\p{L}\p{N}_$]*$/u.test(symbolQuery) &&
+        exportsList.some((symbol) => typeof symbol === 'string' && symbol.toLowerCase() === symbolQuery);
+    if (!query && !exactSymbol)
+        return 0;
+    const containsPhrase = (text, candidate) => ` ${text} `.includes(` ${candidate} `);
+    const hints = (entry.intentHints ?? []).map(phrase);
+    if (q.trim().toLowerCase() === entry.name.toLowerCase() ||
+        q.trim().toLowerCase() === name.toLowerCase()) {
+        score += 400;
+    }
+    // Match the WHOLE symbol, never its prefix/substring; e.g. "use" must not
+    // match every hook, and "useProfileFormState" must not match useProfileForm.
+    if (exactSymbol)
+        score += 160;
+    // A short query can name both a category and a common export (e.g. query).
+    // Keep that category and its providers ahead of unrelated symbol owners.
+    if (entry.category && phrase(entry.category) === query)
+        score += 160;
+    if (query.includes(' ')) {
+        if (hints.includes(query))
+            score += 120;
+        else if (hints.some((hint) => hint.includes(' ') && (containsPhrase(query, hint) || containsPhrase(hint, query))))
+            score += 80;
+        else if ([name, entry.category, entry.label, entry.description].some((field) => field && containsPhrase(phrase(field), query)))
+            score += 60;
+    }
+    for (const tok of tokens) {
+        if (name === tok)
+            score += 40;
+        else if (name.includes(tok))
+            score += 20;
+        if (entry.category?.includes(tok))
+            score += 8;
+        if (entry.intentHints?.some((h) => h.includes(tok) || tok.includes(h)))
+            score += 6;
+        if (entry.description?.toLowerCase().includes(tok))
+            score += 3;
+        if (entry.label?.toLowerCase().includes(tok))
+            score += 3;
+    }
+    return score;
+}
+/**
+ * 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 function searchPackages(entries, query, options = {}) {
+    const { stack, framework, appFrameworks, limit = DEFAULT_SEARCH_LIMIT } = options;
+    const accepted = framework
+        ? new Set(appFrameworks ? frameworksAcceptedBy(framework, appFrameworks) : [framework])
+        : null;
+    const ranked = [];
+    for (const entry of entries) {
+        // The rule `loadRegistry(stack)` applies — declared stack equality — kept
+        // here so the transport that has no loader (hosted MCP) filters identically.
+        if (stack && entry.stack !== stack)
+            continue;
+        if (accepted) {
+            const written = appFrameworks
+                ? packageFramework(entry, appFrameworks)
+                : typeof entry.framework === 'string'
+                    ? entry.framework
+                    : undefined;
+            if (written && !accepted.has(written))
+                continue;
+        }
+        const score = scoreSearchEntry(entry, query);
+        if (score <= 0)
+            continue;
+        const configuration = Array.isArray(entry.decisionGuide?.configuration)
+            ? entry.decisionGuide.configuration.filter((line) => typeof line === 'string' && line.length > 0)
+            : [];
+        ranked.push({
+            name: entry.name,
+            stack: resolveStack(entry),
+            category: entry.category ?? '',
+            label: entry.label ?? entry.name,
+            description: entry.description ?? '',
+            ...(configuration.length > 0 ? { configuration } : {}),
+            score,
+        });
+    }
+    return ranked
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .slice(0, limit)
+        .map(({ score: _score, ...hit }) => hit);
+}

package/dist/remote.js

@@ -16,6 +16,9 @@
 import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
+import { localPackageDoc } from './package-doc-files.js';
+import { docSearchSchema, searchPackageDoc } from './package-doc-search.js';
+import { searchPackages, } from './package-search.js';
 import { serverVersion, tracked } from './telemetry.js';
 const REGISTRY_URL = process.env.MOLECULE_REGISTRY_URL ??
     'https://raw.githubusercontent.com/molecule-dev/mlcl/main/registry.json';
@@ -335,29 +338,12 @@ async function fetchJsonUncached(url, file, timeoutMs, check, generation) {
     cache.set(key, { at: Date.now(), data });
     return data;
 }
-/** Same scoring shape as `mlcl search` — name match dominates, intent/category tokens follow. */
-function scoreEntry(name, entry, q) {
-    const short = name.replace('@molecule/', '');
-    const tokens = q.toLowerCase().split(/\s+/).filter(Boolean);
-    if (tokens.length === 0)
-        return 0;
-    let score = 0;
-    for (const tok of tokens) {
-        if (short === tok)
-            score += 40;
-        else if (short.includes(tok))
-            score += 20;
-        if (entry.category?.includes(tok))
-            score += 8;
-        if (entry.intentHints?.some((h) => h.includes(tok) || tok.includes(h)))
-            score += 6;
-        if (entry.description?.toLowerCase().includes(tok))
-            score += 3;
-        if (entry.label?.toLowerCase().includes(tok))
-            score += 3;
-    }
-    return score;
-}
+// Ranking, stack filtering and the result DTO live in `./package-search.js` — a
+// GENERATED verbatim copy of the canonical owner
+// (`mlcl/src/lib/package-search.ts`) shared with `mlcl search` and the stdio
+// MCP. The copy is what keeps this server buildable from the `mcp/` package
+// alone (mcp/Dockerfile + scripts/deploy-remote.sh ship no CLI); a drift test
+// fails if the copy and the owner diverge.
 const text = (t) => ({
     content: [{ type: 'text', text: t }],
 });
@@ -368,37 +354,44 @@ export function buildRemoteServer() {
     const server = new McpServer({ name: 'molecule-remote', version: serverVersion() });
     server.registerTool('search_packages', {
         title: 'Search @molecule packages',
-        description: 'Search the @molecule/* package fleet by name or capability (e.g. "payments", "social login"). Returns matching packages with stack, category, and install command. Prefer an existing package over hand-rolling any capability.',
+        description: 'Search the @molecule/* package fleet by name or capability (e.g. "payments", "social login"). Returns matching packages with stack, category, label, description, common-shape configuration when declared, and the install command; `stack` restricts results to one stack and `framework` to one UI framework (plus framework-neutral packages). Prefer an existing package over hand-rolling any capability and read its doc before rejecting it.',
         inputSchema: {
-            // Bounded: `scoreEntry` splits the query on whitespace and runs one
-            // pass over EVERY fleet package (~900) for each token, so the work one
+            // Bounded: the scorer splits the query on whitespace and runs one pass
+            // over EVERY fleet package (~900) for each token, so the work one
             // request costs is (tokens × packages). With no cap, an 800 KB body of
             // whitespace-separated words (a few hundred thousand tokens, well under
             // the 1 MB body limit) pinned a core of this public, single-threaded
             // server for minutes — a per-address rate budget does not bound the
             // work a single allowed request may do. A capability query is a phrase.
             query: z.string().max(200).describe('Capability or package-name query'),
+            // Same contract as the stdio server and `mlcl search --stack`, and
+            // applied by the shared owner BEFORE ranking/truncation: an api-only
+            // caller on a crowded query must not lose its matches to app packages
+            // filling the limit window.
+            stack: z.enum(['api', 'app']).optional().describe('Restrict results to one stack'),
+            // A registry appFrameworks key, checked against the fetched registry so a
+            // framework the registry adds needs no change here.
+            framework: z
+                .string()
+                .regex(/^[a-z][a-z0-9-]*$/)
+                .max(40)
+                .optional()
+                .describe("The project's app framework, as its package.json molecule.framework names it (react, vue, svelte, solid, angular, react-native, react-native-web): leaves out packages that framework cannot import (every framework binding exports the same hook names)"),
             limit: z.number().int().min(1).max(100).optional(),
         },
-    }, tracked('search_packages', async ({ query, limit }) => {
+    }, tracked('search_packages', async ({ query, stack, framework, limit }) => {
         // `isRegistryPayload` is the gate the type below cannot provide on its
         // own: without it a body carrying no `packages` map reached
         // `Object.entries(undefined)` and the client was told "Cannot convert
         // undefined or null to object" instead of what went wrong upstream.
         const registry = await fetchJson(REGISTRY_URL, REGISTRY_FILE, FETCH_TIMEOUT_MS, isRegistryPayload);
         const packages = registry.packages;
-        const hits = Object.entries(packages)
-            .map(([name, entry]) => ({
-            name,
-            stack: entry.stack ?? (name.includes('/app-') ? 'app' : 'api'),
-            category: entry.category ?? '',
-            description: entry.description ?? '',
-            score: scoreEntry(name, entry, query),
-        }))
-            .filter((h) => h.score > 0)
-            .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
-            .slice(0, limit ?? 20)
-            .map(({ score: _score, ...hit }) => ({
+        const appFrameworks = isRecord(registry.appFrameworks)
+            ? registry.appFrameworks
+            : {};
+        if (framework && !appFrameworks[framework])
+            throw new Error(`Unknown framework "${framework}". Known: ${Object.keys(appFrameworks).join(', ')}`);
+        const hits = searchPackages(Object.entries(packages).map(([name, entry]) => ({ ...entry, name })), query, { stack, framework, appFrameworks, limit }).map((hit) => ({
             ...hit,
             install: `npx mlcl add ${hit.name} --inject`,
         }));
@@ -428,7 +421,7 @@ export function buildRemoteServer() {
     }));
     server.registerTool('read_package_doc', {
         title: 'Read a package README',
-        description: "Fetch a @molecule/* package's generated usage reference (API, examples, wiring) — the authoritative published doc.",
+        description: "Fetch a @molecule/* package's generated usage reference (API, examples, wiring) — the authoritative published doc. For “where is X”, use search before grepping package internals: literal README lines with headings, then any locally installed type declarations.",
         inputSchema: {
             // Bounded, like the sibling `search_packages` query: this is a public,
             // unauthenticated server, and the name is interpolated into the outbound
@@ -436,8 +429,9 @@ export function buildRemoteServer() {
             // sized by the caller, up to the HTTP body cap, at the per-address
             // budget's full rate. A package short name is under 100 characters.
             name: z.string().max(200).describe('Package name, with or without the @molecule/ scope'),
+            search: docSearchSchema.optional(),
         },
-    }, tracked('read_package_doc', async ({ name }) => {
+    }, tracked('read_package_doc', async ({ name, search }) => {
         const short = name.replace(/^@molecule\//, '');
         // The same package-name shape the stdio server's path guard enforces (see
         // mcp/src/server.ts): a name is a single descending segment, so it cannot
@@ -446,9 +440,15 @@ export function buildRemoteServer() {
         if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(short)) {
             return text(`Invalid package name "${short}" — expected @molecule/<name>.`);
         }
+        const terms = typeof search === 'string' ? [search] : search;
+        const local = terms ? localPackageDoc(short, import.meta.dirname) : null;
+        if (local && terms)
+            return text(searchPackageDoc(local.readme, terms, local.declarations, local.note).doc);
         try {
             const doc = await fetchPackageReadme(short);
             if (doc) {
+                if (terms)
+                    return text(searchPackageDoc(doc, terms, [], 'Published README; declaration files are unavailable on this host.').doc);
                 if (doc.length > 100_000)
                     return text(`${doc.slice(0, 100_000)}\n\n[…truncated — full doc: https://www.molecule.dev/packages/${short}]`);
                 return text(doc);

package/dist/scaffold-args.d.ts

@@ -0,0 +1,12 @@
+/** Arguments accepted by the MCP scaffold_project tool. */
+export interface ScaffoldProjectOptions {
+    name: string;
+    template?: string;
+    type?: string;
+    framework?: string;
+    packages?: string;
+    api_contract?: string;
+    skip_install?: boolean;
+}
+/** Build the real CLI call; auth derivation stays in mlcl's shared scaffold. */
+export declare function scaffoldProjectCliArgs(options: ScaffoldProjectOptions): string[];

package/dist/scaffold-args.js

@@ -0,0 +1,17 @@
+/** Build the real CLI call; auth derivation stays in mlcl's shared scaffold. */
+export function scaffoldProjectCliArgs(options) {
+    const args = ['create', options.name, '--no-interactive', '--json'];
+    if (options.template)
+        args.push('--template', options.template);
+    if (options.type)
+        args.push('--type', options.type);
+    if (options.framework)
+        args.push('--framework', options.framework);
+    if (options.packages)
+        args.push('--packages', options.packages);
+    if (options.api_contract)
+        args.push('--api-contract', options.api_contract);
+    if (options.skip_install)
+        args.push('--skip-install');
+    return args;
+}