Itamos MCP Tools MCP server

Itamos MCP Tools

Built in Greece, for the world.

Free and open source under AGPL-3.0. Commercial licences for closed-source use.

The problem

Every LLM coding assistant faces the same wall: codebases are too large to fit in context. The standard response is to dump files — grep for something promising, cat it, hope for the best. At 50k files this breaks. At 240k files it never worked.

We built four tools that give an LLM structured perception of a codebase instead of raw file access, plus a sandboxed git to bring code in. The result is a model that navigates code the way a senior engineer does — starting from the architecture, narrowing to the module, reading only the segment it needs. One call takes it from the project straight to the lines it needs, and every save is checked before it lands.

Read the full paper: docs/PAPER.md: how each tool works, why it was designed that way, and how the hosted sandbox runs, with diagrams.

Tools

At least 97% fewer tokens than the usual shell workflow (grep, cat, run_cmd), measured against the best case where the model fixes the bug in one attempt. Real sessions save more, because the failed attempts common with raw shell access aren't counted.

How it works

Session model

Every client gets an isolated workspace. No shared state, no cross-session leakage. Workspaces are wiped after 10 minutes of inactivity.

Navigation: project → file → segment

read_file()                                            → your projects
read_file(path="itsdangerous")                         → the structure: folders and files with coordinates, no code
read_file(path="itsdangerous", segment="d.a.f")        → the map of signer.py, one line per segment
read_file(path="itsdangerous", segment="d.a.f.31.17")  → the code of verify_signature, nothing else

Coordinates: letters are location (folders and files share one sequence per folder), numbers are what is inside a file. d.a.f.31.17 reads as src → itsdangerous → signer.py → segment 31.17. A folder that has never been scanned is scanned on first read; a cloned repository is scanned as soon as the clone finishes.

Nothing is dumped: a structure or file map over ~3,000 tokens returns an overview and asks for a search term instead. search works on both: file and folder names in a project, segment names in a file. trace=true shows what a file connects to, or a project's data flow.

Segments

Files are parsed into named segments. A 5000-line file might have 40 segments; its map is one line per segment, with classes listing their methods. The model reads the map, picks the segment it needs, reads that segment. Total context used is roughly 120 lines instead of 5000.

Editing and verification

Shortened. The full README is on GitHub.