puck (Tick Tock Bent)

帕克

X/Twitter MCP连接器

*“主啊，这些凡人真是愚蠢至极！”*

______________________________________________________________________

帕克是一个 主控程序 将X（Twitter）API v2公开为工具的服务器。它通过自动令牌轮换、速率限制跟踪、图像上传和线程构造来处理OAuth 2.0 PKCE，因此消费应用程序不必这样做。

以莎士比亚笔下的淘气精灵命名 *仲夏夜之梦* --快速、随时随地、简短的话语会引起巨大的反应。

快速开始

1.X开发人员设置

1. 在以下位置创建项目 developer.x.com
2. 选择 基本 级别（200美元/月）或更高——免费级别不足以进行有意义的使用
3. 创建一个 OAuth 2.0应用程序 类型：“Web App”（用于PKCE流）
4. 添加 http://localhost:3000/oauth/callback 作为重定向URI
5. 注意你的客户端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小时到期，可轮换刷新令牌）。后续运行以静默方式进行身份验证。

环境变量

工具

认证

帖子

线程

媒体

时间线

建筑

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"
}

OAuth范围（第一阶段）

随着功能的增加，未来的阶段将要求更多的范围。

在没有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

开发阶段

许可证

麻省理工学院

参考文献

• 仲夏夜之梦 --名称的来源
• MCP规范
• X API文件
• X API利率限制