Discourse MCP

🚀 Discourse MCP

Discourse MCP 是一個模型上下文協議（MCP）標準輸入輸出服務器，它將 Discourse 論壇的功能作為工具提供給 AI 智能體使用。

🚀 快速開始

快速開始（發佈版本）

• 運行（只讀模式，推薦啟動方式）

npx -y @discourse/mcp@latest

之後，在你的 MCP 客戶端中，你可以選擇以下兩種方式之一：

• 調用 discourse_select_site 工具，並傳入 { "site": "https://try.discourse.org" } 來選擇一個站點；

• 使用 --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": [] }
  }
}

✨ 主要特性

• 入口點：src/index.ts → 編譯為 dist/index.js（二進制名稱：discourse-mcp）
• SDK：@modelcontextprotocol/sdk
• Node 版本要求：>= 18

📦 安裝指南

本項目依賴 Node >= 18 和 pnpm。安裝、構建、類型檢查和測試的命令如下：

pnpm install
pnpm typecheck
pnpm build
pnpm test

💻 使用示例

基礎用法

• 只讀會話，針對 try.discourse.org 站點

npx -y @discourse/mcp@latest --log_level debug
# 在客戶端中：調用 discourse_select_site 並傳入 {"site":"https://try.discourse.org"}

• 綁定到單個站點

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"}]'

📚 詳細文檔

配置

服務器在 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=false，並且配置了某種認證方式（無論是默認標誌還是匹配的 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 客戶端。

工具

內置工具（除非特別說明，否則始終可用）：

• discourse_search
  • 輸入：{ query: string; with_private?: boolean; max_results?: number (1–50, 默認值 10) }
  • 輸出：文本摘要以及類似以下的緊湊頁腳：

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

• discourse_read_topic
  • 輸入：{ topic_id: number; post_limit?: number (1–20, 默認值 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 (默認值 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 字符) }

注意：輸出首先以人類可讀的形式呈現。在適用的情況下，會在代碼塊中嵌入緊湊的 JSON 格式，以便智能體進行結構化提取。

🔧 技術細節

項目佈局

• 服務器和 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 錯誤，系統內置了重試和退避機制。