# 社媒数据 MCP · Agent 技能文件

> 一份技能文件，装进你的 AI Agent，它就会自己学会读六个平台的公开社媒数据：
> TikTok、Instagram、YouTube、X（Twitter）、抖音、小红书。
> 服务地址已托管，你只需要一个 API Key。

## 一、接入方式（二选一）

**方式 A：远程 MCP（推荐，什么都不用装）**

```json
{
  "mcpServers": {
    "busybee": {
      "type": "streamable-http",
      "url": "https://lucydomi.com/mcp",
      "headers": { "Authorization": "Bearer sk-你的密钥" }
    }
  }
}
```

也兼容 SSE：`https://lucydomi.com/sse`。

**方式 B：本地安装（只支持 stdio 的客户端，如 Claude Desktop）**

```json
{
  "mcpServers": {
    "busybee": {
      "command": "uvx",
      "args": ["busybee-mcp"],
      "env": { "BUSYBEE_API_KEY": "sk-你的密钥" }
    }
  }
}
```

**方式 C：REST（不用 MCP 也能调）**

```bash
curl -X POST https://lucydomi.com/mcp/v1/search_creators \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"platform":"tiktok","keyword":"coffee","limit":5}'
```

> 没有密钥？在 https://lucydomi.com/sign-up 注册即得体验金，密钥在控制台「令牌」页创建。

## 二、十个工具（工具名可直接当 REST 路径用）

| 工具 | 作用 | 必填参数 |
|---|---|---|
| `list_platforms` | 列出六个平台各自支持哪些操作 | 无 |
| `check_balance` | 查当前密钥余额与已用金额 | 无 |
| `search_creators` | 按关键词搜达人 / 账号 | `platform`、`keyword` |
| `get_creator` | 查单个账号详情（粉丝、简介、作品数） | `platform`、`creator` |
| `list_creator_posts` | 拉某账号最近发布的内容 | `platform`、`creator` |
| `search_posts` | 按关键词搜内容（视频 / 笔记 / 帖子） | `platform`、`keyword` |
| `get_post` | 查单条内容详情 | `platform`、`post_id` |
| `get_comments` | 拉某条内容的评论列表 | `platform`、`post_id` |
| `get_comment_insights` | 评论洞察：情绪分布、提问占比、高频词、高赞评论 | `platform`、`post_id` |
| `get_trending` | 拉平台热榜 / 热搜 | `platform` |

## 三、参数约定（容错已做好，不用记全）

- `platform` 支持别名：`tt`/`tiktok`、`ig`/`ins`/`instagram`、`yt`/`youtube`、`x`/`twitter`、`dy`/`douyin`/`抖音`、`xhs`/`小红书`
- 直接传内容链接也行，服务会自动识别：`https://www.tiktok.com/@user/video/123…`、`https://youtu.be/xxx`、`https://x.com/user/status/123…`
- `creator` 传 handle（`@nasa`）、账号 ID 或主页链接都行，服务会自动解析
- `limit` 默认 10，各平台上限不同（小红书单账号内容最多 8 条）；超出会自动钳制，不报错
- 未知名单/参数会返回明确错误码，不会静默给你别家平台的数据

## 四、返回格式（统一字段，跨平台一致）

```json
{
  "ok": true,
  "platform": "tiktok",
  "count": 5,
  "items": [
    {
      "id": "7…",
      "title": "…",
      "author": "@…",
      "url": "https://…",
      "created_at": "2026-10-20T12:00:00Z",
      "likes": 1234,
      "comments": 56,
      "views": 78900
    }
  ],
  "cost_usd": 0.003,
  "balance_usd": 1.234
}
```

- 每次调用都返回 `cost_usd`（本次花费）和 `balance_usd`（剩余余额），Agent 可以自己记账
- 失败时返回 `{"ok": false, "error": "错误码"}`，常见：`unknown_platform`、`unsupported_tool`、`insufficient_balance`、`forbidden`（分组未开通）、`http_4xx`

## 五、计费口径

- 按次计费，成功返回才扣费；查余额本身不扣费
- 具体单价在 https://lucydomi.com/pricing 查询
- 国内平台（抖音、小红书）与海外平台（TikTok、Instagram、YouTube、X）分组不同，未开通的分组会返回 `forbidden`

## 六、给 Agent 的建议工作流

1. 先 `check_balance` 确认余额，再干活，避免中途余额不足
2. 不确定平台支持什么，先 `list_platforms`
3. 找账号 → `search_creators`；摸内容 → `search_posts`；摸口碑 → `get_comments` + `get_comment_insights`
4. 需要更多数据时用 `limit` 递增，不要一次要很大（各平台有上限）
5. 拿到的 `items[].url` 可直接作为出处引用

## 七、其他

- 本服务只读公开数据，不发布、不点赞、不私信、不投流
- 数据使用规范：https://lucydomi.com/data-policy
- 服务说明与示例：https://lucydomi.com/mcp-guide
- OpenAPI 描述文件（可直接导入 Dify / n8n / FastGPT）：https://lucydomi.com/mcp/openapi.json
- OpenAI 工具格式：https://lucydomi.com/mcp/tools?format=openai