MCP 桌面工具
MCP Desktop Tools 提供了一个最小化的模型上下文协议（MCP）服务器和一个本地命令行界面（CLI）mcp-tools) 用于使用 ripgrep 和 git 检查配置的工作区中的源代码树。
特性（C1）
- 最小化MCP服务器注册
search_text，git_graph，repo_map，scaffold，以及open_recent工具，通过标准输入/输出进行JSON通信。 - 通过（某种方式）配置工作区
workspaces.yaml带有环境覆盖（或环境变量重写）。 - 安全辅助工具，用于确保请求仅在声明的工作区根目录内进行，包括检测符号链接逃逸。
- 坚持不懈的 磁盘缓存 for
repo_map以及在加工过程中 TTL缓存 forsearch_text，支持每次请求时选择退出（--no-cache）。 - 带可调工作线程池的有限文件系统并发性
--max-workers/MCPDT_MAX_WORKERS）。 - 丰富的指标：
elapsed_ms，git_cmd_ms，fs_walk_count，bytes_scanned，cache_hit，以及可选的舞台配置（--profile）。 - Ripgrep 和 git 适配器，支持可配置的超时设置
MCPDT_SUBPROC_TIMEOUT_MS) 并对截断结果发出警告。 - 通过可配置的日志级别进行记录
MCPDT_LOG或者命令行界面（CLI）--log-level旗帜。 - 用于生成项目骨架和列出最近修改文件的Scaffold和open_recent工具，支持用户模板覆盖
MCPDT_TEMPLATES_USER_DIR）。 - 新
snapshot该工具将Git历史记录、文件系统统计信息和安全环境标记组合成一个单一的JSON工件，并可选择将其记录到MLflow中。 - 新 最小化的Python客户端
mcp_desktop_tools.integrations.lab_client.LabClient) 用于从\*Lab代理中调用工具。
安装
看 INSTALL.md（安装说明文件） 以获取详细说明。简而言之：
pipx install . # or python -m pip install -e .[dev]所需的外部二进制文件：
通过（指定方式）覆盖发现机制 MCPDT_RG_PATH / MCPDT_GIT_PATH 如果他们没有开启 PATH.
配置
工作区是在 workspaces.yaml. 见 CONFIG.md（配置文件说明/配置文档） 查看架构详细信息。环境变量可以覆盖配置路径和 ripgrep 二进制文件。
CLI 使用方法
使用 ripgrep 搜索文本：
mcp-tools --workspace demo search_text --query "main" --include "**/*.py" --before 1 --after 1 --json总结一个Git仓库：
mcp-tools --workspace demo git_graph --rel-path proj --last-commits 20 --with-files --json生成一个仓库地图：
mcp-tools --workspace demo repo_map --rel-path proj --max-depth 5 --top-dirs 30 --yaml捕获仓库快照并将其记录到MLflow中：
mcp-tools --workspace demo snapshot --rel-path proj --run-name "$BUILD_TAG" --tag repo=proj --mlflow-uri "$MLFLOW_TRACKING_URI" --experiment homelab --artifact-path repo_snapshot.json --json使用内置模板搭建项目框架：
mcp-tools --workspace demo scaffold --target-rel demo --template-id pyproject_min --var project_name=demo --dry-run --json列出最近更新的文件：
mcp-tools --workspace demo open_recent --rel-path proj --count 20 --extensions .py --json使用 --yaml 输出YAML格式而非表格格式。 --profile 打印各阶段时间 stderr 并且包括 metrics.profile 在结构化输出中。 所有启用缓存的命令均可接受 --no-cache; 文件系统密集型命令接受 --max-workers 限制并发数量。 设定 MCPDT_SNAPSHOT_INCLUDE_ENV=1 以包含安全环境标志（os， arch， python在快照输出中（工具版本等）。
服务器使用情况
使用以下命令启动服务器：
python -m mcp_desktop_tools.server服务器接受标准输入（stdin）中的JSON行，其结构如下：
{"tool": "search_text", "input": {"workspace_id": "demo", "query": "main"}}响应遵循文档中记录的统一模式 mcp_desktop_tools/schemas/*.json.
关于脚手架（scaffold）和“打开最近”（open_recent）工具的详细使用指南，包括模板格式和GardenKeeper集成示例，均可在以下位置获取： DOCS/SCAFFOLD.md， DOCS/OPEN_RECENT.md，以及 DOCS/TEMPLATES.md。
记录（日志）
设置 MCPDT_LOG （或者 --log-level （用于CLI）以控制输出的详细程度。日志包括适配器记录的时间信息和工具执行路径。指标如 elapsed_ms， git_cmd_ms， bytes_scanned， cache_hit并且修剪警告会在工具响应中传播。
测试
运行质量套件，使用：
ruff check .
mypy mcp_desktop_tools
pytest -q --cov=mcp_desktop_tools集成测试期望两者都满足 rg 和 git 可供使用。 看 SECURITY.md 翻译为中文是：“安全指南/声明.md” 或 “安全文件.md”（具体翻译可能根据上下文有所调整，但“SECURITY.md”通常指的是一个包含安全相关信息的Markdown文件）， POLICY.md 翻译为中文是：“政策文件.md”（其中“.md”通常表示该文件是Markdown格式的）， CONFIG.md（配置文件说明）， PERF.md（文件名或标题，根据上下文可译为“性能.md”或保持原样，若“PERF”为特定术语则需具体翻译），和 CONTRIBUTING.md 翻译为中文是：“贡献指南.md” 或 “贡献规范文件.md”（具体翻译可能根据上下文调整，但“贡献指南”或“贡献规范”是比较常见的译法） 以获取更多指导。工具特定的架构文档记录在 DOCS/TOOLS.md 翻译为中文是：“文档/工具.md”，以及MLflow/\*Lab示例位于 文件/集成说明.md.