# ashareapi MCP 安装与验证工作流

> 面向 AI Agent 执行。目标：把 `ashareapi` MCP 接入用户的 AI 客户端，并完成一次真实调用验证。
>
> 重要：ashareapi 使用 **API Key 或免费模式**，不使用 OAuth。不要自行改成 OAuth 配置。

## 输入参数

| 参数 | 必填 | 说明 |
|---|---|---|
| `client` | 是 | 客户端：Claude Code / Cursor / VS Code / Codex / OpenCode / WorkBuddy 等 |
| `apiKey` | 否 | `ct-` 开头的 Key。没有则先用免费工具 |
| `freeOnly` | 否 | 为 true 时不配置 Authorization，只使用免费工具 |

如果用户没有提供 `client`，先问清楚，不要猜。

---

## 阶段 1：确认客户端

按客户端选择配置方式：

| 客户端 | 配置位置 |
|---|---|
| Claude Code | `.mcp.json` |
| Cursor | `.cursor/mcp.json` |
| VS Code | `.vscode/mcp.json` |
| Codex | `~/.codex/config.toml` |
| OpenCode | `opencode.json` |
| WorkBuddy | `~/.workbuddy/mcp.json` |
| 其他 | 查看客户端 MCP 设置，或参考 https://ashareapi.com/mcp |

如果是纯 UI 客户端（Trae / Manus / 国内平台等），不要伪造配置文件；按客户端界面引导用户添加远程 MCP。

---

## 阶段 2：确认 Key 模式

### 2a. 有 API Key

使用请求头：

```text
Authorization: Bearer <apiKey>
```

不要在终端输出、日志、总结或聊天记录中完整展示 Key。

### 2b. 没有 Key

使用免费模式，不发送 Authorization 头。

免费工具包括：

```text
quote
kline
hot
market_overview
changedist
wiki_search
```

其余工具需要 Key。不要承诺免费模式能调用全部工具。

---

## 阶段 3：写入 MCP 配置

### 3a. 通用 JSON 客户端

适用于 Claude Code、Cursor、WorkBuddy 等使用 `mcpServers` 的客户端：

```json
{
  "mcpServers": {
    "ashareapi": {
      "type": "http",
      "url": "https://api.ashareapi.com/mcp",
      "headers": {
        "Authorization": "Bearer <apiKey>"
      }
    }
  }
}
```

免费模式删除 `headers`：

```json
{
  "mcpServers": {
    "ashareapi": {
      "type": "http",
      "url": "https://api.ashareapi.com/mcp"
    }
  }
}
```

### 3b. VS Code

```json
{
  "servers": {
    "ashareapi": {
      "type": "http",
      "url": "https://api.ashareapi.com/mcp",
      "headers": {
        "Authorization": "Bearer <apiKey>"
      }
    }
  }
}
```

### 3c. Codex

写入 `~/.codex/config.toml`：

```toml
[mcp_servers.ashareapi]
url = "https://api.ashareapi.com/mcp"
http_headers = { Authorization = "Bearer <apiKey>" }
```

### 3d. OpenCode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ashareapi": {
      "type": "remote",
      "url": "https://api.ashareapi.com/mcp",
      "headers": {
        "Authorization": "Bearer <apiKey>"
      }
    }
  }
}
```

### 3e. 不能设置请求头的客户端

部分网页版/托管平台不允许自定义 Header，可把 Key 放在 URL：

```text
https://api.ashareapi.com/mcp?key=<apiKey>
```

同时明确告知用户：

```text
生产环境优先使用请求头；
URL 中的 Key 可能进入浏览器历史、代理日志和平台日志。
```

---

## 阶段 4：重新加载客户端

```text
Claude Code / Cursor / VS Code / OpenCode：重新加载窗口或重启客户端
Codex：重新启动 Codex CLI / 桌面端
WorkBuddy：重新加载 MCP 连接
UI 平台：保存后重新连接
```

不要跳过这一步。

---

## 阶段 5：验证

### 5.1 检查服务器

确认客户端的 MCP 列表里出现：

```text
ashareapi
```

### 5.2 检查工具

确认能看到 `ashare_` 前缀的工具，例如：

```text
ashare_quote
ashare_kline
```

工具数量会随版本变化，不要用固定数量判断失败。

### 5.3 发起真实调用

让用户或 AI 调用一次：

```text
用 ashareapi 查一下 600519 的最新行情
```

成功判据：

```text
返回包含 600519 的行情数据
不是 401 / 403 / 404 / 405
```

### 5.4 免费模式验证

如果没有 Key，只验证免费工具：

```text
用 ashareapi 查一下 600519 的 K 线
```

---

## 阶段 6：故障处理

| 现象 | 可能原因 | 处理 |
|---|---|---|
| 列表里没有 `ashareapi` | 配置未保存 / 未重载 | 检查 JSON/TOML 语法，重启客户端 |
| 401 | Key 缺失或错误 | 检查 `Bearer <apiKey>`，确认 Key 未过期 |
| 403 | 档位无权 / Key 被限制 | 检查 Key 档位与工具权限 |
| 404 | URL 错 | 必须是 `https://api.ashareapi.com/mcp` |
| 405 | 传输方式错 | 使用 Streamable HTTP，不要用 SSE 旧地址 |
| 连接超时 | 网络/DNS/代理 | 检查网络，尝试浏览器打开 `https://api.ashareapi.com/docs` |
| 能连上但没工具 | 客户端未完成初始化 | 重新加载，检查 MCP 日志 |

### 不要做

```text
不要改成 OAuth
不要猜测不存在的 endpoint
不要把 Key 写入公开仓库
不要用固定工具数量判断安装失败
```

---

## 完成标准

```text
1. 客户端出现 ashareapi
2. 能看到 ashare_ 工具
3. 成功返回一次 600519 行情或 K 线
4. 没有把 Key 输出到日志/聊天
```

全部满足后，向用户报告：

```text
ashareapi MCP 已接入并验证成功。
可以继续问：某只股票今天资金怎么样、最近哪个板块最强、帮我找 PE<20 且 ROE>15 的股票。
```
