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 错误，系统内置了重试和退避机制。