Discourse MCP

🚀 Discourse MCP

Discourseフォーラムの機能をAIエージェント用のツールとして提供する、Model Context Protocol (MCP) の標準入出力サーバーです。

• エントリーポイント: src/index.ts → dist/index.jsにコンパイルされます（バイナリ名: discourse-mcp）
• SDK: @modelcontextprotocol/sdk
• Node: >= 18

🚀 クイックスタート（リリース版）

• 実行（読み取り専用、起動時に推奨）

npx -y @discourse/mcp@latest

その後、MCPクライアントで以下のいずれかを実行します。

• { "site": "https://try.discourse.org" }を指定してdiscourse_select_siteツールを呼び出し、サイトを選択するか、

• --site https://try.discourse.orgを使用してサーバーを特定のサイトに紐付けて起動します（この場合、discourse_select_siteは非表示になります）。

• 書き込みを有効にする（オプトイン、安全措置あり）

npx -y @discourse/mcp@latest --allow_writes --read_only=false --auth_pairs '[{"site":"https://try.discourse.org","api_key":"'$DISCOURSE_API_KEY'","api_username":"system"}]'

• MCPクライアントでの使用例（例: Claude Desktop） — npx経由

{
  "mcpServers": {
    "discourse": {
      "command": "npx",
      "args": ["-y", "@discourse/mcp@latest"],
      "env": {}
    }
  }
}

代替案: グローバルなバイナリをインストールしたい場合は、パッケージにdiscourse-mcpが用意されています。

{
  "mcpServers": {
    "discourse": { "command": "discourse-mcp", "args": [] }
  }
}

📚 設定

サーバーは、MCPサーバー名@discourse/mcpの下にツールを登録します。ターゲットのDiscourseサイトは以下のいずれかの方法で選択できます。

• 実行時にdiscourse_select_siteツールを使用する（/about.jsonを介して検証）か、

• 起動時に--site <url>を指定してサーバーを単一のサイトに紐付ける（/about.jsonを介して検証し、discourse_select_siteを非表示にする）。

• 認証

  • デフォルトではなしです。
  • --auth_pairs '[{"site":"https://example.com","api_key":"...","api_username":"system"}]': サイトごとのAPIキーのオーバーライドです。複数のエントリを含めることができ、選択したサイトに一致するエントリが使用されます。

• 書き込みの安全性

  • デフォルトでは書き込みは無効になっています。
  • discourse.create_postツールは、以下のすべての条件が満たされた場合にのみ登録されます。
    • --allow_writesが指定され、--read_onlyが指定されておらず、かつ何らかの認証が設定されている（デフォルトのフラグまたは一致するauth_pairsエントリ）。
  • create_postには、約1リクエスト/秒のレート制限が適用されます。

• フラグとデフォルト値

  • --read_only（デフォルト: true）
  • --allow_writes（デフォルト: false）
  • --timeout_ms <number>（デフォルト: 15000）
  • --concurrency <number>（デフォルト: 4）
  • --log_level <silent|error|info|debug>（デフォルト: info）
  • --tools_mode <auto|discourse_api_only|tool_exec_api>（デフォルト: auto）
  • --site <url>: MCPを単一のサイトに紐付け、discourse_select_siteを非表示にします。
  • --default-search <prefix>: すべての検索クエリに無条件でプレフィックスを付けます（例: tag:ai order:latest-post）。
  • --max-read-length <number>: 投稿内容で返される最大文字数（デフォルト50000）。discourse_read_postとdiscourse_read_topicの投稿ごとの内容に適用されます。ツールはinclude_raw=trueを要求することでrawコンテンツを優先します。
  • --cache_dir <path>（予約済み）
  • --profile <path.json>（以下を参照）

• プロファイルファイル（コマンドラインからシークレットを除外する）

{
  "auth_pairs": [
    { "site": "https://try.discourse.org", "api_key": "<redacted>", "api_username": "system" }
  ],
  "read_only": false,
  "allow_writes": true,
  "log_level": "info",
  "tools_mode": "auto",
  "site": "https://try.discourse.org"
  ,
  "default_search": "tag:ai order:latest-post"
  ,
  "max_read_length": 50000
}

以下のコマンドで実行します。

node dist/index.js --profile /absolute/path/to/profile.json

フラグは、プロファイルの値を上書きします。

• リモートツール実行API（オプション）

  • tools_mode=auto（デフォルト）またはtool_exec_apiの場合、サーバーはサイトを選択した後（または--siteが指定されている場合は起動時にすぐに）、GET /ai/toolsを介してリモートツールを検出し、動的に登録します。--tools_mode=discourse_api_onlyを設定すると、リモートツールの検出を無効にできます。

• ネットワーキングと回復力

  • 429/5xxエラーが発生した場合、バックオフを伴って3回までリトライします。
  • 選択したエンドポイントに対して、軽量なメモリ内GETキャッシュがあります。

• プライバシー

  • シークレットはログから削除されます。エラーは、人間が読めるメッセージとしてMCPクライアントに返されます。

💻 使用例

基本的な使用法

# 読み取り専用セッションでの実行
npx -y @discourse/mcp@latest --log_level debug
# クライアントで: {"site":"https://try.discourse.org"}を指定してdiscourse_select_siteを呼び出す

高度な使用法

# 特定のサイトに紐付ける
npx -y @discourse/mcp@latest --site https://try.discourse.org

# 投稿を作成する（書き込みを有効にする）
npx -y @discourse/mcp@latest --allow_writes --read_only=false --auth_pairs '[{"site":"https://try.discourse.org","api_key":"'$DISCOURSE_API_KEY'","api_username":"system"}]'

🛠️ ツール

組み込みツール（特に記載がない限り常に存在します）:

• discourse_search
  • 入力: { query: string; with_private?: boolean; max_results?: number (1–50, default 10) }
  • 出力: テキスト要約と、以下のようなコンパクトなフッターです。

    { "results": [{ "id": 123, "url": "https://…", "title": "…" }] }
    

• discourse_read_topic
  • 入力: { topic_id: number; post_limit?: number (1–20, default 5) }
• discourse_read_post
  • 入力: { post_id: number }
• discourse_list_categories
  • 入力: {}
• discourse_list_tags
  • 入力: {}
• discourse_get_user
  • 入力: { username: string }
• discourse_filter_topics
  • 入力: { filter: string; page?: number (default 1); per_page?: number (1–50) }
  • クエリ言語（簡潔）: キー:値のトークンをスペースで区切ります。カテゴリ/カテゴリー（カンマ = OR、=category = サブカテゴリなし、-プレフィックス = 除外）；タグ/タグ（カンマ = OR、+ = AND）とタググループ；ステータス:(open|closed|archived|listed|unlisted|public)；個人用in:（bookmarked|watching|tracking|muted|pinned）；日付: created/activity/latest-post-(before|after)にはYYYY-MM-DDまたは相対日数Nを使用；数値: likes[-op]-(min|max), posts-(min|max), posters-(min|max), views-(min|max)；順序: activity|created|latest-post|likes|likes-op|posters|title|views|categoryにはオプションで-ascを付けることができます；自由テキストの用語が一致します。
• discourse_create_post（書き込みが有効な場合のみ；書き込みの安全性を参照）
  • 入力: { topic_id: number; raw: string (≤ 30k chars) }

注:

• 出力はまず人間が読める形式です。適用可能な場合は、コンパクトなJSONがコードブロックに埋め込まれ、エージェントによる構造化抽出を容易にします。

🔧 開発

• 必要条件: Node >= 18、pnpm

• インストール / ビルド / 型チェック / テスト

pnpm install
pnpm typecheck
pnpm build
pnpm test

• ローカルで実行する（ソースマップ付き）

pnpm build && pnpm dev

• プロジェクト構成

  • サーバーとCLI: src/index.ts
  • HTTPクライアント: src/http/client.ts
  • ツールレジストリ: src/tools/registry.ts
  • 組み込みツール: src/tools/builtin/*
  • リモートツール: src/tools/remote/tool_exec_api.ts
  • ロギング/削除: src/util/logger.ts、src/util/redact.ts

• テストに関する注意事項

  • テストは、Nodeのテストランナーを使用してコンパイルされたアーティファクト（dist/test/**/*.js）に対して実行されます。個別にスクリプトを実行する場合は、pnpm testの前にpnpm buildを実行してください。

• 公開（オプション）

  • パッケージは@discourse/mcpとして公開され、discourse-mcpという名前のバイナリが提供されます。使いやすさのために、npx @discourse/mcp@latestをお勧めします。

• 規約

  • テキスト指向の出力に焦点を当て、埋め込まれたJSONは簡潔に保ちます。
  • 書き込み操作には注意し、オプトインとレート制限を維持します。

エージェントフレームワークからこのサーバーを使用するための追加のガイダンスについては、AGENTS.mdを参照してください。

❓ よくある質問

• create_postがないのはなぜですか？ 読み取り専用モードになっています。上記の説明に従って書き込みを有効にしてください。
• リモートツールの検出を無効にできますか？ はい、--tools_mode=discourse_api_onlyで実行します。
• discourse_select_siteを非表示にできますか？ はい、--site <url>を指定して起動すると、単一のサイトに紐付けることができます。
• タイムアウトやレート制限がありますか？ --timeout_msを増やしてください。また、429/5xxエラーに対して組み込みのリトライ/バックオフがあることに注意してください。