# 从安装到首次成功调用

从一个具体任务开始：[查询一家企业的简介](ONE-SUCCESS-CASE.md)。完成后可用[社区分享素材包](SHARING-KIT.md)记录真实体验与限制。

这是一条统一的最短路径。它把已有教程串成“安装 → 连接 → 找到工具 → 首次只读调用”，不替代各服务商文档。首次调用只选你已获准使用、费用与权限边界明确的只读任务；截图、GIF、连接成功或工具缓存都不等于真实业务调用通过。

需要可直接执行的验收任务时，选择[企业信息只读查询、本地智能文档解析、授权办公文档或日程查询](FIRST-SUCCESS-SCENARIOS.md)中的一个场景；记录状态时使用[可信状态文案规范](TRUSTED-STATUS-COPY.md)，缺少账号、组织、费用或调用证据就明确写“未知/待验收”。

## 开始前先填一张验收卡

把下列内容记在本地工作笔记中，不要粘贴真实 Token、Cookie、授权码或客户数据。无法确认的字段保留“未知/待服务商确认”，不用推测补齐。

| 字段 | 要记录的内容 |
|---|---|
| 连接与范围 | 连接名、`serverName`、当前项目/全局、插件版本 |
| 授权前提 | 账号/组织资格、管理员批准、OAuth scope 或 API Key 权限 |
| 费用 | 免费额度、套餐/按次计费或“未知/待服务商确认” |
| 数据去向 | 仅本机进程，还是会向哪个远程服务发送哪些参数/文件 |
| 首次任务 | 一个已获准、只读、无敏感数据的具体任务 |
| 通过证据 | 配置、发现/注册、业务调用三层的独立结果与时间 |

三条任务教程都按这张卡验收：[JSON 迁移](JSON-MIGRATION.md)、[OAuth 首次成功](OAUTH-DIAGNOSTICS.md)、[工具发现与连接恢复](TOOL-SEARCH-RECOVERY.md)。

## 1. 安装并重启正确的 profile

当前默认安装布局中，DSH Desktop 和 `dsh web` 都从本机 `web` profile 加载插件，因此两种宿主都使用同一条安装命令；不要因为使用 Desktop 就把命令改成 `--profile desktop`。

```bash
dsh plugin --profile web add dsh-mcp-connector
```

安装或升级后，只重启你正在使用的宿主：DSH Desktop 需完全退出应用后重新打开；`dsh web` 需停止原进程后重新启动。打开左侧“MCP连接器”；若侧边栏入口已隐藏，从“设置 → 插件 → 插件配置 → MCP连接器”点击“打开 MCP连接器”。自定义过 profile 布局的部署应以其宿主配置为准。

## 2. 只选一条连接路径

- 已有其他客户端配置：按[迁移 `mcpServers` JSON](JSON-MIGRATION.md)导入，并在提交前确认当前项目或全局范围。
- 使用市场中的 OAuth / API Key 连接器：按服务商要求授权或在本机录入凭据；卡住时转到[OAuth 连接诊断](OAUTH-DIAGNOSTICS.md)。OAuth 能否使用取决于服务商客户端注册政策、账号权限和授权范围。
- 自建 HTTP / stdio Server：按[用户手册的自定义连接说明](../USER-GUIDE.md#6-添加自定义连接)填写可信端点或本机命令。普通 REST API 或 CLI 不能因此自动变成 MCP Server。

连接后先在“已安装”确认名称、项目/全局范围和启停状态。这里只证明配置已保存，不证明工具已经注册或服务当前可调用。

## 3. 找到要调用的工具

在当前 Workspace 打开“工具”，搜索预期工具，核对连接、Server、工具来源和参数。若结果为空、陈旧或最近发现失败，按[跨连接找工具与恢复](TOOL-SEARCH-RECOVERY.md)处理。

工具页只展示当前范围内已启用连接的安全缓存，不执行目标工具。继续之前，确认预期工具已被发现；必要时核对 DSH Host 中的 `mcp__<serverName>__*` 注册状态。

## 4. 在正常 DSH 会话完成首次只读调用

插件页面没有绕过审批的“试运行”按钮。回到正常 DSH 会话，替换尖括号后发送：

```text
请仅使用 MCP 工具 mcp__<serverName>__<toolName> 完成“<一个服务商允许的只读任务>”。
调用前请列出工具来源、将发送的关键参数，以及是否可能产生费用或副作用。
如果需要写入、付费、发布、删除，或超出当前账户权限，请停止并先请求我确认。
```

实际工具执行及权限/审批由 DSH Host 管理。服务商可能另有账号资格、配额和费用；不要为首次验收使用真实敏感数据，或选择写入、删除、发布等有副作用的操作。

## 5. 记录三个独立结果

| 层次 | 通过条件 |
|---|---|
| 配置 | “已安装”中存在目标连接，范围和启停状态正确 |
| 发现/注册 | “工具”中出现预期工具和来源；必要时确认 Host 注册状态 |
| 调用 | 正常会话经 Host 审批链完成服务商许可的只读调用，并得到可辨认结果 |

只有第三项通过，才能把这个具体场景记为“首次成功调用”。若第三项没有条件验证，请明确写“无数据/待验收”，不要从下载量、页面浏览、连接成功或演示素材推算。

如果这条路径确实帮你完成首次调用，欢迎克制地 [Star 项目](https://github.com/duhu2000/dsh-mcp-connector/stargazers)、[提交新连接器](https://github.com/duhu2000/dsh-mcp-connector-registry/blob/main/docs/ONBOARDING.md)或[参与贡献](../../CONTRIBUTING.md)。