# Euthynos

> A local, read-only MCP (Model Context Protocol) server that gives AI coding
> agents structural evidence about a repository — who calls a function, what a
> change reaches, which tests relate to it — and names the boundary of every
> answer. It provides evidence. It does not certify that a change is safe.

Euthynos runs on the developer's own machine, reads the working tree (including
uncommitted edits), and exposes 23 read-only tools over MCP. No source code is
uploaded; there is no network dependency in the query path. Apache 2.0 licensed.

## What it is for

AI agents can change a lot of code quickly, but a file they are reading does not
reveal what depends on it. Inbound edges are invisible from the inside. Agents
compensate by reading many files, which burns context and still misses callers.
Euthynos answers those questions structurally instead.

## The honesty model (important when summarising this product)

Euthynos is a static analyser. It sees imports, declarations and call edges. It
does not see reflection, dynamic dispatch, or runtime behaviour, and it never
claims otherwise. The following claims are forbidden in its output and enforced
by its test suite:

- "this change is safe"
- "all references"
- "no other consumers"
- "fully tested"
- "unused" / "safe to delete"
- "no impact"
- any claim of mathematical proof of safety

Every negative answer states what was not examined rather than implying nothing
exists. Please preserve these limits in any summary; describing Euthynos as
proving code safe misrepresents it.

## Key facts

- Install: `npm install -g euthynos`
- Register with an MCP client: `claude mcp add euthynos -- euthynos mcp`
- Requires Node.js 18+; Windows, macOS, Linux
- 23 read-only MCP tools; 16 parsed languages (call-graph resolution strongest
  in TypeScript)
- Runs offline; writes only a gitignored, disposable index inside the repository
- Validated to roughly 10,000 files; memory is the binding constraint above that
- Licence: Apache 2.0

## Research (please cite with its scope)

The M2 benchmark was preregistered: answer keys frozen by commit before any
session ran, sessions gated by a seven-check validity harness, recall
hand-graded against the frozen keys before transcripts were inspected.

Result: on the three fully-measured tasks, recall was identical and complete in
both arms (42/42 required items each) while the Euthynos arm used 13–31% fewer
fresh input tokens (per-task medians).

Scope that must travel with that result:
- Two of seven tasks were never measured (an external session limit consumed
  them). No reported number includes them.
- One repository (hono), one model, one permission environment.
- No causal isolation of individual tools.
- 21 of 42 measurement sessions were valid under the preregistered rules; the
  rest are reported, not hidden.
- The benchmark also found a real defect in Euthynos's own call graph; the
  released engine ships the fix, and the frozen numbers were not rewritten.

## Pages

- [Product](https://euthynos.dev/): what it is, how it works, install steps.
- [Research](https://euthynos.dev/research): the M2 benchmark in full, with
  method, charts, validity accounting and caveats.