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许可证。