# spider-mcp

面向 agent 的多平台内容平台自动化 MCP(抖音 / 小红书)。通过 MCP 协议暴露登录、搜索、抓取、发布、评论等能力,供 Claude Code、Cursor 等 agent 调用。

## 特性

- **多租户**:每个账号(`accountId`)一套隔离的浏览器 profile 与登录态
- **浏览器自动化**:基于 Playwright,复用登录态,适配反爬严格的平台
- **双传输**:`stdio`(本地开发)+ HTTP/SSE(线上部署)
- **媒体上传**:`upload_asset` + `MediaRef`(url / asset / base64 / path)

## 当前状态

骨架已就位,9 个 tool 已注册并可通过 MCP 协议调用,具体平台实现逐步填充中。

| 部分 | 状态 |
|------|------|
| MCP server(stdio) | ✅ |
| 类型契约 / tool schema | ✅ |
| BrowserManager | 🚧 进行中 |
| DouyinHandler 各方法 | 🟡 桩 |

## 依赖安装

```bash
bun install
bunx playwright install chromium   # 若复用系统 Chrome 可跳过
```

## 在 Claude Code 中接入(stdio)

### 方式一:CLI 命令(推荐)

```bash
claude mcp add spider-mcp -- bun /Users/zeek/Projects/MCP/spider-mcp/index.ts
```

> 可加 scope:`-s user`(全局)或 `-s project`(仅当前项目,写入 `.mcp.json`)。

### 方式二:项目配置文件

在项目根目录创建 `.mcp.json`:

```json
{
  "mcpServers": {
    "spider-mcp": {
      "command": "bun",
      "args": ["/Users/zeek/Projects/MCP/spider-mcp/index.ts"]
    }
  }
}
```

> 全局则编辑 `~/.claude.json` 中的 `mcpServers`。

### 验证

接入后在 Claude Code 里:

```
/mcp
```

应能看到 `spider-mcp` 处于 `connected` 状态,并列出 9 个 tool:

| tool | 说明 |
|------|------|
| `login` | 发起登录,返回二维码(首次 `loggedIn=false`) |
| `login_status` | 查询登录态(配合 login 轮询) |
| `logout` | 退出并清理 session |
| `search` | 搜索作品 |
| `get_note` | 抓取单个作品详情 |
| `get_comments` | 抓取评论列表 |
| `publish` | 发布内容(图文/视频) |
| `comment` | 发评论 |
| `upload_asset` | 上传媒体,返回 assetId |

所有 tool 都带 `platform`(`douyin`/`xiaohongshu`)和 `accountId` 参数。

### 本地调试

不开 Claude Code,直接用 stdin/stdout 喂 JSON-RPC 验证:

```bash
# 初始化握手 + 列出所有 tool
printf '%s\n%s\n%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| bun run index.ts
```

## 目录结构

```
src/
├── types.ts              # 共享数据类型
├── server.ts             # MCP server:tool 注册 + 路由
├── registry.ts           # 平台 handler 注册表
├── stdio.ts              # stdio 传输入口(本地开发)
├── http.ts               # HTTP/SSE 传输入口(线上,占位)
├── browser/manager.ts    # Playwright 持久化浏览器管理(多租户)
├── platforms/
│   ├── base.ts           # PlatformHandler 抽象接口
│   └── douyin.ts         # 抖音实现
├── tools/schemas.ts      # tool 的 zod 参数 schema
└── assets/store.ts       # 媒体资产存储
```

## 开发

```bash
bun run typecheck   # tsc --noEmit
bun run start       # 启动 stdio server
```