Itamos MCP Tools

Itamos MCP 工具

源自希腊，服务全球。 基于 AGPL-3.0 免费开源。闭源使用可购买商业许可证。

---

问题

每个 LLM 编码助手都会遇到同一个难题：代码库太大，无法全部放进上下文。常见的做法是直接输出文件——用 grep 搜索看起来有用的内容，再用 cat 打开，然后祈祷一切顺利。文件达到 5 万个时，这种方法就会失效。达到 24 万个时，它从来就没起作用过。

我们构建了四个工具，让 LLM 能以结构化方式感知代码库，而不是直接访问原始文件；此外还提供了一个沙盒化 git 工具来引入代码。结果是，模型能像资深工程师一样浏览代码——从架构入手，逐步缩小到模块，只读取所需的代码片段。一次调用即可从项目直达所需代码行，而且每次保存都会在写入前经过检查。

阅读完整论文： docs/PAPER.md：了解每个工具的工作原理、设计缘由，以及托管沙盒的运行方式，并附有示意图。

---

工具

工具	功能
read_file	唯一入口点。不提供路径时会列出你的项目；提供项目名称时会显示项目结构及坐标（不含代码）；提供坐标时，一次调用即可打开文件地图或一个代码片段。每次只编辑一个代码片段，并自动验证每次保存。
master_architect	read_file 背后的引擎。将代码库编入图谱（文件、导入、数据库、服务），并随着每次保存同步更新。在沙盒中不会直接调用它：由 read_file 完成调用。
write_file	仅创建新文件，绝不覆盖；编辑操作通过 read_file 进行。每个新文件都归属于 Agent 指定的项目：已有项目，或用于新建项目的新名称。不会自动放置任何内容。
git	Itamos 原有的 git 工具，为安全起见采用沙盒隔离：clone（仅限远程 URL，depth=1）、status、commit。克隆完成后会立即将仓库扫描为一个项目。所有内容都留在会话工作区内；不支持 push。
web_skeleton	面向 LLM 的网页感知工具。与原始 HTML 相比，可减少 97% 的令牌。操作：search、skeleton、read、click。

令牌至少减少 97%，相比常见的 shell 工作流（grep、cat、run_cmd）；该数据是以模型一次尝试就修复错误的最佳情况为基准测得。实际会话节省更多，因为未计入原始 shell 访问中常见的失败尝试。

---

工作原理

会话模型

每个客户端都有独立的工作区。状态不共享，不会发生跨会话数据泄漏。工作区会在闲置 10 分钟后清除。

导航：项目 → 文件 → 代码片段

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

坐标：字母表示位置（文件夹和文件在每个文件夹内共用一个序列），数字表示文件中的内容。d.a.f.31.17 表示 src → itsdangerous → signer.py → 代码片段 31.17。尚未扫描过的文件夹会在首次读取时扫描；克隆的仓库会在克隆完成后立即扫描。

不会直接输出全部内容：结构或文件地图超过约 3,000 个令牌时，会返回概览，并提示提供搜索词。search 可用于两种情况：在项目中搜索文件名和文件夹名，或在文件中搜索代码片段名称。trace=true 会显示文件关联了哪些内容，或项目的数据流。

代码片段

文件会被解析为带名称的代码片段。一个 5000 行的文件可能有 40 个代码片段；它的地图每个代码片段占一行，类会列出其方法。模型读取地图，选出所需的代码片段，然后读取该代码片段。使用的上下文总量大约为 120 行，而不是 5000 行。

编辑和验证

每次只进行一项编辑，而且仅修改自上次更改以来模型已读取的片段，因此它绝不会修改自己尚未查看的代码。保存前会先验证文件：

级别	检查项	失败时的处理
L1	语法：tree-sitter 加语言自带的检查器（py_compile、node --check、php -l、bash -n、gofmt、项目上下文中的 C/C++、配置解析器）	不保存；错误会指出行号
L2	使用相应服务的检查器验证配置文件（nginx -t、sshd -t、visudo、systemd-analyze）。也会运行 Linter	配置检查失败：不保存。仅报告 Linter 的发现
L3	连接关系：每个本地导入都能解析为项目文件（Python 和 JavaScript/TypeScript：其他导入必须是已安装的包；对于 Python，如果项目有虚拟环境，则必须在其中检查）；根据实时数据库架构检查 SQL	保存，并说明哪些内容尚未完成以及如何查看，因此项目的初始文件可以导入尚不存在的文件

L3 检查的是正在保存的内容，而不是较旧的索引；每次保存都会以所有受支持的语言重新索引该文件，因此映射永远不会落后于磁盘上的内容。

web_skeleton 令牌缩减

现代网页的原始 HTML 通常包含 50,000 到 200,000 个令牌。web_skeleton 的输出为 500 到 3,000 个令牌。模型读取骨架，选出所需的区段 ID，然后只读取该区段。

---

基准测试

已通过与 Claude Opus 5.5 和 Claude Sonnet 的实际使用验证。任何支持 MCP 的模型都可以使用这些工具。

不妨亲自验证。在托管沙盒中，使用你自己的模型和仓库免费测试这些工具，然后在 讨论 → 基准测试 中发布结果：模型、任务、令牌数、耗时。

发现了错误？ 请附上复现步骤提交 issue。每份报告都能让这些工具变得更好。

---

连接

沙盒服务通过 HTTP POST 提供标准 MCP，并支持 SSE。

兼容任何 MCP 客户端。实际使用方式包括通过 Claude.ai 使用，以及直接通过 API 集成（我们的基准测试工具）。

在 Claude 中试用（免费实时 Alpha 版）： 复制 https://mcp.itamos-technologia.com/mcp，打开 Claude 的连接器设置，点击 Add custom connector，粘贴地址并点击 Add。随后会打开一个页面，其中只有一个按钮：Create my sandbox；无需账户或邮箱。在聊天中启用它（+ → Connectors），然后试着提问，例如 "前往 bbc.com/news，告诉我头条新闻。" 在其他 MCP 客户端中，将同一地址添加为远程 MCP 服务。沙盒会在闲置 10 分钟后删除，因此请勿用于敏感数据。

---

自托管

要求

• Linux 和 ZFS（必需）。 每个沙盒都是独立的 ZFS 数据集，设有硬性大小限制（配额）并启用压缩，因此任何用户都无法占满磁盘，影响其他所有用户。服务会在启动时检查这一点；如果没有 ZFS，则拒绝启动。
• Node.js 20 或更高版本，以及原生模块所需的构建工具（Debian/Ubuntu：apt install build-essential python3）。
• git（用于 git 工具）以及 Chrome 或 Chromium（用于 web_skeleton）。

安装

git clone https://github.com/itamos-technologia/itamos-mcp-tools.git
cd itamos-mcp-tools
npm install

只需运行一次 npm install，即可完成所有设置，包括 tools 文件夹。

在 Ubuntu 26.04 上，也可以从 Releases 安装软件包：sudo apt install ./itamos-mcp-tools_1.1.0_all.deb。它会创建服务用户、systemd 服务，在 /etc/itamos-mcp-tools/env 中设置配置，并安装 itamos-mcp-create-slots 命令，随后告知你接下来的两个步骤。

额外语言解析器

除了标准 tree-sitter 语法（通过 npm install 安装）外，read_file 和分段器还会使用 grammars/ 文件夹中的额外解析器：

文件	解析器	回退到
.cu .cuh .hip	tree-sitter-cuda-plus	标准 tree-sitter-cuda，然后是 C++
.metal	tree-sitter-metal-plus	tree-sitter-metal，然后是 C++
.cpp .cc .hpp、C++ 的 .h	tree-sitter-cpp-plus	标准 tree-sitter-cpp
.m .mm，包含 @interface 的 .h	tree-sitter-objc	C / C++

“plus”解析器是在标准语法基础上增加额外 C++ 规则的版本；经过检查，在标准语法能够解析的情况下，它们生成的语法树完全相同。缺失或加载失败的解析器会被跳过，不会导致致命错误。

• Linux x64：无需操作。 解析器已预编译并附带在 grammars/tree-sitter-*/prebuilds/linux-x64/ 中（Node-API，适用于任意 Node 18+ 和 glibc 2.14+），其余部分由 npm install 设置。
• 其他平台（macOS、Windows、ARM）：每个解析器只需编译一次。这需要 Python 和 C/C++ 编译器：

  cd grammars/tree-sitter-cuda-plus && npx node-gyp rebuild   # same for tree-sitter-cpp-plus, -metal-plus, -metal
  

• **即插即用：**每个 grammars/tree-sitter-* 文件夹都是独立的软件包。复制其中一个后，沙盒会按名称找到它，无需安装或创建符号链接。若要将语法放在其他位置，请设置 SANDBOX_GRAMMARS_DIR。
• 重新生成（仅在更改 grammars/plus/ 中的规则后）：grammars/plus/build_plus.sh 使用 tree-sitter-cli 0.25.10（ABI 15）生成并编译，然后发布到对应的 tree-sitter-* 文件夹中。其头部会显示参数。

创建沙盒插槽

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

此命令会在 ZFS 数据集 tank/sandboxes 下创建 slot_001 到 slot_500，每个插槽配有 2 GB 配额和 lz4 压缩，并归运行服务器的用户所有。（请使用你自己的池名称。）可以安全地重复运行。

启动

SANDBOX_ROOT=/tank/sandboxes SANDBOX_TOTAL_SLOTS=500 npm start

在同一台机器上，将 http://localhost:4200/mcp 添加为 MCP 客户端中的连接器。本地连接通过 IP 地址识别，无需登录。

对外开放

开放防火墙端口 4200，并在其前面配置 HTTPS 反向代理（例如 nginx），设置 X-Forwarded-For 和 X-Forwarded-Proto。通过代理到达的请求会使用匿名一键登录，因此使用共享地址（例如 claude.ai）的用户会各自获得独立的沙盒。直接连接到端口 4200 的请求会跳过登录，因此该端口不得从外部访问。

文本模型（可选）

read_file 和 web_skeleton 会使用一个小型摘要模型，为没有标题的段落和页面部分生成简短标题（5 到 10 个词），这样 Agent 无需阅读内容就能区分各部分。没有摘要模型也能正常工作；这些部分会改用各自的首行作为名称。

任何兼容 OpenAI 的聊天端点都可使用，通过 ITAMOS_SUMMARIZER_URL 设置（默认值为 http://127.0.0.1:8090）：可以是单个 llama-server、Ollama，或置于多块 GPU 前端的内置路由器。每次都会发送完整段落，不会截断。

托管沙箱在三块 GPU 上运行 Gemma 4 E4B（Q4_0）作为摘要模型，运行 EmbeddingGemma 300M 作为嵌入模型（三块 GPU 分别为一块 16 GB MI50 和两块 8 GB V340 die）；每个摘要模型都按如下方式启动：

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：使用一个共享 KV 池，让每个请求只占用所需的 token 数。
• --cache-type-k q4_0 --cache-type-v q4_0（需要 -fa on）：使用 4-bit KV 缓存；对于此模型，每个 token 约占 4.5 KB。
• -c 表示以 token 为单位的池容量：MI50 为 524,288，每个 V340 die 为 262,144（共 32 个槽位）。

路由器（router/llm-router.js，服务 itamos-llm-router）监听 8090（摘要模型）和 8091（嵌入模型）。发送请求前，它会使用后端自身的分词器统计 token 数，将请求发送到池中有足够空间的 GPU（按权重优先选择速度较快的 GPU）；如果没有可用 GPU，则让请求排队等待。发生故障的 GPU 会被跳过 15 秒，并在另一块 GPU 上重试请求。使用 ROUTES 进行配置（软件包中的配置文件为 /etc/itamos-mcp-tools/router.env）；GET /router/status 会显示每块 GPU 的池容量、预留 token 数和队列。

8091 上的嵌入模型供其他 Itamos 服务使用；这些工具目前还不使用嵌入。

设置

变量	默认值	作用
SANDBOX_ROOT	/fast/sandboxes	存放槽位数据集的文件夹
SANDBOX_TOTAL_SLOTS	500	槽位数量
SANDBOX_PORT	4200	服务监听的端口
SANDBOX_TTL_MINUTES	10	沙箱空闲多少分钟后清空
SANDBOX_DATA_DIR	./data	保存登录数据（已哈希处理）的位置
PUBLIC_BASE_URL, PUBLIC_MCP_URL	从代理标头获取	如果代理无法提供，则使用此处设置的公共地址
WEB_SKELETON_PUBLIC_ONLY	关闭	在公共服务上设为 1：web_skeleton 随后会拒绝私有和本地地址
ITAMOS_SUMMARIZER_URL	http://127.0.0.1:8090	用于生成标题的摘要模型（任何兼容 OpenAI 的聊天端点）。留空则关闭标题生成功能
ITAMOS_SUMMARIZER_MODEL	summarizer	随每个请求发送的模型名称；只有 Ollama 需要填写真实名称
SANDBOX_SMTP_CREDENTIALS	Itamos 服务上的一个路径	JSON 文件（email、app_password、smtp_server、smtp_port），用于发送可选的“沙箱已就绪”邮件。未提供时不会发送邮件，服务会记录原因。
ITAMOS_COSTS_DB	Itamos 服务上的一个路径	用于记录 token 节省统计数据的 SQLite 文件。如果无法写入，则跳过统计。

---

许可证

采用双重许可。依据 AGPL-3.0 可免费使用、修改和分享；修改后的版本（包括通过网络使用的版本）必须公开源代码。如果要将其集成到闭源产品中？商业许可证可免除 AGPL 义务。请联系 [email protected]。

---

关于

由 Konstantinos Karamperis 设计并构建，他是位于希腊特里卡拉的 Itamos Technologia 创始人。他是一位系统架构师，拥有工业工程和基础设施背景，致力于在 AMD 硬件上使用开源推理技术栈构建 AI 原生开发者工具。

LinkedIn · itamos-technologia.com