使用说明
Skim MCP服务器
🚀 用于Skim代码转换的生产就绪模型上下文协议服务器
通过内置的安全、监控和生产功能,智能压缩LLM上下文窗口的代码。
📑 目录
🤔 这是什么?它对我有什么帮助?
简单来说:
如果你正在使用 克劳德代码 (AI编码助手),在分析大型代码项目时,您可能会遇到“上下文太长”的限制。
Skim MCP服务器的功能:
- 📦 自动压缩代码,在保留结构的同时减少60-95%的内容
- 🧠 使Claude Code能够分析更大的项目
- ⚡ 提供更准确的代码建议和分析
先决条件:
- ✅ 你有 克劳德代码 安装
- ✅ 您的计算机安装了Node.js 18.0.0或更高版本
不确定你是否需要这个? 如果你经常使用Claude Code来分析大型代码库,这个工具将非常有用!
🌟 特性
- 🔒 缺省巩固安全 -路径验证、输入净化、速率限制
- 📊 生产监控 -结构化日志记录、健康检查、指标
- 🚀 高性能 -通过spawn快速执行,优化缓冲
- 🛡️ DoS保护 -请求限制、大小限制、超时处理
- 📝 综合录井 -Winston与可配置级别的集成
- 🧪 全面测试覆盖 -包括单元和集成测试
- 📦 零依赖 -只有MCP SDK和Winston(生产依赖关系)
📦 安装
先决条件
- Node.js>=18.0.0
- npm、pnpm或yarn
选项1:全局安装(推荐)
# Install both MCP server and Skim CLI
npm install -g skim-mcp
# Or install skim CLI separately
npm install -g rskim
选项2:项目安装
# In your project directory
npm install skim-mcp
选项3:来源
git clone https://github.com/luw2007/skim-mcp.git
cd skim-mcp
npm install
npm run build
自动滑橇安装
如果找不到Skim CLI,服务器会自动安装:
# During npm install (postinstall hook)
npm install skim-mcp
# Or manually
npm run install-skim
验证安装
安装后,验证是否成功:
# Check if skim-mcp is available
skim-mcp --version
# Check Node.js version
node --version # Should be >= 18.0.0
如果 skim-mcp 显示“找不到命令”:
# Check globally installed packages
npm list -g skim-mcp
# Check npm global path
npm config get prefix
您可能需要将npm全局路径添加到系统path中。
🔧 配置
Claude代码设置
查找并编辑您的Claude Code配置文件(取决于您的操作系统):
macOS/Linux:
~/.claude/config.json(推荐,先试试这个)- 或
~/.config/claude-code/config.json
窗户:
C:\Users\YourUsername\.claude\config.json- 或
C:\Users\YourUsername\AppData\Roaming\claude-code\config.json
如果文件不存在,请创建它。
添加以下配置:
{
"mcpServers": {
"skim_mcp": {
"command": "skim-mcp"
}
}
}
⚠️ 重要:您必须完全退出并重新启动Claude Code才能使更改生效。
环境变量
# Logging level
export LOG_LEVEL=info # debug, info, warn, error
# Allowed base paths (comma-separated)
export SKIM_ALLOWED_PATHS=/workspace,/home/user/projects
# Rate limiting
export SKIM_MAX_REQUESTS_PER_MINUTE=10
# Input size limit
export SKIM_MAX_INPUT_SIZE=10485760 # 10MB in bytes
验证配置成功
配置并重新启动Claude Code后,对其进行测试:
- 打开克劳德代码
- 键入对话:
Help me analyze this project's code structure - 观察Claude Code是否自动使用
mcp__skim__skim_analyze工具
成功指标:
- 在对话中,您将看到“使用skim工具分析代码…”之类的消息
- 或者看看
skim_file/skim_analyze工具调用日志中的调用
如果它不起作用:
- 检查配置文件JSON格式是否有效(使用 Jsonlin.com 验证)
- 确认您完全退出并重新启动Claude Code
- 检查Claude Code的日志文件以获取错误消息
🚀 用法
配置后,这些工具在Claude Code中自动可用:
工具1: skim_transform -转换源代码
从字符串转换代码:
// Claude Code automatically uses this when analyzing code
mcp__skim__skim_transform({
source: 'function add(a, b) { return a + b; }',
language: 'javascript',
mode: 'structure',
show_stats: true
})
// Returns:
// function add(a, b) { /* ... */ }
//
// 📊 Token Reduction Statistics:
// [skim] 24 tokens → 9 tokens (62.5% reduction)
工具2: skim_file -转换文件
转换文件或目录:
mcp__skim__skim_file({
path: '/workspace/src',
mode: 'structure',
show_stats: true
})
// Returns compressed code with statistics
工具3: skim_analyze -架构分析
分析代码架构:
mcp__skim__skim_analyze({
path: '/workspace/src',
mode: 'structure'
})
// Returns:
// 1. Compressed code
// 2. Token statistics
// 3. Analysis framework to guide Claude
实际使用示例
场景1:分析项目架构
You: "Help me analyze the code architecture in src/ directory"
Claude Code:
→ Automatically calls mcp__skim__skim_analyze
→ Compresses code (65% token reduction)
→ Quickly analyzes architecture and provides suggestions
Result: Complete architecture analysis report
场景2:代码审查
You: "Review the code quality of src/auth.ts"
Claude Code:
→ Automatically calls mcp__skim__skim_file
→ Extracts function signatures and key logic
→ Provides detailed code review suggestions
Result: Identifies potential issues and improvement suggestions
场景3:理解大文件
You: "What does this 3000-line file do?"
Claude Code:
→ Automatically calls mcp__skim__skim_transform
→ Compresses to core structure (80% content reduction)
→ Quickly understands main logic
Result: Clear functional overview and workflow explanation
关键点:您不需要手动调用这些工具——Claude Code会自动决定何时使用它们!
🔒 安全功能
路径验证
✅ 只允许绝对路径
✅ 路径遍历攻击被阻止(../../../etc/passwd)
✅ Symlink解析与验证
✅ 可配置的允许基本路径
输入消毒
✅ 最大输入大小(默认10MB) ✅ 空字节检测 ✅ 命令注入预防 ✅ 壳体喷射缓解(参数化命令)
速率限制
✅ 每分钟请求数限制 ✅ 防止DoS攻击 ✅ 在标头后重试
🧪 测试
运行测试
# Install dependencies
npm install
# Run all tests
npm test
# Test with coverage
npm run test:coverage
# Watch mode for development
npm run test:watch
测试覆盖率
- ✅ Skim CLI可用性
- ✅ 路径遍历预防
- ✅ 输入验证
- ✅ 超大输入检测
- ✅ 无效语言检测
- ✅ 空字节拒绝
- ✅ 路径处理格式错误
📊 演出
基准测试
# Single file (300 lines)
skim transform - 1.3ms
# Large file (3000 lines)
skim transform - 14.6ms
# Cached (second run)
skim transform - 5ms (48x faster)
# MCP overhead < 2ms
资源限制
- 最大输入:每个请求10MB
- 最大输出:50MB缓冲区
- 超时:每次请求30秒
- 速率限制:10个请求/分钟
📖 文档
转换模式
| 模式 | 缩减 | 用例 | 示例输出 |
|---|---|---|---|
| 结构 | 60-80% | 架构分析 | function foo() { /* ... */ } |
| 签名 | 85-92% | API文件 | function foo(): void |
| 类型 | 90-95% | 类型系统分析 | interface User { name: string } |
| 满的 | 0% | 调试/验证 | 原始代码 |
支持的语言
- Types/JavaScript
- python
- 锈
- 去
- Java
- JSON(特殊结构模式)
- Markdown(标题提取)
- YAML/YML(结构提取)
CLI参考
# Transform file
skim file.ts --mode=structure --show-stats
# Transform directory
skim src/ --mode=signatures
# Transform with glob
skim 'src/**/*.ts' --jobs 4
# Clear cache
skim --clear-cache
🛠️ 发展
设置
git clone https://github.com/luw2007/skim-mcp.git
cd skim-mcp
npm install
开发工作流程
# Start development
npm run dev
# Lint code
npm run lint
# Fix linting issues
npm run lint:fix
# Format code
npm run format:fix
# Build for production
npm run build
项目结构
skim-mcp/
├── src/
│ └── index.js # Main server
├── test/
│ └── index.test.js # Test suite
├── scripts/
│ ├── install-skim.js # Auto-install script
│ └── build.js # Build script
├── docs/
│ └── examples.md # Usage examples
├── dist/ # Built files
└── README.md
🐳 码头工人
构建图像
docker build -t skim-mcp .
运行容器
docker run -i --rm \
-e LOG_LEVEL=info \
-v /workspace:/workspace \
skim-mcp
Docker Compose
version: '3.8'
services:
skim-mcp:
image: skim-mcp
environment:
- LOG_LEVEL=info
- SKIM_ALLOWED_PATHS=/workspace
volumes:
- ./workspace:/workspace
📄 许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
🤝 贡献
我们欢迎捐款!请看 贡献.md 作为指导方针。
开发设置
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加测试
- 确保棉绒通过
- 提交拉取请求
❓ 常见问题解答(初学者必读)
安装
Q1:获取“skim-mcp:找不到命令”
原因:npm全局安装路径不在您的系统path中。
解决方案:
# Method 1: Find the installation path
npm config get prefix
# Assuming it returns /usr/local, the full path would be:
# /usr/local/bin/skim-mcp
# Method 2: Use the full path in your config file
{
"mcpServers": {
"skim_mcp": {
"command": "/usr/local/bin/skim-mcp" # Replace with actual path
}
}
}
Q2:Node.js版本不兼容错误
检查您的版本:
node --version
必须大于等于18.0.0。如果您的版本太旧,请访问 nodejs.org 下载最新的LTS版本。
配置
Q3:找不到配置文件的位置
按顺序尝试这些位置:
macOS/Linux:
# 1. Check this path first
ls -la ~/.claude/config.json
# 2. If it doesn't exist, check this
ls -la ~/.config/claude-code/config.json
# 3. If neither exists, create the first one
mkdir -p ~/.claude
echo '{"mcpServers":{}}' > ~/.claude/config.json
窗户:
搜索 config.json 在文件资源管理器中,或直接在以下位置创建:
C:\Users\YourUsername\.claude\config.json
Q4:配置无效
检查表:
- []配置文件是有效的JSON格式(使用 Jsonlin.com 验证)
- []完全退出Claude Code(未最小化,完全退出)
- []重新启动克劳德代码
- [ ]
skim-mcp命令在终端中工作 - []检查克劳德代码日志中的错误消息
用法
Q5:工具什么时候会自动使用?
在以下情况下,Claude Code会自动使用Skim:
- 分析大型代码文件或目录
- 代码审查任务
- 架构分析请求
- 理解代码结构
你 不需要手动调用它 -Claude Code将自动决定何时使用它。
Q6:我怎么知道Skim正在工作?
观看Claude Code的对话窗口,了解:
- 工具调用消息:
mcp__skim__skim_file或mcp__skim__skim_analyze - 令牌统计
- “正在压缩代码…”或类似消息
这表明Skim正在工作。
Q7:Skim会修改我的代码吗?
不! Skim只读取和压缩代码进行分析- 它不会修改任何源文件.
🆘 支持
报告问题
请报告以下问题 GitHub问题.
包括:
- Node.js版本(
node --version) - 操作系统和架构
- 重现步骤
- 错误日志
获取帮助
- 📖 文档: docs/
- 💡 示例: docs/examples.md
- 💬 讨论: GitHub 讨论区
🔄 更新日志
看 更改日志.md 版本历史。
🔮 路线图
v1.1.0(下一页)
- []HTTP传输支持
- []WebSocket传输
- []插件系统
- []自定义转换规则
- []与更多LLM平台集成
v1.2.0(未来)
- []并行处理优化
- []内存高效流媒体
- []高级缓存策略
- []指标仪表板
🙏 致谢
特别感谢
此项目是在dean0x创建的优秀Skim项目的基础上构建的MCP服务器包装器。Skim是一个用Rust编写的强大的代码转换工具,为LLM提供了智能代码压缩功能。
- 原始项目: https://github.com/dean0x/skim
- 核心技术:铁锈+树保姆
- 贡献:提供60-95%的代码压缩能力
如果没有dean0x的出色工作,这个MCP服务器就不会存在。我们强烈建议您访问原始项目以了解更多技术细节!
其他致谢
由...制作❤️ LLM社区
