MCP Skill Server

🚀 MCP技能服務器

MCP技能服務器可讓你在日常工作中構建代理技能。如今，大多數編碼助手都原生支持技能，因此單純用於技能發現的MCP服務器並非必要。此軟件包的價值在於使技能的執行具有確定性和可部署性 —— 通過固定的入口點和可控的執行方式，你在編輯器中開發的技能可以在非沙盒的生產環境中運行。它還支持增量加載，這樣代理可以按需發現技能，而不是預先加載所有內容。

🚀 快速開始

構建代理技能的步驟非常簡單。你只需編寫一個Python腳本，添加一個 SKILL.md 文件，你的代理就能立即使用該技能。你可以在日常工作流程中即時迭代。當技能準備好後，無需重寫代碼，即可將相同的技能部署到生產環境。

✨ 主要特性

高效開發流程

大多數技能開發流程通常是：編寫代碼 → 部署 → 在測試代理中測試 → 發現問題 → 重新部署 → 重複上述步驟。這種流程效率低下，而且在構建技能時無法真正使用它。MCP技能服務器改變了這一現狀，它可以在你的機器上、編輯器（如Claude Code、Cursor或Claude Desktop）中運行。你可以在開發技能的同時在實際工作中使用它。這種緊密的反饋循環（編輯 → 保存 → 使用）意味著你可以自然地發現技能的不足之處，而不是通過人為的測試場景。

技能成熟路徑

Claude技能可以有配套腳本，但沒有正式的入口點 —— 代理決定如何調用它們。這適用於本地使用，但無法部署：如果執行路徑不固定，生產環境中的MCP服務器就無法可靠地調用技能。MCP技能服務器強制要求在 SKILL.md 前置元數據中聲明 entry 字段（例如 entry: uv run python my_script.py）。這為你提供了一個由服務器控制的固定入口點。命令和參數從腳本的 --help 輸出中發現 —— 這是事實來源，而不是大語言模型對代碼的解釋。

1. Claude/編碼代理技能                → SKILL.md + 腳本，但沒有固定入口 — 代理決定如何運行它們
2. 本地MCP技能 (+ 入口)   → 固定入口點，從 --help 獲取架構，可通過此服務器日常使用
3. 生產環境                  → 相同的技能，相同的入口 — 部署到企業MCP服務器

本地打磨，生產強化

連接到MCP服務器的每個代理都有相同的接口 —— list_skills、get_skill、run_skill —— 因此無論哪個代理調用，技能的描述、參數名稱和幫助文本都是相同的。不過，不同的代理有不同的優勢 —— 本地運行良好的技能仍需要在生產代理中進行測試。

1. 親自使用 —— 構建技能，通過Claude Code或Cursor日常使用。當代理誤用技能時，修復描述和參數名稱。
2. 使用較弱的模型進行測試 —— 嘗試使用較小的模型來發現接口的歧義。
3. 添加確定性入口點 —— 在 SKILL.md 中聲明 entry 以實現可靠、安全的執行。使用 skill init 搭建框架，使用 skill validate 檢查是否準備好。
4. 在生產代理中測試 —— 在目標環境中進行端到端驗證，然後部署。

📦 安裝指南

Claude Desktop（一鍵安裝）

安裝後，在Claude Desktop配置中編輯技能路徑，使其指向你的技能目錄。

Claude Code

claude mcp add skills -- uvx mcp-skill-server serve /path/to/my/skills

Cursor

將以下內容添加到項目的 .cursor/mcp.json 中（或在設置 → MCP → 添加服務器中操作）：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["mcp-skill-server", "serve", "/path/to/my/skills"]
    }
  }
}

手動安裝

# 從PyPI安裝（推薦）
uv pip install mcp-skill-server

# 或從源代碼安裝
git clone https://github.com/jcc-ne/mcp-skill-server
cd mcp-skill-server && uv sync

# 運行服務器
uvx mcp-skill-server serve /path/to/my/skills

然後將以下內容添加到編輯器的MCP配置中：

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["mcp-skill-server", "serve", "/path/to/my/skills"]
    }
  }
}

💻 使用示例

創建技能

選項A：使用 skill init（推薦）

# 創建新技能
uv run mcp-skill-server init ./my_skills/hello -n "hello" -d "A friendly greeting"

# 或使用獨立命令
uv run mcp-skill-init ./my_skills/hello -n "hello" -d "A friendly greeting"

# 將現有的僅提示Claude技能提升為可運行的MCP技能
uv run mcp-skill-init ./existing_claude_skill

選項B：手動設置

1. 創建一個包含腳本的文件夾

my_skills/
└── hello/
    ├── SKILL.md
    └── hello.py

2. 添加帶有前置元數據的 SKILL.md

---
name: hello
description: A friendly greeting skill
entry: uv run python hello.py
---

# Hello Skill

Greets the user by name.

3. 使用 argparse 編寫腳本

# hello.py
import argparse

parser = argparse.ArgumentParser(description="Greeting skill")
parser.add_argument("--name", default="World", help="Name to greet")
args = parser.parse_args()

print(f"Hello, {args.name}!")

驗證部署

當技能準備好部署到生產環境時：

uv run mcp-skill-server validate ./my_skills/hello
# 或
uv run mcp-skill-validate ./my_skills/hello

檢查內容包括：

• 必需的前置元數據字段（名稱、描述、入口）
• 入口命令使用允許的運行時
• 腳本文件存在
• 命令可通過 --help 發現

📚 詳細文檔

MCP工具

服務器向代理公開了四個工具：

架構發現

服務器通過解析 --help 輸出來自動發現技能的接口：

# 子命令成為單獨的命令
subparsers = parser.add_subparsers(dest='command')
analyze = subparsers.add_parser('analyze', help='Run analysis')

# 參數成為具有推斷類型的參數
analyze.add_argument('--year', type=int, required=True)  # int, required
analyze.add_argument('--file', type=str)                  # string, optional

輸出文件

保存到 output/ 目錄的文件會被自動檢測。或者，你可以將 OUTPUT_FILE:/path/to/file 打印到標準輸出。

🔧 技術細節

插件

輸出處理程序

處理技能生成的文件（上傳、複製、轉換等）：

from mcp_skill_server.plugins import OutputHandler, LocalOutputHandler

# 默認：跟蹤本地文件路徑
handler = LocalOutputHandler()

# 可選的GCS處理程序（需要 `uv sync --extra gcs`）
from mcp_skill_server.plugins import GCSOutputHandler
handler = GCSOutputHandler(
    bucket_name="my-bucket",
    folder_prefix="skills/outputs/",
)

響應格式化器

自定義MCP工具響應中執行結果的格式：

from mcp_skill_server.plugins import ResponseFormatter

class CustomFormatter(ResponseFormatter):
    def format_execution_result(self, result, skill, command):
        return f"Result: {result.stdout}"

# 與 create_server() 一起使用
from mcp_skill_server import create_server
server = create_server(
    "/path/to/skills",
    response_formatter=CustomFormatter()
)

開發

git clone https://github.com/jcc-ne/mcp-skill-server
cd mcp-skill-server
uv sync --dev
uv run pytest
uv run mcp-skill-server serve examples/

擴展閱讀

• 大語言模型的工具設計 —— 為什麼技能使用列表/獲取/運行模式而不是直接暴露原始工具，以及這如何影響大語言模型的準確性

📄 許可證

本項目採用MIT許可證。