skim-mcp-server
No description available
Ask AI about skim-mcp-server
Powered by Claude ยท Grounded in docs
I know everything about skim-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Skim MCP Server
๐ Production-ready Model Context Protocol server for Skim code transformation
Intelligently compress code for LLM context windows with built-in security, monitoring, and production features.
๐ Table of Contents
- ๐ค What is This?
- ๐ Features
- ๐ฆ Installation
- ๐ง Configuration
- ๐ Usage
- ๐ Security Features
- ๐งช Testing
- ๐ Performance
- ๐ Documentation
- ๐ ๏ธ Development
- ๐ณ Docker
- โ FAQ
- ๐ Support
- ๐ Changelog
- ๐ฎ Roadmap
- ๐ Acknowledgments
๐ค What is This? How Can It Help Me?
In Simple Terms:
If you're using Claude Code (an AI coding assistant), you may encounter "context too long" limitations when analyzing large code projects.
What Skim MCP Server Does:
- ๐ฆ Automatically compresses code, preserving structure while reducing 60-95% of content
- ๐ง Enables Claude Code to analyze larger projects
- โก Provides more accurate code suggestions and analysis
Prerequisites:
- โ You have Claude Code installed
- โ Your computer has Node.js 18.0.0 or higher installed
Not sure if you need this? If you frequently use Claude Code to analyze large codebases, this tool will be very helpful!
๐ Features
- ๐ Secure by Default - Path validation, input sanitization, rate limiting
- ๐ Production Monitoring - Structured logging, health checks, metrics
- ๐ High Performance - Fast execution with spawn, optimized buffering
- ๐ก๏ธ DoS Protection - Request limits, size limits, timeout handling
- ๐ Comprehensive Logging - Winston integration with configurable levels
- ๐งช Full Test Coverage - Unit and integration tests included
- ๐ฆ Zero Dependencies - Only MCP SDK and Winston (production dependencies)
๐ฆ Installation
Prerequisites
- Node.js >= 18.0.0
- npm, pnpm, or yarn
Option 1: Global Install (Recommended)
# Install both MCP server and Skim CLI
npm install -g skim-mcp
# Or install skim CLI separately
npm install -g rskim
Option 2: Project Install
# In your project directory
npm install skim-mcp
Option 3: From Source
git clone https://github.com/luw2007/skim-mcp.git
cd skim-mcp
npm install
npm run build
Automatic Skim Installation
The server automatically installs Skim CLI if not found:
# During npm install (postinstall hook)
npm install skim-mcp
# Or manually
npm run install-skim
Verify Installation
After installation, verify it was successful:
# Check if skim-mcp is available
skim-mcp --version
# Check Node.js version
node --version # Should be >= 18.0.0
If skim-mcp shows "command not found":
# Check globally installed packages
npm list -g skim-mcp
# Check npm global path
npm config get prefix
You may need to add the npm global path to your system PATH.
๐ง Configuration
Claude Code Settings
Locate and edit your Claude Code configuration file (depending on your operating system):
macOS / Linux:
~/.claude/config.json(recommended, try this first)- or
~/.config/claude-code/config.json
Windows:
C:\Users\YourUsername\.claude\config.json- or
C:\Users\YourUsername\AppData\Roaming\claude-code\config.json
If the file doesn't exist, create it.
Add the following configuration:
{
"mcpServers": {
"skim_mcp": {
"command": "skim-mcp"
}
}
}
โ ๏ธ Important: You must completely quit and restart Claude Code for the changes to take effect.
Environment Variables
# 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
Verify Configuration Success
After configuring and restarting Claude Code, test it:
- Open Claude Code
- Type in the conversation:
Help me analyze this project's code structure - Watch if Claude Code automatically uses the
mcp__skim__skim_analyzetool
Success indicators:
- You'll see messages like "Using skim tool to analyze code..." in the conversation
- Or see
skim_file/skim_analyzecalls in the tool invocation logs
If it doesn't work:
- Check if config file JSON format is valid (use jsonlint.com to validate)
- Confirm you completely quit and restarted Claude Code
- Check Claude Code's log files for error messages
๐ Usage
Once configured, the tools are automatically available in Claude Code:
Tool 1: skim_transform - Transform Source Code
Transform code from a string:
// 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)
Tool 2: skim_file - Transform Files
Transform file or directory:
mcp__skim__skim_file({
path: '/workspace/src',
mode: 'structure',
show_stats: true
})
// Returns compressed code with statistics
Tool 3: skim_analyze - Architecture Analysis
Analyze code architecture:
mcp__skim__skim_analyze({
path: '/workspace/src',
mode: 'structure'
})
// Returns:
// 1. Compressed code
// 2. Token statistics
// 3. Analysis framework to guide Claude
Real-World Usage Examples
Scenario 1: Analyzing Project Architecture
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
Scenario 2: Code Review
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
Scenario 3: Understanding Large Files
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
Key Point: You don't need to manually invoke these tools - Claude Code will automatically decide when to use them!
๐ Security Features
Path Validation
โ
Only absolute paths allowed
โ
Path traversal attacks blocked (../../../etc/passwd)
โ
Symlink resolution with validation
โ
Configurable allowed base paths
Input Sanitization
โ Maximum input size (10MB default) โ Null byte detection โ Command injection prevention โ Shell injection mitigation (parameterized commands)
Rate Limiting
โ Requests per minute limits โ Prevents DoS attacks โ Retry-after headers
๐งช Testing
Run Tests
# Install dependencies
npm install
# Run all tests
npm test
# Test with coverage
npm run test:coverage
# Watch mode for development
npm run test:watch
Test Coverage
- โ Skim CLI availability
- โ Path traversal prevention
- โ Input validation
- โ Oversized input detection
- โ Invalid language detection
- โ Null byte rejection
- โ Malformed path handling
๐ Performance
Benchmarks
# 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
Resource Limits
- Max input: 10MB per request
- Max output: 50MB buffer
- Timeout: 30 seconds per request
- Rate limit: 10 requests/minute
๐ Documentation
Transformation Modes
| Mode | Reduction | Use Case | Example Output |
|---|---|---|---|
| structure | 60-80% | Architecture analysis | function foo() { /* ... */ } |
| signatures | 85-92% | API documentation | function foo(): void |
| types | 90-95% | Type system analysis | interface User { name: string } |
| full | 0% | Debug/validation | Original code |
Supported Languages
- TypeScript / JavaScript
- Python
- Rust
- Go
- Java
- JSON (special structure mode)
- Markdown (header extraction)
- YAML / YML (structure extraction)
CLI Reference
# 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
๐ ๏ธ Development
Setup
git clone https://github.com/luw2007/skim-mcp.git
cd skim-mcp
npm install
Development Workflow
# 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
Project Structure
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 Image
docker build -t skim-mcp .
Run Container
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
๐ License
MIT License - see LICENSE file for details.
๐ค Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
Development Setup
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Ensure linting passes
- Submit a pull request
โ Frequently Asked Questions (Beginners Must Read)
Installation
Q1: Getting "skim-mcp: command not found"
Reason: npm global install path is not in your system PATH.
Solution:
# 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 version incompatibility error
Check your version:
node --version
Must be >= 18.0.0. If your version is too old, visit nodejs.org to download the latest LTS version.
Configuration
Q3: Can't find where the config file is
Try these locations in order:
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
Windows:
Search for config.json in File Explorer, or create it directly at:
C:\Users\YourUsername\.claude\config.json
Q4: Configuration has no effect
Checklist:
- Config file is valid JSON format (use jsonlint.com to validate)
- Completely quit Claude Code (not minimized, fully quit)
- Restart Claude Code
-
skim-mcpcommand works in terminal - Check Claude Code logs for error messages
Usage
Q5: When will the tool be automatically used?
Claude Code automatically uses Skim when:
- Analyzing large code files or directories
- Code review tasks
- Architecture analysis requests
- Understanding code structure
You don't need to manually invoke it - Claude Code will automatically decide when to use it.
Q6: How do I know Skim is working?
Watch Claude Code's conversation window for:
- Tool invocation messages:
mcp__skim__skim_fileormcp__skim__skim_analyze - Token statistics
- Messages like "Compressing code..." or similar
This indicates Skim is working.
Q7: Will Skim modify my code?
No! Skim only reads and compresses code for analysis - it will not modify any source files.
๐ Support
Reporting Issues
Please report issues on GitHub Issues.
Include:
- Node.js version (
node --version) - OS and architecture
- Steps to reproduce
- Error logs
Getting Help
- ๐ Documentation: docs/
- ๐ก Examples: docs/examples.md
- ๐ฌ Discussions: GitHub Discussions
๐ Changelog
See CHANGELOG.md for version history.
๐ฎ Roadmap
v1.1.0 (Next)
- HTTP transport support
- WebSocket transport
- Plugin system
- Custom transformation rules
- Integration with more LLM platforms
v1.2.0 (Future)
- Parallel processing optimization
- Memory-efficient streaming
- Advanced caching strategies
- Metrics dashboard
๐ Acknowledgments
Special Thanks
Skim Project and its Author @dean0x
This project is an MCP server wrapper built on top of the excellent Skim project created by dean0x. Skim is a powerful code transformation tool written in Rust that provides intelligent code compression capabilities for LLMs.
- Original Project: https://github.com/dean0x/skim
- Core Technology: Rust + tree-sitter
- Contribution: Provides 60-95% code compression capability
Without dean0x's outstanding work, this MCP server wouldn't exist. We highly recommend visiting the original project to learn more about the technical details!
Other Acknowledgments
- Model Context Protocol - MCP protocol specification
- tree-sitter - Code parsing engine
- Claude Code team - For providing an excellent AI coding assistant platform
- All developers who have contributed to this project
Made with โค๏ธ for the LLM community
