mcp-server-scaffold

生成可运行的 MCP Server 骨架（tools/resources/prompts + 写操作确认），含客户端配置。

触发条件（frontmatter.description）

生成一个可运行的 MCP Server 项目骨架（FastMCP + tools/resources/prompts + 客户端配置）。当用户要"写一个 MCP server""把内部 API 接给 Claude""MCP 怎么开始"时使用。不用于 MCP 协议理论讲解。

目录结构

mcp-server-scaffold/
├── SKILL.md
└── templates/server.py

安装方式

Claude Code把技能目录复制到以下位置，重启会话后自动可用~/.claude/skills/<技能名>/项目级可放 <项目>/.claude/skills/
Claude.ai / Desktop下载 .zip 后在设置 → Capabilities → Skills 上传需要开启 Skills 功能
Hermes Agent放到技能目录，Hermes 启动时自动加载~/.hermes/skills/<技能名>/
其它 Agent任何支持 SKILL.md 约定（YAML frontmatter + 步骤 + 脚本）的框架都可直接使用本质是一个带说明文档的脚本目录

下载的 zip 解压后是 mcp-server-scaffold/ 目录，直接整个放进去即可，不用改文件名。

技能包内容

---
name: mcp-server-scaffold
description: 生成一个可运行的 MCP Server 项目骨架（FastMCP + tools/resources/prompts + 客户端配置）。当用户要"写一个 MCP server""把内部 API 接给 Claude""MCP 怎么开始"时使用。不用于 MCP 协议理论讲解。
---

# MCP Server 脚手架

## 什么时候用

- 用户要把某个系统/API 暴露给支持 MCP 的客户端
- 需要一个能跑起来的最小骨架
- 不确定 tools / resources / prompts 怎么划分

**不要用**：只问协议概念时（直接回答，不必生成项目）。

## 步骤

1. **确认三件事**：要暴露什么能力、目标客户端、鉴权方式
2. **先做能力划分**（这一步决定成败）：
   - 有副作用 / 需参数化执行 → tool
   - 可按 URI 读取的数据 → resource
   - 给用户点一下就执行的模板 → prompt
3. **用 `templates/server.py` 起骨架**，替换成真实逻辑
4. **补齐三件工程细节**：返回体截断上限、错误码可区分、写操作二次确认
5. **给出客户端配置片段**（stdio 或 http）

## 输出

```
project/
├── server.py
├── requirements.txt      # mcp
└── README.md             # 客户端配置 + 启动方式
```

## 验证

- `python server.py` 能启动不报错
- 每个 tool 的 docstring 写清「做什么 / 何时用 / 何时不用 / 返回什么」
- 列表类返回有 `limit` 参数且默认 ≤50

## 陷阱

- 把「读数据」做成 tool（应该是 resource）
- 返回体不截断，一次吐几十万字符撑爆上下文
- 写操作不做确认，Agent 一条指令就改数据
- 凭证写死在 server.py 里（应用环境变量）

SKILL.md 说明（Agent 读到后照此执行）

# MCP Server 脚手架

## 什么时候用

- 用户要把某个系统/API 暴露给支持 MCP 的客户端
- 需要一个能跑起来的最小骨架
- 不确定 tools / resources / prompts 怎么划分

**不要用**：只问协议概念时（直接回答，不必生成项目）。

## 步骤

1. **确认三件事**：要暴露什么能力、目标客户端、鉴权方式
2. **先做能力划分**（这一步决定成败）：
   - 有副作用 / 需参数化执行 → tool
   - 可按 URI 读取的数据 → resource
   - 给用户点一下就执行的模板 → prompt
3. **用 `templates/server.py` 起骨架**，替换成真实逻辑
4. **补齐三件工程细节**：返回体截断上限、错误码可区分、写操作二次确认
5. **给出客户端配置片段**（stdio 或 http）

## 输出

```
project/
├── server.py
├── requirements.txt      # mcp
└── README.md             # 客户端配置 + 启动方式
```

## 验证

- `python server.py` 能启动不报错
- 每个 tool 的 docstring 写清「做什么 / 何时用 / 何时不用 / 返回什么」
- 列表类返回有 `limit` 参数且默认 ≤50

## 陷阱

- 把「读数据」做成 tool（应该是 resource）
- 返回体不截断，一次吐几十万字符撑爆上下文
- 写操作不做确认，Agent 一条指令就改数据
- 凭证写死在 server.py 里（应用环境变量）

← 返回技能库