Skill MCP

🚀 技能管理MCP服務器

技能管理MCP服務器是一個模型上下文協議（MCP）服務器，它使Claude能夠管理存儲在 ~/.skill-mcp/skills 中的技能。該系統允許Claude以編程方式創建、編輯、運行和管理技能，包括使用環境變量執行技能腳本。

🚀 快速開始

1. 安裝uv

本項目使用 uv 進行快速、可靠的Python包管理。

# 安裝uv（包含uvx）
curl -LsSf https://astral.sh/uv/install.sh | sh

2. 配置MCP客戶端

將MCP服務器添加到您的配置中。服務器將通過 uvx 從PyPI自動下載並運行。

• Claude桌面版：編輯配置文件
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • Linux：~/.config/Claude/claude_desktop_config.json
• Cursor：編輯配置文件
  • macOS：~/.cursor/mcp.json
  • Windows：%USERPROFILE%\.cursor\mcp.json
  • Linux：~/.cursor/mcp.json

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "skill-mcp",
        "skill-mcp-server"
      ]
    }
  }
}

就是這樣！無需安裝 - uvx 將自動從PyPI下載並運行最新版本。

3. 重啟MCP客戶端

重啟Claude桌面版或Cursor以加載MCP服務器。

4. 測試

在新的對話中輸入：

List all available skills

Claude應該使用 skill-mcp 工具顯示 ~/.skill-mcp/skills/ 中的技能。

✨ 主要特性

🚀 統一的多技能執行（使用MCP進行代碼執行）

• 一次構建，隨處組合：執行Python代碼，可在單次運行中無縫組合多個技能。

# 一次執行，統一多個技能！
# 從計算器、數據處理器和天氣技能中導入
from math_utils import calculate_average          # 計算器技能
from json_fetcher import fetch_json                # 數據處理器技能
from weather_api import get_forecast               # 天氣技能

# 獲取天氣數據
weather = fetch_json('https://api.weather.com/cities')

# 使用計算器工具計算平均值
temps = [city['temp'] for city in weather['cities']]
avg_temp = calculate_average(temps)

# 獲取詳細預報
forecast = get_forecast('London')
print(f"Average temperature: {avg_temp}°F")
print(f"London forecast: {forecast}")

• 強大之處：
  • ✅ 上下文高效：自動聚合所有引用技能的依賴項和環境變量。
  • ✅ 可組合：像搭建積木一樣混合和匹配任何技能的工具。
  • ✅ 無冗餘：在庫技能中聲明一次PEP 723依賴項，可在任何地方重複使用。
  • ✅ 漸進式披露：僅在需要時加載所需的技能。
  • ✅ 遵循Anthropic的MCP模式：使用MCP進行代碼執行，實現高效代理。
• 效率提升：
  • 📉 與一次性加載所有工具相比，漸進式發現工具時減少98.7%的令牌使用。
  • 🔄 中間結果保留在代碼中，處理大型數據集時不會使上下文膨脹。
  • ⚡ 單次執行，將複雜的多步驟工作流放在一個代碼塊中，而不是鏈式調用工具。

🔓 不侷限於Claude界面

與Claude界面不同，該系統使用 模型上下文協議（MCP），具有以下特點：

• ✅ 通用：可與Claude桌面版、claude.ai、Cursor和任何支持MCP的客戶端一起使用。
• ✅ 不依賴Claude：相同的技能可在所有支持MCP的地方使用。
• ✅ 面向未來：不依賴Claude的生態系統或政策變化。
• ✅ 本地優先：完全控制您的技能和數據。

🎯 技能隨處可用

您的技能可以在以下環境中運行：

• Cursor：支持MCP的集成開發環境。
• Claude桌面版：支持MCP的原生應用程序。
• claude.ai：支持MCP的Web界面。
• 任何MCP客戶端：不斷發展的兼容應用程序生態系統。

📦 獨立且模塊化

• ✅ 每個技能都是自包含的，有自己的文件、腳本和環境。
• ✅ 不依賴Claude的專有功能。
• ✅ 可以進行版本控制、共享和在項目間重用。
• ✅ 標準的MCP協議確保兼容性。

🔄 在所有MCP客戶端之間共享技能

• ✅ 一個技能目錄，多個客戶端：創建一次，隨處使用。
• ✅ Cursor和Claude中使用相同的技能：無需重複。
• ✅ 無縫切換：在工具之間切換時無需重新配置。
• ✅ 一致的體驗：技能在所有MCP客戶端中的工作方式相同。
• ✅ 集中管理：在一處更新技能，所有地方都可用。

🤖 由大語言模型管理的技能（無需手動複製粘貼）

❌ 舊方式：手動流程
   1. 在本地創建技能文件
   2. 壓縮技能文件夾
   3. 上傳到Claude界面
   4. 等待處理
   5. 難以修改或進行版本控制

✅ 新方式：由大語言模型以編程方式管理
   1. 告訴Claude：“Create a new skill called 'data-processor'”
   2. Claude創建技能目錄和SKILL.md
   3. 告訴Claude：“Add a Python script to process CSVs”
   4. Claude創建並測試腳本
   5. 告訴Claude：“Set the API key for this skill”
   6. Claude更新.env文件
   7. 告訴Claude：“Run the script with this data”
   8. Claude立即執行並顯示結果！

• 主要優點：
  • ✅ 無需手動文件操作：大語言模型處理創建、編輯和刪除。
  • ✅ 即時更改：無需上傳/下載/重新加載週期。
  • ✅ 完整的版本控制：技能是普通文件，可使用git。
  • ✅ 易於修改：大語言模型可以即時編輯腳本。
  • ✅ 可測試：大語言模型可以立即創建並運行腳本。
  • ✅ 協作性：團隊可以通過MCP共同開發技能。

📦 安裝指南

從PyPI安裝

若要全局安裝該軟件包（可選）：

pip install skill-mcp

或者使用 uvx 無需安裝即可運行（推薦）：

uvx --from skill-mcp skill-mcp-server

開發環境設置

如果您想貢獻代碼或從源代碼運行：

# 克隆倉庫
git clone https://github.com/fkesheh/skill-mcp.git
cd skill-mcp

# 安裝依賴項
uv sync

# 運行測試
uv run pytest

# 在本地運行服務器
uv run -m skill_mcp.server

若要在MCP客戶端配置中使用本地開發版本：

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/skill-mcp",
        "-m",
        "skill_mcp.server"
      ]
    }
  }
}

💻 使用示例

創建新技能

用戶：“Create a new skill called 'pdf-processor' that can rotate and merge PDFs”

Claude將：
1. 創建技能目錄和SKILL.md
2. 添加任何必要的腳本
3. 測試腳本
4. 指導您設置任何所需的依賴項

管理環境變量

用戶：“I need to set up a GitHub API token for my GitHub skills”

Claude將：
1. 指導您將其添加到技能的.env文件中
2. 使用 `read_skill_env` 列出可用的鍵
3. 確認腳本可以通過 `os.environ` 使用它

運行技能腳本

用戶：“Run the data processing script from my analytics skill”

Claude將：
1. 列出可用的技能和腳本
2. 使用環境變量執行腳本
3. 向您顯示輸出和任何錯誤

修改現有技能

用戶：“Add a new reference document about our API schema to the company-knowledge skill”

Claude將：
1. 讀取現有技能結構
2. 創建新的參考文件
3. 如果需要，更新SKILL.md以引用它

📚 詳細文檔

可用的MCP工具

服務器為Claude提供了以下統一的CRUD工具：

CRUD工具操作

skill_crud 操作

• list：列出所有技能，包括描述、路徑和驗證狀態（支持文本/正則搜索）。
• get：獲取全面的技能信息：SKILL.md內容、所有文件、腳本、環境變量。
• create：從模板（基本、Python、Bash、Node.js）創建新技能。
• delete：刪除技能目錄（需要確認）。
• validate：驗證技能結構並獲取診斷信息。
• list_templates：列出所有可用的技能模板及其描述。

skill_files_crud 操作

• read：讀取技能目錄中的一個或多個文件（支持批量讀取）。
• create：創建一個或多個文件（自動創建父目錄，支持原子批量創建）。
• update：更新一個或多個現有文件（支持批量更新）。
• delete：永久刪除文件（防止路徑遍歷，不能刪除SKILL.md）。

skill_env_crud 操作

• read：列出技能的環境變量鍵（為安全起見，隱藏值）。
• set：設置一個或多個環境變量（與現有變量合併）。
• delete：刪除一個或多個環境變量。
• clear：清除技能的所有環境變量。

腳本執行

• run_skill_script：執行腳本，自動檢測PEP 723依賴項並注入環境變量。
• execute_python_code：直接執行Python代碼（支持PEP 723依賴項和跨技能導入）。

高級配置

自定義技能目錄

可以使用 SKILL_MCP_DIR 環境變量自定義技能目錄。如果未設置，默認為 ~/.skill-mcp/skills。

• 通過環境變量設置（推薦）：

# 臨時設置，僅對當前會話有效
export SKILL_MCP_DIR="/custom/path/to/skills"

# 永久設置，在shell配置文件中（如~/.bashrc、~/.zshrc等）
echo 'export SKILL_MCP_DIR="/custom/path/to/skills"' >> ~/.zshrc

• 在MCP客戶端配置中設置： 對於Claude桌面版或Cursor，將環境變量添加到MCP配置中：

{
  "mcpServers": {
    "skill-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "skill-mcp",
        "skill-mcp-server"
      ],
      "env": {
        "SKILL_MCP_DIR": "/custom/path/to/skills"
      }
    }
  }
}

注意：

• 如果目錄不存在，將自動創建。
• 使用自定義目錄的絕對路徑。
• 所有技能都將存儲在配置的目錄中。
• 沒有全局秘密文件；環境變量存儲在每個技能的 .env 文件中。

資源限制

資源限制在 src/skill_mcp/core/config.py 中定義：

MAX_FILE_SIZE = 1_000_000      # 文件讀取限制（1MB）
MAX_OUTPUT_SIZE = 100_000      # 腳本輸出限制（100KB）
SCRIPT_TIMEOUT_SECONDS = 30    # 腳本執行超時時間

要修改這些限制，需要分叉倉庫並在配置文件中調整常量。

🔧 技術細節

包結構

src/skill_mcp/
├── server.py              # MCP服務器入口點
├── models.py              # Pydantic輸入/輸出模型（向後兼容）
├── models_crud.py         # 統一的CRUD輸入模型
├── core/
│   ├── config.py          # 配置常量
│   └── exceptions.py      # 自定義異常類型
├── services/
│   ├── env_service.py     # 環境變量CRUD
│   ├── file_service.py    # 文件CRUD操作
│   ├── skill_service.py   # 技能發現和元數據
│   ├── script_service.py  # 腳本執行和PEP 723
│   └── template_service.py # 模板管理
├── utils/
│   ├── path_utils.py      # 安全路徑驗證
│   ├── yaml_parser.py     # YAML前置元數據解析
│   └── script_detector.py # 腳本能力檢測
└── tools/
    ├── skill_crud.py      # 統一的技能CRUD工具
    ├── skill_files_crud.py # 統一的文件CRUD工具
    ├── skill_env_crud.py  # 統一的環境變量CRUD工具
    └── script_tools.py    # 腳本執行工具

tests/
├── conftest.py            # Pytest測試夾具
└── 20+ 個測試模塊       # 145個測試（86%覆蓋率通過）

新特性

統一的CRUD架構

• ✅ 3個統一的CRUD工具：取代9個以上的單獨工具（skill_crud、skill_files_crud、skill_env_crud）。
• ✅ 批量操作：原子性地創建/更新/刪除多個文件。
• ✅ 一致的模式：所有工具遵循相同的基於操作的模型。
• ✅ 更好的錯誤處理：所有操作的統一錯誤響應。

直接Python執行（多技能統一）

• 🚀 execute_python_code：在一次執行中統一多個技能（Anthropic推薦的MCP模式）。
• ✅ 跨技能導入：從任何技能導入模塊作為可重用庫。
• ✅ 自動依賴聚合：自動合併所有導入技能的依賴項。
• ✅ 自動環境加載：自動加載所有引用技能的 .env 文件。
• ✅ 支持PEP 723：內聯依賴聲明。
• 📉 減少98.7%的令牌使用：漸進式加載技能，而不是一次性加載所有技能。

增強功能

• ✅ 技能模板：從模板（基本、Python、Bash、Node.js）創建技能。
• ✅ 模板發現：列出所有可用模板及其描述。
• ✅ 技能驗證：驗證技能結構並獲取診斷信息。
• ✅ 搜索功能：通過名稱/描述使用文本或正則表達式搜索技能。
• ✅ 命名空間路徑：文件路徑顯示為 "skill_name:file.py"，以提高清晰度。
• ✅ 可配置的技能目錄：使用 SKILL_MCP_DIR 環境變量。

測試結果

單元測試：145/145通過 ✅

覆蓋率：86%（959/1120條語句被覆蓋） 對所有模塊進行了全面的測試覆蓋：

測試組織：

• ✅ CRUD操作：對所有操作（創建、讀取、更新、刪除）進行全面測試。
• ✅ 批量操作：對文件操作進行原子事務測試。
• ✅ 模板系統：模板發現、驗證和創建。
• ✅ 路徑安全：防止目錄遍歷和驗證。
• ✅ 支持PEP 723：依賴項檢測和聚合。
• ✅ 集成測試：完整的MCP服務器工作流測試。

手動測試：全部通過 ✅

• ✅ 列出帶有YAML描述的技能並具有搜索功能。
• ✅ 獲取包含SKILL.md內容的全面技能詳細信息。
• ✅ 從模板（基本、Python、Bash、Node.js）創建技能。
• ✅ 讀取/創建/更新/刪除文件（單個和批量）。
• ✅ 讀取/設置/刪除/清除環境變量。
• ✅ 執行帶有自動依賴項（PEP 723）的腳本。
• ✅ 直接執行帶有跨技能導入的Python代碼。
• ✅ 從導入的技能模塊聚合依賴項。
• ✅ 從引用的技能加載環境變量。

驗證清單

• ✅ 服務器成功導入。
• ✅ 所有5個統一的CRUD工具已註冊並可調用。
• ✅ 145/145個單元測試通過（86%覆蓋率）。
• ✅ 所有手動測試通過。
• ✅ MCP客戶端配置正常工作（Claude桌面版、Cursor）。
• ✅ 軟件包已部署到PyPI並處於活動狀態。
• ✅ 腳本使用PEP 723依賴項成功執行。
• ✅ 文件操作正常工作（包括批量操作）。
• ✅ 環境變量操作正常工作（CRUD操作）。
• ✅ 模板系統正常工作（創建、列出、驗證）。
• ✅ 直接Python執行與跨技能導入正常工作。
• ✅ 與現有技能向後兼容。

📄 許可證

本項目採用MIT許可證。

版權所有 (c) 2025

特此免費授予任何獲得本軟件及相關文檔文件（“軟件”）副本的人，允許其無限制地處理本軟件，包括但不限於使用、複製、修改、合併、發佈、分發、再許可和/或出售軟件副本的權利，並允許向其提供軟件的人這樣做，但需遵守以下條件：

上述版權聲明和本許可聲明應包含在所有副本或軟件的重要部分中。

軟件按“原樣”提供，不附帶任何形式的明示或暗示保證，包括但不限於適銷性、特定用途適用性和不侵權的保證。在任何情況下，作者或版權持有人均不對因合同、侵權或其他方式引起的任何索賠、損害或其他責任負責，無論是在與軟件或軟件的使用或其他交易相關的任何行動中。

貢獻說明

這是一個供個人使用的自定義工具。您可以自由分叉並根據自己的需求進行調整。

支持

如果您在設置過程中遇到問題或有疑問，請參考以下文檔：

• Claude的MCP文檔：https://modelcontextprotocol.io
• MCP Python SDK文檔：https://github.com/modelcontextprotocol/python-sdk

⚠️ 重要提示

最佳實踐

技能開發

• 遵循標準的技能結構（SKILL.md、scripts/、references/、assets/）。
• 保持SKILL.md簡潔明瞭。
• 使用漸進式披露（將大型文檔拆分為參考文件）。
• 創建腳本後立即進行測試。

環境變量

• 使用描述性名稱（如 API_KEY、DATABASE_URL）。
• 切勿記錄或打印敏感值。
• 設置 .env 文件的權限：chmod 600 ~/.skill-mcp/skills/<skill-name>/.env。

腳本開發

• 使用有意義的退出代碼（0表示成功）。
• 向標準輸出打印有用的消息。
• 向標準錯誤輸出打印錯誤信息。
• 包含錯誤處理。
• 對於有依賴項的Python腳本：使用內聯元數據（PEP 723）。

# /// script
# dependencies = [
#   "package-name>=version",
# ]
# ///

• 沒有元數據的腳本使用系統Python解釋器。
• 有元數據的腳本通過uv自動獲得隔離環境。

安全管理敏感機密

為防止大語言模型訪問您的敏感憑證：

# 直接在文件系統上編輯技能的.env文件（大語言模型無法訪問您的本地文件）
nano ~/.skill-mcp/skills/my-skill/.env

# 手動添加您的機密信息
API_KEY=your-actual-api-key-here
DATABASE_PASSWORD=your-password-here
OAUTH_TOKEN=your-token-here

# 保護文件安全
chmod 600 ~/.skill-mcp/skills/my-skill/.env

• 重要原因：
  • ✅ 大語言模型永遠不會看到您的敏感值。
  • ✅ 機密信息僅保留在您的系統中。
  • ✅ 沒有憑證出現在日誌或輸出中的風險。
  • ✅ 完全控制敏感數據。
  • ✅ 可以與 git-secret 或類似工具一起用於版本控制。
• 工作流程：
  1. Claude創建技能結構和腳本。
  2. 您手動將敏感值添加到 .env 文件中。
  3. Claude可以讀取 .env 鍵（看不到值）並使用它們。
  4. 腳本在運行時通過環境變量訪問機密信息。
• 示例：

# 步驟1：Claude通過MCP創建技能 "api-client"
# 您說：“Create a new skill called 'api-client'”

# 步驟2：您手動保護機密信息
$ nano ~/.skill-mcp/skills/api-client/.env
API_KEY=sk-abc123def456xyz789
ENDPOINT=https://api.example.com

$ chmod 600 ~/.skill-mcp/skills/api-client/.env

# 步驟3：Claude現在可以安全地使用該技能
# 您說：“Run the API client script”
# Claude僅讀取環境變量名稱，並在腳本中使用它們
# 您的實際API密鑰永遠不會暴露給Claude

• ❌ 切勿這樣做：
  • ❌ 告訴Claude您的實際API密鑰或密碼。
  • ❌ 要求Claude設置帶有敏感值的環境變量。
  • ❌ 將機密信息存儲在SKILL.md或其他跟蹤文件中。
  • ❌ 使用 update_skill_env 工具處理真實的機密信息（僅用於非敏感配置）。
• ✅ 應該這樣做：
  • ✅ 在您的系統上手動更新 .env 文件。
  • ✅ 將 .env 文件添加到 .gitignore 中。
  • ✅ 使用 chmod 600 限制文件訪問。
  • ✅ 僅告訴Claude變量名稱（例如，“the API key is in API_KEY”）。
  • ✅ 使機密信息與大語言模型交互完全分離。

驗證大語言模型生成的代碼

當Claude或其他大語言模型使用此MCP系統創建或修改技能和腳本時，在生產環境中運行之前，始終驗證生成的代碼：

安全考慮

• ⚠️ 始終審查生成的代碼：大語言模型可能會出錯或生成次優代碼。
• ⚠️ 檢查安全問題：查找硬編碼的憑證、不安全的操作或漏洞。
• ⚠️ 徹底測試：首先在隔離環境中運行腳本。
• ⚠️ 驗證權限：確保腳本具有適當的文件和系統權限。
• ⚠️ 監控依賴項：審查通過PEP 723安裝的任何外部軟件包。

大語言模型生成技能的最佳實踐

1. 執行前審查：始終通讀生成的腳本。
2. 在隔離環境中測試：在生產使用之前在安全環境中運行。
3. 使用版本控制：使用git跟蹤所有更改以進行審計。
4. 實施錯誤處理：添加強大的錯誤處理和日誌記錄。
5. 設置資源限制：使用超時和資源約束。
6. 以最小權限運行：不要以root或提升的權限運行技能。
7. 驗證輸入：清理任何用戶提供的數據。
8. 審計日誌：審查腳本實際執行的操作並跟蹤其執行情況。

常見檢查項

• ❌ 硬編碼的API密鑰、密碼或令牌。
• ❌ 不安全的文件操作或路徑遍歷風險。
• ❌ 未驗證的外部命令或shell注入風險。
• ❌ 缺少錯誤處理或邊緣情況處理。
• ❌ 無限制的資源密集型操作。
• ❌ 不安全的反序列化（如 eval、pickle 等）。
• ❌ 請求過多權限。
• ❌ 不可信的外部依賴項。

有疑問時

• 要求Claude/大語言模型解釋代碼。
• 讓其他人審查關鍵代碼。
• 使用代碼檢查器和安全掃描工具。
• 在容器或虛擬機中運行以進行隔離。
• 在進行破壞性操作之前先進行只讀操作。

請記住：大語言模型生成的代碼只是一個起點。您的驗證和審查對於安全性和可靠性至關重要。