内容
# 命令列表
[](https://opensource.org/licenses/MIT)
[](https://github.com/Ev3lynx727/commands-rtk/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/commands-rtk)
[](https://glama.ai/mcp/servers/Ev3lynx727/server-commands-rtk)
---
[](https://glama.ai/mcp/servers/Ev3lynx727/server-commands-rtk)
MCP 服务器，通过 MCP 工具执行 shell 命令 - 支持流式启动、自动 [RTK](https://github.com/rtk-ai/rtk) 令牌减少、持久缓存和完整的执行日志。
- **流式启动** - 使用 `spawn`（而非 `exec`），无 `maxBuffer` 上限，直接传输 stdout/stderr
- **自动 RTK** - 透明地为命令添加 RTK，令牌减少率约 90%
- **超时和取消** - `AbortController` 立即取消流收集，`SIGKILL` 终止进程树
- **持久缓存** - 结果缓存在 `~/.local/share/state/commands-rtk/command-cache.json`，跨会话有效
- **执行日志** - 追加式 JSONL，自动旋转，gzip 压缩，存档列表
- **安全的文件写入** - `write_file` 使用 base64 内容，避免特殊字符导致的 JSON 序列化问题
- **URI 解析器** - `resolve_uri` 通过共享 TOML 配置将 `scheme://path` 解析为绝对文件路径
## 包含内容
- ✅ **许可证** - 该仓库包含 LICENSE 文件
- ✅ **提示** - 该 MCP 服务器包含用户可以调用的提示
- ✅ **资源** - 该 MCP 服务器包含用于附加和管理上下文数据的资源
---
## 需求
- **Node.js 24+**（ESM，`package.json` 中 `"type": "module"`）
- **rtk CLI** - 通过以下方式安装
```bash
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
```
## 安装
### npx（无需安装）
```bash
npx commands-rtk # 运行 MCP 服务器（按需下载）
npx commands-rtk setup # 应用一次性补丁（rtk 修复等）
```
### npm（全局安装）
```bash
npm install -g commands-rtk
commands-rtk setup # 一次性补丁设置
```
### 从源码构建
```bash
git clone https://github.com/Ev3lynx727/server-commands-rtk.git
cd server-commands-rtk
npm install
npm run build
npm run setup # 一次性补丁设置（如果需要，从源码重建 rtk）
```
### npx（无需安装，MCP 客户端配置）
```json
{
"mcpServers": {
"commands-rtk": {
"command": "npx",
"args": ["commands-rtk"],
"env": {}
}
}
}
```
> **首次运行：** 在首次使用前运行 `npx commands-rtk setup` 以应用一次性补丁。
### 全局安装（MCP 客户端配置）
```json
{
"mcpServers": {
"commands-rtk": {
"command": "commands-rtk",
"args": [],
"env": {}
}
}
}
```
### OpenCode
```json
{
"mcp": {
"commands-rtk": {
"type": "local",
"command": ["node", "/path/to/commands-rtk/dist/index.js"],
"enabled": true,
"timeout": 60000
}
}
}
```
## 工具
| 工具 | 描述 |
|------|-------------|
| `run_process` | 执行带有 RTK 自动过滤的 shell 命令 |
| `get_cache_stats` | 显示缓存命中/未命中次数和条目计数 |
| `clear_command_cache` | 清除所有缓存的命令结果 |
| `cached_commands` | 列出所有缓存的命令键和时间戳 |
| `execution_log` | 读取执行日志条目，可选地从存档中读取 |
| `list_archives` | 列出已旋转的 `.jsonl.gz` 存档文件 |
| `write_file` | 从 base64 内容写入文件（对特殊字符安全） |
| `resolve_uri` | 通过 TOML 配置或 `MCP_RESOURCE_ROOTS` 将 `scheme://path` 解析为绝对文件路径 |
## 架构
commands-rtk 如何处理 MCP 工具调用：
流程：`server.ts` 接收 `tools/call` → `Zod.parse()` 验证 → `executor.ts` 使用 `rtk` 前缀启动 → 结果缓存 + 日志 → 返回 JSON-RPC 响应。
## 用例
```javascript
// 自动 RTK（默认）- 约 90% 令牌减少
run_process({command: "ls -la"})
// 完全绕过 RTK 过滤
run_process({command: "ls -la"})
// 显式启用/禁用 RTK
run_process({command: "ls -la"})
// 覆盖默认超时（60s）每次调用
run_process({command: "sleep 30", timeout_ms: 5000})
// 设置工作目录并附加元数据
run_process({
command: "npm test",
cwd: "/path/to/project",
description: "运行单元测试",
model_used: "claude-sonnet-4",
timeout_ms: 30000
})
// 强制缓存绕过
run_process({command: "npm install", clear_cache: true})
```
### execution_log
```javascript
// 尾部 100 条记录
execution_log({limit: 100})
// 包括已旋转的存档以获取完整历史记录
execution_log({limit: 500, include_archives: true})
```
### write_file
MCP 工具参数是 JSON 序列化的。内容包含引号、反引号或长特殊字符字符串可能会破坏 JSON 框架。使用 `write_file` 和 base64 编码：
```javascript
write_file({
path: "/tmp/output.txt",
content_b64: "SGVsbG8gV29ybGQ="
})
```
### resolve_uri
```javascript
resolve_uri({uri: "headquarters://."})
// { scheme: "headquarters", relativePath: ".", absolutePath: "/home/ev3lynx/headquarters" }
resolve_uri({uri: "datasets://train/run-001.parquet"})
// { scheme: "datasets", relativePath: "train/run-001.parquet", absolutePath: "/home/ev3lynx/datasets/memory-graph/train/run-001.parquet" }
```
方案从 `~/.config/uri-resolver/config.toml`（主要）加载，`MCP_RESOURCE_ROOTS` 作为备用。`scheme://.` 解析为基准目录。
### list_archives
```javascript
list_archives()
// 返回：{ archives: ["file1.jsonl.gz", ...], count: 7 }
```
## 配置（rtk-hook.toml）
| 部分 | 键 | 默认值 | 描述 |
|---------|-----|---------|-------------|
| `[execution]` | `timeout_ms` | `60000` | 默认每命令超时（可覆盖每次调用） |
| `[execution]` | `max_buffer_mb` | `10` | 每命令收集的最大 stdout/stderr |
| `[execution]` | `max_log_entries` | `1000` | 活动日志中保留的条目数 |
| `[execution]` | `max_archives` | `50` | 保留的最大已旋转存档文件数 |
| `[execution]` | `compress_archives` | `true` | 压缩已旋转的日志 |
| `[cache]` | `debounce_ms` | `2000` | 取消重复命令的窗口期 |
示例：
```toml
[execution]
timeout_ms = 60000
max_buffer_mb = 10
max_log_entries = 1000
max_archives = 50
compress_archives = true
[cache]
debounce_ms = 2000
```
## 状态文件
所有运行时状态都位于 `~/.local/share/state/commands-rtk/`：
```
~/.local/share/state/commands-rtk/
├── command-cache.json # 持久命令缓存
└── execution-log.jsonl # 追加式执行日志
```
在首次运行时自动创建（`mkdirSync` 递归 `true`）。
### 缓存
- **文件**：`command-cache.json` - 持久 JSON，服务器重启后仍然有效
- **键**：`(command + cwd)` 的 SHA-256 哈希值
- **统计信息**：通过 `get_cache_stats` 获取命中/未命中计数器
- **刷新**：每次变更和 SIGTERM/SIGINT 信号时写入磁盘
### 执行日志
- **文件**：`execution-log.jsonl` - 追加式，每个 JSON 对象一行
- **旋转**：当达到 `max_log_entries` 时，半数条目存档。已旋转的文件与活动日志一起存放在 `execution-log-{timestamp}.jsonl.gz`
- **每项元数据**：`timestamp`、`key`、`command`、`rtk_filtered`、`rtk_rewritten`、`cached`、`success`、`exitCode`、`duration_ms`、`error_type`、`stdout`/`stderr`、`stdout_lines`/`stderr_lines`、`model_used`
## MCP 资源和 URI 解析
资源模板和 URI 解析共享一个统一的方案注册表，从两个来源加载（TOML 优先）：
1. **主要**：`~/.config/uri-resolver/config.toml` — 与独立的 uri-resolver MCP 服务器共享
2. **备用**：`MCP_RESOURCE_ROOTS` 环境变量 — 用于部署特定的覆盖
```bash
export MCP_RESOURCE_ROOTS='{"headquarters": "~/headquarters"}'
```
每个方案注册一个资源模板 `{scheme}://{path}`，可通过 `resolve_uri` 工具查询。路径遍历通过 `startsWith()` 保护机制拒绝。
## 响应格式
所有工具返回 JSON：
```json
{
"cached": false,
"key": "sha256-hash",
"command": "echo hello",
"result": {
"success": true,
"stdout": "hello\n",
"stderr": "",
"exitCode": 0,
"duration_ms": 12,
"error_type": null
},
"rtk_filtered": true,
"rtk_rewritten": true
}
```
错误类型：`timeout`、`not_found`（ENOENT）、`permission_error`（EACCES/EPERM）、`memory_error`（ENOMEM）、`unknown_error`。
超时返回 `exitCode: 124`，附带 `stderr` 中的消息。
## 令牌节省
| 命令 | 原始令牌 | RTK 令牌 | 节省 |
|---------|-----------|------------|---------|
| `ls -la` | ~25,000 | ~3,000 | **88%** |
| `tree` | ~50,000 | ~5,000 | **90%** |
| `git diff` | ~15,000 | ~500 | **97%** |
| `npm install` | ~5,000 | ~200 | **96%** |
## 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `SERVER_DIR` | 否 | 自定义服务器根目录（默认为包含 `dist/` 的目录） |
| `RTK_MODEL_USED` | 否 | 执行日志元数据中 `model_used` 的覆盖 |
| `MCP_RESOURCE_ROOTS` | 否 | 将方案名称映射到目录路径的 JSON 对象（备用，TOML 配置优先） |
| `LOG_LEVEL` | 否 | 日志级别（`error`、`warn`、`info`、`debug`） |
## 致谢
如果没有 [RTK](https://github.com/rtk-ai/rtk) - 用于过滤 shell 命令输出以节省约 90% 令牌的 Rust 令牌减少器，该项目将无法实现。
## 许可证
MIT
