SkillMCP（技能管理系统）

一个容器化、可水平扩展的 Model Context Protocol (MCP) 服务器，用于分发和管理 AI 智能体技能。

概述与动机

AI 智能体依赖领域专属技能（指令、元数据、模式和参考资产）来执行复杂的工程与分析任务。然而，在多样化团队和智能体集群之间管理技能，往往会带来严峻的运维挑战：

• 技能碎片化与过期：技能存储在零散的个人仓库中，或通过手工复制维护，很快会失去同步，导致智能体执行过时或不兼容的工作流。

• 分发与更新瓶颈：在分布式智能体实例之间分发技能更新，需要人工同步或脆弱的文件复制步骤。

• 缺乏版本管理，诊断困难：在没有不可变版本管理的情况下编辑技能，几乎无法诊断回归问题或智能体行为变化。

• 单主机扩展性限制：传统基于 stdio 的 MCP 服务器绑定在单一本地主机进程上，阻碍了水平扩展和高可用性。

SkillMCP 通过提供一套以 无状态 Streamable HTTP（兼容旧版 SSE）为支撑的集中化、容器化且可水平扩展的技能管理系统，解决了上述挑战。

Related MCP server: SkillShare MCP Server

核心能力与特性

1. 集中化与版本化技能打包

• 不可变容器发布：技能（SKILL.md、references/、examples/）直接打包进带有明确 semver 标签（v1.2.0）的 Docker 镜像中，确保 100% 可复现的环境和可审计性。

• 统一技能仓库：在单一可维护的仓库中管理、校验并打包所有领域技能，消除多仓库碎片化造成的漂移。

• 快速排障与可追溯性：带版本管理的容器标签使诊断智能体问题、复现历史行为和即时回滚变更变得简单直接。

2. 基于 Streamable HTTP 的无状态 MCP（水平扩展）

• 真正无状态的请求/响应架构：Streamable HTTP 使用标准 HTTP POST 请求，后端实例在客户端调用之间不维护长期驻留内存的 socket 状态。

• 会话解耦与水平扩展：单个请求可路由到 Nginx 反向代理或负载均衡器后的任意后端容器副本，无需粘性会话。

• 短时流式传输：需要流式传输的响应仅在传输该特定载荷期间升级为 text/event-stream，一旦 JSON-RPC 响应结束便立即关闭。

• 旧版 SSE 兼容性：支持旧版 Server-Sent Events（/sse），通过配置代理缓冲绕过（proxy_buffering off）并延长读取超时，为需要持久通道的客户端提供支持。

• Nginx 入口负载均衡：配置了 least_conn 路由、keepalive 连接池以及专门的 /healthz 健康检查，支持零停机滚动更新。

[!WARNING] 传输与水平扩展性：

• Streamable HTTP（default，推荐）：真正无状态。支持跨副本的水平自动扩缩容和任意负载均衡，无需会话亲和性。

• 原生 SSE（SKILLMCP_TRANSPORT=sse）：由于绑定了持久的 TCP 流，因此属于有状态模式。在原生 SSE 模式下，如果在标准 round-robin/least-connections 负载均衡器之后进行水平扩展，将导致 POST /messages 路由错误，除非使用粘性会话（如 Nginx ip_hash 或 cookie 亲和性），或采用单副本部署。

3. 开发者与智能体工具

• 内置技能校验器 CLI：skillmcp validate ./skills 会在打包前自动校验目录结构、YAML frontmatter 和资产链接。

• 动态发现与搜索：

  • MCP 工具：list_skills、get_skill、search_skills、read_skill_reference、read_skill_example。

  • MCP 资源：skill://{name} 用于直接检视 markdown 文档。

• 双 Compose 环境：docker-compose.local.yml 用于即时本地开发（通过卷挂载实现热重载），docker-compose.yml 用于生产部署。

• TREM Python 标准：严格遵循可测试、可读、可扩展、可维护（TREM）原则构建，使用 uv、pydantic-settings、标准库 logging 和 pytest。

• 自动化 CI/CD 发布：GitHub Actions 流水线在版本标签（v*.*.*）上校验测试，并将不可变的 semver 版本发布到 Docker Hub。

快速开始

前置条件

• Python 3.11+

• uv

• Docker & Docker Compose

本地安装

# Sync dependencies
uv sync

# Run tests
uv run pytest -v

# Validate skills
uv run skillmcp validate ./skills

# List discovered skills
uv run skillmcp list --skills-path ./skills

本地运行服务器

# Start MCP server directly (Streamable HTTP on port 8000)
uv run skillmcp serve --host 0.0.0.0 --port 8000

Docker 拓扑

本地开发（热重载与入口）

docker compose -f docker-compose.local.yml up -d --build

• Nginx 入口：http://localhost:8080（/healthz 健康检查）

• 后端应用：http://localhost:8000（/healthz 健康检查）

生产部署

docker compose up -d

测试接缝

• 接缝 1：领域服务：tests/test_domain_service.py（校验扫描器、解析器、遍历安全性及查询引擎）

• 接缝 2：MCP 协议与工具：tests/test_mcp_server.py 与 tests/test_mcp_http.py（校验 FastMCP 工具、资源及 ASGI 传输路由）

• 接缝 3：CLI 与集成：tests/test_cli.py（校验 CLI 的 validator、list 和 serve 命令）