xkcd Comic Suggester

xkcdai

会話に関連する場合、適切な xkcd コミックを表示する MCP サーバーです。

稼働中のコネクター： https://xkcdai.onrender.com/mcp — claude.ai → 設定 → コネクターに追加してください。デプロイ済み 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）を検索できません。ジョークのテキストは画像の中にしかないためです。
• 埋め込み： fastembed（ONNX）と BAAI/bge-small-en-v1.5 を使用します。ローカルで動作し、無料で、初回ダウンロード後はオフラインで利用でき、PyTorch も不要です。src/xkcdai/embed.py でモデルを切り替えられます（例：BAAI/bge-base-en-v1.5 は、サイズが約 3 倍になる一方、ランキングがわずかに改善します）。
• 検索： 正規化した numpy 行列とドット積を使います。数千件のコミックを扱う場合、ベクトル DB は不要です。
• 慎重な表示： xkcd にはほぼあらゆるものを題材にしたコミックがあるため、類似度のしきい値だけでは関連性を判断できません。min_score（デフォルトは 0.62）は大まかな下限にすぎません。「これを話題に出すべきか」という実際の判断は、find_xkcd ツールに記載されたスコア帯を参考に、呼び出し元のモデルが行います。

デプロイ済み MCP サーバーを使う（カスタムコネクターとして）

サーバーは Render 上の https://xkcdai.onrender.com にデプロイされています。Claude のウェブアプリやモバイルアプリで使うには、Claude のカスタムコネクターとして追加してください（注：Free プランで追加できるカスタムコネクターは 1 つだけです）。 誰でも自分のアカウントに同じ URL を追加できます。

claude.ai（ウェブ — ここで一度設定すると、モバイルアプリにも同期されます）で：

1. 設定 → コネクター → カスタムコネクターを追加を選択します。
2. コネクター URL を、/mcp パスも含めて貼り付けます：https://xkcdai.onrender.com/mcp
3. OAuth は空欄のまま（このサーバーは認証不要です）にして、追加をクリックします。
4. コネクターの find_xkcd ツールが、デスクトップとスマートフォンのチャットで利用可能になります。 Claude が自発的にコミックを提案するようにするには、 Claude がコミックを積極的に提案するようにする の指示もプロフィールの設定に追加してください。

注意

• サーバーは公開されており、認証はありません。読み取り専用のコミック検索で、秘密情報も扱わないため問題ありません。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

explainxkcd の取得をスキップするには --no-enrich を追加してください（高速化・オフラインでの実行が可能になりますが、マッチ精度は下がります）。

コマンドラインからテストします：

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 が漫画を積極的に提案するようにする

サーバーを接続するだけでは、Claude に find_xkcd を呼び出す能力が与えられるだけです。自発的に呼び出すことはありません。Claude が漫画を自発的に提案するようにするには、Claude が永続的な指示として読み込む場所に、以下の指示を貼り付けてください。

• Claude Code — グローバルな ~/.claude/CLAUDE.md（どこでも適用）またはリポジトリごとの CLAUDE.md に記載します。変更を読み込むには、セッションを再起動してください。
• Claude.ai / Claude Desktop — ［設定］→［プロフィール］→ 「応答時に Claude が考慮すべき個人の設定は何ですか？」（無料プランを含むすべてのプランで利用でき、モバイルアプリと同期されます）。コネクターを使う各自が、自分のアカウントに追加してください。

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 の判断に委ねられるため、判断が微妙な話題で毎回実行されるわけではありません。"この話題に合う xkcd はある？" と尋ねれば、必ず検索が実行されます。

Claude 以外でも — あらゆる MCP クライアントで利用可能

上記の例では Claude を使用していますが、find_xkcd は標準の Model Context Protocol ツールなので、MCP 対応のホストならどれでも利用できます。クライアントを次のいずれかのトランスポートに接続してください。

• stdio： xkcdai-server をローカルで実行します（MCP サーバーとしてローカルで使用するを参照）、または
• HTTP： デプロイ済みの URL https://xkcdai.onrender.com/mcp を使用します。

サーバー内部も LLM に依存しません。マッチングはローカルの埋め込みモデルで実行されます。ホストごとに異なるのは、サーバーの登録方法と、「合う場合は漫画を提案する」という指示を記載する場所だけです（各クライアントには独自のシステムプロンプト／ルールの仕組みがあります。たとえば 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 を、explainxkcd の取得を省略するには --no-enrich を使用します。xkcdai enrich は explainxkcd のコンテキストのみを取得します。

クレジットとライセンス

このプロジェクトには、各々独自のライセンスに従う2つのソースのコンテンツが含まれているため、コードとデータには別々のライセンスが適用されます。

• コード（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 との提携や、いずれかからの承認を受けたものではありません。