javascript-mcp-server

Deterministic MCP server for semantic analysis of JavaScript/TypeScript with interpretation of the Vue, Nuxt, Angular, React, Next, Svelte and Node frameworks.

Inspired by the existing deterministic servers (COBOL, Go, Rust, Python, Java): the server parses, resolves types and normalizes code 100% statically; the LLM only queries already-resolved structures. The AI never interprets the framework directly.

Deterministic mechanism

Layer	Mechanism
JS/TS language	TypeScript Compiler API via ts-morph (AST + TypeChecker + scope)
Vue	@vue/compiler-sfc (parse + compileScript with registerTS): resolves defineProps<Props>(), defineProps({}), defineEmits, and the real template bindings (prop/ref/const/function). Also registers defineModel (v-model), useTemplateRef and defineSlots<{...}>() from <script setup>. RegEx fallback for Options API (props: { a: { type, required } } and props: { a: String } forms)
Nuxt	Conventions over Vue: pages/ → routes, composables/ and utils/ → auto-imports, server/api → HTTP routes
Angular	@angular/compiler (parseTemplate) for real template analysis (inputs/outputs/interpolations/pipes); decorators (@Component, @Input/@Output, DI, lifecycle) and @NgModule/Routes metadata read structurally with ts-morph (RegEx fallback when there is no ts-morph project)
React / Next / Svelte	Structure conventions: .tsx/.jsx with JSX, Next app//pages/, .svelte (props/stores/events/lifecycle) and Svelte 5 runes ($state, $derived, $effect, $props, $inspect)
Node	ts-morph + detection of express/fastify/koa, node: builtins, process.env

The ProjectManager keeps an incremental cache: each file is indexed with its size:mtime signature; refresh_js_project only re-reads modified/new files and removes deleted ones, without rebuilding the whole project. Re-loading the same alias (load_js_project) also refreshes incrementally instead of rebuilding.

Requirements

• Node.js ≥ 20
• npm

Evolution roadmap: see ROADMAP.md.

Installation and build

npm install
npm run build        # compiles to dist/
npm start            # starts the stdio server
npm run typecheck    # type checking
npm test             # smoke tests (node:test + InMemoryTransport)
npm run test:snapshots               # verifies golden markdown snapshots
npm run test:snapshots:update        # regenerates the snapshots (only if the change is intentional)
npm run test:stress                  # performance and incremental cache over a synthetic project of 240+ files (fixture in tmpdir)

Tools (103)

Projects

• load_js_project — loads a directory, detects the framework (if already loaded, does an incremental refresh)
• list_loaded_projects / unload_js_project / refresh_js_project
• program_summary — executive summary
• detect_framework — vue | nuxt | angular | react | next | svelte | express | fastify | node | plain
• get_file_content — content of a file by path suffix
• search_source — case-insensitive search
• list_files — TS/JS files with lines, optionally filter by extension (includes .vue)

Language / TypeScript

• list_functions — functions and class methods with signature
• list_ts_types — interfaces, type aliases, enums, classes
• list_variables — module variables
• function_call_graph — local call graph
• find_references — references to a symbol
• variable_xref — data flow of a variable: definition/read/write (semantic classification)
• function_callers — invocations of a function
• resolve_type — definition of a symbol
• find_check_implementations — classes that implement/inherit
• get_type_hierarchy — what a type extends/implements and who uses it
• inspect_function — signature, parameters, doc and body of a function or Class.method
• inspect_class — decorators, extends/implements, fields, methods, constructor
• typecheck_project — real type errors of the project (TypeChecker diagnostics via ts-morph)

Metrics / technical debt

• function_metrics — cyclomatic complexity, body lines and parameters per function/method (with filters)
• find_high_complexity — functions with high cyclomatic complexity (configurable threshold)
• find_long_functions — functions with a long body (configurable threshold)

Quality / bug-hunt (heuristics)

• find_unchecked_errors — async calls without await/.catch: fetch, fs.*, exec, spawn, query, DB clients and axios/HTTP; also map/forEach over unawaited promises; excludes Node callback variants (fs.writeFile(path, data, cb)); exact callee match and per-line dedup
• find_unused_variables — unused module variables (cross-file analysis; exported excluded)
• find_dead_code — unreferenced functions/methods (cross-file analysis; Angular lifecycle hooks excluded)
• find_unimplemented_interfaces — interfaces whose methods no class implements explicitly
• find_any_usages — uses of any (annotations, as any, <any>, arrays, parameters/returns) grouped by file; type debt

Vue

• list_vue_components / analyze_vue_component (props, emits, slots, composables, reactive state, provide/inject; defineModel → v-model section, useTemplateRef → Template refs section, defineSlots → Slots section)
• vue_template_binding_analysis — which script variables the template uses, classified with the compiler's real bindings (prop/ref/const/function)
• find_vue_provide_inject — cross-file provide/inject graph by key (resolves exported constants, detects orphan keys)
• find_vue_unused_reactive — declared reactive state unused in template/script (heuristic)
• find_vue_template_undefined — template identifiers without binding/local/builtin (heuristic)

Nuxt

• list_nuxt_pages — routes from pages/ + server/api
• list_nuxt_composables / list_nuxt_server_api / list_nuxt_plugins_middleware
• nuxt_auto_imports / nuxt_config
• list_nuxt_page_meta — definePageMeta per page (layout, middleware, title, validate, pageTransition)

Angular

• list_angular_components / analyze_angular_component (Input/Output, DI, lifecycle)
• angular_template_analysis — template analysis with @angular/compiler (inputs/outputs/interpolations/pipes/structural directives + references without a class member)
• angular_dependency_graph — @Injectable services and consumers
• list_angular_routes / list_angular_modules / list_angular_services
• angular_module_graph — NgModules (declarations, imports, providers)
• analyze_angular_route_guards — route guards/resolvers (canActivate/canActivateChild/canActivateFn/canDeactivate/canLoad/canMatch/resolve) and their definitions
• list_angular_standalone_components — standalone components (composition imports) vs non-standalone (NgModule)
• find_angular_change_detection — ChangeDetectionStrategy (OnPush/Default) and manual CD (heuristic)
• find_angular_subscription_leaks — subscribe() without unsubscribe/takeUntil/async pipe (heuristic)

React / Next / Svelte

• list_react_components — .tsx/.jsx components with JSX, exports and used hooks
• analyze_react_component — deep analysis of a component: typed props, hooks with arguments, custom hooks, early returns, memo/forwardRef and contexts
• list_react_hooks_deps — useEffect/useMemo/useCallback with their deps array (heuristic: flags missing deps)
• list_react_context — cross-file contexts: createContext, providers and useContext consumers
• list_next_routes — app router routes (app/**/page.tsx) and pages router
• list_next_api_routes — API routes (app/**/route.ts) with HTTP methods and middleware.ts
• analyze_react_state — state inventory per component: useState/useReducer/useRef with bindings
• find_react_effect_leaks — useEffect with listeners/timers/subscriptions without cleanup (heuristic)
• list_next_data_fetching — ISR/cache in app router: revalidate, generateStaticParams, generateMetadata, fetch with next.revalidate/tags and use client/server directives
• find_react_memo_opportunities — components with non-primitive props without memo() and JSX with new values per render (heuristic)
• list_svelte_components — .svelte components with props, stores and dispatched events
• analyze_svelte_component — deep analysis of a Svelte component: props, reactivity ($:), Svelte 5 runes ($state/$derived/$effect/$props/$inspect/…), stores, context, lifecycle, bindings, snippets and dispatched events
• list_sveltekit_routes — SvelteKit routes by directory convention (src/routes): +page, +page.server (load/actions), +layout, +server.ts (API) and +error
• find_svelte_effect_leaks — onMount with listeners/timers/subscriptions without cleanup in onDestroy (heuristic)
• find_svelte_unused_stores — stores (writable/readable/derived) unused in any template or script (heuristic)
• list_sveltekit_server_hooks — hooks.server.ts: handle (sequence), handleError and handleFetch with their structure
• list_sveltekit_load_actions — load and actions per route with details (throw error/fail/redirect/params)
• list_react_files — .tsx/.jsx/.svelte files with lines

Node

• list_api_endpoints — Express/Fastify/Koa
• analyze_api_endpoint — handler call chain (→ service → repo), validation, auth middleware and next(err); resolves mounted routers
• list_express_routers — sub-routers, mounts, global middleware in order and error-handlers (4 args)
• node_native_modules / node_entry_points / node_async_flow
• node_process_env — variables read with process.env (dot/bracket), crossed with the root .env* files: flags defined keys (✓) and undefined keys (⚠ must be set in the environment/CI), and lists .env keys without any read in the code (orphans)
• find_event_emitter_leaks — EventEmitter listeners without their cleanup pair in scope (heuristic)
• find_sync_io_blocking — fs.*Sync in handlers/async that blocks the event loop (heuristic)
• find_unclosed_resources — streams/connections/http.request without close/end/destroy (heuristic)
• find_deprecated_apis — new Buffer, url.parse, util.is*, createCipher, require.extensions (heuristic)

Cross-framework

• module_dependency_graph — relative imports/requires graph between modules, with cycles and modules without importers
• find_test_mapping — production modules (src/) → tests that import them, and src/ without tests

Security and robustness (heuristics)

• find_xss_vectors — XSS vectors: v-html (Vue), {@html} (Svelte), dangerouslySetInnerHTML (React), innerHTML/insertAdjacentHTML/document.write
• find_sql_injection — query/execute with interpolated template literal or string concatenation
• find_eval_sites — eval / new Function / Function() (dynamic execution)
• find_command_injection — exec/execSync/spawn with variable interpolation
• find_hardcoded_secrets — keys/passwords/tokens with literal value, URLs with credentials, private keys and AWS keys
• find_insecure_http — http://, ws:// WebSocket and cookies without Secure/HttpOnly
• find_silent_catches — empty catches, console-only, or without error binding (discarded error)
• find_event_listener_leaks — addEventListener/setInterval without removeEventListener/clearInterval in the same scope

Technical debt and quality (heuristics)

• find_code_duplication — duplicated code blocks (copy-paste) between functions/methods
• find_todo_fixme — TODO / FIXME / HACK / XXX markers in comments
• find_unused_dependencies — package.json dependencies never imported in any file
• find_ts_ignores — type suppressors @ts-ignore / @ts-nocheck / @ts-expect-error
• find_magic_numbers — numeric literals that are not 0/1 outside named constants

TypeScript types in depth (heuristics)

• find_non_null_assertions — non-null assertions expr! (trust without verification)
• find_unsafe_type_casts — as any, as never and double cast as unknown as X
• find_loose_generics — type parameters without constraint or unused in the body
• find_untyped_exports — exported functions/methods without return type or unannotated params

Limitations and heuristics

• The bug-hunt tools (find_unchecked_errors, find_unused_variables, find_dead_code, find_unimplemented_interfaces) are heuristics by design: they flag "possible" dead code and can produce false positives/negatives (indirect use via decorators, template refs or dynamic calls). The reference count is cross-file over the real AST (ts-morph), not grep.
• find_dead_code excludes exported symbols and Angular lifecycle hooks (ngOnInit, etc.), which are invoked by the framework.
• find_dead_code/find_unused_variables also count identifiers from templates (.html in Angular, <template> block in Vue/Nuxt): a method used only from the template is not reported as dead.
• find_unimplemented_interfaces is heuristic: in TypeScript interface satisfaction is structural, so a class can satisfy one without declaring it in implements. Empty interfaces and those extended by another interface are discarded.
• find_any_usages is a type-debt heuristic: it detects ts-morph's semantic any nodes (: any, as any, <any>, any[], parameters/returns). It does not distinguish intentional any (e.g. an any at the boundary with untyped libraries) from accidental; it groups by file sorted by number of uses.
• find_unchecked_errors only considers known callees (fetch, fs.*, exec, spawn, query, DB client verbs…) and requires the line to be free of await/.catch/.then/Promise.all. Generic HTTP verbs (get, post, put, patch, delete, head, options) only count when the receiver is HTTP/axios (axios, http(s), client, request, api) — so map.get(...) is not flagged. It also detects map/forEach that fire unawaited promises (fire-and-forget), excluding those already handled with await/Promise.all/.catch on the same line. Node callback variants (fs.writeFile(path, data, cb), fs.readFile(p, cb)) are excluded because the callback receives the error.
• variable_xref classifies DEFINITION/WRITE/READ with ts-morph semantic references (findReferences); it is not interprocedural flow analysis.
• angular_template_analysis reports template identifiers without a class member. Members are resolved via ts-morph (incl. @Input/@Output, methods, getters/setters, constructor parameters); if there is no ts-morph project a RegEx fallback is used that can miss cases. Template pipes are resolved to the project's @Pipe/@Directive class (by class name or by the decorator's name) and excluded from the "without a member" section; the real parseTemplate errors are shown in "Compiler diagnostics". @Component metadata (analyze_angular_component, list_angular_components) is read structurally with ts-morph, with RegEx fallback.
• detect_framework is heuristic over package.json + directory structure. A project that uses @vue/compiler-sfc only as a build dependency (without SFCs in the app code) is no longer classified as Vue. React is detected by dependency + presence of .tsx/.jsx; Next/Svelte by dependency.
• list_files with ext='.vue' lists SFCs by directory walk (ts-morph does not parse .vue); the rest of the extensions come from the ts-morph project.
• inspect_function and resolve_type resolve top-level functions, nested functions and Class.method methods; arrow-functions are only shown in inspect_function.
• The analysis does not run npm install on the analyzed project: it only reads package.json, tsconfig.json and the source code.
• Vue SFC parsing is cached by size:mtimeMs signature (same criterion as the ProjectManager): SFCs are not re-parsed on every tool call.
• analyze_vue_component: the Composables section lists each composable once (dedup); defineSlots is extracted by finding the real }>() closing so it does not cut on nested types ({ title: string }), and defineModel supports generics (defineModel<string>()).
• analyze_svelte_component: the Runes (Svelte 5) section lists the lines with runes ($state, $derived/$derived.by, $effect/$effect.pre, $props, $inspect, $bindable); the $: (classic reactivity) stay in their own section. Svelte 5 converts $: into runes, but they are not translated into each other: each syntax is reported where it appears.

Distribution (single-file)

The server can be packaged into a single self-contained JS file that includes all the dependencies (TypeScript, ts-morph, Vue/Angular compilers). On the destination only Node ≥ 20 is needed — no npm, no node_modules, no copying the directory:

npm run dist:bundle        # generates release/javascript-mcp-server.cjs (~26 MB)
./release/javascript-mcp-server.cjs   # executable, shebang included

• It is the same server (103 tools), verified with stdio smoke: initialize, tools/list, project loading, Vue analysis with @vue/compiler-sfc and semantic analysis with ts-morph.
• The --external are the optional template-engines that @vue/compiler-sfc tries to require lazily inside try/catch (twig, ejs, pug, handlebars, …); they are not used and do not affect the tools.
• The bundle is CJS (format=cjs): even if the project is ESM, the final file is a single .cjs.
• The release/ directory is not versioned; regenerate it with the script after each change.

MCP client configuration

{
  "mcpServers": {
    "javascript": {
      "command": "node",
      "args": ["/path/to/javascript-mcp-server/dist/index.js"]
    }
  }
}

Or using the single-file bundle:

{
  "mcpServers": {
    "javascript": {
      "command": "/path/to/javascript-mcp-server/release/javascript-mcp-server.cjs"
    }
  }
}

Structure

src/
├── index.ts             # MCP server + tool registration
├── project-manager.ts   # project loading, framework detection, ts-morph cache
├── analysis.ts          # language semantic engine (ts-morph) + cross-framework bug-hunt
├── markdown.ts / version.ts
└── ast/
    ├── vue.ts           # Vue interpretation (+ SFC cache by signature)
    ├── nuxt.ts          # Nuxt conventions
    ├── angular.ts       # Angular interpretation
    ├── react.ts         # React / Next
    ├── svelte.ts        # Svelte / SvelteKit (leaks, stores, hooks, load/actions)
    ├── node.ts          # Node/Express/Fastify
    ├── security.ts      # security (XSS, injection, secrets, …)
    ├── debt.ts          # technical debt (duplication, unused deps, magic numbers)
    ├── cross.ts         # module_dependency_graph and find_test_mapping
    └── types.ts         # TypeScript types in depth (non-null, casts, generics, exports)
test/
├── smoke.test.ts        # smoke tests via InMemoryTransport
├── snapshot.test.ts     # golden markdown snapshots (regenerate with npm run test:snapshots:update)
├── stress.test.ts       # performance/incremental cache (npm run test:stress; generates the fixture in tmpdir)
├── generate-stress.ts   # generator of the synthetic project of 240+ files used by stress.test.ts
├── snapshots/           # golden tool outputs
└── fixtures/            # example projects (vue-basic, vue-deep, nuxt-basic, nuxt-deep, angular-basic,
                         # angular-deep, react-basic, react-next-deep, next-basic, svelte-basic, sveltekit-basic,
                         # svelte-deep, node-express, node-deep, ts-deep, cross-modules, security-vulns,
                         # debt-vulns, js-pure, type-errors, callgraph-basic)