javascript-mcp-server: Instructions file for Codex

AGENTS.md

Commands

• npm run build — compiles TypeScript to dist/
• npm start — starts the stdio server (node dist/index.js)
• npm run dist:bundle — generates release/javascript-mcp-server.cjs (single-file, ~26 MB) with all deps embedded (Node ≥ 20, no npm). Marks the optional template-engines of @vue/compiler-sfc (consolidate: twig/ejs/pug/handlebars…, lazy require in try/catch) as external — see scripts/bundle.mjs. release/ is in .gitignore; regenerate after every change.
• npm run typecheck / npm run lint — type checking (tsc --noEmit)
• npm test — smoke tests (tsx test/smoke.test.ts, node:test + InMemoryTransport)
• npm run test:snapshots — verifies the golden markdown snapshots
• npm run test:snapshots:update — regenerates the snapshots (only if the output change is INTENTIONAL)
• npm run test:stress — performance/incremental-cache tests over a synthetic project of 240+ files (test/stress.test.ts, generates the fixture in tmpdir)

Conventions

• module: NodeNext type: relative imports use the .js extension (e.g. from './analysis.js'), never .ts.
• Regexes passed to String.prototype.matchAll MUST carry the /g flag, or Node throws an error.
• Each framework lives in src/ast/<framework>.ts (Vue, Nuxt, Angular, React/Next, Svelte, Node) and exposes functions that return markdown strings. The domain modules (security.ts, debt.ts, cross.ts, types.ts) add heuristic/structural cross-framework tools. Tools are registered in src/index.ts.
• Do not use an LLM to interpret the framework: everything is static parsing + typed resolution; the AI only queries.
• Tool arguments are read from Record<string, unknown>; the SDK validates the schema at runtime. Do not rely on the typing of the callback's args (use any in withProject).

Pipeline architecture (to onboard new servers)

1. Loading (load_js_project → ProjectManager.load, src/project-manager.ts): walk of JS_TS_EXT+VUE_EXT (collectFiles, excludes node_modules). If the project is already in the map, it only does an incremental refresh.
2. Framework detection (detectFramework, project-manager.ts:112): only from package.json (deps + devDeps) and directory structure, with fixed priority — Nuxt → Next → Svelte/SvelteKit → React (confirmed with .tsx/.jsx) → NestJS → Angular → Vue (weighs real SFCs outside test/fixtures) → Fastify → Express/Koa → plain Node. Returns { kind, confidence }.
3. ts-morph project: if there is a tsconfig.json it is used; otherwise, default compilerOptions (ES2022, ESNext, strict, allowJs: true — essential for semantic resolution over .js). Each .ts/.js/.mjs/.cjs is added as a source file; non-parseable ones are ignored (try/catch).
4. Incremental cache (fileSignatures, signature size:mtimeMs per file): repeated refresh_js_project/load re-read only the changed files (add/update/remove) and detect framework change via package.json. Vue SFCs use the same criterion (readSfcCached, ~300 entries).
5. Tool registration (src/index.ts): srv.registerTool(name, { description, inputSchema }, callback). The callback is wrapped with withProject(cb) (src/index.ts:77), which resolves the ProjectInfo by name/alias and wraps the string in toResult. Schemas use z.object(...) with the base projectSchema ({ name: z.string() }) + optional parameters.
6. Layers: src/ast/<framework>.ts (Vue, Nuxt, Angular, React/Next, Svelte, Node) exposes functions that return markdown strings; the domain modules (security.ts, debt.ts, cross.ts, types.ts) add heuristic/structural cross-framework tools; src/analysis.ts concentrates the language tools (bug-hunt, xref, call graph, typecheck); src/markdown.ts formatting helpers. No layer uses an LLM: static parsing + typed resolution.
7. Performance: tools that need a ts-morph project request it with requireTsProject (built lazily, only if needed). Never re-walk the tree: use collectFiles/collectVueFiles/collectAngularFiles.