内容
# 技能树
一个MCP（模型上下文协议）服务器，提供可搜索、版本控制、分层结构的技能树，供AI工具发现、比较、下载和安装。
## 什么是技能树？
技能树是一个通用的**自托管技能注册表**。MCP服务器**提供技能本身** — 它们嵌入在软件包中 — 因此任何兼容MCP的客户端（Claude Desktop、Cursor、Kimi、自定义代理等）都可以浏览、搜索、比较和安装技能，而无需依赖外部文件系统路径。
技能是Markdown文件（`SKILL.md`），组织在目录层次结构中。每个技能都带有元数据（名称、描述、版本、标签、依赖项），并且可以位于四个范围之一：
| 范围 | 优先级 | 来源 |
|---|---|---|
| `built-in` | 最低 | **嵌入服务器软件包中** — 始终可用 |
| `extra` | 低 | 来自文件系统的可选社区包 |
| `user` | 中等 | `~/.config/agents/skills/`、 `~/.claude/skills/` （可选覆盖） |
| `project` | 最高 | 项目中的 `./.skills/` （可选覆盖） |
优先级较高的范围可以覆盖或扩展优先级较低的范围，但**服务器是主要来源** — 它自带一个全面的技能树。
## 功能
- **分层技能树** — 技能嵌套在目录中；树作为MCP资源公开
- **全文搜索** — 名称、描述、标签和内容的倒排索引，带有相关性评分
- **来源跟踪** — 每个技能都了解其来源（git、HTTP、嵌入、本地），并且可以检查远程更新
- **版本比较** — 带有已安装 vs 本地 vs 来源差异的语义版本控制
- **安装跟踪** — 记录已安装的技能及其版本
- **多重传输** — stdio（本地）、SSE/HTTP（远程/Docker）和原生REST API
- **Docker支持** — 一键容器化部署
- **CLI** — 查询、探索和检查来源，无需MCP客户端
## 快速开始
### 安装
```bash
pip install -e "."
```
### 运行stdio MCP（适用于Claude Desktop等）
```bash
skilltree-mcp stdio
```
在MCP客户端配置文件中添加：
```json
{
"mcpServers": {
"skilltree": {
"command": "skilltree-mcp",
"args": ["stdio"]
}
}
}
```
### 运行SSE/HTTP服务器
```bash
skilltree-mcp sse --host 0.0.0.0 --port 8080
```
然后通过SSE连接到 `http://localhost:8080/sse`。
### Docker
```bash
docker compose up --build
```
或手动：
```bash
docker build -t skilltree .
docker run -p 8080:8080 -v ./skills:/app/skills:ro skilltree
```
### CLI用法
```bash
# 列出所有技能
skilltree-mcp list
# 搜索
skilltree-mcp search docker
# 显示树
skilltree-mcp tree
# 检查来源是否有更新
skilltree-mcp check-updates
# 列出仅过时的技能
skilltree-mcp outdated
# JSON输出
skilltree-mcp list --format json
```
## MCP工具
| 工具 | 描述 |
|---|---|
| `list_skills` | 列出技能，可选范围/标签筛选 |
| `search_skills` | 全文搜索，带有相关性评分 |
| `get_skill` | 获取技能的完整详细信息和元数据 |
| `get_skill_tree` | 返回分层树结构 |
| `compare_skill` | 比较已安装 vs 本地 vs 来源版本 |
| `install_skill` | 标记技能为已安装（跟踪版本） |
| `check_updates` | 检查技能来源的更新 |
| `list_outdated` | 列出来源报告有更新版本的技能 |
| `sync_skill` | 从来源同步技能的元数据 |
| `refresh` | 重新扫描技能目录并重建索引 |
## MCP资源
每个技能都作为可读的MCP资源公开：
- `skill://built-in/docker-expert` — 读取Docker Expert技能内容
- `skill://user/my-custom-skill` — 读取用户定义的技能
## 技能格式
技能是一个目录，至少包含`SKILL.md`：
```text
src/skilltree/skills/built-in/devops/docker/
├── SKILL.md
└── skill.json # 可选的附属元数据
```
`SKILL.md` frontmatter：
```markdown
---
name: Docker Expert
description: 高级Docker容器化...
version: 2.1.0
tags: [docker, container, devops, security]
dependencies: []
origin_type: embedded
metadata:
author: skilltree
license: MIT
---
# Docker Expert
您的Markdown内容在这里...
```
### 来源元数据
技能可以声明其来源，以便服务器可以检查更新：
| 字段 | 值 | 描述 |
|---|---|---|
| `origin_type` | `embedded`, `git`, `http`, `local` | 如何检查更新 |
| `origin` | URL或路径 | Git仓库URL、HTTP端点或文件系统路径 |
| `origin_ref` | 分支、标签或子URL | Git引用或清单URL以查询 |
## 项目结构
```
skilltree/
├── src/skilltree/ # MCP服务器和注册表
│ ├── server.py # 带有工具和资源的MCP服务器
│ ├── registry.py # 技能发现和管理
│ ├── models.py # 数据模型（Skill, SkillTree, SemVer, Scope）
│ ├── search.py # 倒排索引搜索
│ ├── transport/ # stdio和SSE传输
│ ├── cli.py # CLI入口点
│ └── skills/ # **嵌入式内置技能树**
│ └── built-in/
│ ├── software-engineering/
│ ├── languages/
│ ├── devops/
│ ├── cloud/
│ ├── data-engineering/
│ ├── security/
│ ├── ai-ml/
│ ├── productivity/
│ ├── communication/
│ └── project-management/
├── tests/ # pytest套件
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml
```
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `SKILLTREE_HOST` | `127.0.0.1` | SSE服务器绑定地址 |
| `SKILLTREE_PORT` | `8080` | SSE服务器端口 |
## 贡献技能
在`src/skilltree/skills/built-in/`（嵌入软件包中）或任何配置的文件系统根目录中添加技能。运行`skilltree-mcp refresh`（或`refresh` MCP工具）以拾取它们。有关完整格式和流程，请参见 [docs/EXTENDING.md](docs/EXTENDING.md)。
## 文档
| 指南 | 内容 |
|---|---|
| [docs/BUILD_AND_TEST.md](docs/BUILD_AND_TEST.md) | 开发环境设置、linting、类型检查、运行测试、构建软件包、CI |
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Stdio vs SSE、Docker/docker-compose、配置、状态持久性、发布 |
| [docs/EXTENDING.md](docs/EXTENDING.md) | 架构概述、添加技能/范围/来源检查器/工具/传输 |
| [docs/ROADMAP.md](docs/ROADMAP.md) | 计划和提出的未来工作 |
| [CONTRIBUTING.md](CONTRIBUTING.md) | 如何贡献更改、PR约定、代码样式 |
## 开发与贡献
```bash
pip install -e ".[dev]"
pytest -v
```
欢迎贡献 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取工作流程和 [docs/BUILD_AND_TEST.md](docs/BUILD_AND_TEST.md) 以获取完整的构建/测试详细信息。
## 许可证
MIT
