discourse-mcp-extended

Discourse MCP（扩展分支）

这是 discourse/discourse-mcp 的一个分支，扩展了用于处理 Discourse 审核队列（/review）的工具——列出待审核和已标记的条目，并批准或拒绝这些条目。其余内容与上游版本相同。请参阅下文的此分支新增内容。

一个基于标准输入/输出的模型上下文协议（MCP）服务，可将 Discourse 论坛功能作为工具和资源提供给 AI Agent。

• 入口点：src/index.ts → 编译为 dist/index.js（二进制名称：discourse-mcp）
• SDK：@modelcontextprotocol/sdk
• Node：>= 24
• 版本：0.2.4（0.2.x 相较于 0.1.x 有破坏性变更——仅输出 JSON，资源取代列表工具）

此分支新增内容

• discourse_list_reviewables — 列出审核队列中的条目（如 /review?sort_order=score 所示），例如等待批准的新帖／排队帖子和被标记的帖子。需要该站点的管理员或版主 API 密钥，或用户 API 密钥。
• discourse_perform_reviewable_action — 批准、拒绝审核队列中的条目，或对其执行其他操作（仅在启用写入时注册，与其他写入工具相同）。

完整的输入／输出详情请见下文的工具部分。此版本尚未发布到 npm，因此请从此仓库构建并在本地运行（pnpm install && pnpm build，然后将 MCP 客户端指向 dist/index.js），而不要使用 npx @discourse/mcp@latest。

快速开始（发布版）

• 运行（只读，建议从此模式开始）

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

配置

服务会在名称为 @discourse/mcp 的 MCP 服务下注册工具。可通过以下任一方式选择目标 Discourse 站点：

• 在运行时使用 discourse_select_site 工具（通过 /about.json 验证），或

• 启动时传入 --site <url>，将服务绑定到单个站点（通过 /about.json 验证，并隐藏 discourse_select_site）。

• 身份验证

  • 默认不进行身份验证。
  • 管理员 API 密钥（需要管理员权限）：--auth_pairs '[{"site":"https://example.com","api_key":"...","api_username":"system"}]'
  • 用户 API 密钥（任何用户都可以生成）：--auth_pairs '[{"site":"https://example.com","user_api_key":"...","user_api_client_id":"..."}]'
  • HTTP Basic 身份验证（适用于位于反向代理之后的站点）：在任意 auth_pairs 条目中添加 http_basic_user 和 http_basic_pass。这适用于在反向代理层受 HTTP Basic 身份验证保护的 Discourse 站点。
  • 可以在 auth_pairs 中包含多个条目；系统会使用与所选站点匹配的条目。如果同一站点同时提供了 user_api_key 和 api_key，则优先使用 user_api_key。

• 写入安全

  • 默认禁用写入。
  • 仅当启用 --allow_writes 且未启用 --read_only 时，才会注册写入工具（discourse_create_post、discourse_create_topic、discourse_create_category、discourse_update_topic、discourse_create_user、discourse_update_user、discourse_upload_file、discourse_save_draft、discourse_delete_draft、discourse_perform_reviewable_action）。
  • 写入工具需要所选站点对应的 auth_pairs 条目，否则会返回错误。
  • 写入操作会受到每秒约 1 次请求的速率限制。

• 标志和默认值

  • --read_only（默认值：true）
  • --allow_writes（默认值：false）
  • --timeout_ms <number>（默认值：15000）
  • --concurrency <number>（默认值：4）
  • --log_level <silent|error|info|debug>（默认值：info）
    • debug：显示所有 HTTP 请求、响应和详细错误信息
    • info：显示重试尝试和一般运行消息
    • error：仅显示错误
    • silent：不输出日志
  • --show_emails（默认值：false）。在用户工具中包含电子邮件地址。需要管理员权限
  • --tools_mode <auto|discourse_api_only|tool_exec_api>（默认值：auto）
  • --site <url>：将 MCP 绑定到单个站点，并隐藏 discourse_select_site。
  • --default-search <prefix>：无条件为每个搜索查询添加此前缀（例如：tag:ai order:latest）。
  • --max-read-length <number>：返回帖子内容的最大字符数（默认值：50000）。适用于 discourse_read_post，以及 discourse_read_topic 中每篇帖子的内容。这些工具会通过请求 include_raw=true，优先使用 raw 内容。
  • --allowed_upload_paths <paths>：允许本地文件上传的目录列表，使用逗号分隔或 JSON 数组表示。要启用 discourse_upload_file 中的本地文件上传，必须设置此选项。示例：--allowed_upload_paths "/home/user/images,/tmp/uploads" 或 --allowed_upload_paths '["/home/user/images"]'
  • --transport <stdio|http>（默认值：stdio）：传输类型。使用 stdio 表示标准输入/输出（默认值），使用 http 表示 Streamable HTTP 传输（无状态模式，返回 JSON 响应）。
  • --port <number>（默认值：3000）：使用 HTTP 传输时监听的端口。
  • --cache_dir <path>（保留）
  • --profile <path.json>（见下文）

• 配置文件（避免在命令行中暴露密钥）

{
  "auth_pairs": [
    {
      "site": "https://try.discourse.org",
      "api_key": "<redacted>",
      "api_username": "system"
    },
    {
      "site": "https://example.com",
      "user_api_key": "<user_api_key>",
      "user_api_client_id": "<client_id>"
    },
    {
      "site": "https://protected.example.com",
      "api_key": "<redacted>",
      "api_username": "system",
      "http_basic_user": "username",
      "http_basic_pass": "password"
    }
  ],
  "read_only": false,
  "allow_writes": true,
  "show_emails": true,
  "log_level": "info",
  "tools_mode": "auto",
  "site": "https://try.discourse.org",
  "default_search": "tag:ai order:latest",
  "max_read_length": 50000,
  "transport": "stdio",
  "port": 3000,
  "allowed_upload_paths": ["/home/user/images", "/tmp/uploads"]
}

运行方式：

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 客户端。

MCP 资源

资源通过 URI 寻址提供静态／半静态的只读数据。对于列表操作，请使用资源，而不是工具。

• discourse://site/categories

  • 列出所有类别及其层级和权限
  • 输出：{ categories: [{id, name, slug, pid, read_restricted, topic_count, post_count, perms}], meta: {total} }
  • perms 是由 {gid, perm} 组成的数组，其中 perm：1=完全权限，2=创建帖子，3=只读
  • 注意：仅在使用管理员／版主身份验证时才会填充 perms。未使用管理员身份验证时，只提供 read_restricted 布尔值。

• discourse://site/tags

  • 列出所有标签及其使用次数
  • 输出：{ tags: [{id, name, count}], meta: {total} }

• discourse://site/groups

  • 列出所有群组及其可见性、互动级别和访问设置
  • 输出：{ groups: [{id, name, automatic, user_count, vis, members_vis, mention, msg, public_admission, public_exit, allow_membership_requests}], meta: {total} }
  • 级别（0-4）：0=公开，1=已登录用户，2=成员，3=工作人员，4=所有者
  • 用例：将类别权限中的 gid 值解析为群组名称，并在迁移过程中复现群组设置

• discourse://chat/channels

  • 列出所有公开聊天频道
  • 输出：{ channels: [{id, title, slug, status, members_count, description}], meta: {total} }

• discourse://user/chat-channels

  • 列出用户的聊天频道（公开频道和私信），包含未读数／提及数
  • 输出：{ public_channels: [...], dm_channels: [...], meta: {total} }
  • 需要身份验证

• discourse://user/drafts

  • 列出用户的草稿
  • 输出：{ drafts: [{draft_key, sequence, title, category_id, created_at, reply_preview}], meta: {total} }
  • 需要身份验证

工具

内置工具（除非另有说明，否则始终可用）。所有工具均返回严格 JSON（不含 Markdown）。

• discourse_search
  • 输入：{ query: string; max_results?: number (1–50, 默认 10) }
  • 输出：{ results: [{id, slug, title}], meta: {total, has_more} }
• discourse_read_topic
  • 输入：{ topic_id: number; post_limit?: number (1–50, 默认 5); start_post_number?: number }
  • 输出：{ id, title, slug, category_id, tags, posts_count, posts: [{id, post_number, username, created_at, raw}], meta }
• discourse_read_post
  • 输入：{ post_id: number }
  • 输出：{ id, topic_id, topic_slug, post_number, username, created_at, raw, truncated }
• discourse_get_user
  • 输入：{ username: string }
  • 输出：{ id, username, name, trust_level, created_at, bio, admin, moderator }
• discourse_list_user_posts
  • 输入：{ username: string; page?: number (从 0 开始); limit?: number (1–50, 默认 30) }
  • 输出：{ posts: [{id, topic_id, post_number, slug, title, created_at, excerpt, category_id}], meta: {page, limit, has_more} }
• discourse_filter_topics
  • 输入：{ filter: string; page?: number; per_page?: number (1–50) }
  • 输出：{ results: [{id, slug, title}], meta: {page, limit, has_more} }
  • 查询语言（简要）：以空格分隔的 key:value 标记；category/categories（逗号 = 或，=category = 不包含子类别，- 前缀 = 排除）；tag/tags（逗号 = 或，+ = 且）和 tag_group；status:(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_get_chat_messages
  • 输入：{ channel_id: number; page_size?: number (1–50, 默认 50); target_message_id?: number; direction?: "past" | "future"; target_date?: string (ISO 8601) }
  • 输出：{ channel_id, messages: [{id, username, created_at, message, edited, thread_id, in_reply_to_id}], meta }
• discourse_get_draft
  • 输入：{ draft_key: string; sequence?: number }
  • 输出：{ draft_key, sequence, found, data: {title, reply, category_id, tags, action} }
• discourse_list_reviewables（需要管理员/版主 API 密钥）
  • 输入：{ status?: "pending"|"approved"|"rejected"|"ignored"|"deleted"|"reviewed"|"all"; type?: string; priority?: "low"|"medium"|"high"; sort_order?: "score"|"score_asc"|"created_at"|"created_at_asc"; category_id?: number; topic_id?: number; page?: number }
  • 输出：{ reviewables: [{id, type, status, score, created_at, topic_id, category_id, post_id, target_user_id, created_by, target_created_by, title, excerpt, version, actions}], meta: {page, limit, total, has_more} }
  • 列出审核队列中的条目（如 /review?sort_order=score 所示），包括等待批准的新帖/排队帖子和被举报的帖子。actions 是该条目有效操作 ID 的列表（例如 approve_post、reject_post、agree_and_hide、disagree、delete），可传给 discourse_perform_reviewable_action。每页 10 条（Discourse 固定页大小）。
• discourse_perform_reviewable_action（仅在启用写入时可用；参见写入安全）
  • 输入：{ reviewable_id: number; action_id: string; version: number; reject_reason?: string; revise_feedback?: string }
  • 输出：{ success, reviewable_id, action_id, version, created_post_id, created_post_topic_id, reviewable_updates }
  • 批准、拒绝或以其他方式处理审核队列条目。先使用 discourse_list_reviewables 获取该条目的 reviewable_id、当前 version 和有效的 action_id 值。
• discourse_save_draft（仅在启用写入时可用；参见写入安全）
  • 输入：{ draft_key: string; reply: string; title?: string; category_id?: number; tags?: string[]; sequence?: number (默认 0); action?: "createTopic" | "reply" | "edit" | "privateMessage" }
  • 输出：{ draft_key, sequence, saved }
• discourse_delete_draft（仅在启用写入时可用；参见写入安全）
  • 输入：{ draft_key: string; sequence: number }
  • 输出：{ draft_key, deleted }
• discourse_create_post（仅在启用写入时可用；参见写入安全）
  • 输入：{ topic_id: number; raw: string (≤ 30k 个字符); author_username?: string }
  • 输出：{ id, topic_id, post_number }
• discourse_create_topic（仅在启用写入时可用；参见写入安全）
  • 输入：{ title: string; raw: string (≤ 30k 个字符); category_id?: number; tags?: string[]; author_username?: string }
  • 输出：{ id, topic_id, slug, title }
• discourse_update_topic（仅在启用写入时可用；参见写入安全）
  • 输入：{ topic_id: number; title?: string; category_id?: number; tags?: string[]; featured_link?: string; original_title?: string; original_tags?: string[] }
  • 输出：{ success, topic_id, updated_fields, topic: {id, title, slug, category_id, tags, featured_link} }
• discourse_list_users（需要管理员 API 密钥）
  • 输入：{ query?: "active"|"new"|"staff"|"suspended"|"silenced"|"pending"|"staged"; filter?: string; order?: "created"|"last_emailed"|"seen"|"username"|"trust_level"|"days_visited"|"posts"; asc?: boolean; page?: number }
  • 输出：{ users: [{id, username, name, email, avatar_template, trust_level, created_at, last_seen_at, admin, moderator, suspended, silenced}], meta: {page, has_more} }
  • 注意：每页返回约 100 个用户（Discourse 固定页大小）。avatar_template 包含 {size} 占位符，将其替换为像素尺寸（例如 120）即可获得头像 URL
• discourse_create_user（仅在启用写入时可用；参见写入安全）
  • 输入：{ username: string (1–20 个字符); email: string; name: string; password: string; active?: boolean; approved?: boolean; upload_id?: number }
  • 输出：{ success, username, name, email, active, avatar_updated, message, avatar_error? }
  • 注意：如果提供了 upload_id，但头像更新失败，avatar_error 会包含错误消息
• discourse_update_user（仅在启用写入时可用；参见写入安全）
  • 输入：{ username: string; name?: string; bio_raw?: string; location?: string; website?: string; title?: string; date_of_birth?: string; locale?: string; profile_background_upload_url?: string; card_background_upload_url?: string; upload_id?: number }
  • 输出：{ success, username, updated_fields, avatar_updated, user: {...}, avatar_error? }
  • 注意：如果提供了 upload_id，但头像更新失败，avatar_error 会包含错误消息
• discourse_upload_file（仅在启用写入时可用；参见写入安全）
  • 输入：{ upload_type: "avatar"|"profile_background"|"card_background"|"composer"; image_data?: string (base64); url?: string; filename?: string; user_id?: number }
  • 输出：{ id, url, short_url, short_path, original_filename, extension, width, height, filesize, human_filesize }
  • 限制：
    • 必须且只能提供以下其中一项：image_data（需要 filename）、远程 HTTP(S) URL 或绝对本地文件路径
    • 头像/个人资料背景/卡片背景上传必须提供 user_id
    • 本地文件上传需要配置 --allowed_upload_paths（安全措施：防止任意文件读取）
  • 注意：使用 short_url（例如 upload://abc123.png）在帖子中嵌入图像。
• discourse_create_category（仅在启用写入时可用；参见写入安全）
  • 输入：{ name: string; color?: hex; text_color?: hex; emoji?: string; icon?: string; parent_category_id?: number; description?: string }
  • 输出：{ id, slug, name }
• discourse_select_site（提供 --site 时隐藏）
  • 输入：{ site: string }
  • 输出：{ site, title }

开发

• 要求：Node >= 24、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/resources/registry.ts
  • 内置工具：src/tools/builtin/*
  • 远程工具：src/tools/remote/tool_exec_api.ts
  • JSON 辅助工具：src/util/json_response.ts
  • 日志记录 / 脱敏：src/util/logger.ts、src/util/redact.ts

• 测试说明

  • 测试使用 Node 的测试运行器，针对已编译的产物（dist/test/**/*.js）运行。若单独执行脚本，请确保先运行 pnpm build，再运行 pnpm test。

• 发布（可选）

  • 此软件包以 @discourse/mcp 发布，并提供名为 discourse-mcp 的 bin。推荐使用 npx @discourse/mcp@latest，以便轻松上手。

• 约定

  • 所有输出均为纯 JSON，以便 Agent 可靠地进行程序化解析。
  • 请谨慎执行写入操作；仅在主动启用且受到速率限制时使用。

有关如何在 Agent 框架中使用此服务的更多指导，请参阅 AGENTS.md。

示例

使用 User API Key 快速开始（无需管理员权限）

# Step 1: Generate a User API Key
npx @discourse/mcp@latest generate-user-api-key \
  --site https://discourse.example.com \
  --save-to profile.json

# Step 2: Visit the authorization URL shown, approve the request, and paste the payload

# Step 3: Run the MCP server with your new key
npx @discourse/mcp@latest --profile profile.json --allow_writes --read_only=false

其他示例

• 在 try.discourse.org 上进行只读会话：

npx -y @discourse/mcp@latest --log_level debug
# In client: call discourse_select_site with {"site":"https://try.discourse.org"}

• 绑定到单个站点：

npx -y @discourse/mcp@latest --site https://try.discourse.org

• 使用 Admin API Key 创建帖子（已启用写入）：

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

• 使用 User API Key 创建帖子（已启用写入，无需管理员权限）：

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

• 创建类别（已启用写入）：

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"}]'
# In your MCP client, call discourse_create_category with for example:
# { "name": "AI Research", "color": "0088CC", "text_color": "FFFFFF", "description": "Discussions about AI research" }

• 创建主题（已启用写入）：

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"}]'
# In your MCP client, call discourse_create_topic, for example:
# { "title": "Agentic workflows", "raw": "Let's discuss agent workflows.", "category_id": 1, "tags": ["ai","agents"] }

• 使用 HTTP 传输运行（端口 3000）：

npx -y @discourse/mcp@latest --transport http --port 3000 --site https://try.discourse.org
# Server will start on http://localhost:3000
# Health check: http://localhost:3000/health
# MCP endpoint: http://localhost:3000/mcp

• 连接到受 HTTP Basic Auth 保护的站点：

npx -y @discourse/mcp@latest --auth_pairs '[{"site":"https://protected.example.com","api_key":"'$DISCOURSE_API_KEY'","api_username":"system","http_basic_user":"username","http_basic_pass":"password"}]' --site https://protected.example.com

身份验证

Admin API Keys 与 User API Keys

此 MCP 服务支持两种 Discourse API 身份验证方式：

1. Admin API Keys（api_key + api_username）

   • 生成密钥需要管理员 / 版主权限
   • 通过“管理面板” → “API” → “新建 API Key”创建
   • 可执行所有操作，包括创建用户 / 类别
   • 使用请求头：Api-Key 和 Api-Username

2. User API Keys（user_api_key + 可选的 user_api_client_id）

   • 任何用户都可以生成（无需管理员权限）
   • 权限和速率限制因用户而异
   • 非常适合个人使用和非管理员操作
   • 使用请求头：User-Api-Key 和 User-Api-Client-Id
   • 在 180 天不活动后自动过期（可按站点配置）
   • 了解更多：https://meta.discourse.org/t/user-api-keys-specification/48536

获取 User API Key

简便方法：内置生成器（推荐）

此软件包提供了一个方便的命令来生成 User API Keys：

# Interactive mode - follow the prompts
npx @discourse/mcp@latest generate-user-api-key --site https://discourse.example.com

# Save directly to a profile file
npx @discourse/mcp@latest generate-user-api-key --site https://discourse.example.com --save-to profile.json

# Specify custom scopes
npx @discourse/mcp@latest generate-user-api-key --site https://discourse.example.com --scopes "read,write,notifications"

# Get help
npx @discourse/mcp@latest generate-user-api-key --help

该命令将：

1. 生成一对 RSA 密钥
2. 显示供你访问的授权 URL
3. 提示你在授权后粘贴加密载荷
4. 解密并显示你的 User API Key
5. 可选择将其保存到配置文件中

手动方法

User API Keys 需要遵循 https://meta.discourse.org/t/user-api-keys-specification/48536 中说明的类似 OAuth 的流程。主要步骤：

1. 生成一对公钥 / 私钥
2. 使用你的公钥、应用名称、客户端 ID 和所请求的作用域，通过 /user-api-key/new 请求授权
3. 用户批准请求（必要时先登录）
4. Discourse 返回包含 User API Key 的加密载荷
5. 使用你的私钥解密，并在配置中使用该密钥

如果站点已启用，你也可以通过 Discourse 界面手动创建 User API Keys：

• 访问你的用户偏好设置 → 安全 → API
• 或使用实现 User API Key 流程的第三方工具

常见问题

• 为什么没有 create_post？ 你处于只读模式。请按上文所述启用写入。
• 可以禁用远程工具发现吗？ 可以，使用 --tools_mode=discourse_api_only 运行。
• 可以不公开 discourse_select_site 吗？ 可以，使用 --site <url> 启动，将其绑定到单个站点。
• 超时或遇到速率限制？ 增大 --timeout_ms，并注意遇到 429/5xx 时会内置重试和退避机制。
• 应该使用 Admin API Keys 还是 User API Keys？ 个人使用时请使用 User API Keys（无需管理员权限）。仅在需要执行管理员级别操作或设置系统范围的集成时，才使用 Admin API Keys。
• 遇到“fetch failed”错误？ 使用 --log_level debug 运行，以查看详细错误信息，包括：
  • 请求的确切 URL
  • HTTP 状态码和响应正文
  • 网络层错误（DNS、SSL/TLS、连接问题）
  • 重试次数和时间
  • 超时诊断信息