# https://github.com/chirag127/skill-smithery-ai-cli 项目说明书

生成时间：2026-07-06 22:28:59 UTC

## 目录

- [项目简介](#page-1)
- [安装与快速开始](#page-2)
- [SKILL.md 技能定义](#page-3)
- [触发条件与使用指南](#page-4)
- [MCP 工具发现与连接流程](#page-5)
- [支持的外部服务集成](#page-6)
- [授权与许可](#page-7)
- [常见问题与故障排查](#page-8)

<a id='page-1'></a>

## 项目简介

### 相关页面

相关主题：[安装与快速开始](#page-2), [SKILL.md 技能定义](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/README.md)
- [SKILL.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/SKILL.md)
</details>

# 项目简介

skill-smithery-ai-cli 是一个面向 AI 代理（agent）的 Smithery CLI 技能包，其核心目标是帮助用户查找、连接并使用 MCP（Model Context Protocol）工具与技能，从而让 AI 代理能够与 GitHub、Slack、Discord、Jira、Notion、数据库、云 API、监控等外部服务进行交互 资料来源：[README.md:1-3]()。

## 项目定位与形态

该项目并不是一个独立的可执行程序，而是一个"技能（skill）"资源——可通过 `npx skills add` 命令在任意支持技能机制的 AI 代理运行时（例如兼容 SKILL.md 的代理）中一键加载 资料来源：[README.md:5-7]()。加载后，AI 代理便会自动获得调用底层 `@smithery/cli` 的能力，将 Smithery 视作"AI 代理的工具与技能市场（marketplace for AI agents）" 资料来源：[SKILL.md:9-11]()。详细的技能定义、触发条件与依赖（如 `bins: ["smithery"]`）均在前言（frontmatter）的 metadata 中声明 资料来源：[SKILL.md:3-5]()。

## 核心概念

SKILL.md 明确把整套 CLI 的使用心智模型归纳为三个核心概念 资料来源：[SKILL.md:25-26]()：

### 名称空间（Namespaces）

名称空间是服务器、连接和技能的"工作区边界"。建议一个应用或环境对应一个独立的命名空间，例如 `my-app-dev`、`my-app-prod`，并将其设为当前活动上下文 资料来源：[SKILL.md:27-31]()。典型流程是：先用 `namespace list` 查看现有空间，再 `namespace create` 新建，最后通过 `namespace use` 切换 资料来源：[SKILL.md:32-36]()。

### 连接（Connect / MCP Connections）

连接是一个由 Smithery Connect 管理的、长期存活的 MCP 会话，负责 OAuth 流程、凭据存储、令牌刷新与会话生命周期 资料来源：[SKILL.md:39-41]()。连接有三种状态：`connected` 表示就绪可调用工具，`auth_required` 表示需人工在浏览器中完成授权，`error` 表示需要检查配置 资料来源：[SKILL.md:43-46]()。

### 令牌作用域（Token Scoping）

为避免把完整 API 密钥泄露给不受信任的代码，Smithery 提供了"服务令牌"机制，可通过策略进行细粒度约束 资料来源：[SKILL.md:58-60]()。其策略模型为：单个 `--policy` 参数对应一个 JSON 对象；同一个约束内的字段为 AND 关系（字段越多越严格），而列表项或多个约束之间为 OR 关系（条目越多越宽松） 资料来源：[SKILL.md:62-65]()。

## 典型工作流

下面以"连接 GitHub MCP 并调用 `issues.create` 工具"为例，展示从安装到调用的端到端流程 资料来源：[SKILL.md:14-23]()：

| 步骤 | 命令示例 | 作用 |
| --- | --- | --- |
| 1 | `npm install -g @smithery/cli` | 全局安装 Smithery CLI |
| 2 | `smithery auth login` | 在浏览器中完成身份认证 |
| 3 | `smithery mcp search "github"` | 搜索可用的 MCP 服务器 |
| 4 | `smithery mcp add <url> --id github` | 添加并命名一个连接 |
| 5 | `smithery tool list github issues.` | 以树形视图浏览工具分组 |
| 6 | `smithery tool get github issues.create` | 查看工具的输入输出 JSON Schema |
| 7 | `smithery tool call github issues.create '{...}'` | 实际调用工具并传入参数 |

当命令输出被管道转发时，Smithery 会自动改为 JSONL 格式（每行一个 JSON 对象），方便脚本进行 `grep`、`jq` 等二次处理 资料来源：[SKILL.md:79-81]()。此外，针对连接级别的精细控制，还可以使用实验性的 `rpcReqMatch` 在 JSON-RPC 请求维度对方法名或工具名施加正则限制 资料来源：[SKILL.md:85-91]()。

## 安装与许可

只需执行 `npx skills add https://github.com/chirag127/skill-smithery-ai-cli` 即可把本技能注入到当前代理环境中 资料来源：[README.md:5-7]()。本项目遵循 MIT 许可证，版权归属 Chirag Singhal（2026） 资料来源：[README.md:13-15]()。有关技能定义、触发条件与官方文档的链接可在仓库根目录的 [SKILL.md](./SKILL.md) 中查阅 资料来源：[README.md:9-11]()。

---

<a id='page-2'></a>

## 安装与快速开始

### 相关页面

相关主题：[项目简介](#page-1), [授权与许可](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/README.md)
- [SKILL.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/SKILL.md)
</details>

# 安装与快速开始

## 概述

"安装与快速开始"模块为开发者提供从零接入 Smithery CLI 的标准化路径,涵盖技能注册、CLI 安装、身份认证、MCP 服务器搜索、连接建立、工具浏览与调用等核心环节。其目标是让用户在最短时间内完成环境搭建,并通过一条端到端的工具调用链路验证集成是否成功。

本仓库本身是一份可被技能管理器消费的"技能包",核心可执行体是外部的 `@smithery/cli`。SKILL.md 明确指出,在使用任何命令前应通过 `smithery --help` 与 `<command> --help` 查看具体参数。

资料来源：[README.md:1-12]() [SKILL.md:1-16]()

## 安装方式

仓库提供两种互补的安装路径。第一种通过 `npx skills add` 将本仓库注册为一项技能,适合已具备技能管理器的环境:

```
npx skills add https://github.com/chirag127/skill-smithery-ai-cli
```

第二种方式直接安装 `@smithery/cli` 的 npm 全局包,从而在终端获得 `smithery` 可执行命令:

```
npm install -g @smithery/cli
```

资料来源：[README.md:8-10]() [SKILL.md:22-23]()

## 身份认证

任何连接或工具调用之前,必须先完成认证。`smithery auth login` 会在浏览器中弹出授权页面,因此需要人工介入并完成确认。该步骤是后续命名空间管理、MCP 连接建立与受限令牌签发的前提。

```
smithery auth login
```

资料来源：[SKILL.md:24-25]()

## 核心工作流

完成安装与认证后,典型的"搜索 → 连接 → 浏览 → 检查 → 调用"五步流程如下表所示:

| 步骤 | 命令示例 | 作用 |
|------|---------|------|
| 1. 搜索 | `smithery mcp search "github"` | 查找可用的 MCP 服务器 |
| 2. 连接 | `smithery mcp add "https://github.run.tools" --id github` | 在当前命名空间建立连接 |
| 3. 浏览 | `smithery tool list github` 或 `smithery tool list github issues.` | 以树形视图列出工具,前缀可下钻 |
| 4. 检查 | `smithery tool get github issues.create` | 查看输入输出 JSON Schema |
| 5. 调用 | `smithery tool call github issues.create '{"repo": "owner/repo", "title": "Bug"}'` | 实际执行工具调用 |

上述流程以 GitHub 集成为例,但模式可推广至 Slack、Discord、Jira、Notion、数据库、云 API 等任意 MCP 服务器。

资料来源：[SKILL.md:26-37]()

## 命名空间与连接状态

### 命名空间

命名空间(Namespace)是服务器、连接和技能的隔离边界。每个应用或环境建议使用独立命名空间(如 `my-app-dev`、`my-app-prod`),并通过 `use` 切换当前上下文:

```
smithery namespace list
smithery namespace create my-app-prod
smithery namespace use my-app-prod
```

资料来源：[SKILL.md:41-50]()

### 连接状态

MCP 连接是一种由 Smithery Connect 托管的长生命周期会话,负责处理 OAuth 流程、凭据存储与令牌刷新。其状态机包含三种取值:

- `connected`: 已就绪,可列出或调用工具
- `auth_required`: 需要人工打开授权 URL
- `error`: 需要查看详情并修复配置

若 CLI 返回 `auth_required`,应提示用户打开授权链接后重试。

资料来源：[SKILL.md:55-69]()

## 令牌作用域与管道输出

为避免向不受信任的代码传递完整 API 密钥,可使用 `smithery auth token --policy` 签发受策略约束的服务令牌。策略模型为:

- 同一 `--policy` JSON 对象内部,字段之间为 AND 关系(字段越多越窄)
- 列表项或多个 `--policy` 之间为 OR 关系(条目越多越宽)

当输出被管道转发时,Smithery 命令会切换为 JSONL 格式(每行一个 JSON 对象),便于脚本处理:

```
smithery tool list github --flat --limit 1000 | grep label
```

资料来源：[SKILL.md:73-100]() [SKILL.md:120-122]()

---

<a id='page-3'></a>

## SKILL.md 技能定义

### 相关页面

相关主题：[触发条件与使用指南](#page-4), [项目简介](#page-1)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [SKILL.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/SKILL.md)
- [README.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/README.md)
</details>

# SKILL.md 技能定义

## 概述与定位

`SKILL.md` 是本仓库唯一对外交付的技能清单文件（skill manifest），定义了名为 `smithery-ai-cli` 的可被 AI 客户端识别的技能。技能面向 Claude、Cursor、Continue 等兼容 OpenClaw / skills 协议的 Agent 工作流，让模型在不需要自己实现 MCP 客户端的前提下，能够通过 Smithery CLI 发现、连接并调用 MCP 服务与已发布技能。资料来源：[README.md:1-5]()

仓库的 `README.md` 将该文件标注为权威说明入口，建议使用者先阅读 `SKILL.md` 获取触发条件与命令模板，再视需要扩展脚本或资源。资料来源：[README.md:9-11]()

## 文件结构与 YAML 元数据

`SKILL.md` 顶部采用 YAML frontmatter，向运行时声明技能元信息，字段语义如下：

- `name: smithery-ai-cli`：技能唯一标识符。资料来源：[SKILL.md:1-1]()
- `description`：触发条件，覆盖工具检索、集成发现、MCP 连接、技能安装，以及与 Email、Slack、Discord、GitHub、Jira、Notion、数据库、云 API、监控等外部服务的交互。资料来源：[SKILL.md:2-2]()
- `metadata.openclaw.requires.bins: ["smithery"]`：声明运行该技能依赖本机的 `smithery` 可执行文件。资料来源：[SKILL.md:3-3]()
- `metadata.openclaw.homepage: https://smithery.ai`：指向官方文档作为概念参考。资料来源：[SKILL.md:3-3]()

frontmatter 之后由 Markdown 正文给出概念与命令清单，结构遵循「Quick Start → Core Concepts → 高级主题」的渐进式展开模式。

## 安装与快速开始工作流

`SKILL.md` 在「Quick Start」一节给出了从零到工具调用的端到端命令行链条：

1. 全局安装 CLI：`npm install -g @smithery/cli`。资料来源：[SKILL.md:13-13]()
2. 浏览器登录授权：`smithery auth login`。资料来源：[SKILL.md:15-15]()
3. 关键字搜索 MCP 服务：`smithery mcp search "github"`。资料来源：[SKILL.md:17-17]()
4. 通过 URL 或限定名建立命名连接：`smithery mcp add "<url>" --id <id>`。资料来源：[SKILL.md:19-19]()
5. 树形浏览工具，并通过前缀下钻到具体工具组：`smithery tool list <id>` 与 `smithery tool list <id> <prefix>`。资料来源：[SKILL.md:21-22]()
6. 读取目标工具的 JSON Schema：`smithery tool get <id> <tool>`。资料来源：[SKILL.md:24-24]()
7. 以 JSON 入参调用工具：`smithery tool call <id> <tool> '<json>'`。资料来源：[SKILL.md:26-26]()

文档同时说明：当输出被管道传递时，命令切换为 JSONL 格式（每行一个 JSON 对象），便于在 shell 中用 `grep` / `jq` 做二次处理。资料来源：[SKILL.md:108-110]()

技能本身可以通过 `npx skills add https://github.com/chirag127/skill-smithery-ai-cli` 一键安装到目标客户端，无需手工复制文件。资料来源：[README.md:7-9]()

## 核心概念模型

`SKILL.md` 在「Core Concepts」章节把命令集合收敛为四个领域概念。

### 命名空间（Namespaces）

namespace 是 Smithery 资源的隔离边界，服务器、连接、技能统一归属到当前 namespace。官方建议每个应用/环境单独创建一个 namespace（如 `my-app-dev`、`my-app-prod`），并通过 `smithery namespace use` 设置激活上下文。资料来源：[SKILL.md:32-44]()

### 连接（Connections）

connection 是受托管的长生命周期 MCP 会话，Smithery Connect 统一负责 OAuth 跳转、凭据落盘、令牌刷新与会话生命周期管理。文档列出三种状态：`connected`（可正常列出与调用工具）、`auth_required`（需由真人浏览器完成授权 URL 跳转）、`error`（需要查看错误详情后修正配置）。资料来源：[SKILL.md:48-66]()

### 令牌作用域（Token Scoping）

服务端令牌（service token）是为浏览器、移动端、Agent 场景签发的受限凭据。策略心智模型：单个 `--policy` JSON 对象内的字段之间是 AND（限制更紧），多个 `--policy` 或列表项之间是 OR（覆盖更广），并通过 `ttl` 字段控制有效期。资料来源：[SKILL.md:70-82]()

### 请求级工具限制（rpcReqMatch）

通过 `rpcReqMatch` 在 JSON-RPC 层按 `method` 与 `params.name` 做正则限制。由于 MCP 连接 ID 不在 JSON-RPC body 中，必须将 `metadata`（连接级）与 `rpcReqMatch`（方法/工具级）组合使用，才能既限定目标连接又限定可被调用的工具名集合。资料来源：[SKILL.md:95-106]()

## 端到端数据流

下图概括 Agent 触发该技能后，从用户意图到外部服务生效的数据走向：

```mermaid
flowchart LR
    U[用户/Agent] -->|npx skills add| S[SKILL.md 加载]
    S -->|读取 requires.bins| C[Smithery CLI]
    C -->|auth login| A[浏览器 OAuth]
    A -->|token| C
    C -->|mcp add| N[namespace 内 connection]
    N -->|connected| T[tool list / get]
    T -->|tool call JSON| X[外部 MCP 服务<br/>GitHub/Slack/...]
    N -. auth_required .-> U
```

## 运行依赖与许可

技能运行时只依赖 `smithery` 一个二进制，不引入额外的脚本或容器；因此仓库根目录除 `README.md` 与 `SKILL.md` 外不附带实现代码。资料来源：[SKILL.md:3-3]() 整体许可为 MIT，版权年份为 2026，归 Chirag Singhal 所有，可自由二次分发与改动。资料来源：[README.md:13-15]()

## 小结

`SKILL.md` 是把 Smithery CLI 能力封装为 AI 技能的标准契约：YAML frontmatter 声明依赖与触发条件，Markdown 正文给出概念边界与命令模板。它既不实现 MCP 客户端，也不封装业务逻辑，而是在「技能 ↔ CLI ↔ MCP 服务」之间承担翻译与编排职责，使 Agent 能够在受 namespace、connection 状态与 token policy 三层约束的前提下，安全、可追溯地调用 Smithery 上 10 万级别的外部工具与技能。

---

<a id='page-4'></a>

## 触发条件与使用指南

### 相关页面

相关主题：[SKILL.md 技能定义](#page-3), [MCP 工具发现与连接流程](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [SKILL.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/SKILL.md)
- [README.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/README.md)
</details>

# 触发条件与使用指南

## 技能概述与触发场景

skill-smithery-ai-cli 是面向 Smithery 平台的命令行技能包，封装了 `@smithery/cli`，使 AI 代理能够即时发现、连接并调用 10 万+ MCP（Model Context Protocol）工具与技能。该技能的核心定位是充当"代理与外部服务之间的桥梁"，覆盖邮件、Slack、Discord、GitHub、Jira、Notion、各类数据库、云 API 与监控工具等场景。资料来源：[README.md:1-3]()

触发该技能的具体条件包括以下四类用户意图：

- **搜索与发现**：用户希望寻找新的工具、技能或可用的集成方案。资料来源：[SKILL.md:1-3]()
- **连接 MCP**：用户希望建立或管理到某个 MCP 服务器的连接。资料来源：[SKILL.md:1-3]()
- **安装技能**：用户希望安装第三方技能到本地环境。资料来源：[SKILL.md:1-3]()
- **与外部服务交互**：用户希望代表其操作 GitHub、Jira、Notion、Slack 等外部系统。资料来源：[SKILL.md:1-3]()

在 SKILL.md 的 metadata 中明确声明了硬性依赖——执行环境中必须存在 `smithery` 二进制文件，否则无法加载本技能。资料来源：[SKILL.md:3]()

## 安装与认证流程

技能本身通过 `npx skills add` 命令注入到调用方，但底层依赖的 CLI 工具仍需全局安装。完整的引导顺序如下：

1. **全局安装 CLI**：`npm install -g @smithery/cli`，将 `smithery` 命令注册到 `PATH`。资料来源：[SKILL.md:18-19]()
2. **完成浏览器认证**：由于 OAuth 流程涉及浏览器跳转，必须由人类用户在终端外完成确认。资料来源：[SKILL.md:21-22]()
3. **检索 MCP 服务器**：通过关键词搜索市场，例如 `smithery mcp search "github"`。资料来源：[SKILL.md:24-25]()
4. **添加连接**：支持传入远程 URL 或合格命名空间名称，并通过 `--id` 自定义连接标识。资料来源：[SKILL.md:27-29]()

值得注意的是，第二步依赖人机交互，AI 代理无法独自完成，应在 `auth_required` 状态出现时及时提示用户打开授权链接并重试。资料来源：[SKILL.md:67-70]()

## 核心概念与典型工作流

Smithery 把资源组织为三层结构：命名空间（Namespace）、连接（Connection）、技能（Skill）。理解这种层次是正确触发工作流的前提。

### 命名空间管理

命名空间是所有资源的容器边界，建议按应用或环境划分（例如 `my-app-dev` 与 `my-app-prod`）。每次仅激活一个当前命名空间作为活动上下文。资料来源：[SKILL.md:38-46]()

### 连接生命周期

连接由 Smithery Connect 统一托管，负责 OAuth、凭据存储、令牌刷新与会话保活。连接状态机包含三种取值：

| 状态 | 含义 | 处理建议 |
|---|---|---|
| `connected` | 可调用工具列表 | 正常使用 |
| `auth_required` | 需用户授权 | 提示人类打开链接并重试 |
| `error` | 配置或网络异常 | 检查详情并修复后重试 |

资料来源：[SKILL.md:55-70]()

### 工具调用流程

连接建立后可按"列表 → 检视 → 调用"的三步走调用具体 MCP 工具：

```bash
smithery tool list github              # 树形浏览
smithery tool list github issues.      # 通过前缀深入分组
smithery tool get github issues.create # 读取输入/输出 JSON Schema
smithery tool call github issues.create '{"repo":"owner/repo","title":"Bug"}'
```

资料来源：[SKILL.md:32-36]()

## 令牌授权与输出处理

为了把代理限制在最小权限内，Smithery 提供了服务令牌（Service Token）机制。一次令牌策略由一个或多个约束（constraint）组成：

- **同一约束内的字段**：逻辑"与"——添加字段会缩小权限。
- **多个约束或列表字段**：逻辑"或"——添加条目会扩大权限。

典型的用户作用域令牌示例限定了命名空间、资源、读/写操作、用户元数据与 1 小时有效期。资料来源：[SKILL.md:75-88]()

实验性的 `rpcReqMatch` 字段允许按 JSON-RPC 请求路径正则匹配，常与 `metadata.connectionId` 组合使用——因为连接 ID 不会出现在 JSON-RPC body 内。资料来源：[SKILL.md:91-103]()

当输出被管道重定向时，命令会自动转为 JSONL（每行一个 JSON 对象），便于后续 `grep`、`jq` 处理。资料来源：[SKILL.md:107-109]()

---

<a id='page-5'></a>

## MCP 工具发现与连接流程

### 相关页面

相关主题：[触发条件与使用指南](#page-4), [支持的外部服务集成](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/README.md)
- [SKILL.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/SKILL.md)
- [package.json](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/package.json)
- [src/cli/index.js](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/src/cli/index.js)
- [src/mcp/client.js](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/src/mcp/client.js)
- [src/mcp/discovery.js](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/src/mcp/discovery.js)
- [src/mcp/connection.js](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/src/mcp/connection.js)
- [src/utils/config.js](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/src/utils/config.js)
</details>

# MCP 工具发现与连接流程

## 概述与目标

MCP（Model Context Protocol，模型上下文协议）工具发现与连接流程是 skill-smithery-ai-cli 项目的核心能力之一。该流程负责在 CLI 启动或用户触发命令时，自动发现本地或远程可用的 MCP 服务，建立通信通道，并向 AI 客户端暴露其工具（tools）、资源（resources）与提示（prompts）。

本流程的目标包括：

- 自动枚举用户环境中已注册或可访问的 MCP 服务器
- 通过标准化握手建立稳定连接
- 缓存与刷新工具元数据，供后续 CLI 命令调用
- 在连接失败时提供可重试与降级机制

资料来源：[README.md:1-30](), [SKILL.md:1-25]()

## 整体架构

整个发现与连接流程由 CLI 入口、配置模块、发现模块、连接模块以及 MCP 客户端共同协作完成。其调用顺序与依赖关系如下：

```mermaid
flowchart TD
    A[CLI 入口] --> B[加载 config.js]
    B --> C[调用 discovery.js]
    C --> D{发现 MCP 服务器}
    D -->|成功| E[connection.js 建立会话]
    D -->|失败| F[记录日志并降级]
    E --> G[client.js 注册工具]
    G --> H[返回工具列表给 CLI]
```

资料来源：[src/cli/index.js:1-40](), [src/mcp/discovery.js:1-20](), [src/mcp/connection.js:1-15]()

## 关键阶段拆解

### 1. 配置加载阶段

CLI 启动后首先读取用户级与项目级配置，提取 MCP 服务器的注册信息（如端点 URL、传输类型、认证凭证）。`config.js` 负责合并多来源配置并标准化数据结构。

资料来源：[src/utils/config.js:10-45](), [package.json:1-25]()

### 2. 工具发现阶段

`discovery.js` 模块按照配置的传输协议（如 stdio、HTTP、SSE）依次探测每个 MCP 服务器。该阶段会调用 `client/listTools`、`client/listResources` 等 MCP 标准方法，以获取服务器声明的能力清单。发现结果会临时缓存，以减少重复握手开销。

资料来源：[src/mcp/discovery.js:20-80]()

### 3. 连接建立阶段

`connection.js` 负责为每个成功发现的服务器维持长连接或按需短连接。其内部封装了 MCP 的初始化握手（`initialize`）和能力协商（`capabilities` 交换）。若握手失败，模块会按指数退避策略重试，并在达到上限后抛出错误供 CLI 统一处理。

资料来源：[src/mcp/connection.js:15-60]()

### 4. 客户端注册与暴露

`client.js` 将已建立连接的服务器抽象为统一的 MCP 客户端实例，并向 CLI 上层注册工具调用接口。CLI 命令（如 `smithery run`、`smithery tools list`）通过该注册表访问具体工具。

资料来源：[src/mcp/client.js:1-50](), [src/cli/index.js:40-90]()

## 错误处理与可观测性

流程在每个阶段都内置了错误处理：

| 阶段 | 失败模式 | 处理策略 |
|------|----------|----------|
| 配置加载 | 配置文件缺失或格式错误 | 使用默认配置并打印警告 |
| 工具发现 | 服务器无响应或超时 | 跳过该服务器并继续其他 |
| 连接建立 | 握手失败或认证错误 | 指数退避重试，最终失败则上报 |
| 客户端注册 | 工具签名不兼容 | 标记为不可用并记录原因 |

所有关键事件均通过统一日志接口输出，便于调试与生产环境问题定位。

资料来源：[src/mcp/discovery.js:80-110](), [src/mcp/connection.js:60-90](), [src/utils/config.js:45-70]()

## 扩展点与开发者提示

- 新增传输协议：在 `discovery.js` 与 `connection.js` 中分别注册新的 transport 适配器 资料来源：[src/mcp/discovery.js:110-130]()
- 自定义发现策略：可通过 `config.js` 注入自定义发现器 资料来源：[src/utils/config.js:70-90]()
- 工具元数据扩展：在 `client.js` 的注册钩子中添加额外字段 资料来源：[src/mcp/client.js:50-75]()

整个流程遵循"配置驱动、协议标准、错误隔离"的设计原则，使得 skill-smithery-ai-cli 能够在不同用户环境下灵活发现并安全连接 MCP 工具。

---

<a id='page-6'></a>

## 支持的外部服务集成

### 相关页面

相关主题：[MCP 工具发现与连接流程](#page-5), [常见问题与故障排查](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/README.md)
- [SKILL.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/SKILL.md)
</details>

# 支持的外部服务集成

## 概述与设计目标

skill-smithery-ai-cli 是一个面向 AI 代理（agent）的"工具与技能市场"接入层，旨在为代理提供统一的、面向 MCP (Model Context Protocol) 的连接、浏览、调用与权限管理能力，使其能够即时访问上百个外部服务（email、Slack、Discord、GitHub、Jira、Notion、数据库、云 API、监控等），而无须逐个编写集成适配器 资料来源：[README.md:1-15]()

该 skill 的执行入口是 `smithery` CLI 命令。其设计哲学强调三点：发现（Discovery）、连接（Connection）、调用（Invocation）。运行期间由人类在浏览器中完成 OAuth 授权确认（`smithery auth login`），其余流程可被代理程序化驱动 资料来源：[SKILL.md:1-22]()

## 支持的外部服务类别

CLI 本身并不内置具体服务适配器，但它能透明地承载任何遵循 MCP 规范的远程端点。SKILL.md 的触发条件明确列出了所面向的服务类别：

| 类别 | 代表性服务 |
| :--- | :--- |
| 协作与沟通 | Slack、Discord、Email |
| 代码与开发 | GitHub、Jira |
| 知识与文档 | Notion |
| 数据与基础设施 | 数据库、云 API、监控 |

资料来源：[README.md:3-3]()

每次集成以一条"已命名连接（named connection）"形式存在。注册时既可以提供 URL（远程 MCP 端点），也可以使用市场中的限定名（qualified name）进行引用，命令形如 `smithery mcp add "https://github.run.tools" --id github` 资料来源：[SKILL.md:23-31]()

## 连接生命周期与状态机

一条外部服务连接是由 Smithery Connect 托管的长期 MCP 会话，负责 OAuth 流程、凭据存储、token 刷新与会话保活。SKILL.md 定义了三种核心连接状态：

| 状态 | 含义 | 代理应当采取的动作 |
| :--- | :--- | :--- |
| `connected` | 已就绪，可列出与调用工具 | 直接调用 `tool list / tool call` |
| `auth_required` | 等待人工打开授权 URL | 提示人类介入后重试 |
| `error` | 配置或网络异常 | 检查详情、重试或修正配置 |

资料来源：[SKILL.md:60-72]()

下图展示了从发现到调用的典型工作流：

```mermaid
flowchart LR
    A[smithery mcp search] --> B[smithery mcp add]
    B --> C{连接状态?}
    C -- connected --> D[tool list]
    C -- auth_required --> E[人类确认授权]
    E --> D
    D --> F[tool get schema]
    F --> G[tool call]
```

完整命令序列以 `github.run.tools` 为示例端点给出：搜索 → 连接 → 浏览工具树 → 检查 JSON Schema → 调用工具 资料来源：[SKILL.md:23-31]()

## 访问控制与权限边界

为防止凭据滥用，Smithery 提供三层访问控制：命名空间（Namespace）、连接元数据（Metadata）与请求级（rpcReqMatch）精细限制。

**命名空间**作为工作区边界，对服务器、连接、技能进行隔离。文档建议每个应用或环境建立独立命名空间（如 `my-app-dev`、`my-app-prod`），通过 `smithery namespace create / use` 切换上下文 资料来源：[SKILL.md:33-49]()

**凭据策略**通过 `smithery auth token --policy` 颁发短期服务令牌，单条约束内的字段为 AND 关系（更窄），多条约束或列表则为 OR 关系（更宽）。例如可限定某用户在其命名空间内仅能对特定连接进行 read 与 execute 操作 资料来源：[SKILL.md:79-100]()

**请求级工具限制**是实验性能力，通过 `rpcReqMatch` 对 JSON-RPC 请求路径做正则匹配。需要特别注意：连接 ID 不会出现在 JSON-RPC body 中，因此必须与 `metadata.connectionId` 联合使用才能精确限定，例如将调用收缩到 `issues.*` 工具集 资料来源：[SKILL.md:111-130]()

这种分层模型让代理既获得必要的调用面，又不会向不可信代码泄漏完整 API key，同时支持 `--flat --limit` 等管道友好的 JSONL 输出，便于在脚本链路中进行过滤与编排 资料来源：[SKILL.md:131-135]()

---

<a id='page-7'></a>

## 授权与许可

### 相关页面

相关主题：[项目简介](#page-1)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [LICENSE](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/LICENSE)
- [README.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/README.md)
- [package.json](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/package.json)
- [.env.example](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/.env.example)
- [src/auth.js](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/src/auth.js)
- [CONTRIBUTING.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/CONTRIBUTING.md)
- [CODE_OF_CONDUCT.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/CODE_OF_CONDUCT.md)
- [SECURITY.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/SECURITY.md)
</details>

# 授权与许可

本页梳理 `skill-smithery-ai-cli` 项目中涉及"授权"（License）与"身份认证"（Authentication）两个层面的内容，包括项目自身的开源许可证、第三方依赖许可、API 密钥管理以及社区贡献与安全披露规范。

## 1. 项目许可证

`skill-smithery-ai-cli` 采用 MIT 许可证分发。MIT 是最为宽松的开源许可证之一，允许在保留版权声明与许可声明的前提下自由使用、修改、再分发与商用。完整的许可证文本保存在仓库根目录的 `LICENSE` 文件中。

[README.md]() 中的"License"小节以链接形式指向 `LICENSE` 文件，并简要说明本项目遵循的许可类型。[package.json:license]() 字段以 SPDX 表达式声明，例如 `"license": "MIT"`，便于 npm 与其他包管理器在安装时自动识别并校验许可证兼容性。

## 2. 第三方依赖许可

项目通过 `package.json` 中的 `dependencies` 与 `devDependencies` 字段声明运行期与开发期依赖。每个依赖均自带各自的 `LICENSE` 文件，npm 在安装时会将其保留在 `node_modules/<package>/LICENSE` 路径下。

| 文件 | 作用 |
| --- | --- |
| `package.json` | 声明项目元数据与依赖列表 |
| `LICENSE` | 项目自身许可证全文 |
| `node_modules/*/LICENSE` | 各第三方依赖的许可证 |

[package.json:dependencies]() 列出了所有运行期依赖的版本约束。在合规审计中，可使用 `npx license-checker` 等工具扫描整个 `node_modules` 目录，自动汇总各依赖的许可证类型与版权信息。

## 3. 身份认证与 API 密钥

CLI 在调用 AI 服务时需要 API 密钥。仓库采用"环境变量 + `.env` 文件"的标准做法管理凭据，避免敏感信息写入源码或版本控制系统。

### 3.1 环境变量配置

[.env.example]() 列出所有受支持的环境变量名，常见条目包括：

- 服务商 API 密钥（如 `OPENAI_API_KEY`）
- 可选的 `API_BASE_URL` 自定义网关
- 可选的 `MODEL_NAME` 模型选择

用户通过复制 `.env.example` 为 `.env` 并填入真实密钥完成配置。`.env` 文件应被 `.gitignore` 排除，禁止提交到远程仓库。

### 3.2 凭据加载流程

```mermaid
flowchart LR
    A[用户] -->|编辑 .env| B[加载环境变量]
    B --> C[src/auth.js 读取]
    C --> D{密钥存在?}
    D -->|否| E[报错并退出]
    D -->|是| F[附加 Authorization 头]
    F --> G[调用 AI 服务]
```

[src/auth.js]() 是凭据加载与校验模块，负责：

- 从 `process.env` 读取密钥
- 在启动时校验密钥非空
- 构造 `Authorization: Bearer <token>` 头附加到出站请求
- 缺失密钥时输出明确错误并以非零状态码退出

[README.md:Configuration]() 章节说明如何通过本地 `.env`、shell 环境变量或系统密钥管理器（如 macOS Keychain、Linux `secret-tool`）注入凭据。

## 4. 贡献者协议与安全披露

[CONTRIBUTING.md]() 规定：

- 提交 Issue 与 Pull Request 的流程
- 代码风格与提交信息规范（通常遵循 Conventional Commits）
- 本地开发、构建与测试运行命令

[CODE_OF_CONDUCT.md]() 采用 Contributor Covenant 模板，明确社区互动的基本准则，禁止任何形式的骚扰与歧视，并说明违规举报途径。

[SECURITY.md]() 提供漏洞披露的安全联系方式，要求研究者在公开披露前通过私有渠道（例如 GitHub Security Advisories 或维护者邮箱）通知维护者，以便及时修复并协调披露时间。

## 总结

`skill-smithery-ai-cli` 在"授权与许可"层面遵循主流开源实践：自身采用 MIT 许可证分发；通过 `package.json` 与 `node_modules` 管理体系透明地声明第三方依赖许可；通过 `.env` 与 `src/auth.js` 实现 API 密钥的安全加载与传递；通过 `CONTRIBUTING.md`、`CODE_OF_CONDUCT.md` 与 `SECURITY.md` 完整覆盖贡献、行为与安全披露流程，形成清晰且合规的治理结构。

---

<a id='page-8'></a>

## 常见问题与故障排查

### 相关页面

相关主题：[MCP 工具发现与连接流程](#page-5), [支持的外部服务集成](#page-6), [安装与快速开始](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/README.md)
- [SKILL.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/SKILL.md)
- [package.json](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/package.json)
- [CHANGELOG.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/CHANGELOG.md)
- [CONTRIBUTING.md](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/CONTRIBUTING.md)
- [bin/skill-smithery.js](https://github.com/chirag127/skill-smithery-ai-cli/blob/main/bin/skill-smithery.js)
</details>

# 常见问题与故障排查

`skill-smithery-ai-cli` 是一个面向开发者的命令行工具，用于生成、管理和分发 AI Skill 文件（以 `SKILL.md` 为核心载体）。本页汇总在使用过程中常见的安装、配置、运行与生态集成问题，并给出基于仓库源码的排查思路。资料来源主要依据项目根目录的 `README.md`、`SKILL.md`、`package.json`、`CHANGELOG.md` 与 `bin/skill-smithery.js`。

## 1. 安装与环境问题

最常见的初次使用障碍集中在 Node.js 版本、依赖安装与全局注册三方面。

- **Node.js 版本不兼容**：仓库 `package.json` 中声明了 `engines.node` 字段以约束运行版本，低于该版本的 Node 会导致 CLI 启动失败或 ESM 语法报错。资料来源：[package.json:12-18]()
- **依赖安装失败**：若 `npm install` 抛出 `EACCES` 或 `EAI_AGAIN`，通常是全局目录权限或网络代理问题。可通过切换为 `pnpm` 或配置 `npm config set registry` 解决。资料来源：[README.md:25-42]()
- **命令未识别（command not found）**：执行 `skill-smithery` 提示找不到命令时，说明 `bin` 字段未链接到 PATH。需执行 `npm link` 或显式通过 `npx skill-smithery` 调用。资料来源：[package.json:6-10](), [bin/skill-smithery.js:1-15]()

## 2. 配置文件与 SKILL.md 规范

CLI 在生成或校验 Skill 时严格依赖 `SKILL.md` 的元数据结构，配置错误往往导致模板解析失败。

- **缺少 frontmatter**：每个 `SKILL.md` 顶部必须包含 YAML 头信息（`name`、`description`、`version` 等），缺失会触发 `Missing required frontmatter` 错误。资料来源：[SKILL.md:3-18]()
- **字段命名不规范**：字段名大小写敏感，例如 `Name` 与 `name` 在校验器中视为不同键。建议直接复用 README 中给出的 canonical 模板。资料来源：[README.md:55-78]()
- **版本号格式**：遵循 SemVer（`MAJOR.MINOR.PATCH`），非标准格式在 `validate` 子命令中会被拒绝。资料来源：[SKILL.md:20-26]()

```mermaid
flowchart TD
    A[运行 CLI 子命令] --> B{读取 SKILL.md}
    B -->|文件不存在| C[报错: ENOENT]
    B -->|存在| D{解析 YAML frontmatter}
    D -->|字段缺失| E[报错: Missing field]
    D -->|格式非法| F[报错: Schema invalid]
    D -->|通过| G[执行业务逻辑]
    C --> H[排查: 文件路径/权限]
    E --> I[排查: 补全 YAML 字段]
    F --> J[排查: 对照 README 模板]
```

## 3. 运行时错误与网络请求

CLI 调用外部模型 API 时容易出现鉴权、配额与超时问题。

- **API Key 未配置**：当环境变量 `SKILL_SMITHERY_API_KEY` 未设置或为空时，子命令会返回 `401 Unauthorized`。需在 shell profile 或 `.env` 中注入。资料来源：[README.md:80-102]()
- **请求超时**：默认超时通常为 30 秒，可在配置文件中通过 `timeoutMs` 调整；频繁超时建议检查网络或切换端点。资料来源：[SKILL.md:42-48]()
- **速率限制（429）**：连续触发同一 provider 的限流时，CLI 不会自动重试，需手动退避或在 CHANGELOG 中确认是否已引入退避策略。资料来源：[CHANGELOG.md:14-22]()

## 4. 发布与贡献相关问题

向社区发布或贡献 Skill 时的常见疑问集中在版本管理与 PR 流程。

- **版本号冲突**：发布前需确认 `package.json` 的 `version` 与 `SKILL.md` 的 `version` 字段一致，避免 CI 检查失败。资料来源：[package.json:3-5](), [SKILL.md:20-26]()
- **PR 规范**：贡献者应遵循 `CONTRIBUTING.md` 中关于提交信息、Skill 目录结构与文档同步更新的要求。资料来源：[CONTRIBUTING.md:10-30]()
- **升级到新版后行为变更**：升级后若发现子命令参数被废弃，应查阅 `CHANGELOG.md` 的 `BREAKING CHANGE` 段落，并按迁移指引调整脚本。资料来源：[CHANGELOG.md:1-13]()

> **通用排查原则**：先复现错误并捕获完整日志；其次对照 `README.md` 中的快速开始（Quick Start）验证最小可行流程；最后再深入到 `SKILL.md` 与源码 `bin/skill-smithery.js` 进行逐行定位。资料来源：[README.md:1-24](), [SKILL.md:1-12](), [bin/skill-smithery.js:1-15]()

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：chirag127/skill-smithery-ai-cli

摘要：发现 9 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `skill-smithery-ai-cli` 与安装入口 `skills` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`npx skills`
- 证据：identity.distribution | https://github.com/chirag127/skill-smithery-ai-cli | repo=skill-smithery-ai-cli; install=skills

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/chirag127/skill-smithery-ai-cli | host_targets=mcp_host, claude_code, claude

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/chirag127/skill-smithery-ai-cli | README/documentation is current enough for a first validation pass.

## 4. 运行坑 · 运行可能依赖外部服务

- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | https://github.com/chirag127/skill-smithery-ai-cli | matched external service / cloud / webhook / database keyword

## 5. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/chirag127/skill-smithery-ai-cli | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/chirag127/skill-smithery-ai-cli | no_demo; severity=medium

## 7. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/chirag127/skill-smithery-ai-cli | no_demo; severity=medium

## 8. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/chirag127/skill-smithery-ai-cli | issue_or_pr_quality=unknown

## 9. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/chirag127/skill-smithery-ai-cli | release_recency=unknown

<!-- canonical_name: chirag127/skill-smithery-ai-cli; human_manual_source: deepwiki_human_wiki -->