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 代碼助手平臺
• 所有為這個項目做出貢獻的開發者

為大語言模型社區用心打造 ❤️