LegendKeeper

legendkeeper-mcp

AI アシスタント（Claude、Copilot、Cursor など）が、LegendKeeper の公式 v3 REST APIを通じて、LegendKeeper の世界を読み取り、 構築できるMCP サーバーです。Wiki ページ、インフォボックスの事実、マップのピン、タイムライン、 タグ、テンプレート、画像に対応しています。

非公式です。 このプロジェクトは LegendKeeper が開発、推奨、サポートするものではありません。ご自身の API キーを使って、マシン上でローカルに実行します。

You: Create a tavern called The Drunken Dragon in Waterdeep, give it an infobox with its owner and
     a pin on the city map, and mention it on Volo's page.
Claude: (search → create_resource → set_facts → create_map_feature → write_page) Done! ...

目次

• 機能
• 要件
• クイックスタート
• クライアントの設定
• 設定
• ツール
• ページの編集方法（Markdown）
• 安全性
• トラブルシューティング
• 開発
• リリース

機能

• 厳選された31個のツールをLLM向けに設計しています。リソースはIDだけでなく名前でも指定でき、エラーには修正方法が表示されます。api_request を使えば、その他すべての v3 エンドポイントにアクセスできます。
• ページをMarkdownとして双方向に編集できます。[[Wiki Links]] は実際の LegendKeeper のメンションになります。コールアウト、GM のみが閲覧できる秘密情報、折りたたみ可能なセクション、タスクリスト、表、画像に対応しています。Markdown では表現できないブロック（インフォボックス、埋め込み、コレクションなど）は、書き換え時もそのまま保持されます。ページの編集方法を参照してください。
• セクション単位の編集：ページの残りの部分に触れることなく、見出しのセクションを追記、先頭への追加、置換、拡張できます。すべての書き込みでバージョンを確認（If-Match）するため、アプリ内での同時編集が気付かないうちに上書きされることはありません。
• 構造化されたワールド構築：インフォボックスとサイドバーの事実、マップのピン／領域／経路（緯度・経度または画像上のピクセル）、タイムラインのイベントとレーン（"3 March 1204" などの人間が読みやすい日付）、テンプレート、最大100個のリソースの一括作成（相互リンク対応）、ディスクまたは URL からの画像アップロードに対応しています。
• 1つのサーバーから複数の世界を扱えます（世界ごとにAPIキーが必要です）。また、読み取り専用モードにも対応しています。
• 2種類のトランスポート：デスクトップクライアント向けの stdio、またはベアラートークンの背後でストリーミング可能な HTTP を提供する長時間稼働の Docker コンテナ。
• 堅牢なクライアント：バックオフ付きの再試行、Retry-After の尊重、再試行による二重作成を防ぐすべての POST への冪等性キーの付与、レート制限の追跡に対応しています。
• コントラクトテスト済み：テストスイートは、LegendKeeper が公開している OpenAPI 仕様に照らしてすべてのリクエストとレスポンスを検証するフェイク API に対して実行されます。週次の CI ジョブで最新の仕様を再確認します。

要件

1. 所有者が有料プランを利用している LegendKeeper プロジェクト。 LegendKeeper では、有料プランのプロジェクトの API キーのみ受け付けます（トライアルは対象外です）。それ以外の場合は 402 PAID_PLAN_REQUIRED が返されます。
2. API キー：LegendKeeper でプロジェクトを開き、プロジェクト設定 → 開発者 → API キーに移動して、キーに名前を付け、ロールを選択して作成します。lk_… シークレットをコピーしてください。シークレットが表示されるのは一度だけです。
   • メンバーキーでは、コンテンツの読み取りと書き込みができます。
   • 管理者キーでは、非表示のリソースや GM シークレットの表示と作成、タグの読み取り（list_tags はメンバーキーの場合、タグを自ら数えて結果を返します）、メンバーのメールアドレスの表示、テンプレートの保存もできます。
   • キーの権限は作成者の権限を超えることはなく、作成者自身のプロジェクトでのみ機能します。
3. 次のいずれか：uv（推奨）、Docker、または pip を使用する Python ≥ 3.11。

クイックスタート

いずれかを選んでください。どの方法でも、キーは LEGENDKEEPER_API_KEY から読み込まれます。

uvx（インストール不要）：

LEGENDKEEPER_API_KEY=lk_... uvx legendkeeper-mcp check   # verify the key

Docker：

docker run -i --rm -e LEGENDKEEPER_API_KEY=lk_... ghcr.io/chase-roohms/legendkeeper-mcp:latest check

pip：

pip install legendkeeper-mcp
legendkeeper-mcp check

check を実行すると、設定された各キーで開くワールドが表示され、その後終了します。check を指定しない場合、コマンドは stdio で MCP サーバーを起動します。デスクトップクライアントはこの方法でサーバーを起動します（下記を参照）。

PyPI で初めてリリースされる前は、uvx --from git+https://github.com/chase-roohms/legendkeeper-mcp legendkeeper-mcp を使用するか、docker build -t legendkeeper-mcp . で自分でイメージをビルドしてください。

長時間稼働する HTTP サーバー（Docker Compose）：

cp .env.example .env              # set LEGENDKEEPER_API_KEY and MCP_AUTH_TOKEN (openssl rand -hex 32)
docker compose up -d              # serves http://localhost:8000/mcp, bound to 127.0.0.1 only
curl http://localhost:8000/healthz

HTTP 対応クライアントの接続先を http://localhost:8000/mcp に設定し、ヘッダーに Authorization: Bearer <MCP_AUTH_TOKEN> を指定します。./uploads に配置した画像は、upload_image（source: /uploads/<file>）でアップロードできます。

クライアントの設定

そのまま使える設定ファイルは examples/ にあります。

Claude Desktop：claude_desktop_config.json に追加し（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）、その後 Claude を再起動します。

{
  "mcpServers": {
    "legendkeeper": {
      "command": "uvx",
      "args": ["legendkeeper-mcp"],
      "env": { "LEGENDKEEPER_API_KEY": "lk_your_key_here" }
    }
  }
}

VS Code（.vscode/mcp.json。キーの入力を求められ、安全に保存されます）：

{
  "inputs": [{ "type": "promptString", "id": "lk-key", "description": "LegendKeeper API key", "password": true }],
  "servers": {
    "legendkeeper": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "LEGENDKEEPER_API_KEY", "ghcr.io/chase-roohms/legendkeeper-mcp:latest"],
      "env": { "LEGENDKEEPER_API_KEY": "${input:lk-key}" }
    }
  }
}

Claude Code：

claude mcp add legendkeeper --env LEGENDKEEPER_API_KEY=lk_... -- uvx legendkeeper-mcp

Cursor、Windsurf など： クライアントの MCP 設定ファイルで、Claude Desktop と同じ command／args／env を指定します。

設定

すべて環境変数で設定します。CLI フラグ（--transport、--host、--port、--read-only）は環境変数より優先されます。

変数	デフォルト	説明
LEGENDKEEPER_API_KEY	—	default という名前のプロジェクトの API キーです。
LEGENDKEEPER_API_KEY_<NAME>	—	追加のワールドです。LEGENDKEEPER_API_KEY_HOMEBREW はプロジェクト homebrew になります。
LEGENDKEEPER_API_KEY_FILE、LEGENDKEEPER_API_KEY_<NAME>_FILE	—	ファイルからキーを読み込みます（Docker シークレット）。
LEGENDKEEPER_DEFAULT_PROJECT	default、それ以外は最初の名前	project が省略された場合にツールが使用するワールドです。
LEGENDKEEPER_PROJECT_ID、LEGENDKEEPER_PROJECT_ID_<NAME>	自動検出	キーに対応するプロジェクト ID の検索を省略します。
LEGENDKEEPER_READ_ONLY	false	読み取りツールのみを登録します。api_request は GET のみ許可します。
LEGENDKEEPER_BASE_URL	https://www.legendkeeper.com	API のオリジン（プロキシやモック用）。
LEGENDKEEPER_TIMEOUT	30	リクエストのタイムアウト（秒）。
LEGENDKEEPER_MAX_RETRIES	3	429／5xx／ネットワークエラー時の再試行回数。
LEGENDKEEPER_UPLOAD_ROOT	制限なし（Docker では /uploads）	upload_image が読み取れるファイルを、このディレクトリ以下に制限します。
LEGENDKEEPER_MAX_UPLOAD_MB	25	画像の最大サイズ。
LEGENDKEEPER_ALLOW_URL_UPLOADS	true	upload_image が http(s) URL からダウンロードすることを許可します。
LEGENDKEEPER_LOG_LEVEL	INFO	ログレベル（ログは stderr に出力され、キーが記録されることはありません）。
MCP_TRANSPORT	stdio	stdio または http（ストリーム可能な HTTP）。
MCP_HOST	127.0.0.1（Docker では 0.0.0.0）	HTTP のバインドアドレス。
MCP_PORT	8000	HTTP ポート。
MCP_PATH	/mcp	HTTP エンドポイントのパス。
MCP_AUTH_TOKEN、MCP_AUTH_TOKEN_FILE	—	すべての HTTP リクエスト（/healthz を除く）で必要なベアラートークン。
MCP_ALLOW_UNAUTHENTICATED	false	トークンなしでループバック以外のアドレスで HTTP を許可します（推奨されません）。
MCP_ALLOWED_HOSTS	—	カンマ区切りの host:port 値です。DNS リバインディング対策を有効にします（例：localhost:8000）。

複数のワールド

LEGENDKEEPER_API_KEY_HOMEBREW=lk_aaa
LEGENDKEEPER_API_KEY_STRAHD=lk_bbb
LEGENDKEEPER_DEFAULT_PROJECT=homebrew

すべてのツールは任意の project 引数（"strahd"）を受け取り、list_projects で設定済みのプロジェクトを確認できます。

ツール

領域	ツール
検出	list_projects、browse_tree、search、get_resource、list_tags、list_templates、list_calendars、list_members、list_assets
読み取り	read_document：ページは Markdown、マップは座標付きのフィーチャー、タイムラインはレーン／イベント、ボードはテキストとして返します。format: "json" を指定すると、生の API データを返します。
ページ	write_page（モード：append、prepend、replace、replace_section、append_to_section）
リソース	create_resource、create_resources（一括作成は最大 100 件、key／parent_key で入れ子にできます）、update_resource（名前、タグの追加／削除、エイリアス、アイコン、バナー、非表示、ロック）、move_resource、delete_resource、restore_resource、create_from_template
ドキュメント	create_document（ページ／マップ／タイムライン／ボード）、update_document、delete_document
ファクト	set_facts：ページのインフォボックス（なければ作成）またはサイドバーにキーと値のファクトを設定します。null を指定するとファクトを削除します。
マップ	create_map_feature（ピン／ラベル／領域／パス／フォルダー、緯度／経度またはピクセル座標、ページへのリンク）、update_map_feature、delete_map_feature
タイムライン	create_timeline_event（タイムラインのカレンダーに合わせて人間向けの日付を解析し、レーン名を指定できます。レーンがない場合は作成します）、update_timeline_event、delete_timeline_event、create_timeline_lane
アセット	upload_image（ローカルファイルまたは URL → ページ、バナー、マップ画像で使えるアセット URL）
その他	api_request：プロジェクトの任意の v3 エンドポイント（ボード、カレンダー、ブロック単位の編集、招待、復元など）

このサーバーは、アシスタントが読み取れる 2 つの MCP リソースも公開します。 legendkeeper://guides/markdown（Markdown の方言）と legendkeeper://guides/style（LegendKeeper のスタイルガイドをもとにした、タグ、アイコン、インフォボックス、ピン、イベントの規約）です。書き込みツールにはクライアントが確認を求められるよう注釈が付いています。破壊的なツールでは confirm: true も必要です。

ページの編集方法（Markdown）

LegendKeeper はページを Markdown ではなく、型付きブロックのツリーとして保存します。このサーバーは双方向に変換します。

Markdown	LegendKeeper
# … ######、段落、- リスト、1. リスト、> 引用、``` コード、---、GFM テーブル	対応するブロック
- [ ] タスク / - [x] 完了	タスクリスト
> [!info]、[!note]、[!success]／[!tip]、[!warning]、[!error]／[!caution]	コールアウト
> [!secret]	シークレットブロック（GM のみ。プレイヤーと公開ページには表示されません）
> [!expand] タイトル	折りたたみ可能なセクション
**b**、*i*、~~s~~、`c`、<u>、<sub>、<sup>、<span style="color:#…; background-color:#…">	テキストの装飾と色
[[Name]]、[[Name|label]]、[label](lk://resources/<id>)	メンション（別のページへのリンク）
	画像（先に upload_image でアップロード）
```lk-block + JSON	任意の生ブロック（インフォボックス、埋め込み、メーター、コレクションなど）

ページを読み込むと、Markdown では表現できないブロックは読みやすい領域として表示されます。

**Infobox**
*Facts*
- **Ruler:** [Princess Bubblegum](lk://resources/pb…)

これらのマーカー行を書き戻すと、元のブロックがそのまま保持されます。領域内の編集は警告とともに無視されます。編集するには set_facts を使うか、opaque_blocks: "json" を指定して読み込み、生の JSON を編集してください。replace モードでは、段落など、内容が変更されていないブロックは元のブロックと照合されます。ID と、Markdown では表現できないスタイル（色、配置、コールアウトアイコンなど）は保持されます。

このコンバーターは、扱いにくい句読点、入れ子の装飾、エスケープを含む厳密な往復変換について、Hypothesis によるファズテストを実施済みです。

安全性

• 読み取り専用モード（LEGENDKEEPER_READ_ONLY=true または --read-only）では、書き込みツールは一切登録されません。
• 確認：delete_* ツールと api_request の DELETE は、confirm: true がないと実行を拒否します。削除されたリソースは LegendKeeper のゴミ箱に移動し、restore_resource で復元できます。
• 更新の消失を防止：ページへの書き込みでは、基準にしたバージョン（If-Match）を送信し、競合時には最新の状態を読み直して一度だけ再試行します。
• 再試行時の重複を防止：すべての POST に冪等性キーが付与されます。
• HTTP モードでは、MCP_AUTH_TOKEN がない場合、ループバック以外のアドレスでのリッスンを拒否します。compose は 127.0.0.1 のみにバインドし、読み取り専用ファイルシステムを使用して、すべてのケーパビリティを無効にし、非 root ユーザーで実行します。
• アップロード：コンテンツを検証した実際の JPEG／PNG／GIF／WebP ファイルのみがサイズ制限内でアップロードされ、必要に応じて LEGENDKEEPER_UPLOAD_ROOT の範囲に制限されます。
• シークレット：キーがログに記録されることはなく（lk_ab…wxyz のようにマスクされます）、LegendKeeper 以外に送信されることもありません。署名付きアップロード URL に送信されるのは画像データであり、キーではありません。

トラブルシューティング

症状	解決方法
402 PAID_PLAN_REQUIRED	プロジェクトの所有者に有料の LegendKeeper プランが必要です（トライアルは対象外です）。
401 UNAUTHENTICATED	キーがない、入力ミスがある、取り消されている、または期限切れです。legendkeeper-mcp check を実行してください。
403 FORBIDDEN	キー（またはキーの作成者）のロールの権限が低すぎます。たとえば、Member キーでは非公開リソースやタグにアクセスできません。
403 WRONG_PROJECT	キーはそれぞれのワールド内でのみ機能します。ワールドごとにキーを設定してください。
429 RATE_LIMITED	LegendKeeper では、キーごとに 1 分あたり 120 回の書き込みと 300 件のリクエストが許可されています。1 分待つか、create_resources でまとめて処理してください。
VALIDATION_ERROR で画像が拒否される	画像 URL は LegendKeeper のアセット URL である必要があります。先に upload_image を使用してください。
クライアントにツールが表示されない	クライアントの MCP ログを確認してください。設定したコマンドを自分で実行してください。設定エラーは終了コード 2 で stderr に出力されます。

開発

uv sync                       # create .venv with dev dependencies
uv run pytest                 # full test suite (downloads the OpenAPI spec once into tests/.cache)
uv run ruff check . && uv run ruff format --check . && uv run mypy
uv run legendkeeper-mcp       # run from source
npx @modelcontextprotocol/inspector uv run legendkeeper-mcp   # poke at it interactively

テストのレイヤー：

• tests/test_markdown*.py：コンバーターの単体テストと Hypothesis のプロパティテスト（往復変換は完全に一致する必要があります）。

• tests/test_tools.py：tests/fake_lk.py のメモリ内 LegendKeeper を対象に、実際の MCP クライアントセッションを通じてすべてのツールをエンドツーエンドでテストします。OpenAPI 仕様が利用可能な場合、すべてのリクエストはスキーマに適合した本文で実際のルートに到達し、すべてのフェイクレスポンスはドキュメントに記載されたレスポンススキーマに適合する必要があります。CI では仕様が必須です（LK_REQUIRE_SPEC=1）。

• tests/test_live.py：実際の API に対するオプトインのスモークテストです。書き込みテストでは、1 つの [mcp-test] … サンドボックスリソース内にすべてを作成し、その後削除します。

  LEGENDKEEPER_LIVE_TESTS=1 LEGENDKEEPER_LIVE_WRITE=1 LEGENDKEEPER_API_KEY=lk_... uv run pytest tests/test_live.py -v
  

プロジェクトの構成：

src/legendkeeper_mcp/
  client.py      async HTTP client (auth, retries, idempotency, pagination, errors)
  config.py      environment configuration
  service.py     per-project sessions, project-id discovery, cached resource index
  documents.py   reading/writing documents (page Markdown, maps, timelines, boards)
  markdown/      Markdown <-> block conversion (parse, render, merge)
  tools/         MCP tool definitions
  server.py      server assembly; http_app.py streamable HTTP + bearer auth; cli.py entry point

リリース

CI はプッシュと PR のたびに実行されます。内容は、リント、mypy、Linux／macOS／Windows（Python 3.11-3.13）でのテスト、wheel のビルド、stdio／HTTP のスモークテストを含む Docker ビルドです。

リリースするには、pyproject.toml、src/legendkeeper_mcp/__init__.py、server.json（サーバーとパッケージのバージョン、およびイメージタグ）の version を更新し、CHANGELOG.md を更新してコミットした後、git tag v0.2.0 && git push --tags を実行します。その後、リリースワークフローが次の処理を行います。

1. タグがパッケージのバージョンと一致することを確認し、CI を再実行します。
2. トラステッドパブリッシングを使用して PyPI に公開します。
3. SBOM とプロヴェナンスを付与したマルチアーキテクチャ（amd64/arm64）イメージを ghcr.io/<owner>/legendkeeper-mcp にプッシュします。
4. ビルドした配布物を含む GitHub リリースを作成します。
5. server.json を、io.github.chase-roohms/legendkeeper-mcp として公式 MCP Registry に公開します（GitHub OIDC ログインを使用するため、シークレットは不要です）。レジストリは、この README の先頭にある mcp-name コメント（PyPI ではパッケージの説明として表示されます）と、Docker イメージの io.modelcontextprotocol.server.name ラベルを通じて所有権を確認します。

初回のみ必要な設定：PyPI で、プロジェクト legendkeeper-mcp とこのリポジトリ、ワークフロー release.yml、環境 pypi を紐付けた 保留中のトラステッドパブリッシャー を追加し、リポジトリの設定で pypi 環境を作成します。GHCR の設定は不要です。初回のプッシュ後、GitHub のパッケージ設定でパッケージを公開します。

ライセンス

MIT。LegendKeeper はそれぞれの所有者の商標です。このプロジェクトではその公開 API のみを使用します。