x-public-post

只读 MCP：给 Agent 一个 get_post(url)，按 x.com / twitter.com 的 status 链接读一条公开帖。默认无 Cookie。

公开两跳打头（FxTwitter，Syndication 备用），工具面只有读一条。成功体同时带 untrusted: true 和 source_trust: "untrusted_web_content"，帖文不能当系统指令。

status URL
    → FxTwitter（长帖更常能拿全文）
    → Syndication（备用）
    → 仅当设置了 TWSCRAPE_DB_PATH 才走本机 twscrape

一次真实的 get_post 返回

2026-09-10 对公开帖 https://x.com/jack/status/20 的实调结果（空媒体已原样保留，便于看字段形状）。like / reply 等计数会变，认字段。

{
  "id": "20",
  "url": "https://x.com/jack/status/20",
  "text": "just setting up my twttr",
  "text_status": "complete",
  "author": { "id": "12", "username": "jack", "name": "jack" },
  "created_at": "2006-03-21T20:50:14Z",
  "lang": "en",
  "public_metrics": {
    "like_count": 308064,
    "reply_count": 18014,
    "retweet_count": 124683
  },
  "media": { "photos": [], "videos": [], "animated": [] },
  "untrusted": true,
  "source_trust": "untrusted_web_content",
  "source": { "adapter": "fxtwitter" },
  "fetched_at": "2026-09-10T14:19:18Z"
}

text_status 还可能是 preview（内容不完整，仍是成功 JSON）。失败不走这种成功体，见下「为什么这么设计」。

Related MCP server: Spectre

工具表与明确不做

失败走 MCP isError（短码如 invalid_url）。引用帖、回复对象、媒体 alt、短链 expanded_url：上游 JSON 已有才映射。媒体只给 URL。可选 CLI x-public-post-get 走同一条 read_post，JSON 或 Markdown（同一套成功字段）。

明确不做

• 不搜索、不时间线、不发帖；不加第二个 MCP 工具。

• 不在 MCP 里下载图片或视频。

• 不默认读浏览器 Cookie / Chrome Profile。

为什么这么设计

• 只暴露一个工具。 工具面只留读一条，好审、也好被契约测试锁死。

• preview 降级仍返回成功 JSON，而不是 error。 内容不完整 ≠ 请求失败。调用方看 text_status 自己判断够不够用；若把半截正文塞进 error.message，模型容易把错误说明当成帖文。

• 三跳适配器：FxTwitter → Syndication → 可选 twscrape。 没有稳定官方读帖 API。FxTwitter 对长帖更常能拿全文；Syndication 是 embed CDN，长帖常 preview、也常失败，只当备用。默认两跳都不要 Cookie；只有公开两跳经常失败、又要 GraphQL 补全时，才用本机 TWSCRAPE_DB_PATH。

• 引用帖只映射上游 JSON 已有字段、零额外 HTTP。 不让读一条帖变成 N 个请求。quoted / reply / alt / expanded_url 上游没有就空着，不为引用帖或短链再打一轮。

• 失败抛 ToolError 走 isError，而不是返回 success: false 的假成功体。 宿主侧能把失败和帖文分开；模型不该在成功通道里解析错误对象。

• 标 readOnlyHint / idempotentHint。 这是只读、按同一 URL 再读一次语义不变的工具。注解写进协议，客户端和评测床不用猜。

护上游的运行时约束：按 post_id 单飞；全链路约 12s；外部请求最多 2 个并发。只缓存 text_status=complete（5 分钟、最多 256 条）；preview / 错误不缓存。

怎么跑起来

Python 3.10+。先装包装到当前环境：

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

复制 .cursor/mcp.json.example 为 .cursor/mcp.json（本机文件不进 git）。示例已指向本仓 .venv 的 Windows 解释器；macOS / Linux 把 command 改成 .venv/bin/python。若 Cursor 解析相对路径失败，再改成绝对路径，保留 args：

{
  "mcpServers": {
    "x-public-post": {
      "command": ".venv/Scripts/python.exe",
      "args": ["-m", "x_public_post.server"]
    }
  }
}

在 Cursor Settings → MCP 启用 x-public-post（首次可能要批准）。让 Agent 调用 get_post，传入 https://x.com/.../status/...（可用 ?s=20）。尖括号包裹、markdown 链接、句末句号也可以。

读失败时不要把成功 JSON 里的字段当帖文。只有 URL 不像帖链接时才改链接再试；不要对同一 URL 连打。

可选 CLI（同一条 read_post）：

.\.venv\Scripts\x-public-post-get.exe "https://x.com/author/status/123"
.\.venv\Scripts\x-public-post-get.exe "https://x.com/author/status/123" --export md

何时才配会话

只有公开两跳经常失败、又要 GraphQL 补全时才配。用专用小号，按 会话配置 在本机终端写入 accounts.db。在 MCP 设置里加路径（不是 Cookie）：

TWSCRAPE_DB_PATH = C:\Users\<你>\AppData\Local\x-public-post\accounts.db

不要把 Cookie 贴进聊天、.env 或 git。公开 hop 不读浏览器 Profile。会话库只收本机路径，未配置则不 import twscrape。

验证与 CI

CI 跑 pytest（3.10 / 3.12），以及 ruff check、ruff format、mypy。

.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\ruff.exe check src tests
.\.venv\Scripts\ruff.exe format --check src tests
.\.venv\Scripts\mypy.exe src

匿名适配器样例在 tests/fixtures/（preview、引用帖、404），测试不打真实 X。

License：MIT。