molecule-mcp 0.2.0 → 0.3.0

package/dist/services.d.ts

@@ -4,9 +4,21 @@ export interface ServiceKey {
     source: string;
 }
 /**
- * The project API key for service calls: MOLECULE_API_KEY from the server's
- * environment, else `MOLECULE_API_KEY` in `.env` at `directory` or up to two
- * parents (a full-stack project keeps it in `api/.env` or the root).
+ * The project API key for service calls, resolved in this documented order:
+ *
+ *   1. `MOLECULE_API_KEY` in this server's environment (always wins);
+ *   2. `.env`, then every `.env.<variant>` (byte-sorted), in `directory` —
+ *      then the same set in `directory/api`;
+ *   3. the same two locations in each parent, up to two parents.
+ *
+ * Inside one file, Node's dotenv rules apply: the LAST assignment wins, and
+ * inline comments / quoting are honoured. A file that does not define a
+ * non-blank MOLECULE_API_KEY is skipped, and placeholder variants
+ * (`.env.example`, `.env.schema`, …) are never read. Because `create_api_key`
+ * writes only these names through the same predicate, a key it writes at
+ * `<dir>/.env[.<variant>]` or `<dir>/api/.env[.<variant>]` is found by a later
+ * service call whose `directory` is that project directory (or up to two
+ * levels below it).
  *
  * @param directory - Project directory to search (default cwd).
  * @returns The key and where it came from, or null.
@@ -48,8 +60,14 @@ export interface CreatedKey {
 }
 /**
  * Mint a project API key and write it into a dotenv file as
- * MOLECULE_API_KEY, replacing an existing line. The plaintext is returned by
- * the platform exactly once and is never echoed back to the agent.
+ * MOLECULE_API_KEY, replacing an existing assignment and dropping duplicate
+ * ones. The plaintext is returned by the platform exactly once and is never
+ * echoed back to the agent.
+ *
+ * The destination is validated BEFORE the platform is asked to mint anything,
+ * and only names `resolveServiceKey` reads are accepted (`.env` or
+ * `.env.<variant>`, never a placeholder like `.env.example`) — so a written
+ * key is always discoverable by the service tools that follow.
  *
  * @param projectId - The project the key bills to.
  * @param name - A label shown in the project's key list.

package/dist/services.js

@@ -6,28 +6,116 @@
  *     projects, mint a project API key;
  *   - a PROJECT API key (`mk_…`) pays for service calls, metered and billed to
  *     that project exactly like a deployed app calling the same URL. It is read
- *     from MOLECULE_API_KEY, else from the project's `.env` (the same place the
- *     app's `@molecule/*-molecule` bonds read it), so the key never has to pass
- *     through the chat transcript.
+ *     from MOLECULE_API_KEY, else from the project's dotenv files (`.env`, then
+ *     `.env.<variant>`, in the project root and its `api/` directory — the same
+ *     place the app's `@molecule/*-molecule` bonds read it), so the key never
+ *     has to pass through the chat transcript.
  */
-import { chmodSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
+import { parseEnv } from 'node:util';
 import { apiBase, sessionToken } from './auth.js';
-/** Parse one variable out of a dotenv file; undefined when absent. */
+/**
+ * The dotenv file names this server treats as project env files — the names
+ * `create_api_key` may write and the names key resolution reads. The SAME
+ * predicate on both sides is what keeps a written key discoverable.
+ */
+const ENV_FILE_NAME_RE = /^\.env(?:\.([A-Za-z0-9_-]+))?$/;
+/**
+ * Variants that hold placeholders or tool bookkeeping, never credentials
+ * (`.env.example`, `.env.schema`, `.env.vault`, …). Auto-loading one would
+ * send a placeholder as the bearer key, so neither side accepts them.
+ * Compared case-insensitively.
+ */
+const PLACEHOLDER_ENV_VARIANTS = new Set([
+    'example',
+    'sample',
+    'schema',
+    'template',
+    'tmpl',
+    'dist',
+    'vault',
+    'keys',
+]);
+/**
+ * Whether a dotenv basename is a project env file: `.env`, or `.env.<variant>`
+ * where the variant is not a placeholder.
+ *
+ * @param name - A dotenv file's basename.
+ * @returns True when the file may hold — and be written with — the project key.
+ */
+function isProjectEnvFileName(name) {
+    const match = ENV_FILE_NAME_RE.exec(name);
+    if (!match)
+        return false;
+    return match[1] === undefined || !PLACEHOLDER_ENV_VARIANTS.has(match[1].toLowerCase());
+}
+/**
+ * Parse one variable out of a dotenv file with Node's own dotenv parser
+ * (`util.parseEnv`), so inline comments, single/double quoting, `export`
+ * prefixes, duplicate assignments (last wins) and multi-line quoted values
+ * follow exactly the rules `node --env-file` applies — not a lookalike regex.
+ *
+ * @param file - Dotenv file to read.
+ * @param name - Variable name.
+ * @returns The parsed non-blank value, or undefined when absent.
+ */
 function readDotenvVar(file, name) {
     if (!existsSync(file))
         return undefined;
-    for (const line of readFileSync(file, 'utf8').split('\n')) {
-        const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
-        if (m && m[1] === name)
-            return m[2].replace(/^(['"])(.*)\1$/, '$2') || undefined;
+    // A BOM would otherwise become part of the first variable's NAME.
+    const content = readFileSync(file, 'utf8');
+    const parsed = parseEnv(content.charCodeAt(0) === 0xfeff ? content.slice(1) : content);
+    const value = parsed[name];
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+/**
+ * The dotenv files in one directory that may hold the project key, in
+ * precedence order: `.env` first, then `.env.<variant>` byte-sorted — a fixed
+ * order across filesystems, so the same tree always resolves the same file.
+ *
+ * @param dir - Directory to list.
+ * @returns Candidate paths (empty when `dir` is not a readable directory).
+ */
+function dotenvCandidates(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (_error) {
+        // Not a directory, or not readable: this location has no candidates.
+        return [];
     }
-    return undefined;
+    return entries
+        .filter(isProjectEnvFileName)
+        .sort((a, b) => {
+        if (a === b)
+            return 0;
+        if (a === '.env')
+            return -1;
+        if (b === '.env')
+            return 1;
+        return a < b ? -1 : 1;
+    })
+        .map((name) => join(dir, name));
 }
 /**
- * The project API key for service calls: MOLECULE_API_KEY from the server's
- * environment, else `MOLECULE_API_KEY` in `.env` at `directory` or up to two
- * parents (a full-stack project keeps it in `api/.env` or the root).
+ * The project API key for service calls, resolved in this documented order:
+ *
+ *   1. `MOLECULE_API_KEY` in this server's environment (always wins);
+ *   2. `.env`, then every `.env.<variant>` (byte-sorted), in `directory` —
+ *      then the same set in `directory/api`;
+ *   3. the same two locations in each parent, up to two parents.
+ *
+ * Inside one file, Node's dotenv rules apply: the LAST assignment wins, and
+ * inline comments / quoting are honoured. A file that does not define a
+ * non-blank MOLECULE_API_KEY is skipped, and placeholder variants
+ * (`.env.example`, `.env.schema`, …) are never read. Because `create_api_key`
+ * writes only these names through the same predicate, a key it writes at
+ * `<dir>/.env[.<variant>]` or `<dir>/api/.env[.<variant>]` is found by a later
+ * service call whose `directory` is that project directory (or up to two
+ * levels below it).
  *
  * @param directory - Project directory to search (default cwd).
  * @returns The key and where it came from, or null.
@@ -37,11 +125,13 @@ export function resolveServiceKey(directory) {
         return { key: process.env.MOLECULE_API_KEY, source: 'MOLECULE_API_KEY env' };
     }
     let dir = resolve(directory ?? process.cwd());
-    for (let i = 0; i < 3; i++) {
-        for (const file of [join(dir, '.env'), join(dir, 'api', '.env')]) {
-            const key = readDotenvVar(file, 'MOLECULE_API_KEY');
-            if (key)
-                return { key, source: file };
+    for (let level = 0; level < 3; level++) {
+        for (const location of [dir, join(dir, 'api')]) {
+            for (const file of dotenvCandidates(location)) {
+                const key = readDotenvVar(file, 'MOLECULE_API_KEY');
+                if (key)
+                    return { key, source: file };
+            }
         }
         const parent = dirname(dir);
         if (parent === dir)
@@ -83,7 +173,7 @@ function retryHint(seconds, errorKey) {
 export async function callHostedService(service, operation, body, directory) {
     const found = resolveServiceKey(directory);
     if (!found) {
-        throw new ServiceCallError('No molecule project API key. Call create_api_key (it writes MOLECULE_API_KEY into the project .env), or set MOLECULE_API_KEY for this server.');
+        throw new ServiceCallError('No molecule project API key. Call create_api_key (it writes MOLECULE_API_KEY into the project .env or .env.<name>), or set MOLECULE_API_KEY for this server.');
     }
     const response = await fetch(`${apiBase()}/v1/services/${service}/${operation}`, {
         method: 'POST',
@@ -156,12 +246,16 @@ export async function listProjects() {
         return { id: p.id, name: p.name, ...((p.role ?? r.role) ? { role: p.role ?? r.role } : {}) };
     });
 }
-/** The only files create_api_key will write: a dotenv file by name. */
-const ENV_FILE_RE = /^\.env(\.[A-Za-z0-9_-]+)?$/;
 /**
  * Mint a project API key and write it into a dotenv file as
- * MOLECULE_API_KEY, replacing an existing line. The plaintext is returned by
- * the platform exactly once and is never echoed back to the agent.
+ * MOLECULE_API_KEY, replacing an existing assignment and dropping duplicate
+ * ones. The plaintext is returned by the platform exactly once and is never
+ * echoed back to the agent.
+ *
+ * The destination is validated BEFORE the platform is asked to mint anything,
+ * and only names `resolveServiceKey` reads are accepted (`.env` or
+ * `.env.<variant>`, never a placeholder like `.env.example`) — so a written
+ * key is always discoverable by the service tools that follow.
  *
  * @param projectId - The project the key bills to.
  * @param name - A label shown in the project's key list.
@@ -171,8 +265,8 @@ const ENV_FILE_RE = /^\.env(\.[A-Za-z0-9_-]+)?$/;
  */
 export async function createApiKeyIntoEnv(projectId, name, envFile, scopes) {
     const target = resolve(envFile);
-    if (!ENV_FILE_RE.test(basename(target))) {
-        throw new ServiceCallError('env_file must be a dotenv file named .env or .env.<name>.');
+    if (!isProjectEnvFileName(basename(target))) {
+        throw new ServiceCallError('env_file must be a dotenv file named .env or .env.<name>; placeholder files such as .env.example are never read for credentials.');
     }
     if (!existsSync(dirname(target))) {
         throw new ServiceCallError(`Directory ${dirname(target)} does not exist.`);
@@ -186,33 +280,37 @@ export async function createApiKeyIntoEnv(projectId, name, envFile, scopes) {
     const line = `MOLECULE_API_KEY=${minted.token}`;
     const existed = existsSync(target);
     const lines = existed ? readFileSync(target, 'utf8').split('\n') : [];
-    const at = lines.findIndex((l) => /^\s*(?:export\s+)?MOLECULE_API_KEY\s*=/.test(l));
-    if (at >= 0)
-        lines[at] = line;
-    else {
-        if (lines.length && lines[lines.length - 1] === '')
-            lines.pop();
-        lines.push(line, '');
-    }
-    writeFileSync(target, lines.join('\n'), { mode: 0o600 });
+    // Rewrite the FIRST assignment and drop any later ones: Node's dotenv parser
+    // takes the LAST assignment in a file, so leaving an older line below the new
+    // one would keep the superseded key in force and every service call would use
+    // it. Only assignment lines are matched (a commented-out `# KEY=` is not one).
+    const assignment = /^\s*(?:export\s+)?MOLECULE_API_KEY\s*=/;
+    const next = [];
+    let written = false;
+    for (const current of lines) {
+        if (!assignment.test(current)) {
+            next.push(current);
+            continue;
+        }
+        if (!written) {
+            next.push(line);
+            written = true;
+        }
+    }
+    if (!written) {
+        if (next.length && next[next.length - 1] === '')
+            next.pop();
+        next.push(line, '');
+    }
+    writeFileSync(target, next.join('\n'), { mode: 0o600 });
     // The file now holds a secret: owner-only even if it existed with wider bits.
     chmodSync(target, 0o600);
-    // A .gitignore in the file's directory or up to three parents that names it.
-    // A heuristic for a warning, not a guarantee — git's own rules are richer.
-    const patterns = ['.env', '.env*', '.env.*', '*.env', basename(target), `/${basename(target)}`];
-    let gitignored = false;
-    for (let dir = dirname(target), i = 0; i < 4 && !gitignored; i++) {
-        const gitignore = join(dir, '.gitignore');
-        gitignored =
-            existsSync(gitignore) &&
-                readFileSync(gitignore, 'utf8')
-                    .split('\n')
-                    .some((l) => patterns.includes(l.trim()));
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
+    // Ask Git, including negations, nested rules and tracked-file status. A failed
+    // or unavailable Git check never claims that a secret is excluded.
+    const gitignored = spawnSync('git', ['check-ignore', '--quiet', '--', target], {
+        cwd: dirname(target),
+        stdio: 'ignore',
+    }).status === 0;
     return {
         id: minted.id,
         masked: minted.masked,

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "molecule-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server exposing the Molecule.dev package ecosystem — search, templates, scaffolding — to any MCP-capable coding agent",
   "author": "Molecule Dev, Inc. (https://molecule.dev)",
   "license": "Apache-2.0",
+  "homepage": "https://www.molecule.dev/mlcl",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/molecule-dev/mlcl.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/molecule-dev/mlcl/issues"
+  },
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -20,18 +29,19 @@
   ],
   "scripts": {
     "build": "shx rm -rf dist && tsc -b",
+    "gen:package-search": "node ../scripts/generate-mcp-package-search.mjs",
     "smoke": "node scripts/smoke.mjs",
     "serve": "node dist/http.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.17.0",
-    "execa": "10.0.0",
-    "zod": "3.25.76",
-    "express": "5.2.1"
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "execa": "10.2.1",
+    "zod": "4.6.7",
+    "express": "5.3.0"
   },
   "devDependencies": {
     "@types/express": "5.0.6",
-    "@types/node": "26.1.2",
+    "@types/node": "26.6.5",
     "shx": "0.4.0",
     "typescript": "6.0.3"
   }