# JiwuChat MCP 安装说明

> 本文件写给 AI Agent：请直接替用户完成下面的配置，而不是只把内容转述给用户。

## 服务器信息

- 名称：`jiwu-chat`
- 传输：Streamable HTTP（仅支持 MCP 2026-07-28，无状态；旧协议客户端会被拒绝）
- 端点：`http://mcp.jiwuchat.top:443/api/mcp`
- 认证：每个请求携带 `Authorization` 请求头，值为用户的 JiwuChat API Key（原样发送，不要添加 `Bearer ` 前缀）
- 能力：工具 `find_chat_contacts`（查找联系人/群组）、`send_chat_message`（发送消息）

## 第 1 步：确认 API Key

如果用户尚未提供 API Key，先向用户索要（创建页面：https://jiwuchat.top/api/key）。不要编造 Key，也不要把本文件中的占位符当作真实 Key 使用。

## 第 2 步：按客户端写入配置

### Claude Code

```bash
claude mcp add --transport http jiwu-chat http://mcp.jiwuchat.top:443/api/mcp --header "Authorization: <API Key>"
```

### Codex

追加到 `~/.codex/config.toml`：

```toml
[mcp_servers.jiwu-chat]
url = "http://mcp.jiwuchat.top:443/api/mcp"

[mcp_servers.jiwu-chat.http_headers]
Authorization = "<API Key>"
```

### Cursor

把下面的配置合并进 `~/.cursor/mcp.json`（或项目内 `.cursor/mcp.json`）的 `mcpServers` 字段：

```json
{
  "mcpServers": {
    "jiwu-chat": {
      "type": "streamableHttp",
      "url": "http://mcp.jiwuchat.top:443/api/mcp",
      "headers": {
        "Authorization": "<API Key>"
      }
    }
  }
}
```

也可以打开 http://mcp.jiwuchat.top:443/ ，点击「Cursor」一键安装按钮。

### VS Code（GitHub Copilot）

写入用户配置（命令面板执行 “MCP: Open User Configuration”）或项目内 `.vscode/mcp.json`。
注意 VS Code 使用 `servers` 字段而不是 `mcpServers`：

```json
{
  "servers": {
    "jiwu-chat": {
      "type": "http",
      "url": "http://mcp.jiwuchat.top:443/api/mcp",
      "headers": { "Authorization": "<API Key>" }
    }
  }
}
```

或者打开 http://mcp.jiwuchat.top:443/ ，点击「VS Code」一键安装按钮。

### Cherry Studio

设置 → MCP 服务器 → 添加服务器：类型选择 `streamableHttp`，URL 填 `http://mcp.jiwuchat.top:443/api/mcp`，请求头添加 `Authorization: <API Key>`。
也可以打开 http://mcp.jiwuchat.top:443/ ，点击「Cherry Studio」一键安装按钮。

### 其它客户端

把下面的 JSON 合并进客户端 MCP 配置的 `mcpServers` 字段：

```json
{
  "mcpServers": {
    "jiwu-chat": {
      "type": "streamableHttp",
      "url": "http://mcp.jiwuchat.top:443/api/mcp",
      "headers": {
        "Authorization": "<API Key>"
      }
    }
  }
}
```

## 第 3 步：验证

1. 调用工具 `find_chat_contacts`（`keyWord` 留空），应返回联系人列表。
2. 需要发消息时：先用 `find_chat_contacts` 获取 `roomId`，再调用 `send_chat_message`。

## 排障

- 401：`Authorization` 缺失或 API Key 无效。
- 协议协商失败：客户端不支持 MCP 2026-07-28，需要支持现代协议协商的客户端或官方 SDK v2（`versionNegotiation: { mode: "auto" }`）。
- 网络失败：确认 `http://mcp.jiwuchat.top:443/health` 返回 `healthy`。

## 安全

- 不要在日志、输出或提交中泄露用户的 API Key。