xkcd Comic Suggester

xkcdai

一个MCP 服务，可在对话中展示合适的 xkcd 漫画（如果有相关内容）。

在线连接器： https://xkcdai.onrender.com/mcp — 在 claude.ai → Settings → Connectors 中添加。请参阅使用已部署的 MCP 服务。

它使用本地设备上的嵌入，为每篇 xkcd 漫画（标题 + 鼠标悬停文本 + 文字稿）建立语义索引，然后提供一个 find_xkcd 工具。Claude 对话可以在话题似乎适合 xkcd 漫画时调用该工具；相关性阈值会让匹配度较低的结果不返回任何内容，因此它会保持安静，而不是强行引用牵强的内容。

目前，获取的文字稿、解释和嵌入都已提交到此仓库的 data/ 目录下。

工作原理

xkcd JSON API ─┐
               ├─► comics.json + explain.json ─► embeddings.npy ─► find_xkcd ─► Claude
explainxkcd  ──┘        (cache)                    (bge-small)     (cosine)    (mentions it
 (transcripts +                                                                 if it fits)
  explanations)

• 数据： 标题 + 来自官方 API 的鼠标悬停替代文本，以及来自 explainxkcd.com 社区的文字稿和解释。explainxkcd 的上下文至关重要：官方 API 大约从第 1675 篇漫画起不再提供文字稿，因此没有它，分享最广的现代漫画（例如 #2347 Dependency）将无法匹配——其中的笑点文字只存在于图片中。
• 嵌入： 使用 BAAI/bge-small-en-v1.5 的 fastembed（ONNX）——本地运行、免费，首次下载后可离线使用，无需 PyTorch。可在 src/xkcdai/embed.py 中更换模型（例如 BAAI/bge-base-en-v1.5，排名略好，但体积约为 3 倍）。
• 搜索： 经过归一化的 numpy 矩阵 + 点积。几千篇漫画无需使用向量数据库。
• 克制： xkcd 几乎什么都有对应的漫画，因此仅靠相似度阈值无法判断相关性。min_score（默认值为 0.62）只是一个粗略下限；真正的“我该不该提起这个？”判断由调用模型完成，并由 find_xkcd 工具中记录的分数区间提供指引。

使用已部署的 MCP 服务（作为自定义连接器）

此服务已部署在 Render 上，地址为 **https://xkcdai.onrender.com**。将其添加为 Claude 自定义连接器，即可在 Claude 网页版和移动应用中使用（注意：Free 套餐只允许添加一个自定义连接器）。 任何人都可以在自己的账户中添加相同的 URL。

在 claude.ai 中（网页版——设置一次后会同步到移动应用）：

1. Settings → Connectors → Add custom connector。
2. 粘贴连接器 URL，包括 /mcp 路径：https://xkcdai.onrender.com/mcp
3. OAuth 留空（此服务无需身份验证），然后点击 Add。
4. 连接器的 find_xkcd 工具现在可在聊天中使用，桌面和手机端均可。 若要让 Claude 主动推荐漫画，还要将让 Claude 主动推荐漫画中的指示添加到 Profile preferences 中。

注意

• 此服务是公开且无需身份验证的——在这里没有问题（只读漫画搜索，不涉及机密）。未经 OAuth 保护，请勿将此模式用于任何敏感用途。
• 通过此仓库中的 Dockerfile 和 render.yaml 托管；推送到 main 后会自动重新部署。
• GET /healthz 会报告服务是否存活、索引是否已加载，以及当前 RSS——在 512 MB 实例上很实用：

  curl https://xkcdai.onrender.com/healthz
  

本地设置

python -m venv .venv
# Windows (PowerShell):  .venv\Scripts\Activate.ps1
# macOS/Linux:           source .venv/bin/activate
pip install -e .

# Fetch comics + their explainxkcd context, then embed (downloads the model once).
# First run ~10 min; re-running later only fetches what's new.
xkcdai build

添加 --no-enrich 可跳过 explainxkcd 获取步骤（速度更快／可离线运行，但匹配效果较弱）。

从命令行测试：

xkcdai search "my code finally compiled after an hour"
xkcdai search "arguing about the correct date format"
xkcdai search "spent more time automating it than doing it by hand"

在本地将其用作 MCP 服务

此服务通过 stdio 运行。将你的 MCP 宿主指向它。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "xkcdai": {
      "command": "C:\\your\\path\\to\\xkcdai\\.venv\\Scripts\\xkcdai-server.exe",
      "env": { "XKCDAI_DATA_DIR": "C:\\your\\path\\to\\xkcdai\\data" }
    }
  }
}

Claude Code（-s user 表示在每个项目中都可使用，而不仅限于此文件夹）：

claude mcp add xkcdai -s user -e XKCDAI_DATA_DIR=C:\your\path\to\xkcdai\data -- C:\your\path\to\xkcdai\.venv\Scripts\xkcdai-server.exe

请务必设置 XKCDAI_DATA_DIR，因为宿主会从任意工作目录启动此服务。

MCP 只让 Claude 能够调用 find_xkcd——它不会主动推荐漫画。请参阅让 Claude 主动推荐漫画。

让 Claude 主动推荐漫画

连接服务只赋予 Claude 调用 find_xkcd 的能力；如果不加提示，它不会主动调用。要让 Claude 主动推荐漫画，请将以下指令粘贴到 Claude 读取持久化指令的位置：

• Claude Code — 全局 ~/.claude/CLAUDE.md（适用于所有场景）或特定仓库的 CLAUDE.md；重启会话以加载更改。
• Claude.ai / Claude Desktop — Settings → Profile → "What personal preferences should Claude consider in responses?"（所有套餐均可使用，包括免费套餐；会同步到移动应用）。每位使用该连接器的人都需要在自己的账号中添加此指令。

When a conversation naturally lands on a topic xkcd is known for — programming,
science, math, statistics, engineering, the absurdity of standards, relationships,
everyday life — call the find_xkcd tool (xkcdai) with a short phrase describing the
topic. Then judge whether to bring it up:
- score >= 0.75 — strong match; mention it if it fits the moment
- 0.66-0.75 — only if it genuinely lands
- below that — stay silent
When you share one, give just that single comic: its number and title, its URL, and
quote the alt (mouseover) text — that's half the joke. At most one comic per topic,
and never force a tangential reference. When in doubt, say nothing.

这仍由 Claude 自行判断，因此遇到边缘话题时不一定会触发——询问 "is there an xkcd for this?" 总会触发查询。

不止支持 Claude — 兼容任何 MCP 客户端

上面的示例使用 Claude，但 find_xkcd 是标准的 Model Context Protocol 工具，因此任何支持 MCP 的宿主都能使用它。将客户端指向以下任一传输方式：

• stdio： 在本地运行 xkcdai-server（参见在本地用作 MCP 服务），或
• HTTP： 已部署的网址 https://xkcdai.onrender.com/mcp。

该服务在内部也与大模型无关：匹配使用本地嵌入模型。 不同之处仅在于宿主特定的部分——如何注册服务，以及将“在合适时推荐漫画”指令放在哪里（各客户端都有自己的系统提示词／规则机制，例如 Cursor Rules 或 VS Code .instructions 文件）。

配置

• XKCDAI_DATA_DIR — comics.json、explain.json、embeddings.npy 和 index.json 所在的位置。
• find_xkcd(context, max_results=3, min_score=0.62) — 降低 min_score 可获得更多（匹配条件更宽松的）建议，提高该值则会使匹配更严格。

维护

定期重新运行 xkcdai build 以获取新漫画——该命令会增量获取新漫画及其 explainxkcd 上下文，然后重新生成嵌入：

xkcdai build

使用 --force 从头重建所有内容，或使用 --no-enrich 跳过 explainxkcd 内容的获取。xkcdai enrich 仅获取 explainxkcd 上下文。

致谢与许可

本项目包含来自两个来源的内容，各自适用不同许可，因此代码和数据分别授权：

• 代码（src/、Dockerfile 等）——MIT。
• 漫画与鼠标悬停文本——© Randall Munroe / xkcd， 采用 CC BY-NC 2.5 许可：仅限非商业用途，并须注明出处。
• 文字稿与解释（缓存在 data/ 中）——来自 explainxkcd.com，采用 CC BY-SA 3.0 许可： 本项目依据相同许可重新分发，并注明出处。

由于 data/ 混合了 xkcd 的非商业内容和 explainxkcd 的相同方式共享内容，请将数据视为非商业内容，并确保任何重新分发都遵守这些条款。MIT 许可仅涵盖源代码，不涵盖 data/。在运行时，find_xkcd 的结果会链接回 xkcd 和 explainxkcd，以便标注各条目的来源。

这是一个非官方的粉丝项目，与 xkcd 或 explainxkcd 无关，也未获其认可。