javats-impact-mcp

Read-only MCP server for cross-stack impact analysis across a Java (Spring Boot) backend and a TypeScript frontend, linked through OpenAPI.

The one-question demo: "If I rename an enum value, what breaks?"

OrderStatus.PENDING is a Java enum value. It is stored in the DB (orders.status, @Enumerated(STRING)), exposed on OrderDto.status in the OpenAPI spec, returned by GET /api/orders, and consumed by the frontend two ways.

find_symbol { name: "OrderStatus", kind: "enum" }      -> symbol_id
analyze_impact { symbol_id }

Returns (abridged):

{
  "endpoints": [{ "path": "/api/orders", "method": "GET" }],
  "tsCallers": [
    { "kind": "client_call", "file": ".../OrdersPage.tsx", "confidence": "high" },
    { "kind": "fetch_call",  "file": ".../rawFetchOrders.ts", "confidence": "heuristic" }
  ],
  "jpa": { "table": "orders", "column": "status", "enumerated": "EnumType.STRING" },
  "migration_checklist": [ "...", "Review 1 heuristic TS site (raw fetch URL match — verify manually)." ]
}

How it works

1. index_project builds a SQLite index with three indexers:
   • Java (tree-sitter): classes, enums, fields, methods, annotations, scoped references.
   • TypeScript (ts-morph): type-aware symbols, property accesses, fetch/axios call sites.
   • OpenAPI (swagger-parser): endpoints, schemas, and maps_to edges bridging Java DTO fields to schema fields.
2. The 7 read-only tools query that index. analyze_impact walks Java → OpenAPI → TypeScript.

Tools (exactly 7, all read-only)

index_project, find_symbol, find_references, get_endpoint, analyze_impact, get_git_context, explain_symbol.

Configuration

javats-mcp.config.json (paths resolve relative to the file):

{ "backendPath": "...", "frontendPath": "...", "openApiSource": "./openapi.json",
  "generatedClientPath": "...", "indexPath": ".javats-mcp/index.db", "allowNetwork": false }

Register in Claude Desktop / Cursor

{
  "mcpServers": {
    "javats-impact": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { "JAVATS_CONFIG": "/absolute/path/to/javats-mcp.config.json" }
    }
  }
}

Run npm run build first. For development, use command: "npx", args: ["tsx", "/abs/src/index.ts"].

Limitations / confidence model

• high — resolved through the TypeScript type system (ts-morph) or a generated-client method reference. Renames provably affect these sites.
• heuristic — matched by URL/path string against fetch/axios. Can miss dynamic URLs (template concatenation) and can over-match similar paths. Always verify these manually.
• Java analysis is syntactic (tree-sitter), scoped by simple type name — it does not do full type resolution, so same-named types in different packages may conflate.
• OpenAPI linking assumes springdoc-style schema names match Java DTO class names.
• Read-only: no writes, no shell exec except git log/blame. Network off unless allowNetwork.

Requirements & no native builds

Requires Node 22+ (the index store uses the built-in node:sqlite). There are no native modules: Java parsing uses web-tree-sitter (WASM runtime) with prebuilt grammars from tree-sitter-wasms, and storage uses node:sqlite. npm install needs no C++ compiler on any platform. (node:sqlite is currently a stable-but-experimental Node API and prints a one-time notice on stderr at startup; it does not affect the MCP stdio protocol.)