# MCP 接入

PageDrop 提供官方 MCP 服务 [`@pagedrop/mcp`](https://www.npmjs.com/package/@pagedrop/mcp)，
把 v1 REST API 暴露成 6 个 MCP tool，任何支持 MCP 的 AI 客户端（Claude Code、
Cursor、Claude Desktop，或基于
[`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol) 自研的
Agent）都能直接调用。两种传输方式：**stdio** 给本地客户端用，**streamable HTTP**
给远端 / 多租户代理用。

## 可用的 tool

| Tool | 对应接口 |
|---|---|
| `pagedrop_upload(content, name, kind, folder?, share?)` | `POST /v1/files`（multipart，可选内嵌 share 段） |
| `pagedrop_share(fileId, options)` | `POST /v1/shares` |
| `pagedrop_revoke(shareId)` | `DELETE /v1/shares/:id` |
| `pagedrop_get(fileId)` | `GET /v1/files/:id` |
| `pagedrop_list(folderId?)` | `GET /v1/files` |
| `pagedrop_validate(content, kind)` | `POST /v1/validate` |

底层 API 报错会以 MCP `isError: true` 形式返回，content 体里带
`{ code, status, message }`，Agent 可以基于 `code` 分支处理
（`RATE_LIMITED`、`INFECTED`、`SLUG_TAKEN` 等）。

## stdio 模式（Claude Code / Cursor / Claude Desktop）

### 安装

```bash
npm install -g @pagedrop/mcp
```

（或者免安装直接跑：`npx -y @pagedrop/mcp`。）

### 配置

**Claude Code**（`~/.config/claude-code/mcp.json`）：

```json
{
  "mcpServers": {
    "pagedrop": {
      "command": "pagedrop-mcp",
      "env": {
        "PAGEDROP_API_URL": "http://117.72.193.223:10180",
        "PAGEDROP_API_KEY": "pd_XXXXXXXX_YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
      }
    }
  }
}
```

**Cursor**（`~/.cursor/mcp.json`）和 **Claude Desktop**
（macOS 下是 `~/Library/Application Support/Claude/claude_desktop_config.json`，
Windows / Linux 路径类似）用同样的 JSON 结构。

重启客户端后，6 个 `pagedrop_*` tool 应该会出现在可用 tool 列表里。

### 获取 token

打开 [/developers/tokens](/developers/tokens) → 点 "新建 token" → 把
`pd_xxxxxxxx_yyyy...` 拷到 `PAGEDROP_API_KEY` 里。明文 token 只显示一次，请妥善保存。

## Streamable HTTP 模式（远端 / 共享部署）

如果是多用户部署或浏览器 MCP 客户端，跑 HTTP 传输：

```bash
PAGEDROP_API_URL=http://117.72.193.223:10180 \
PAGEDROP_API_KEY=pd_xxx_yyy \
PORT=7180 HOST=0.0.0.0 \
pagedrop-mcp-http
```

客户端配置：

```json
{
  "mcpServers": {
    "pagedrop": {
      "url": "http://your-host:7180/mcp",
      "transport": "streamable-http"
    }
  }
}
```

HTTP 服务默认是单租户（一个进程 = 一个 `PAGEDROP_API_KEY`）。生产环境请在前面套
TLS + 反向代理鉴权；默认 `HOST=127.0.0.1` 只绑本机，避免误暴露。

健康检查：`GET /healthz` → `{ ok: true, server: '@pagedrop/mcp' }`。

## 一个完整的"提示词 → 上传"演示

配好 MCP 服务后，把这段提示直接发给你的 AI 客户端：

> 把下面这几条要点整理成一份干净的 Markdown 摘要，然后上传到 PageDrop，
> 生成一个 7 天有效期的分享链接。要点：
> 1. 报价上调 5%
> 2. 运维改用 GMT 时区
> 3. Q4 之前不招人

预期行为：

1. Agent 起草 markdown。
2. 调 `pagedrop_validate({ content, kind: 'MARKDOWN' })` 检查 CRLF / 未闭合代码块等。
3. 调 `pagedrop_upload({ name: 'notes-...md', kind: 'MARKDOWN', content,
   share: { expiresInDays: 7 } })` 上传并直接建分享。
4. Agent 回复返回的 `url`，并说明默认的有效期 / 密码策略。

## 源码与反馈

- npm：<https://www.npmjs.com/package/@pagedrop/mcp>
- 源码：PageDrop 仓库的 `packages/mcp/src/`
- Tool 规格：`packages/mcp/src/tools.ts`（zod schema，可以直接贴进你的客户端获得类型提示）