Skim MCP

🚀 Skim MCP Server

Skim MCP Server 是一个面向生产环境的模型上下文协议（MCP）服务器，专为 Skim 代码转换而设计。它基于 @dean0x 的 Skim 项目构建，能够智能地为大语言模型（LLM）的上下文窗口压缩代码，同时具备安全、监控和生产所需的特性。

🚀 快速开始

如果你在使用 Claude Code（一款 AI 代码助手）分析大型代码项目时，遇到“上下文过长”的限制，Skim MCP Server 可以帮助你解决这一问题。它能自动压缩代码，保留代码结构的同时减少 60 - 95% 的内容，让 Claude Code 能够分析更大的项目，并提供更准确的代码建议和分析。

使用前，请确保你已经安装了 Claude Code，并且你的计算机安装了 Node.js 18.0.0 或更高版本。

✨ 主要特性

• 🔒 默认安全：具备路径验证、输入清理和速率限制功能。
• 📊 生产监控：提供结构化日志记录、健康检查和指标监控。
• 🚀 高性能：通过生成和优化缓冲实现快速执行。
• 🛡️ 拒绝服务（DoS）保护：设置请求限制、大小限制和超时处理。
• 📝 全面日志记录：集成 Winston 日志系统，支持可配置的日志级别。
• 🧪 完整测试覆盖：包含单元测试和集成测试。
• 📦 零依赖：仅依赖 MCP SDK 和 Winston（生产依赖）。

📦 安装指南

前提条件

• Node.js >= 18.0.0
• npm、pnpm 或 yarn

选项 1：全局安装（推荐）

# 同时安装 MCP 服务器和 Skim CLI
npm install -g skim-mcp

# 或者单独安装 Skim CLI
npm install -g rskim

选项 2：项目安装

# 在你的项目目录中
npm install skim-mcp

选项 3：从源代码安装

git clone https://github.com/luw2007/skim-mcp.git
cd skim-mcp
npm install
npm run build

自动安装 Skim

如果未找到 Skim CLI，服务器会自动安装：

# 在 npm install 期间（postinstall 钩子）
npm install skim-mcp

# 或者手动安装
npm run install-skim

验证安装

安装完成后，验证安装是否成功：

# 检查 skim-mcp 是否可用
skim-mcp --version

# 检查 Node.js 版本
node --version  # 应 >= 18.0.0

如果 skim-mcp 显示“命令未找到”，可以执行以下操作：

# 检查全局安装的包
npm list -g skim-mcp

# 检查 npm 全局路径
npm config get prefix

你可能需要将 npm 全局路径添加到系统的 PATH 环境变量中。

💻 使用示例

基础用法

一旦完成配置，这些工具将自动在 Claude Code 中可用。

工具 1: skim_transform - 转换源代码

// Claude Code 在分析代码时会自动使用此工具
mcp__skim__skim_transform({
  source: 'function add(a, b) { return a + b; }',
  language: 'javascript',
  mode: 'structure',
  show_stats: true
})

// 返回:
// function add(a, b)  { /* ... */ }
//
// 📊 令牌减少统计:
// [skim] 24 个令牌 → 9 个令牌 (减少 62.5%)

工具 2: skim_file - 转换文件

mcp__skim__skim_file({
  path: '/workspace/src',
  mode: 'structure',
  show_stats: true
})

// 返回带有统计信息的压缩代码

工具 3: skim_analyze - 架构分析

mcp__skim__skim_analyze({
  path: '/workspace/src',
  mode: 'structure'
})

// 返回:
// 1. 压缩后的代码
// 2. 令牌统计信息
// 3. 用于指导 Claude 的分析框架

高级用法

实际使用示例

场景 1: 分析项目架构

你: "帮我分析 src/ 目录下的代码架构"

Claude Code:
→ 自动调用 mcp__skim__skim_analyze
→ 压缩代码（减少 65% 的令牌）
→ 快速分析架构并提供建议

结果: 完整的架构分析报告

场景 2: 代码审查

你: "审查 src/auth.ts 文件的代码质量"

Claude Code:
→ 自动调用 mcp__skim__skim_file
→ 提取函数签名和关键逻辑
→ 提供详细的代码审查建议

结果: 识别潜在问题并提供改进建议

场景 3: 理解大文件

你: "这个 3000 行的文件是做什么的？"

Claude Code:
→ 自动调用 mcp__skim__skim_transform
→ 压缩到核心结构（减少 80% 的内容）
→ 快速理解主要逻辑

结果: 清晰的功能概述和工作流程解释

📚 详细文档

转换模式

CLI 参考

# 转换文件
skim file.ts --mode=structure --show-stats

# 转换目录
skim src/ --mode=signatures

# 使用通配符转换
skim 'src/**/*.ts' --jobs 4

# 清除缓存
skim --clear-cache

🔧 技术细节

安全特性

• 路径验证：只允许使用绝对路径，阻止路径遍历攻击（如 ../../../etc/passwd），解析符号链接并进行验证，支持可配置的允许基本路径。
• 输入清理：设置最大输入大小（默认 10MB），检测空字节，防止命令注入和 shell 注入（使用参数化命令）。
• 速率限制：限制每分钟的请求数，防止 DoS 攻击，提供重试后响应头。

测试

# 安装依赖
npm install

# 运行所有测试
npm test

# 运行带覆盖率的测试
npm run test:coverage

# 开发时的监视模式
npm run test:watch

性能

# 单个文件（300 行）
skim transform - 1.3ms

# 大文件（3000 行）
skim transform - 14.6ms

# 缓存后（第二次运行）
skim transform - 5ms（快 48 倍）

# MCP 开销 < 2ms

资源限制

• 最大输入：每个请求 10MB
• 最大输出：50MB 缓冲区
• 超时：每个请求 30 秒
• 速率限制：每分钟 10 个请求

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

❓ 常见问题解答（初学者必读）

安装问题

问题 1: 出现 "skim-mcp: 命令未找到" 原因：npm 全局安装路径未添加到系统的 PATH 环境变量中。 解决方案：

# 方法 1: 查找安装路径
npm config get prefix

# 假设返回 /usr/local，完整路径将是:
# /usr/local/bin/skim-mcp

# 方法 2: 在配置文件中使用完整路径
{
  "mcpServers": {
    "skim_mcp": {
      "command": "/usr/local/bin/skim-mcp"  # 替换为实际路径
    }
  }
}

问题 2: Node.js 版本不兼容错误 检查你的 Node.js 版本：

node --version

版本必须 >= 18.0.0。如果版本过旧，请访问 nodejs.org 下载最新的 LTS 版本。

配置问题

问题 3: 找不到配置文件 按以下顺序尝试这些位置：

macOS / Linux:

# 1. 先检查此路径
ls -la ~/.claude/config.json

# 2. 如果不存在，检查此路径
ls -la ~/.config/claude-code/config.json

# 3. 如果两个都不存在，创建第一个
mkdir -p ~/.claude
echo '{"mcpServers":{}}' > ~/.claude/config.json

Windows: 在文件资源管理器中搜索 config.json，或者直接在以下位置创建：

C:\Users\YourUsername\.claude\config.json

问题 4: 配置无效 检查清单：

• [ ] 配置文件是有效的 JSON 格式（使用 jsonlint.com 进行验证）
• [ ] 完全退出 Claude Code（不是最小化，而是完全关闭）
• [ ] 重新启动 Claude Code
• [ ] skim-mcp 命令在终端中可以正常工作
• [ ] 检查 Claude Code 的日志文件以查看错误消息

使用问题

问题 5: 工具何时会自动使用？ Claude Code 在以下情况下会自动使用 Skim：

• 分析大型代码文件或目录
• 进行代码审查任务
• 处理架构分析请求
• 理解代码结构

你无需手动调用这些工具，Claude Code 会自动决定何时使用它们。

问题 6: 如何知道 Skim 是否正在工作？ 观察 Claude Code 的对话窗口，查看是否有以下信息：

• 工具调用消息：mcp__skim__skim_file 或 mcp__skim__skim_analyze
• 令牌统计信息
• 类似“正在压缩代码...”的消息

这些信息表明 Skim 正在工作。

问题 7: Skim 会修改我的代码吗？ 不会！ Skim 仅读取和压缩代码以进行分析，不会修改任何源文件。

🆘 支持

报告问题

请在 GitHub Issues 上报告问题。报告时请包含以下信息：

• Node.js 版本 (node --version)
• 操作系统和架构
• 复现步骤
• 错误日志

获取帮助

• 📖 文档：docs/
• 💡 示例：docs/examples.md
• 💬 讨论：GitHub Discussions

🔄 变更日志

版本历史请参阅 CHANGELOG.md。

🔮 路线图

v1.1.0（下一个版本）

• [ ] 支持 HTTP 传输
• [ ] 支持 WebSocket 传输
• [ ] 插件系统
• [ ] 自定义转换规则
• [ ] 与更多 LLM 平台集成

v1.2.0（未来版本）

• [ ] 并行处理优化
• [ ] 内存高效的流式传输
• [ ] 高级缓存策略
• [ ] 指标仪表盘

🙏 致谢

特别感谢

Skim 项目及其作者 @dean0x

本项目是一个基于 dean0x 优秀的 Skim 项目构建的 MCP 服务器包装器。Skim 是一个用 Rust 编写的强大代码转换工具，为大语言模型提供智能代码压缩功能。

• 原始项目：https://github.com/dean0x/skim
• 核心技术：Rust + tree-sitter
• 贡献：提供 60 - 95% 的代码压缩能力

没有 dean0x 的杰出工作，这个 MCP 服务器就不会存在。我们强烈建议访问原始项目以了解更多技术细节！

其他致谢

• Model Context Protocol - MCP 协议规范
• tree-sitter - 代码解析引擎
• Claude Code 团队 - 提供了出色的 AI 代码助手平台
• 所有为这个项目做出贡献的开发者

为大语言模型社区用心打造 ❤️