stump (Hegner123)

Stump-令牌高效目录树MCP工具

  

一个高性能的MCP服务器工具，提供紧凑、令牌高效的目录树可视化，针对LLM消费进行了优化。

建筑

Stump使用双二进制架构进行并发MCP请求处理：

• stump （Go）——处理JSON-RPC 2.0 stdio协议的MCP服务器。每 tools/call 请求生成一个执行的goroutine stump-core 作为一个子流程。多个请求同时运行，不会相互阻塞。
• stump-core （Zig）——执行实际目录遍历并输出JSON的CLI工具。每个请求作为一个一次性进程运行。

这种设计解决了并发MCP客户端（例如父代理和子代理）共享单个MCP服务器进程的问题。Go包装器通过goroutines处理并发性，而Zig核心则专注于快速文件系统遍历。

特性

• 令牌高效输出：通过紧凑的JSON格式，与标准树工具相比减少了50%以上
• 并发请求处理：多个代理可以同时调用树桩而不会阻塞
• 可配置深度：控制遍历深度以限制输出大小
• 智能过滤：按扩展名、模式或隐藏文件包含/排除
• Symlink处理：默认情况下检测符号链接，可选择使用循环检测
• 安全保障措施：具有覆盖功能的大目录检测
• 双输出模式:

- 具有可配置令牌限制的Stdout模式（1k-100k令牌） - 文件模式，树大小不受限制

• 性能指标：可选的详细计时、内存和文件系统操作跟踪
• 差错恢复：区分致命警告和非致命错误
• 交叉平台的：macOS、Linux和Windows

快速开始

先决条件

• Zig 0.15.2或更高版本
• 转到1.23或更高版本

构建

# Development build (both binaries)
just build

# Optimized release build
just release

# Build and install to /usr/local/bin
just install

或手动：

# Zig core
zig build release-fast

# Go MCP wrapper
go build -o stump-mcp

Zig二进制文件将在 zig-out/bin/stump-core。Go二进制文件将是 stump-mcp.

CLI使用情况

这 stump-core 二进制可以直接从命令行使用：

# Basic usage
stump-core .                           # Current directory
stump-core ~/projects -d 3             # Max depth 3
stump-core src --exclude-ext log,tmp   # Filter extensions
stump-core . --no-hidden               # Hide hidden files
stump-core . -o tree.json              # Output to file
stump-core . --modified                # Include modification timestamps
stump-core . --follow-symlinks         # Follow symlinks with cycle detection
stump-core . --performance             # Include performance metrics
stump-core . --token-limit 50000       # Custom token limit

CLI标志

跑 stump-core --help 对于所有选项。

安装为MCP服务器

# Install both binaries
just install

然后添加到MCP客户端配置中：

# Register the Go MCP wrapper (which execs stump-core internally)
claude mcp add --transport stdio stump -- /usr/local/bin/stump

测试

# Run all tests (Zig + Go)
just test

# Zig tests only
zig build test
zig build test-unit
zig build test-integration

用法

基本树可视化

{
  "method": "tools/call",
  "params": {
    "name": "stump",
    "arguments": {
      "dir": "~/projects/myapp"
    }
  }
}

具有深度限制和过滤功能

{
  "method": "tools/call",
  "params": {
    "name": "stump",
    "arguments": {
      "dir": "~/projects/myapp",
      "depth": 3,
      "exclude_ext": ["log", "tmp"],
      "show_hidden": false
    }
  }
}

文件输出模式（大树）

{
  "method": "tools/call",
  "params": {
    "name": "stump",
    "arguments": {
      "dir": "~/projects/large-repo",
      "output_file": "tree-output.json"
    }
  }
}

使用性能指标

{
  "method": "tools/call",
  "params": {
    "name": "stump",
    "arguments": {
      "dir": "~/projects/myapp",
      "performance": true
    }
  }
}

遵循Symlinks

{
  "method": "tools/call",
  "params": {
    "name": "stump",
    "arguments": {
      "dir": "~/projects/app",
      "follow_symlinks": true
    }
  }
}

强制模式（旁路安全检查）

{
  "method": "tools/call",
  "params": {
    "name": "stump",
    "arguments": {
      "dir": "/home/user",
      "force": true,
      "depth": 2,
      "output_file": "home-tree.json"
    }
  }
}

配置

参数

环境变量

• STUMP_TOKEN_LIMIT：stdout模式的默认令牌限制（范围：1000-100000）

- 每次通话都可以被覆盖 token_limit 参数 - 超出范围的值被限制为最接近的有效值

输出格式

紧凑的JSON结构

{
  "root": "/path/to/dir",
  "depth": 3,
  "stats": {
    "dirs": 15,
    "files": 42,
    "filtered": 8,
    "symlinks": 2
  },
  "tree": [
    {"path": "src", "type": "d"},
    {"path": "src/main.zig", "type": "f", "size": 1024},
    {"path": "src/lib", "type": "d"},
    {"path": "src/lib/util.zig", "type": "f", "size": 512}
  ]
}

可选字段

字段仅在相关时显示：

• symlinks_detected：检测到的符号链接数组（当 follow_symlinks: false)
• errors：遍历过程中遇到的非致命错误数组
• performance：详细的性能指标（当 performance: true)
• _note：“你要求这个”消息（当 force: true)

检测到符号链接

当发现符号链接但未遵循时：

{
  "symlinks_detected": [
    {"path": "build", "target": "/tmp/build-cache"},
    {"path": "vendor/lib", "target": "../external/lib"}
  ]
}

错误数组

遍历过程中收集的非致命错误：

{
  "errors": [
    {"type": "permission_denied", "path": "private/data", "message": "Permission denied"},
    {"type": "invalid_symlink", "path": "broken", "target": "/nonexistent", "message": "Target does not exist"}
  ]
}

性能指标

当 performance: true:

{
  "performance": {
    "total_ms": 1234,
    "traversal_ms": 980,
    "filtering_ms": 45,
    "serialization_ms": 209,
    "peak_memory_bytes": 5242880,
    "final_memory_bytes": 3145728,
    "allocations": 42350,
    "stat_calls": 1523,
    "readdir_calls": 156,
    "symlink_resolutions": 8,
    "items_per_second": 1234,
    "bytes_per_second": 32145,
    "avg_time_per_item_us": 810,
    "filter_efficiency": 23.5
  }
}

错误处理

致命警告（阻止执行）

除非 force: true 已设置：

1. 大目录检测：拒绝遍历已知的大目录(/, /usr, /home 在Unix上； C:\, C:\Windows, C:\Users 在Windows上）
2. Symlink循环：何时 follow_symlinks: true，检测并阻止循环引用
3. 非-UTF8文件名：文件名中的UTF-8编码无效

非致命错误（已收集，继续执行）

总是收集在 errors 数组：

1. 权限不足：无法读取目录或文件
2. 无效的符号链接：Symlink指向不存在的路径
3. 路径太长：超出操作系统路径长度限制
4. 无法读取的文件：文件存在，但无法读取

演出

基准测试

现代硬件的典型性能：

• 1000个文件：\<100ms
• 10000个文件：\<1s
• 100000个文件：\<10s

禁用指标跟踪时的性能开销：\<1%

代币效率

与标准相比 tree 命令输出：

• 小型项目 （100个文件）：减少60%
• 中型项目 （1000个文件）：减少55%
• 大型项目 （10000+个文件）：减少50%+

平台支持

• macOS（x86_64，aarch64）
• Linux（x86_64，aarch64）
• Windows（x86_64）

平台说明

发展

项目结构

stump/
├── main.go               # Go MCP wrapper (JSON-RPC, goroutines)
├── go.mod                # Go module
├── src/                  # Zig core (stump-core)
│   ├── main.zig          # CLI entry point
│   ├── mcp.zig           # MCP protocol types (used by Zig MCP, retained for tests)
│   ├── lib.zig           # Library exports for testing
│   ├── config.zig        # Config resolution (token limits, env vars)
│   ├── types.zig         # All data structures
│   ├── tree.zig          # Core tree traversal logic
│   ├── filter.zig        # Filtering and pattern matching
│   ├── symlink.zig       # Symlink handling (detection + following)
│   ├── errors.zig        # Error types and handling
│   ├── safeguards.zig    # Large dir detection, UTF-8 validation
│   ├── output.zig        # JSON formatting
│   └── performance.zig   # Metrics tracking
├── test/
│   ├── unit/             # Unit tests for each module
│   ├── integration/      # End-to-end integration tests
│   └── fixtures/         # Test directories
├── build.zig             # Zig build configuration
├── justfile              # Build, install, test commands
└── LICENSE               # MIT license

贡献

在处理代码库时：

1. 遵循Zig最佳实践（早期返回、最小抽象、无OOP）
2. 保持输出格式的令牌效率
3. 为新功能添加测试
4. 更新文档

许可证

MIT许可证-有关详细信息，请参阅许可证文件

作者

采用人工智能增强并发开发构建：

• 初始计划：合著者 @黑格尔123 克劳德·十四行诗4.5
• 实施：通过并发任务代理 总部 Claude Sonnet 4.5协调平台
• 第一轮Bug修复：克劳德·十四行诗4.5，附文件 @黑格尔123
• 第二轮Bug修复：克劳德作品4.5，附文件 @黑格尔123
• 最终Bug修复和测试：克劳德作品4.5
• Windows兼容性：克劳德·奥普斯4.6
• Go MCP包装器（并发请求）：克劳德·奥普斯4.6