使用说明
帕克
X/Twitter MCP连接器
“主啊，这些凡人真是愚蠢至极！”
帕克是一个 主控程序 将X（Twitter）API v2公开为工具的服务器。它通过自动令牌轮换、速率限制跟踪、图像上传和线程构造来处理OAuth 2.0 PKCE，因此消费应用程序不必这样做。
以莎士比亚笔下的淘气精灵命名 仲夏夜之梦 --快速、随时随地、简短的话语会引起巨大的反应。
快速开始
1.X开发人员设置
- 在以下位置创建项目 developer.x.com
- 选择 基本 级别（200美元/月）或更高——免费级别不足以进行有意义的使用
- 创建一个 OAuth 2.0应用程序 类型：“Web App”（用于PKCE流）
- 添加
http://localhost:3000/oauth/callback作为重定向URI - 注意你的客户端ID（公共）——PKCE不需要客户端密钥
2.MCP配置
将Puck添加到MCP客户端配置中：
{
"mcpServers": {
"puck": {
"command": "npx",
"args": ["@ticktockbent/puck"],
"env": {
"PUCK_CLIENT_ID": "your_oauth2_client_id"
}
}
}
}
3.第一轮
在第一次连接时，Puck会打开浏览器以获得X OAuth同意。一旦获得授权，令牌将被加密并存储在本地 ~/.puck/tokens.json访问令牌会自动刷新（2小时到期，可轮换刷新令牌）。后续运行以静默方式进行身份验证。
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
PUCK_CLIENT_ID |
是 | X OAuth 2.0客户端ID |
PUCK_REDIRECT_URI |
否 | OAuth回调URI（默认值： http://localhost:3000/oauth/callback) |
PUCK_TOKEN_PATH |
否 | 令牌存储位置（默认值： ~/.puck/tokens.json) |
PUCK_API_TIER |
否 | API层： free, basic, pro, enterprise （默认值： basic) |
PUCK_LOG_LEVEL |
否 | 日志记录级别（默认值： info) |
工具
认证
| 工具 | 说明 |
|---|---|
puck_auth_status |
检查身份验证状态、用户名、作用域、令牌过期和API层 |
puck_auth_logout |
撤销令牌并清除存储的凭据 |
puck_rate_status |
显示所有跟踪端点组的当前速率限制状态 |
帖子
| 工具 | 说明 |
|---|---|
puck_post_create |
创建帖子（支持文本、投票、回复设置、引用推文、媒体） |
puck_post_edit |
在30分钟/5编辑窗口内编辑帖子 |
puck_post_delete |
删除帖子 |
puck_post_get |
通过ID获取帖子，并进行全字段扩展 |
puck_post_lookup |
按ID批量查找帖子（最多100个） |
线程
| 工具 | 说明 |
|---|---|
puck_thread_create |
从帖子对象数组创建一个线程（自动处理链式回复ID） |
puck_thread_get |
按对话ID获取一个帖子中的所有帖子 |
媒体
| 工具 | 说明 |
|---|---|
puck_media_upload |
上传图像（JPG、PNG、WebP，最多4个文件，每个文件最大5MB），可选alt文本 |
puck_media_status |
检查上传媒体项目的处理状态 |
时间线
| 工具 | 说明 |
|---|---|
puck_timeline_user |
通过用户ID或@username获取用户的帖子 |
puck_timeline_mentions |
获取经过身份验证的用户的提及 |
建筑
src/
├── index.ts # MCP server entry point (stdio transport)
├── types.ts # TypeScript interfaces and X API types
├── auth/
│ ├── oauth2-pkce.ts # OAuth 2.0 PKCE flow, browser consent, token exchange
│ ├── token-manager.ts # Proactive refresh, rotation handling, deduplication
│ └── storage.ts # Encrypted token storage (~/.puck/)
├── client/
│ ├── x-api.ts # X API v2 client wrapper (all calls route through here)
│ ├── rate-limiter.ts # Per-endpoint rate limit tracking from response headers
│ ├── media.ts # Image upload pipeline
│ └── fields.ts # Field/expansion constants for v2 response shaping
├── tools/
│ ├── auth.ts # Auth status, logout, rate status tools
│ ├── posts.ts # Post CRUD and thread construction
│ ├── media.ts # Media upload tools
│ └── timelines.ts # Timeline and mentions tools
└── util/
├── character-count.ts # Accurate post length calculation (URLs=23, emoji=2)
├── pagination.ts # Pagination helper
└── errors.ts # Typed error classes and normalizer
关键设计决策
- 无状态 -没有缓存API响应。每个工具调用都会直接命中X API。利率限制状态是唯一的例外。
- 单一账户 --每个服务器实例一个X帐户。为多个帐户运行多个实例。
- 仅限V2 --没有v1.1端点。整个API表面使用
api.x.com/2/. - 响应标头速率限制 --从以下位置跟踪费率限制
x-rate-limit-*响应标头。没有预播种，没有猜测。只有当标题确认窗口已耗尽时才会阻塞。 - 主动令牌刷新 --访问令牌每2小时过期一次。Puck在剩余时间不足15分钟时刷新，而不是等待401。
- 原子令牌持久性 --刷新令牌是一次性轮换使用的。然后，Puck写入临时文件
fs.renameSync()以防止“丢失刷新令牌”故障模式。 - 线程部分故障恢复 --如果线程在创建过程中失败，则成功发布的部分将返回失败元数据。
- 加密存储 --静止的令牌使用特定于机器的派生密钥进行AES-256-CBC加密。
错误处理
所有工具返回一致的错误形状：
{
"error": "rate_limited",
"message": "POST /2/tweets rate limit reached (100/window). Resets at 2026-02-25T15:30:00Z.",
"retryAfter": 340,
"endpoint": "POST /2/tweets"
}
| 错误代码 | 含义 |
|---|---|
not_found |
帖子或用户不存在 |
rate_limited |
达到端点速率限制（包括 retryAfter) |
auth_failed |
令牌已过期/吊销，刷新失败 |
auth_required |
未通过身份验证 |
forbidden |
权限或层级不足 |
invalid_request |
参数错误 |
content_too_long |
帖子超过280个字符 |
media_failed |
媒体上传或处理失败 |
api_error |
X API错误（包含详细信息） |
OAuth范围（第一阶段）
| 范围 | 目的 |
|---|---|
tweet.read |
阅读帖子和时间表 |
tweet.write |
创建和删除帖子 |
users.read |
用户配置文件（大多数端点都需要） |
media.write |
上传媒体 |
offline.access |
接收刷新令牌 |
随着功能的增加，未来的阶段将要求更多的范围。
在没有API访问的情况下进行测试
X没有为核心API提供沙箱环境。以下是您的测试选项：
单元测试（不需要API）：
npm test
所有57个单元测试都针对模拟数据运行，没有API调用。
模拟服务器（不需要API）：
嘲讽 提供了一个本地运行的预构建的X API v2 mock。点 twitter-api-v2 在 http://localhost:your-port 用于无凭据的集成测试。
免费等级（有限，可能会停止）：
免费层（0美元）允许OAuth身份验证， POST /2/tweets （创建），以及 DELETE /2/tweets/:id （删除）--但没有读取端点。您可以验证OAuth流程是否正常工作，以及帖子是否被创建/删除。截至2026年2月，X正在向按次付费过渡，免费套餐可能不再可用。
VCR/盒式磁带录音（一次性API访问）： 记录一次真实的API响应，在测试中永远回放。这是Tweepy和其他主要Twitter库使用的方法。如果您甚至可以临时访问API，这就是黄金标准。
推荐方法： 使用单元测试+Mockoon进行开发。装运前，使用真实凭证进行一次手动烟雾测试。
发展
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run dev
# Run tests
npm test
# Manual smoke test (requires real X API credentials)
PUCK_CLIENT_ID=your_id node dist/index.js
开发阶段
| 阶段 | 状态 | 范围 |
|---|---|---|
| 1 | 完成 | OAuth、CRUD后、线程、图像上传、时间线、速率限制 |
| 2 | 计划 | 视频/GIF上传、参与（点赞、转发、书签）、搜索 |
| 3 | 计划 | 主页时间线、DM、用户查找、关注/静音 |
| 4 | 计划 | 过滤流媒体、趋势、完整存档搜索 |
许可证
麻省理工学院
