Skim MCP Server

🚀 Production-ready Model Context Protocol server for Skim code transformation

Built on top of @dean0x's Skim project

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_analyze tool

Success indicators:

You'll see messages like "Using skim tool to analyze code..." in the conversation
Or see skim_file / skim_analyze calls 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-mcp command 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_file or mcp__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)

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

Skim