# javats-impact-mcp

![Demo: cross-stack blast radius from a single symbol](demo/blast-radius.gif)

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):
```json
{
  "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):
```json
{ "backendPath": "...", "frontendPath": "...", "openApiSource": "./openapi.json",
  "generatedClientPath": "...", "indexPath": ".javats-mcp/index.db", "allowNetwork": false }
```

## Register in Claude Desktop / Cursor

```json
{
  "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.)