使用说明

🛠️ MCP服务器技能

一个集中式、沙盒化的模型上下文协议（MCP）服务器，旨在管理、执行和公开高级 代理技能 任何支持MCP的框架或低代码平台（如n8n、自定义代理等）。

💡 它解决的问题

目前，许多流行的编排框架和低代码平台只支持基本的工具或 主控程序然而，现代人工智能代理需要完全封装、复杂的 代理技能 （提示、工具链和逻辑相结合）。 Agno框架 本机支持这些高级代理技能，但将它们引入n8n或自定义代理系统等平台历来是一个挑战。

skills_mcp_server 是桥。 通过将Agno技能封装在隔离的FastAPI服务器中并通过通用模型上下文协议（MCP）公开它们，任何支持MCP的系统现在可以立即利用复杂的代理技能。

✨ 关键优势

🎯 选择性技能暴露（情境优化）： 在服务器上安装一个庞大的技能库，但只公开特定代理所需的确切技能。通过为每个代理定制技能列表，您可以防止LLM上下文膨胀，节省令牌，并大大提高代理的准确性。
🗄️ 集中技能中心： 停止将自定义脚本和函数分散在不同的存储库或n8n节点上。在一个统一、易于更新的服务器中管理整个组织的人工智能功能。
🔒 沙盒执行： 所有技能都在孤立的环境中运行。您可以安全地安装第三方社区技能，而不会危及主机应用程序或主要基础设施的完整性。
📦 自动依赖隔离： 技能包括 requirements.txt 使用以下命令自动为文件配置专用虚拟环境 uv这确保了完美的隔离和干净的卸载，而不会增加主服务器的依赖关系。
🧠 由Agno提供技术支持： 超越简单的工具。利用Agno构建丰富的、有状态的代理技能，可以在通过MCP返回最终有效载荷之前处理复杂的多步推理。
📦 动态热负荷： 使用动态添加、更新或删除技能 .zip 文件，自定义 .skill 而无需重新启动服务器。

🏗️ 建筑概念

该系统在双接口架构上运行：

REST API（管理器）： 一个用于动态安装、更新、列出和删除技能的控制平面。它充当您的私人技能库。
MCP服务器（提供商）： 执行平面将精心策划的技能列表安全地暴露给具有MCP能力的代理（n8n、Cursor、Claude Desktop等）。

🚀 需求

紫外线（极快的Python包安装程序和解析器）
Python 3.12+
快速API
FastMCP
硝酸银

🛠️ 安装和设置

克隆存储库：

git clone [https://github.com/chameleonbr/skills_mcp_server.git](https://github.com/chameleonbr/skills_mcp_server.git)
cd skills_mcp_server

配置环境：

cp env.example .env
# Edit .env and set API_KEY and SKILLS_DIR

安装依赖项：
```
uv sync
```
运行服务器：
```
uv run uvicorn main:app --reload
```

码头工人

docker-compose up --build

🧪 运行测试

该项目包括一个全面的单元测试套件，涵盖模型、路由、服务和MCP服务器。

要运行测试，请确保已安装开发依赖项，然后使用 pytest:

uv run pytest -v tests/

要运行具有覆盖率报告的测试，请执行以下操作：

uv run pytest --cov=. tests/

🗂️ 项目结构

skills_mcp_server/
├── main.py          # FastAPI app + FastMCP mount + lifespan
├── routes.py        # REST API routes (/skills)
├── services.py      # SkillManager (install, delete, reload, GitHub support)
├── mcp_server.py    # FastMCP server with Agno skill tools
├── models.py        # Pydantic request/response schemas
├── s3_skills.py     # S3Skills loader (sync from S3 bucket → LocalSkills)
├── skills/          # Skill folders (each must contain SKILL.md)
├── pyproject.toml
└── Dockerfile / docker-compose.yml

🔑 认证

全部 /skills 路线需要 X-API-Key 头球

-H "X-API-Key: your_api_key"

集 API_KEY 在你的 .env 文件。

📡 REST API-控制平面

交互式文档可在 http://localhost:8000/docs.

技能管理

方法	路线	描述
`GET`	`/skills`	列出所有加载的技能
`GET`	`/skills/{name}`	获取技能的完整细节
`POST`	`/skills`	从URL或base64 zip安装技能
`POST`	`/skills/upload`	通过文件上传安装技能
`DELETE`	`/skills/{name}`	删除技能
`DELETE`	`/skills`	删除所有技能
`GET`	`/skills/prompt_snippet`	获取代理的系统提示代码段（支持 `?skill_list=skill1,skill2` 和 `?prompt_enforcement=false`)
`POST`	`/skills/prompt_snippet`	将提示代码段注入到传递的JSON有效负载中（支持 `?skill_list=...` 和 `?prompt_enforcement=false`)

健康检查

GET /health

退货 200 OK 当前加载的技能数量。

📥 安装技能

注意：您不再需要提供名称。服务器将自动从中提取技能名称 SKILL.md 档案中的文件。如果您的文件夹或URL包含多个技能，它们都将自动安装。

1.文件上传（多部分）

curl -X POST http://localhost:8000/skills/upload \
  -H "X-API-Key: your_api_key" \
  -F "file=@my_skill.skill" \
  -F "overwrite=true" # optional, defaults to false

2.URL（直接zip下载）

curl -X POST "http://localhost:8000/skills" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/my_skill.zip", "overwrite": true}'

3.代理技能发现RFC（索引JSON）📖

安装多个技能策划在 skills_index.json 文件定义如下 Cloudflare发现RFC:

curl -X POST "http://localhost:8000/skills" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://raw.githubusercontent.com/LambdaTest/agent-skills/refs/heads/main/skills_index.json", "overwrite": true}'

3.GitHub URL🐙

您可以直接指向 GitHub存储库 或a 子目录 里面一个：

# Entire repository (uses main branch)
curl -X POST "http://localhost:8000/skills" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo"}'

# Specific branch
curl -X POST "http://localhost:8000/skills" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo/tree/develop"}'

# Specific subfolder inside a repo
curl -X POST "http://localhost:8000/skills" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/anthropics/skills/tree/main/skills/skill-creator"}'

4.Base64拉链

curl -X POST "http://localhost:8000/skills" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"zip_base64\": \"$(base64 -w0 my_skill.zip)\", \"overwrite\": true}"

🤖 MCP服务器——提供者平面

MCP服务器安装在 /mcp 使用 流式HTTP 运输。

MCP端点

传输	URL
流式HTTP	`POST /mcp`
上海证券交易所 `GET /mcp/sse`

MCP配置（克劳德桌面/任何MCP客户端）

{
  "mcpServers": {
    "skills": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "your_api_key"
      }
    }
  }
}

可用的MCP工具

工具	说明
`get_available_skills()`	列出所有加载的技能及其名称和描述
`get_skill_instructions(skill_name)`	加载技能的完整说明
`get_skill_reference(skill_name, reference_path)`	阅读技能参考文档
`get_skill_script(skill_name, script_path, execute)`	从技能中读取或执行脚本

代理系统快速集成

要将技能意识注入任何代理，请检索预构建的提示代码段。您可以选择通过 skill_list 仅按名称列出特定技能。默认情况下，会在前面添加一个严格的提示强制字符串，以确保代理完全按照指示使用工具，可以通过以下方式禁用 prompt_enforcement=false提示强制字符串会定期进行优化，以实现最佳格式和上下文效率。

# Get snippet containing ALL installed skills (includes prompt enforcement by default)
curl -X GET http://localhost:8000/skills/prompt_snippet \
  -H "X-API-Key: your_api_key"

# Get snippet without the prompt enforcement rules
curl -X GET "http://localhost:8000/skills/prompt_snippet?prompt_enforcement=false" \
  -H "X-API-Key: your_api_key"

# Get snippet filtered to specific skills
curl -X GET "http://localhost:8000/skills/prompt_snippet?skill_list=web_browsing,yahoo_finance" \
  -H "X-API-Key: your_api_key"

将返回的XML片段粘贴到代理的 system_prompt它描述了加载的技能以及如何使用MCP工具访问它们。

低代码集成（n8n、自制、自定义应用程序）

要简化难以操纵字符串的平台中的集成，请使用 POST 端点以JSON格式发送有效载荷，并使用 prompt 您需要将额外的系统指令附加到代理的系统提示符中：

curl -X POST "http://localhost:8000/skills/prompt_snippet" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Help me"}], "temperature": 0.7}'

返回原始有效载荷 "prompt" 动态附加/覆盖系统指令：

{
  "messages": [{"role": "user", "content": "Help me"}],
  "temperature": 0.7,
  "prompt": "<skills_system>...</skills_system>"
}

📂 技能结构

每个技能都是一个文件夹 SKILLS_DIR 布局如下：

my_skill/
├── SKILL.md         # Required: frontmatter (name, description) + instructions
├── scripts/         # Optional: executable script files
│   └── run.py
└── references/      # Optional: documentation files
    └── guide.md

SKILL.md 例子：

---
name: yahoo_finance
description: Fetch stock quotes and financial data from Yahoo Finance.
---

## Instructions

Use this skill when the user asks about stock prices or financial data...

⚙️ 环境变量

核心

变量	默认值	描述
`API_KEY`	（必填）	REST API和MCP身份验证的密钥
`SKILLS_DIR`	`skills`	技能文件夹的本地目录（由使用 `local` 后端）
`SKILLS_STORAGE`	`local`	存储后端： `local` 或 `s3`
`ALLOW_RUN_SCRIPTS`	`false`	是否允许通过以下方式执行脚本 `mcp_get_script`
`LAZY_INSTALL_VENVS`	`false`	如果 `true`，推迟 `requirements.txt` 生成/安装到第一次执行脚本。如果 `false`，在技能安装后立即安装依赖项。
`ALLOW_GET_AVAILABLE_SKILLS`	`true`	暴露 `get_available_skills` 通过FastMCP在全球范围内使用该工具。设置为 `false` 通过工具调用隐藏发现机制。

核心变量的详细说明

API_KEY：这是用于保护REST API端点和FastMCP传输连接的主机密。这对任何操作都是强制性的。
SKILLS_DIR：定义维护技能文件夹的路径（相对于应用程序根或绝对）。默认为 skills 在本地后端。
SKILLS_STORAGE：确定加载技能的策略。可以设置为 local （读自 SKILLS_DIR)或 s3 （从AWS S3兼容对象存储中同步技能）。
ALLOW_RUN_SCRIPTS：安全开关。如果设置为 false （默认） get_skill_script 工具与 execute=True 将被申请拒绝。将其设置为 true 允许代理有效地运行由技能定义的python脚本。
LAZY_INSTALL_VENVS：性能切换。如果 false （默认），服务器在技能安装过程中会阻止构建Python虚拟环境并安装 requirements.txt.如果 true，安装是即时的，但运行时将暂停安装 .venv 仅当首次执行该技能的脚本时。
ALLOW_GET_AVAILABLE_SKILLS：集成切换。如果 true （默认） get_available_skills 该工具通过FastMCP在全球范围内公开，用于动态发现。如果 false，该工具是隐藏的，需要系统提示明确定义技能或使用 /skills/prompt_snippet REST端点用于注入，这有助于避免LLM发现不应该使用的技能，要求开发人员在系统提示中明确定义技能，注入代码段。

S3存储(`SKILLS_STORAGE=s3`)

变量	默认值	描述
`S3_BUCKET`	（必填）	S3存储桶名称
`S3_PREFIX`	`skills/`	密钥前缀充当远程技能根
`S3_CACHE_DIR`	`.s3cache`	缓存S3文件的本地目录
`AWS_ACCESS_KEY_ID`	--	AWS访问密钥（或使用IAM角色/ `~/.aws/credentials`)
`AWS_SECRET_ACCESS_KEY`	--	AWS密钥
`AWS_DEFAULT_REGION`	`us-east-1`	AWS区域
`AWS_ENDPOINT_URL`	--	MinIO/LocalStack的自定义端点

☁️ 存储后端

本地（默认）

技能从加载 SKILLS_DIR 磁盘上的文件夹。使用Docker，命名卷(skills_data)用于持久化：

# .env
SKILLS_STORAGE=local
SKILLS_DIR=skills

这 docker-compose.yml 山丘 skills_data:/app/skills 自动-- 技能生存 docker-compose down / up 循环。

S3/S3兼容

技能从S3存储桶同步到本地缓存目录 reload(). 这 S3Skills 装载机(s3_skills.py)遵循相同的 SkillLoader 界面为Agno LocalSkills.

# .env
SKILLS_STORAGE=s3
S3_BUCKET=my-bucket
S3_PREFIX=skills/
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=us-east-1

# MinIO / LocalStack:
# AWS_ENDPOINT_URL=http://localhost:9000

预期铲斗布局：

my-bucket/
└── skills/
    ├── my_skill/
    │   ├── SKILL.md
    │   ├── scripts/run.py
    │   └── references/guide.md
    └── another_skill/
        └── SKILL.md