graph LR
    A[AI Agent<br/>Claude / Cursor / Codex / Opencode] -->|MCP| B[java-inspector<br/>TypeScript Server]
    B -->|auto-detect| C{Maven Resolver}
    C -->|priority 1| D[MAVEN_CMD env]
    C -->|priority 2| E[mvnd daemon<br/>~2x faster]
    C -->|priority 3| F[MAVEN_HOME/bin/mvn]
    C -->|priority 4| G[mvn from PATH]
    B -->|dependency:build-classpath| H[~/.m2/repository]
    H -->|JAR streams| I[yauzl extractor]
    I -->|class names| J[JSON Lines Cache]
    B -->|cache hit| J
    B -->|cache miss| I
    B -->|java -jar vineflower.jar| K[Vineflower 1.11.2<br/>Decompiler]
    K -->|*.java source| A

~/.cache/java-inspector/<project>_<hash>/
├── classpath.json           # pomHash + jarPaths[] + classpathHash + timestamp
├── class-index.jsonl        # Append-only ClassIndexEntry batches
├── scan-state.json          # jarCount, processedJars[], isComplete
├── server-<pid>.log         # Per-process append-only logs (multi-process safe)
├── write.lock               # Cross-process lock for JSONL / state writes
├── scan.lock                # Cross-process lock for scan lifecycle
└── decompile-cache-vineflower/  # Cached .java sources

{
  "mcpServers": {
    "java-inspector": {
      "command": "npx",
      "args": ["-y", "@mustafagoksever/java-inspector"]
    }
  }
}

{
  "mcpServers": {
    "java-inspector": {
      "command": "npx",
      "args": ["-y", "@mustafagoksever/java-inspector"]
    }
  }
}

[mcp_servers.java-inspector]
command = "npx"
args = ["-y", "@mustafagoksever/java-inspector"]

{
  "mcp": {
    "java-inspector": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@mustafagoksever/java-inspector"
      ]
    }
  }
}

sequenceDiagram
    participant U as User
    participant A as AI Agent
    participant S as java-inspector
    participant M as Maven / mvnd
    participant C as Cache

    U->>A: "Show me JpaRepository source"
    A->>S: decompile_class("org.springframework.data.jpa.repository.JpaRepository")
    alt Index not built yet
        S->>M: dependency:build-classpath
        M-->>S: JAR list
        S->>S: Background scan (20 JARs in parallel)
        S-->>A: Class found via lazy JAR search
    else Cache hit
        S->>C: Map.get(className) — O(1)
        C-->>S: ClassIndexEntry
    end
    S->>S: Extract .class from JAR (yauzl)
    S->>S: java -jar vineflower.jar ...
    S-->>A: Decompiled .java source
    A-->>U: Formatted response

flowchart TD
    A[scan_dependencies called] --> B{isIndexComplete?}
    B -->|pomHash mismatch| C[Invalidate disk + memory]
    B -->|classpathHash mismatch| C
    B -->|both match| D[Return existing index]
    C --> E[Delete ~/.cache/java-inspector/<hash>/*]
    E --> F[Re-run Maven dependency:build-classpath]
    F --> G[Start background scan]
    D --> H[Return Map of classes]

npx @mustafagoksever/java-inspector

npm install -g @mustafagoksever/java-inspector
java-inspector start

git clone https://github.com/mustafagoksever/java-inspector.git
cd java-inspector
npm install
npm run build

~/.cache/java-inspector/<project>_<hash>/server-<pid>.log

# PowerShell
Get-Content ~/.cache/java-inspector/<project>_<hash>/server-<pid>.log -Wait -Tail 20

# Unix/macOS
tail -f ~/.cache/java-inspector/<project>_<hash>/server-<pid>.log