Itamos MCP Tools

io.github.itamos-technologiav1.1.0更新於 Oct 9, 2026

Code-map tools for AI agents: see a repo's structure first, then edit only what matters.

已驗證Streamable HTTP可網頁執行Cloud & InfrastructureDeveloper ToolsWeb Search & Scraping

概覽

AI 產生的概覽

讓編碼助理以圖結構感知程式碼庫，只導覽與編輯真正相關的程式碼片段。

功能
四個工具以結構化程式碼感知取代直接傾倒檔案。master_architect 建立程式碼庫圖，並提供拓撲、單一檔案骨架結構與片段級定址（R14、R15）。read_file 預設回傳骨架，可讀取或編輯指定片段，並採先驗證後提交（R17-R20）；write_file 建立新檔案並自動放置到專案中，且拒絕覆寫（R22、R23）。沙箱化 git 工具支援以 depth 1 複製遠端 URL、查看狀態與提交，但不支援 push（R24）。web_skeleton 提供網頁的 search、skeleton、read 與 click 操作（R28）。
適用情境
當助理處理無法放入上下文的大型程式碼庫，需要從架構著手再縮小到模組，而不是用 grep 並讀取整個檔案時，適合加入（R6、R11）。也適合以更少 token 閱讀長網頁（R27、R45、R46）。README 建議用自己的模型與程式碼庫在託管沙箱中試用（R52）。
執行需求
遠端方式：在任一 MCP 用戶端加入託管端點作為連接器，會開啟頁面一鍵建立沙箱，不需帳號（R59、R60）。自架需要搭配 ZFS 的 Linux、Node.js 20 或更新版本與建置工具、git，以及 Chrome 或 Chromium（R64、R66、R67）。設定項包括 SANDBOX_ROOT、SANDBOX_TOTAL_SLOTS、SANDBOX_PORT、SANDBOX_TTL_MINUTES 與 SANDBOX_DATA_DIR（R96-R100）。選用摘要模型透過 ITAMOS_SUMMARIZER_URL 設定（R83）。
安裝前請注意
託管沙箱是免費即時 alpha；沙箱在閒置 10 分鐘後會被刪除，因此不要放入敏感資料（R61）。git 工具只能複製遠端 URL，不能 push（R24）。自架時該連接埠不可從外部存取，因為直連會跳過登入（R79）；公開伺服器應設定 WEB_SKELETON_PUBLIC_ONLY=1（R102）。選用設定包括 SANDBOX_SMTP_CREDENTIALS，即含 email 與 app_password 的 JSON 檔案（R106），以及 ITAMOS_COSTS_DB 統計用 SQLite 檔案（R108）。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Itamos MCP Tools，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "mcpServers": {
    "itamos-mcp-tools": {
      "type": "http",
      "url": "https://mcp.itamos-technologia.com/mcp"
    }
  }
}

README

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.

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

ToolWhat it does
master_architectProject-aware code navigation. Builds a graph of your codebase, exposes topology, per-file bone structure, and segment-level addressing. The entry point for any codebase task.
read_fileSegment-addressed file editor. Returns a skeleton by default. Read segment N to get the code. Edit with verify then commit. Project-aware.
write_fileCreate new files with automatic project placement. Refuses overwrites — edits go through read_file.
gitThe original Itamos git tool, sandboxed for security: clone (remote URLs only, depth=1), status, commit. Everything stays inside the session workspace; push is not available.
web_skeletonLLM-first web perception. 97% token reduction vs raw HTML. Actions: search, skeleton, read, click.

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.

master_architect navigation flow

The model is guided through four phases: scan to index the repo, topology to see the data-flow graph, bones to inspect a file, navigate or read_file to read the specific segment. The model never reads a file it has not first located in the graph.

read_file segment addressing

Files are parsed into named segments. A 5000-line file might have 40 segments. The model reads the skeleton, picks the segment it needs, reads that segment. Total context used is roughly 120 lines instead of 5000.

web_skeleton token reduction

Raw HTML of a modern web page runs 50,000 to 200,000 tokens. web_skeleton output is 500 to 3,000 tokens. The model reads the skeleton, picks the section id it needs, reads that section only.

Benchmarks

Verified in live use with Claude Opus 5.5 and Claude Sonnet. Any MCP-capable model can use the tools.

Don't take our word for it. Test the tools free in the hosted sandbox with your own model and your own repository, then post your results in Discussions → Benchmarks: model, task, tokens, time.

Found a bug? Open an issue with the steps to reproduce it. Every report makes the tools better.

Connecting

The sandbox server speaks standard MCP over HTTP POST with SSE support.

Compatible with any MCP client. Used in practice through Claude.ai and through direct API integration (our benchmark harness).

Hosted sandbox (free live alpha): add https://mcp.itamos-technologia.com/mcp as a connector in any MCP client. A page opens where you create your sandbox with one click, no account needed. Sandboxes are deleted after 10 minutes of inactivity, so don't use them for sensitive data.

Self-hosting

Requirements

  • Linux with ZFS (required). Every sandbox is its own ZFS dataset with a hard size limit (quota) and compression, so no user can fill the disk for everyone else. The server checks this at startup and refuses to start without it.
  • Node.js 20 or newer, plus build tools for the native modules (Debian/Ubuntu: apt install build-essential python3).
  • git for the git tool, and Chrome or Chromium for web_skeleton.

Install

sh
git clone https://github.com/itamos-technologia/itamos-mcp-tools.gitcd itamos-mcp-toolsnpm install

One npm install sets up everything, including the tools folder.

On Ubuntu 26.04 you can install the package from Releases instead: sudo apt install ./itamos-mcp-tools_1.1.0_all.deb. It sets up a service user, a systemd service, settings in /etc/itamos-mcp-tools/env and the command itamos-mcp-create-slots, then tells you the next two steps.

Create the sandbox slots

sh
sudo scripts/create-slots.sh tank/sandboxes 500 2G $USER

This creates slot_001 to slot_500 under the ZFS dataset tank/sandboxes (use your own pool name), each with a 2 GB quota and lz4 compression, owned by the user the server runs as. It is safe to run again.

Start

sh
SANDBOX_ROOT=/tank/sandboxes SANDBOX_TOTAL_SLOTS=500 npm start

From the same machine, add http://localhost:4200/mcp as a connector in your MCP client. Local connections are identified by IP address and need no sign-in.

Going public

Firewall port 4200 and put an HTTPS reverse proxy (for example nginx) in front of it that sets X-Forwarded-For and X-Forwarded-Proto. Requests that arrive through the proxy use the anonymous one-click sign-in, so users on shared addresses (such as claude.ai) each get their own sandbox. Direct connections to port 4200 skip the sign-in, which is why the port must not be reachable from outside.

Text models (optional)

read_file and web_skeleton give untitled paragraphs and page sections a short title (5 to 10 words) from a small summarizer model, so the agent can tell parts apart without reading them. Without a summarizer everything still works; those parts are then named by their first line.

Any OpenAI-compatible chat endpoint works, set with ITAMOS_SUMMARIZER_URL (default http://127.0.0.1:8090): a single llama-server, Ollama, or the included router in front of several GPUs. The whole paragraph is always sent, never cut.

The hosted sandbox runs Gemma 4 E4B (Q4_0) as summarizer and EmbeddingGemma 300M as embedder on three GPUs (one 16 GB MI50 and two 8 GB V340 dies), each summarizer started like this:

sh
llama-server -m gemma-4-E4B-it-Q4_0.gguf -ngl 99 --port 8190 \  -np 64 -c 524288 --kv-unified -fa on --cache-type-k q4_0 --cache-type-v q4_0 -rea off
  • --kv-unified: one shared KV pool, so each request uses only the tokens it needs.
  • --cache-type-k q4_0 --cache-type-v q4_0 (needs -fa on): a 4-bit KV cache, about 4.5 KB per token for this model.
  • -c is the pool in tokens: 524,288 on the MI50, 262,144 on each V340 die (with 32 slots).

The router (router/llm-router.js, service itamos-llm-router) listens on 8090 (summarizer) and 8091 (embedder). Before sending a request it counts its tokens with the backend's own tokenizer, sends it to a GPU whose pool has room (preferring faster GPUs by weight), and makes it wait in line when none has. A GPU that fails is skipped for 15 seconds and the request is retried on another. Configure it with ROUTES (in the package: /etc/itamos-mcp-tools/router.env); GET /router/status shows each GPU's pool, reserved tokens and queue.

The embedder on 8091 serves other Itamos services; the tools don't use embeddings yet.

Settings

VariableDefaultWhat it does
SANDBOX_ROOT/fast/sandboxesFolder holding the slot datasets
SANDBOX_TOTAL_SLOTS500Number of slots
SANDBOX_PORT4200Port the server listens on
SANDBOX_TTL_MINUTES10Idle minutes before a sandbox is emptied
SANDBOX_DATA_DIR./dataWhere sign-in data is kept (hashed)
PUBLIC_BASE_URL, PUBLIC_MCP_URLfrom the proxy headersPublic addresses, if the proxy can't supply them
WEB_SKELETON_PUBLIC_ONLYoffSet to 1 on a public server: web_skeleton then refuses private and local addresses
ITAMOS_SUMMARIZER_URLhttp://127.0.0.1:8090Summarizer for titles (any OpenAI-compatible chat endpoint). Empty turns titling off
ITAMOS_SUMMARIZER_MODELsummarizerModel name sent with each request; only Ollama needs a real one
SANDBOX_SMTP_CREDENTIALSa path on the Itamos serverJSON file (email, app_password, smtp_server, smtp_port) for the optional "your sandbox is ready" email. Without it the email is not sent and the server logs why.
ITAMOS_COSTS_DBa path on the Itamos serverSQLite file for token-savings statistics. If it can't be written, statistics are skipped.

License

Dual licensed. Free under AGPL-3.0: use, modify and share, with source published for modified versions, including network use. Building it into a closed product? A commercial licence removes the AGPL obligations. Contact [email protected].

About

Designed and built by Konstantinos Karamperis, founder of Itamos Technologia in Trikala, Greece. A systems architect with a background in industrial engineering and infrastructure, building AI-native developer tools on AMD hardware with open-source inference stacks.

LinkedIn · itamos-technologia.com

來源：README.md，提交 7a9ed90

工具

0
工具後設資料尚未被收錄。

版本歷史

1
  1. v1.1.0最新Oct 9, 2026