ts-graph-tools

English | 한국어

External host for @ttsc/graph — a TypeScript code-graph MCP server (from the ttsc toolchain by samchon, author of typia/nestia).

The @ttsc/graph server running in this host indexes a TypeScript codebase and exposes the result through one MCP tool, inspect_typescript_graph. It returns names, edges, signatures, and source spans rather than file bodies. Questions about callers, flows, and usages can therefore obtain graph facts without reading source bodies directly. End-to-end token and latency effects still depend on the task and model and are measured separately in agent-bench. tsc diagnostics are included in the same graph result. @ttsc/graph resolves tsconfig aliases, re-exports, and symlink relationships through the TypeScript checker rather than plain text search.

Why a separate host repo

The whole point is to analyze a target repo without touching it:

• The graph engine is TypeScript 7 native (typescript-go). Some projects still build on older TypeScript (e.g. a service still pinned to TypeScript 4.7).

• Installing the engine into each target repo would change its package.json / node_modules / lockfile. Instead, everything lives here, and each target project gets a local-scope MCP registration pointing at this host's binaries via two env overrides.

• Result: the target repo's build pipeline (nest build, ts-jest, tsc) keeps using its own TypeScript version. Only the graph uses TS7. Zero footprint on the target — no committed files, no dependency changes.

This is intended as a reusable external host for TypeScript repositories. Each project gets its own local MCP registration while reusing the same host binaries.

Related MCP server: knocoph

What's installed here

Version lockstep: ttsc, @ttsc/graph (and @ttsc/lint, if ever added) must share the same version — @ttsc/graph declares ttsc as an exact peer. Pinned exactly (no ^) in package.json for this reason.

The native binaries are per-platform optional dependencies, so committing package.json + package-lock.json is cross-platform safe: npm install on Linux/CI fetches that platform's binaries automatically. node_modules/ is gitignored.

Setup

git clone https://github.com/KimHG1995/ts-graph-tools.git
cd ts-graph-tools
npm install

Then register a target project's MCP (local scope, private to you, not committed):

./scripts/register-mcp.sh <mcp-name> <path-to-target-project>

Restart Claude Code inside the target project to pick up the inspect_typescript_graph tool.

What the registration does

Equivalent to (run from inside the target project):

claude mcp add <mcp-name> --scope local \
  -e TTSC_GRAPH_BINARY="<host>/node_modules/@ttsc/<platform>/bin/ttscgraph" \
  -e TTSC_TSGO_BINARY="<host>/node_modules/@typescript/typescript-<platform>/lib/tsc" \
  -- node "<host>/node_modules/@ttsc/graph/lib/bin.js"

• <host> — the absolute path where you cloned this repo.

• <platform> — e.g. darwin-arm64, linux-x64 (the script fills this in).

• TTSC_TSGO_BINARY — the TS7 native checker. resolveTsgo uses it first, so the target project's node_modules is never consulted for the compiler.

• TTSC_GRAPH_BINARY — the native graph builder. resolveGraphBinary uses it first.

• cwd — Claude Code launches the MCP with cwd = the project root, which is how the graph knows which project (and tsconfig.json) to analyze.

Both env paths are absolute and identical for every project; the only per-project difference is which project the local-scope MCP is attached to.

Usage — the inspect_typescript_graph tool

Once registered, the host exposes a single MCP tool, inspect_typescript_graph. You don't call it by hand — ask Claude a question about the codebase in plain language and it selects and submits one request. The names, edges, signatures, and spans returned by @ttsc/graph are based on compiler-resolved information. They are useful directly for relationship queries such as callers and callees, while questions that depend on source-body text or non-TypeScript files still require file inspection.

Request envelope (chain of thought)

Each call carries a short reasoning plus exactly one request:

The result carries an audit (what was verified) and a next hint — answer / inspect / outside / clarify — that paces any follow-up.

The seven request types (methods)

Parameter notes

• trace.direction: forward = what the start uses (callees) · reverse = what uses it (callers) · impact = reverse trace prioritizing public API + the tests a change reaches.

• trace.focus: execution (runtime calls/instantiations/JSX) · types (type refs/inheritance) · all.

• trace.to: when both ends are known, returns the path between them — the one call for "how does A reach B".

• details returns an interface's implementers — the one call for "what actually implements this".

• Ranked ops (lookup, entrypoints, tour) return a scored, capped shortlist: the facts are verified, but whether the shortlist covers your question is yours to judge.

Example questions → the method it picks

Coding agent skill

The canonical usage workflow is skills/ts-graph/SKILL.md. The MCP server supplies graph facts; the skill explains project selection, request routing, source-reading boundaries, incomplete results, and fallback when no graph tool is available. It works with the connected tool's schema rather than hard-coding a client-specific MCP server name.

Install the same source for either local client from this host checkout:

bash scripts/install-agent-skill.sh codex
bash scripts/install-agent-skill.sh claude

The installer creates an absolute directory symlink to the canonical skill. It requires Bash and standard Unix utilities, creates no files in target projects, and does not install dependencies or register an MCP. Running it again for the same link is a no-op. Existing files, directories, and other symlinks are rejected without replacement. An optional second argument selects a different skills directory, for example bash scripts/install-agent-skill.sh codex /tmp/skill-check.

Keep the host checkout at the same path: updating its skill updates both local clients through their links. If you move the checkout, remove only the old skill symlink and reinstall. To uninstall, remove only the symlink printed by the installer. Reload the client's skill list or restart the client if it does not show ts-graph. A skill by itself does not make an MCP tool available.

ChatGPT packaging and connection remain manual; this repository does not provide a ChatGPT installer or HTTP adapter. Secure MCP Tunnel can connect to a stdio server where available, so a new HTTP adapter is not always required. A local Claude/Codex symlink does not install the skill into a ChatGPT account.

See the current client documentation for Codex skill discovery, Claude Code skills, and ChatGPT plugin connections.

To verify the installer without changing user settings (Python 3 standard library):

bash -n scripts/install-agent-skill.sh
python3 -m unittest discover -s tests -p 'test_*.py'

Scope: graph only (not lint)

@ttsc/lint is a compile plugin, not an MCP server, and it requires a lint.config.ts inside the target repo to activate its rules — so it can't be hosted here with zero footprint. This host covers graph only.

CLI & verify

The native builder runs directly from this host — env-free, still zero-footprint on the target (<platform> is e.g. darwin-arm64, linux-x64):

# Smoke test — build the graph and discard it:
node_modules/@ttsc/<platform>/bin/ttscgraph dump \
  --cwd <path-to-target-project> --tsconfig tsconfig.json > /dev/null && echo OK

# Full graph as JSON (every node/edge, no MCP response caps):
node_modules/@ttsc/<platform>/bin/ttscgraph dump \
  --cwd <path-to-target-project> --tsconfig tsconfig.json --pretty > graph.json

ttscgraph serve is the internal incremental protocol the MCP server drives — not run by hand.

License

Unlicense — public domain. Do whatever you want; no attribution required, no warranty. The npm packages this repo installs keep their own licenses; none of them are vendored here.