用途
discourse-mcp 是一个 Model Context Protocol（MCP）stdio 服务器，用于将 Discourse 论坛的功能以工具（tools）和资源（resources）的形式提供给 AI 智能体。它允许 AI 客户端搜索论坛主题、阅读帖子、管理分类和标签、发现用户，并与社区进行交互。
主要能力
- 搜索主题与帖子，支持通过 discourse_select_site 选择目标站点，或使用 --site 参数将服务器绑定到单一站点。
- 读取帖子内容，支持通过 --max-read-length 控制返回字符数（默认 50000），并优先请求原始内容（include_raw=true）。
- 管理分类、群组和标签组：分类和群组资源作为兼容性接口保留，同时提供规范的列表工具；标签组有专门的工具集（tag_groups），包含搜索、列表、获取、创建、更新和删除等六个工具。
- 用户发现与交互：支持列出用户、查看用户信息（可通过 --show_emails 包含邮箱，需管理员权限）。
- 写入操作：包括发帖、主题、私信、分类、用户、上传、草稿以及 Data Explorer 查询的变更，默认禁用，需通过 --allow_writes 开启。
- 内置 Data Explorer 工具集：可暴露只读的 Data Explorer 工具，用于查询检索和执行。
使用方式
快速开始（只读模式）
在 MCP 客户端中调用 discourse_select_site 工具并传入 { "site": "https://try.discourse.org" } 选择站点，或使用 --site https://try.discourse.org 启动服务器并绑定站点（此时 discourse_select_site 被隐藏）。
启用写入
使用 --allow_writes 标志开启写入工具。写入工具需要为所选站点配置匹配的 auth_pairs 条目，否则返回错误。写入操作有约 1 请求/秒的速率限制。
认证
默认无认证。支持以下方式：
- 管理员 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。 可包含多个 auth_pairs 条目，匹配所选站点的条目会被使用。如果同一站点同时提供 user_api_key 和 api_key，user_api_key 优先。
在 MCP 客户端中使用（例如 Claude Desktop）
通过 npx 运行。服务器在 MCP 服务器名称 @discourse/mcp 下注册工具。
标志与默认值
- --help, -h：打印 CLI 帮助并退出。
- --version, -v：打印版本行并退出。
- --allow_writes（默认 false）：启用变更工具。
- --read_only <boolean>：已弃用的兼容性设置，true 与 --allow_writes 冲突，false 无效果。
- --timeout_ms <number>（默认 15000）
- --concurrency <number>（默认 4）
- --log_level <silent|error|info|debug>（默认 info）
- --show_emails（默认 false）：在用户工具中包含邮箱，需管理员权限。
- --tools_mode <auto|discourse_api_only|tool_exec_api>（默认 auto）
- --toolsets <name[,name...]>：暴露选定的内置域，省略则使用紧凑默认目录。
- --site <url>：绑定到单一站点并隐藏 discourse_select_site。
- --default-search <prefix>：为每个搜索查询无条件添加前缀。
- --max-read-length <number>：帖子内容返回的最大字符数（默认 50000）。
- --allowed_upload_paths <paths>：允许本地文件上传的目录列表，需启用 discourse_upload_file。
- --transport <stdio|http>（默认 stdio）：使用标准输入输出，或仅回环的 Streamable HTTP。
- --port <number>（默认 3000）：HTTP 传输时的监听端口。
- --cache_dir <path>（保留）
- --profile <path.json>：使用配置文件，标志仍会覆盖配置文件中的值。
内置工具集（Toolsets）
工具集允许操作者仅暴露 MCP 客户端所需的内置域。省略 --toolsets 和配置文件字段时，服务器注册默认目录（包括 search、discourse_search 和 discourse_filter_topics）。标记为（opt-in）的管理和专用域（包括 themes）必须显式选择。使用 --toolsets all 仅在确实需要所有内置域时。 可用工具集包括：data_explorer、administration、groups、tag_groups 等。工具集选择与安全性和授权分离：选定的工具集形成并集，只读模式仍会移除需要写入启用的工具。工具集仅过滤内置工具，不是授权或完整能力边界。
适用场景
- AI 智能体需要与 Discourse 论坛交互，进行信息检索、内容阅读或社区管理。
- 自动化社区运营任务，如批量管理分类、标签组或用户。
- 通过 MCP 客户端（如 Claude Desktop）集成论坛功能到 AI 工作流中。
限制
- 写入操作默认禁用，需显式开启并配置认证。
- 私信列表和阅读需要匹配的已认证站点，因为私信数据从不公开。
- 写入操作有约 1 请求/秒的速率限制。
- 工具集选择不绕过写入安全，选定的写入工具在未启用写入时仍不可用。
- 未知或空的工具集选择是配置错误。
- 本地文件上传需要 --allowed_upload_paths 指定允许的目录，且这些路径不进行 ~ 扩展。
- HTTP 传输明确支持每个进程一个状态化 MCP 客户端/会话，请求体限制为 4 MiB。
- 部分功能（如标签组操作）需要上游 staff 权限或 tagging_enabled 设置。
- 版本 0.3.1 简化了写入选择，--allow_writes 足够，并弃用 read_only=false；0.2.x 引入了与 0.1.x 的破坏性变更，包括仅 JSON 工具输出。
