better-dsh 0.2.5 → 0.3.0-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/mcp/mcp-fastmcp.md

@@ -1,315 +0,0 @@
----
-title: "Fastmcp — 使用 FastMCP 在 Python 中构建、测试、检查、安装和部署 MCP 服务器"
-sidebar_label: "Fastmcp"
-description: "使用 FastMCP 在 Python 中构建、测试、检查、安装和部署 MCP 服务器"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Fastmcp
-
-使用 FastMCP 在 Python 中构建、测试、检查、安装和部署 MCP 服务器。适用于创建新的 MCP 服务器、将 API 或数据库封装为 MCP 工具、暴露资源或 prompt（提示词）、或为 Claude Code、Cursor 或 HTTP 部署准备 FastMCP 服务器。
-
-## Skill 元数据
-
-| | |
-|---|---|
-| 来源 | 可选 — 通过 `hermes skills install official/mcp/fastmcp` 安装 |
-| 路径 | `optional-skills/mcp/fastmcp` |
-| 版本 | `1.0.0` |
-| 作者 | Hermes Agent |
-| 许可证 | MIT |
-| 平台 | linux, macos, windows |
-| 标签 | `MCP`, `FastMCP`, `Python`, `Tools`, `Resources`, `Prompts`, `Deployment` |
-| 相关 skill | [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`mcporter`](/user-guide/skills/optional/mcp/mcp-mcporter) |
-
-## 参考：完整 SKILL.md
-
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
-:::
-
-# FastMCP
-
-使用 FastMCP 在 Python 中构建 MCP 服务器，在本地验证，安装到 MCP 客户端，并部署为 HTTP 端点。
-
-## 使用时机
-
-在以下任务中使用此 skill：
-
-- 在 Python 中创建新的 MCP 服务器
-- 将 API、数据库、CLI 或文件处理工作流封装为 MCP 工具
-- 除工具外还需暴露资源或 prompt
-- 在接入 Hermes 或其他客户端之前，使用 FastMCP CLI 对服务器进行冒烟测试
-- 将服务器安装到 Claude Code、Claude Desktop、Cursor 或类似的 MCP 客户端
-- 为 HTTP 部署准备 FastMCP 服务器仓库
-
-若服务器已存在且只需连接到 Hermes，请使用 `native-mcp`。若目标是对现有 MCP 服务器进行临时 CLI 访问而非构建新服务器，请使用 `mcporter`。
-
-## 前置条件
-
-首先在工作环境中安装 FastMCP：
-
-```bash
-pip install fastmcp
-fastmcp version
-```
-
-如需使用 API 模板，且 `httpx` 尚未安装，请先安装：
-
-```bash
-pip install httpx
-```
-
-## 包含文件
-
-### 模板
-
-- `templates/api_wrapper.py` - 支持 auth header 的 REST API 封装
-- `templates/database_server.py` - 只读 SQLite 查询服务器
-- `templates/file_processor.py` - 文本文件检查与搜索服务器
-
-### 脚本
-
-- `scripts/scaffold_fastmcp.py` - 复制入门模板并替换服务器名称占位符
-
-### 参考资料
-
-- `references/fastmcp-cli.md` - FastMCP CLI 工作流、安装目标及部署检查
-
-## 工作流
-
-### 1. 选择最小可行的服务器形态
-
-优先选择最窄的有用接口：
-
-- API 封装：从 1-3 个高价值端点开始，而非整个 API
-- 数据库服务器：暴露只读自省能力和受约束的查询路径
-- 文件处理器：暴露带有明确路径参数的确定性操作
-- prompt/资源：仅在客户端需要可复用 prompt 模板或可发现文档时添加
-
-优先选择接口精简、名称清晰、有 docstring 和 schema 的服务器，而非工具繁多但含义模糊的服务器。
-
-### 2. 从模板脚手架生成
-
-直接复制模板或使用脚手架辅助工具：
-
-```bash
-python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py \
-  --template api_wrapper \
-  --name "Acme API" \
-  --output ./acme_server.py
-```
-
-可用模板：
-
-```bash
-python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py --list
-```
-
-如手动复制，请将 `__SERVER_NAME__` 替换为实际服务器名称。
-
-### 3. 优先实现工具
-
-在添加资源或 prompt 之前，先实现 `@mcp.tool` 函数。
-
-工具设计规则：
-
-- 为每个工具起一个具体的动词式名称
-- 将 docstring 作为面向用户的工具描述
-- 保持参数明确且有类型注解
-- 尽可能返回结构化的 JSON 安全数据
-- 尽早验证不安全的输入
-- 第一版默认采用只读行为
-
-良好的工具示例：
-
-- `get_customer`
-- `search_tickets`
-- `describe_table`
-- `summarize_text_file`
-
-不佳的工具示例：
-
-- `run`
-- `process`
-- `do_thing`
-
-### 4. 仅在有帮助时添加资源和 Prompt
-
-当客户端需要获取稳定的只读内容（如 schema、策略文档或生成的报告）时，添加 `@mcp.resource`。
-
-当服务器应为已知工作流提供可复用 prompt 模板时，添加 `@mcp.prompt`。
-
-不要将每个文档都变成 prompt。优先原则：
-
-- 工具用于操作
-- 资源用于数据/文档检索
-- prompt 用于可复用的 LLM 指令
-
-### 5. 集成前先测试服务器
-
-使用 FastMCP CLI 进行本地验证：
-
-```bash
-fastmcp inspect acme_server.py:mcp
-fastmcp list acme_server.py --json
-fastmcp call acme_server.py search_resources query=router limit=5 --json
-```
-
-如需快速迭代调试，在本地运行服务器：
-
-```bash
-fastmcp run acme_server.py:mcp
-```
-
-如需在本地测试 HTTP transport：
-
-```bash
-fastmcp run acme_server.py:mcp --transport http --host 127.0.0.1 --port 8000
-fastmcp list http://127.0.0.1:8000/mcp --json
-fastmcp call http://127.0.0.1:8000/mcp search_resources query=router --json
-```
-
-在声明服务器可用之前，务必对每个新工具至少执行一次真实的 `fastmcp call`。
-
-### 6. 本地验证通过后安装到客户端
-
-FastMCP 可将服务器注册到支持的 MCP 客户端：
-
-```bash
-fastmcp install claude-code acme_server.py
-fastmcp install claude-desktop acme_server.py
-fastmcp install cursor acme_server.py -e .
-```
-
-使用 `fastmcp discover` 检查机器上已配置的命名 MCP 服务器。
-
-若目标是集成到 Hermes，可选择：
-
-- 使用 `native-mcp` skill，在 `~/.hermes/config.yaml` 中配置服务器，或
-- 在接口稳定之前，在开发阶段继续使用 FastMCP CLI 命令
-
-### 7. 本地契约稳定后再部署
-
-对于托管部署，Prefect Horizon 是 FastMCP 文档中最直接的路径。部署前执行：
-
-```bash
-fastmcp inspect acme_server.py:mcp
-```
-
-确保仓库包含：
-
-- 含有 FastMCP 服务器对象的 Python 文件
-- `requirements.txt` 或 `pyproject.toml`
-- 部署所需的环境变量文档
-
-对于通用 HTTP 托管，先在本地验证 HTTP transport，然后在任何能暴露服务器端口的 Python 兼容平台上部署。
-
-## 常见模式
-
-### API 封装模式
-
-适用于将 REST 或 HTTP API 暴露为 MCP 工具。
-
-推荐的第一个切片：
-
-- 一个读取路径
-- 一个列表/搜索路径
-- 可选的健康检查
-
-实现注意事项：
-
-- 将认证信息保存在环境变量中，不要硬编码
-- 将请求逻辑集中在一个辅助函数中
-- 以简洁的上下文暴露 API 错误
-- 在返回前对上游不一致的 payload 进行规范化
-
-从 `templates/api_wrapper.py` 开始。
-
-### 数据库模式
-
-适用于暴露安全的查询和自省能力。
-
-推荐的第一个切片：
-
-- `list_tables`
-- `describe_table`
-- 一个受约束的只读查询工具
-
-实现注意事项：
-
-- 默认使用只读数据库访问
-- 早期版本拒绝非 `SELECT` SQL
-- 限制返回行数
-- 同时返回行数据和列名
-
-从 `templates/database_server.py` 开始。
-
-### 文件处理器模式
-
-适用于服务器需要按需检查或转换文件的场景。
-
-推荐的第一个切片：
-
-- 汇总文件内容
-- 在文件中搜索
-- 提取确定性元数据
-
-实现注意事项：
-
-- 接受明确的文件路径
-- 检查文件缺失和编码失败
-- 限制预览和结果数量
-- 除非需要特定外部工具，否则避免调用 shell
-
-从 `templates/file_processor.py` 开始。
-
-## 质量标准
-
-在交付 FastMCP 服务器之前，验证以下所有内容：
-
-- 服务器可以干净地导入
-- `fastmcp inspect <file.py:mcp>` 成功
-- `fastmcp list <server spec> --json` 成功
-- 每个新工具至少有一次真实的 `fastmcp call`
-- 环境变量已有文档说明
-- 工具接口足够精简，无需猜测即可理解
-
-## 故障排查
-
-### FastMCP 命令缺失
-
-在当前激活的环境中安装该包：
-
-```bash
-pip install fastmcp
-fastmcp version
-```
-
-### `fastmcp inspect` 失败
-
-检查：
-
-- 文件导入时不存在导致崩溃的副作用
-- FastMCP 实例在 `<file.py:object>` 中命名正确
-- 模板所需的可选依赖已安装
-
-### 工具在 Python 中正常但通过 CLI 不工作
-
-运行：
-
-```bash
-fastmcp list server.py --json
-fastmcp call server.py your_tool_name --json
-```
-
-这通常会暴露命名不匹配、缺少必填参数或返回值无法序列化等问题。
-
-### Hermes 无法看到已部署的服务器
-
-服务器构建部分可能正确，但 Hermes 配置有误。加载 `native-mcp` skill 并在 `~/.hermes/config.yaml` 中配置服务器，然后重启 Hermes。
-
-## 参考资料
-
-有关 CLI 详情、安装目标和部署检查，请阅读 `references/fastmcp-cli.md`。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/mcp/mcp-mcporter.md

@@ -1,138 +0,0 @@
----
-title: "Mcporter"
-sidebar_label: "Mcporter"
-description: "使用 mcporter CLI 列出、配置、认证并直接调用 MCP 服务器/工具（HTTP 或 stdio），包括临时服务器、配置编辑及 CLI/类型生成等功能。"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Mcporter
-
-使用 mcporter CLI 列出、配置、认证并直接调用 MCP 服务器/工具（HTTP 或 stdio），包括临时服务器、配置编辑及 CLI/类型生成等功能。
-
-## Skill 元数据
-
-| | |
-|---|---|
-| 来源 | 可选 — 通过 `hermes skills install official/mcp/mcporter` 安装 |
-| 路径 | `optional-skills/mcp/mcporter` |
-| 版本 | `1.0.0` |
-| 作者 | community |
-| 许可证 | MIT |
-| 平台 | linux, macos, windows |
-| 标签 | `MCP`, `Tools`, `API`, `Integrations`, `Interop` |
-
-## 参考：完整 SKILL.md
-
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
-:::
-
-# mcporter
-
-使用 `mcporter` 直接从终端发现、调用并管理 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器和工具。
-
-## 前置条件
-
-需要 Node.js：
-```bash
-# 无需安装（通过 npx 运行）
-npx mcporter list
-
-# 或全局安装
-npm install -g mcporter
-```
-
-## 快速开始
-
-```bash
-# 列出此机器上已配置的 MCP 服务器
-mcporter list
-
-# 列出指定服务器的工具及 schema 详情
-mcporter list <server> --schema
-
-# 调用工具
-mcporter call <server.tool> key=value
-```
-
-## 发现 MCP 服务器
-
-mcporter 会自动发现机器上其他 MCP 客户端（Claude Desktop、Cursor 等）已配置的服务器。如需查找新服务器，可浏览 [mcpfinder.dev](https://mcpfinder.dev) 或 [mcp.so](https://mcp.so) 等注册表，然后以临时方式连接：
-
-```bash
-# 通过 URL 连接任意 MCP 服务器（无需配置）
-mcporter list --http-url https://some-mcp-server.com --name my_server
-
-# 或临时运行 stdio 服务器
-mcporter list --stdio "npx -y @modelcontextprotocol/server-filesystem" --name fs
-```
-
-## 调用工具
-
-```bash
-# key=value 语法
-mcporter call linear.list_issues team=ENG limit:5
-
-# 函数语法
-mcporter call "linear.create_issue(title: \"Bug fix needed\")"
-
-# 临时 HTTP 服务器（无需配置）
-mcporter call https://api.example.com/mcp.fetch url=https://example.com
-
-# 临时 stdio 服务器
-mcporter call --stdio "bun run ./server.ts" scrape url=https://example.com
-
-# JSON 载荷
-mcporter call <server.tool> --args '{"limit": 5}'
-
-# 机器可读输出（推荐用于 Hermes）
-mcporter call <server.tool> key=value --output json
-```
-
-## 认证与配置
-
-```bash
-# 对服务器进行 OAuth 登录
-mcporter auth <server | url> [--reset]
-
-# 管理配置
-mcporter config list
-mcporter config get <key>
-mcporter config add <server>
-mcporter config remove <server>
-mcporter config import <path>
-```
-
-配置文件位置：`./config/mcporter.json`（可通过 `--config` 覆盖）。
-
-## Daemon（守护进程）
-
-用于持久化服务器连接：
-```bash
-mcporter daemon start
-mcporter daemon status
-mcporter daemon stop
-mcporter daemon restart
-```
-
-## 代码生成
-
-```bash
-# 为 MCP 服务器生成 CLI 包装器
-mcporter generate-cli --server <name>
-mcporter generate-cli --command <url>
-
-# 检查已生成的 CLI
-mcporter inspect-cli <path> [--json]
-
-# 生成 TypeScript 类型/客户端
-mcporter emit-ts <server> --mode client
-mcporter emit-ts <server> --mode types
-```
-
-## 注意事项
-
-- 使用 `--output json` 获取结构化输出，便于解析
-- 临时服务器（HTTP URL 或 `--stdio` 命令）无需任何配置即可使用，适合一次性调用
-- OAuth 认证可能需要交互式浏览器流程 — 如有需要，请使用 `terminal(command="mcporter auth <server>", pty=true)`