specgraphen

AI-operated code meaning extraction substrate built on Higher Graphen.

specgraphen pre-analyzes your codebase and exposes structured, evidence-backed code intelligence to AI agents via MCP (Model Context Protocol). Instead of grepping through hundreds of files, an AI agent queries specgraphen once and gets back type-resolved call graphs, feature scopes, column usage maps, and change impact analysis — with source witnesses (file:line) for every claim.

Why

When an AI agent investigates code with grep + Read, it burns tokens and time on each file. Cross-cutting queries like "what calls this method?" or "what columns does this table have?" require dozens of tool calls and still miss things.

specgraphen solves this by:

1. Pre-analyzing the entire codebase (tree-sitter + optional LSP) into a structured graph
2. Storing entities, relations, and witnesses in a Higher Graphen Space
3. Serving 20 query tools via MCP — one call per question, sub-second response

Java-first by design. specgraphen targets legacy enterprise codebases: parsing, LSP integration (jdtls), and the analysis heuristics are built and field-tested for Java — plus what surrounds it in real legacy systems (Shift_JIS/EUC-JP sources, MyBatis mapper XML, SQL, and JSP/JSTL screen logic). The decision-table engine (specgraphen-logic) and the graph substrate are language-agnostic, so other languages can be added as front-ends, but Java is what works today.

| Without specgraphen | With specgraphen | |---|---| | grep → Read → grep → Read → ... (dozens of calls) | feature("Order") → structured result in 1 call | | No type resolution, text matching only | LSP-backed type-strict symbol resolution | | Can't do cross-file call graphs | Pre-computed call graph with witnesses | | Tokens: 10,000-50,000 per question | Tokens: 300-2,000 per question |

Installation

npx — recommended for MCP usage

No install step — Claude Code users already have Node.js:

npx -y specgraphen --help

Shell installer (macOS / Linux)

curl -fsSL https://github.com/fuwasegu/specgraphen/releases/latest/download/specgraphen-cli-installer.sh | sh

PowerShell installer (Windows)

powershell -ExecutionPolicy Bypass -c "irm https://github.com/fuwasegu/specgraphen/releases/latest/download/specgraphen-cli-installer.ps1 | iex"

From source (requires Rust toolchain)

cargo install --git https://github.com/fuwasegu/specgraphen specgraphen-cli

Prebuilt binaries for each release are also on the releases page, and cargo binstall specgraphen-cli picks them up automatically.

Quick Start

Analyze a Java project

# Basic (tree-sitter only)
specgraphen lift --root ./my-java-project --space-id myproject

# With LSP type resolution (requires jdtls)
specgraphen lift --root ./my-java-project --space-id myproject --lsp java

Register as MCP server

Add to your Claude Code project config (.claude.json or mcp.json):

{
  "mcpServers": {
    "specgraphen": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y", "specgraphen",
        "serve",
        "--space-id", "myproject",
        "--store", ".specgraphen",
        "--source-root", "./my-java-project",
        "--transport", "stdio"
      ]
    }
  }
}

Use from Claude Code

Just ask naturally:

• "What's the overall structure of this project?"
• "Show me the Order feature — what classes are involved?"
• "What would break if I change UserService?"
• "What are the columns of the Customer table and where are they used?"
• "Explain the createUser method"

21 MCP Tools

Project-wide

| Tool | What it returns | |---|---| | overview | Entity/relation counts, package structure | | search | Find entities by name (partial match, type filter) | | package_dependencies | Cross-package dependency graph |

Feature & table analysis

| Tool | What it returns | |---|---| | feature | Classes, entry points, internal calls, external deps for a business feature | | column_usage | Per-column logical name, data type, and all read/write sites — in Java code and SQL statements (.sql files, DDL COMMENT) |

Symbol-level

| Tool | What it returns | |---|---| | explain | Signature, intent, behavior, contracts, witnesses, callers, callees | | callers | All verified callers with confidence and witnesses | | callees | All verified callees with confidence and witnesses | | class_dependencies | What a class depends on and what depends on it |

Change analysis

| Tool | What it returns | |---|---| | impact | Direct + transitive impacts of changing a symbol, affected files | | unknowns | Ambiguous points, unresolved references (known unknowns) |

Legacy analysis

| Tool | What it returns | |---|---| | dead_code | Unused methods/classes with confidence levels (deletion candidates) | | hotspots | Methods ranked by approximate cyclomatic complexity (refactoring triage) | | crud_matrix | Entry-point × table CRUD matrix from SQL, mapper XML, and repository conventions | | extract_core_rules | Minimal decision table for a method's branching logic (Quine-McCluskey); flags dead conditions | | debug_trace | Runtime-less interactive symbolic stepping: replay branch choices, inspect variables/path-conditions, choose world lines — agent-drivable, no runtime | | export_spec | Markdown specification built from structure + accumulated annotations |

Enrich flow (Claude Code as LLM)

| Tool | What it does | |---|---| | enrich | Returns source code + context for a symbol, ready for analysis | | enrich_batch | Returns a batch of unannotated entities | | annotate | Saves Claude's analysis (intent, behavior, etc.) back to the Space | | save | Persists annotations to disk |

No API key needed — Claude Code itself is the LLM engine.

LSP Integration

specgraphen can optionally use Language Server Protocol for type-strict symbol resolution:

specgraphen lift --root ./project --space-id myproject --lsp java

| Without LSP | With LSP (jdtls) | |---|---| | Name-based heuristic resolution | Type-strict definition lookup | | Cross-file and overloaded calls often stay unresolved | Far fewer unresolved references, much denser call graph |

The TypeResolver trait supports multiple languages:

• Java: jdtls (Eclipse JDT Language Server)
• TypeScript: typescript-language-server (planned)
• Python: pyright (planned)

Falls back to tree-sitter heuristics when LSP is unavailable.

Architecture

specgraphen-cli          CLI binary (lift / query / serve / export / rules)
specgraphen-mcp          MCP server (stdio JSON-RPC, 21 tools)
specgraphen-query         Query engine + projection
specgraphen-lift          tree-sitter Java parser → HG Space
specgraphen-resolver      TypeResolver trait (LSP / heuristic / chain)
specgraphen-logic         Boolean decision-table compression (Quine-McCluskey / cube)
specgraphen-vm            Resumable symbolic stepper (shared by extraction + debug_trace)
specgraphen-corroboration Multi-derivation fusion (HG Bayesian + Correspondence)
specgraphen-invariant     Structural checks (HG reachable + cycle detection)
specgraphen-model         Domain types (JavaEntityType, SpaceData)
specgraphen-store         JSON file persistence
specgraphen-llm           LLM abstraction (Claude / OpenAI)

Built on Higher Graphen reasoning engines:

• InMemorySpaceStore — indexed graph storage with traversal
• EvidenceLikelihood + update_confidence() — Bayesian confidence
• find_simple_cycles() — inheritance cycle detection
• derive_correspondence_candidates() + attempt_gluing() — multi-derivation fusion

License

MIT

specgraphen (日本語)

Higher Graphen を基盤とした、AI エージェント向けコード意味抽出基盤。

specgraphen はコードベースを事前解析し、構造化された根拠付きのコード知識を MCP（Model Context Protocol）経由で AI エージェントに提供します。何百ものファイルを grep する代わりに、AI エージェントは specgraphen に1回問い合わせるだけで、型解決済みの呼び出しグラフ、機能スコープ、カラム使用マップ、変更影響分析を — すべてソース witness（ファイル:行番号）付きで — 取得できます。

なぜ必要か

AI エージェントが grep + Read でコードを調査すると、ファイルごとにトークンと時間を消費します。「このメソッドを呼んでいるのは？」「このテーブルのカラムは何に使われている？」のような横断クエリは、何十回ものツール呼び出しが必要で、それでも見落としが発生します。

specgraphen は:

1. コードベース全体を事前解析（tree-sitter + オプションで LSP）して構造化グラフに変換
2. エンティティ・関係・根拠を Higher Graphen Space に格納
3. MCP 経由で 21 種類のクエリツールを提供 — 1回の問い合わせ、サブ秒で応答

設計として Java に寄せています。 specgraphen の照準はレガシーエンタープライズのコードベースで、パース・LSP 統合（jdtls）・解析ヒューリスティックは Java とその周辺（Shift_JIS/EUC-JP ソース、MyBatis mapper XML、SQL、JSP/JSTL の画面ロジック）向けに作られ、実案件で検証されています。数理コア（specgraphen-logic）とグラフ基盤は言語非依存なので他言語はフロントエンド追加で対応可能ですが、現時点で実用になるのは Java です。

インストール

# npx（MCP 用途はこれが最も簡単。インストール不要）
npx -y specgraphen --help

# シェルインストーラ (macOS / Linux)
curl -fsSL https://github.com/fuwasegu/specgraphen/releases/latest/download/specgraphen-cli-installer.sh | sh

# ソースからビルド（Rust toolchain が必要）
cargo install --git https://github.com/fuwasegu/specgraphen specgraphen-cli

クイックスタート

Java プロジェクトを解析

# 基本（tree-sitter のみ）
specgraphen lift --root ./my-java-project --space-id myproject

# LSP で型解決を強化（jdtls が必要）
specgraphen lift --root ./my-java-project --space-id myproject --lsp java

MCP サーバとして登録

Claude Code のプロジェクト設定（.claude.json または mcp.json）に追加:

{
  "mcpServers": {
    "specgraphen": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y", "specgraphen",
        "serve",
        "--space-id", "myproject",
        "--store", ".specgraphen",
        "--source-root", "./my-java-project",
        "--transport", "stdio"
      ]
    }
  }
}

使う

Claude Code で自然に聞くだけ:

• 「このプロジェクトの全体像を教えて」
• 「注文機能の仕様は？関連するクラスは？」
• 「UserService を変えたら何に影響する？」
• 「User テーブルの各カラムはどこで使われてる？」
• 「createUser メソッドを説明して」

LSP 統合

LSP を使うと型厳密なシンボル解決が可能に:

| LSP なし | LSP あり (jdtls) | |---|---| | 名前ベースのヒューリスティック解決 | 型厳密な定義ルックアップ | | クロスファイル・オーバーロード呼び出しが未解決になりやすい | 未解決参照が大幅に減り、呼び出しグラフが密になる |

TypeResolver trait で言語を抽象化:

• Java: jdtls（実装済み）
• TypeScript: typescript-language-server（予定）
• Python: pyright（予定）

LSP が使えない環境では tree-sitter ヒューリスティックに自動フォールバック。

21 の MCP ツール

| カテゴリ | ツール | 説明 | |---|---|---| | 全体 | overview | プロジェクト全体の構造 | | 全体 | search | 名前でエンティティ検索 | | 全体 | package_dependencies | パッケージ間依存グラフ | | 機能 | feature | 機能単位の分析（関連クラス、エントリポイント、依存） | | 機能 | column_usage | テーブルカラムの論理名・型・読み書き箇所（Java コードと SQL 文・DDL の両方から検出） | | シンボル | explain | シンボルの意味（signature, witness, callers, callees） | | シンボル | callers | 呼び出し元一覧 | | シンボル | callees | 呼び出し先一覧 | | シンボル | class_dependencies | クラスの依存関係 | | 変更 | impact | 変更影響範囲（直接 + 推移 + 影響ファイル） | | 変更 | unknowns | 曖昧点・未解決参照 | | レガシー | dead_code | 未使用メソッド/クラスの検出（確信度付き削除候補） | | レガシー | hotspots | 複雑度によるメソッドランキング（リファクタ優先度） | | レガシー | crud_matrix | エントリポイント × テーブルの CRUD マトリクス | | レガシー | extract_core_rules | 分岐ロジックを最小ディシジョンテーブルに圧縮（不要条件を数学的に特定） | | レガシー | debug_trace | ランタイムレスの対話的シンボリックステップ実行（分岐選択を再生、変数・経路条件を観察） | | レガシー | export_spec | 構造 + 注釈から Markdown 仕様書を生成 | | 学習 | enrich | ソースコード + コンテキストを返す | | 学習 | enrich_batch | 未分析エンティティの一括取得 | | 学習 | annotate | Claude の分析結果を Space に書き戻す | | 学習 | save | 注釈をディスクに永続化 |

ライセンス

MIT