内容
# @jungho-dev/fs-mcp
## 概述
`@jungho-dev/fs-mcp` 是一个基于标准输入输出的本地文件工作模型上下文协议服务器，支持批量搜索、精确块编辑和基本 Git 工作流程。
该软件包是 MCP 服务器运行时。它不是 VS Code 扩展包，不需要特定的 AI 客户端，也不开辟网络监听器。任何支持 MCP 的客户端都可以启动一个标准输入输出命令来使用它，包括 Codex、Claude、Cline、Roo、Cursor、Windsurf、VS Code MCP 客户端、Gemini CLI 和 GitHub Copilot。
当前运行时不包括 SQLite 边车、上下文索引存储或 MCP 资源目录。资源和资源模板处理程序故意返回空列表以兼容客户端。
## 性能测量和令牌节省
AI 文件工作的实用基线通常是重复的 shell 调用，每个调用都会支付进程和工具调用开销。当前的基准测试显示了 `fs-mcp` 如何减少这种开销，同时保持完整的有效载荷可供客户端使用。
| 场景 | `fs-mcp` 路径 | 基线 | 测量效果 |
| --- | --- | --- | --- |
| 读取 12 个文件，每个文件 4 KB | 一个 `file-read` 批次：`3.11 ms` 平均值，`1.86 ms` 中位数 | 顺序 PowerShell 读取：`2,617.42 ms` 平均值，`2,579.75 ms` 中位数 | 大约平均时间快 `842x`，中位数时间快 `1,387x` |
| 写入 20 个文件，每个文件 4 KB | `args_path` 引用：`140` 传输字符，`35` 令牌估计 | 内联 JSON 有效载荷：`82,911` 传输字符，`20,728` 令牌估计 | 减少 `99.83%` 传输字符，避免估计 `20,693` 令牌 |
| 标准化一个 128 KB 文本结果 | 可见显示：`498` 字符；重复 `content` 槽：`817` 字符 | 原始文本正文：`131,072` 字符 | 完整文本保留在 `data.text` 中，而重复的可见文本保留为预览 |
上述数字于 `2026-05-24` 由此检出并运行七次计时场景生成：
```bash
bun tests/scripts/performance-benchmark.mjs
bun tests/scripts/write-files-args-path-benchmark.mjs
```
令牌估计使用项目启发式 `4` 个字符/令牌。实际模型计费取决于客户端及其是否仅转发 `content[0].text` 或也将 `structuredContent` 注入模型上下文。
## 安装
使用 npm 全球安装软件包：
```bash
npm install -g @jungho-dev/fs-mcp
```
或使用 Bun 全球安装：
```bash
bun add -g @jungho-dev/fs-mcp
```
## MCP 客户端配置
对于接受 JSON 样式 `mcpServers` 配置的 MCP 客户端，请使用以下服务器命令：
```json
{
"mcpServers": {
"fs-mcp": {
"command": "fs-mcp",
"args": []
}
}
}
```
Codex 使用 TOML 而不是 JSON。请在全局安装后将相同的命令添加到 `~/.codex/config.toml` 中：
```toml
[mcp_servers.fs-mcp]
enabled = true
startup_timeout_sec = 60.0
tool_timeout_sec = 120.0
command = "fs-mcp"
args = []
```
如果客户端无法解析全局二进制文件，请将 `command` 设置为绝对的 `fs-mcp` 可执行文件路径。
## 当前公共工具表面
当前源代码和编译运行时公开了 24 个公共工具，这些工具映射了 rust-fs-mcp 表面。工具名称故意设计为简短、连字符且稳定，以供缓存 MCP 目录的客户端使用。
| 领域 | 工具 | 目的 |
| --- | --- | --- |
| 文件系统 | `file-read`、`file-read-line-range`、`file-write`、`path-stat` | 读取、行范围读取、写入和检查文件。 |
| 目录 | `dir-list`、`dir-create` | 列出目录树和创建目录。 |
| 文件操作 | `path-copy`、`path-move`、`path-remove`、`file-edit`、`file-edit-lines` | 复制、移动、删除、精确编辑和行范围编辑文件或目录。 |
| 检查 | `fs-inspect` | 将文件计数、搜索、json-pick、代码片段和 git-status 查询捆绑到一个只读调用中。 |
| 搜索 | `fs-search` | 运行直接的 ripgrep 兼容的正则表达式扫描。 |
| 网络 | `web-fetch`、`web-render`、`web-extract`、`download-to-file` | 获取 URL、通过 obscura 渲染 JS/SPA 页面、提取保存的 HTML 和下载文件。 |
| Git | `git-set-workdir`、`git-status`、`git-diff`、`git-show`、`git-add`、`git-commit`、`git-amend` | 固定存储库状态、检查更改、暂存、提交和修订。 |
`src/schemas/schemas-git.ts` 包含其他 Git 操作的架构，但 `src/tools/tools-git.ts` 在此版本中仅导出上述基本 Git 集。配置工具和进程控制在当前公共目录中不可用。
## 主要功能
- 批量文件系统读取、写入、列表、元数据检查、目录创建、复制、移动、删除、精确块替换和基于 1 的行范围编辑。
- `fs-inspect` 综合查询，将文件计数、搜索、json-pick、代码片段和 git-status 绑定到一个往返中。
- 通过 `fs-search` 进行直接 ripgrep 兼容的正则表达式搜索。
- SSRF 防守的 Web 层：`web-fetch` 用于静态页面，`web-render` 用于 JS/SPA 页面通过 obscura 无头浏览器，`web-extract` 用于离线 HTML 转换，和 `download-to-file` 用于沙箱下载。
- 当目标输入或模式包括 `.docx` 时，可选的 DOCX 文本提取用于内容搜索。
- 用于存储库固定、状态、差异、显示、暂存和提交的基本 Git 会话工作流。
- 规范化的工具响应，带有可见的显示块、可机器读取的 `structuredContent` 和紧凑的 `_meta.fsMcpResult` 元数据。
## 批量工具使用
`SERVER_INSTRUCTIONS` 和批量工具描述告诉客户端将重复的同类工作折叠成一个多项调用。这适用于：
- 通过 `paths` 或 `items` 读取文件。
- 通过 `items` 或 `paths` 数组进行目录和文件操作。
- 通过 `fs-search.items` 进行搜索工作。
- 通过 `web-fetch.items`、`web-extract.items` 和 `download-to-file.items` 进行 Web 工作。
大型参数可以移到 UTF-8 JSON 文件中，并使用 `args_path` 传递。内联字段提供在 `args_path` 旁边可以覆盖来自引用 JSON 对象的字段。大型文本有效载荷也可以使用基于路径的字段，如 `content_path`、`old_string_path`、`new_string_path`、`pattern_path` 和 `messagePath`。
`file-read`、`file-read-line-range`、`dir-list` 和 `path-stat` 接受 `allowMissing=true`，因此探索性候选读取可以将缺失的本地路径作为非错误结果返回。
## 运行时笔记
当前编译的目录度量来自此检出：
- 工具数量：`24`。
- `list_tools` 有效载荷：`32,048` 个字符。
- 工具描述：`8,544` 个字符。
- 工具架构：`20,097` 个字符。
运行时行为：
- 工具目录在服务器创建期间组装一次。
- Zod 到 JSON 架构的转换对每个工具条目进行延迟缓存。
- 工具调用在控制器验证之前解析 `args_path`、`args_offset` 和 `args_length`。
- `fs-search` 没有隐含的 `maxResults` 上限。请显式设置 `maxResults`，当需要有界扫描时。
- 默认开启紧凑信封，正文仅存在于 `data.content` 中，而 `data.text` 副本被省略；`FS_MCP_COMPACT=0` 恢复它。
- 标准输入输出过滤捕获意外控制台输出，防止其破坏 MCP JSON-RPC 帧。
## 运行时配置
运行时配置仅在内存中。服务器不会创建首运行配置文件。
内部运行时配置键是:
- `allowedDirectories`
- `blockedCommands`
- `defaultShell`
`FS_MCP_ALLOWED_DIRECTORIES` 可以播种允许的目录。在 Windows 上，条目用分号分隔。
`FS_MCP_COMPACT=0` 禁用紧凑信封并恢复 `data.text` 副本。
`FS_MCP_TOOL_PROFILE=fast-coding` 将 `tools/list` 限制在仅 `fs-inspect`。
## 客户端兼容性
- 客户端元数据在初始化期间捕获，也可以通过调用元数据刷新。
- Git 调用在客户端范围的 Git 会话密钥内运行。
- Claude 和 Codex 保持标准的服务器端通知行为。
- Gemini CLI 和 GitHub Copilot 抑制服务器端 JSON-RPC 通知以兼容。
- 资源和资源模板列表处理程序返回空列表，以便探测客户端清洁初始化。
## 仓库结构
```text
项目根目录/
|-- src/
| |-- assets/ 共享读取器、类型声明和跨域实用程序
| |-- controllers/ MCP 请求处理程序和批量响应帮助程序
| |-- cores/ 运行时、stdio 传输、服务器组装和响应规范
| |-- features/ 配置、编辑、文件系统、git、进程和搜索行为
| |-- schemas/ 请求参数验证架构
| `-- tools/ 工具目录条目和调度器
|-- tests/ 合同测试、烟雾测试、夹具和验证脚本
`-- out/ 发布到 npm 的编译运行时
```
## 响应形状
每个派发的工具结果都由 `src/cores/responses/responses-tool-result.ts` 规范化。
- 可见的 `content[0].text` 由 `src/cores/responses/responses-tool-display.ts` 生成。
- 默认可见行是 `tool`、`items`、`status`、`duration`、`tokens`、`contents` 和 `structuredText`。
- `tokens` 使用基于内容的文本和序列化结构化内容的轻量级字符估计。
- `structuredContent` 存储架构版本、工具名称、状态、持续时间、错误详细信息、原始规范内容和原始结构化有效载荷。
- 默认开启紧凑信封，正文仅存在于 `data.content` 中，而 `data.text` 副本被省略。批量逐项结果仅携带 `structuredContent` 和 `isError`，而回声输入字符串超过 256 个字节变为 `<N bytes elided>`。`FS_MCP_COMPACT=0` 恢复以前的形状。
- `_meta.fsMcpResult` 存储紧凑状态、持续时间、内容类型、错误、架构和工具元数据。
- 已经规范化的结果不会再次包装；可见的显示文本会再生。
## 开发
当前开发检查使用 Bun：
```bash
bun x tsc --noEmit
bun tests/run-all-tests.js
bun tests/scripts/performance-benchmark.mjs
bun tests/scripts/write-files-args-path-benchmark.mjs
```
有用的作用域检查：
```bash
bun tests/scripts/scripts-verify-release-shape.mjs
bun tests/scripts/scripts-verify-tool-surface.mjs
bun tests/scripts/scripts-verify-optimization-reports.mjs
bun tests/scripts/scripts-verify-doc-sync.mjs
```
`tests/run-all-tests.js` 在 `FS_MCP_SKIP_BUILD=1` 设置之前重建 `out`，然后运行合同和烟雾测试。
`tests/scripts/` 下的验证脚本检查发布形状、源边界、优化报告和编译的工具表面。
## 文档
- 英文 README：`README.md`
- 韓文 README：`readme-ko.md`
- 英文架构：`architecture.md`
- 韓文架构：`architecture-ko.md`
- 更新日志：`changelog.md`
## 打包说明
npm 软件包通过 `out/index.mjs` 公开 `fs-mcp` 二进制文件。运行时版本元数据从软件包根目录 `package.json` 读取。软件包文件允许列表包括 `out`、发布文档和更新日志文件。
源文件、测试、夹具和本地运行时工件保留为仅限开发的表面。
