内容
for Flarum
一个适用于 [Flarum](https://flarum.org) 的 [Model Context Protocol](https://modelcontextprotocol.io) 服务器。
它为任何兼容 MCP 的 AI 客户端（Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Zed 等）提供对 Flarum 论坛 API 的完全访问权限：读取和搜索讨论和帖子、创建主题和回复、管理用户、标签和分组、审核内容、更改设置以及调用任何第三方扩展端点。
> Flarum 的整个 API 都是统一的 [JSON:API](httpsapi.org)，因此一组小型通用工具涵盖了**整个**表面，包括扩展，而不是数百个手工编写的工具。
## 工具列表
**通用工具（全 API 覆盖）：**
| 工具 | 功能描述 |
| --- | --- |
| `flarum_list` | 列出/搜索任何资源类型，带有过滤器、包含、排序、分页 |
| `flarum_get` | 通过类型和 ID 获取一个资源 |
| `flarum_create` | 创建任何资源 |
| `flarum_update` | 更新任何资源（也包括锁定/置顶/审核） |
| `flarum_delete` | 删除任何资源 |
| `flarum_request` | 原始的 escape hatch，用于任何端点 |
**便捷工具：**
| 工具 | 功能描述 |
| --- | --- |
| `flarum_whoami` | 论坛信息 + API 密钥所使用的用户 |
| `flarum_search` | 全文讨论搜索 |
| `flarum_create_discussion` | 开始一个主题（标题 + 内容 + 可选标签） |
| `flarum_reply` | 回复讨论 |
**官方文档（默认开启）：**
搜索和阅读 Flarum 的官方 [2.0 文档](https://docs.flarum.org/2.x/)，以便 AI 可以在操作前检查设置、权限、扩展器或 REST 端点的工作方式。这些文档只读取公共文档，从不读取您的论坛或其密钥，因此它们在任何模式下都有效，包括只读模式和无 API 密钥。它们读取实时文档，因此结果始终反映当前的 2.0 文档。您可以通过设置 `FLARUM_DOCS=0` 来关闭它们。
| 工具 | 功能描述 |
| --- | --- |
| `flarum_docs_search` | .0 文档；返回带有排名页面 `flarum_docs_get` | 读取一个通过 slug、路径或 URL） |
| `flarum_docs_list` | 列出/浏览可用的 2.0 文档页面 |
**扩展开发（默认开启）：**
Flarum 2.0 扩展的开发参考：脚手架和架构、`composer.json`、TypeScript 前端、后端（API 资源/模型/迁移）、国际化、测试、静态分析和 CI 以及发布。结合官方文档确立的约定、事实上的 FriendsOfFlarum 标准以及防止实际生产错误的模式。静态内容，因此它在任何模式下都有效，包括只读模式和无 API 密钥。您可以通过设置 `FLARUM_DEV=0` 来关闭它。
| 工具 | 功能描述 |
| --- | --- |
| `flarum_dev` | 返回扩展开发参考；可选 `topic`（脚手架、composer、前端、后端、国际化、测试、质量-ci、发布）以缩小范围 |
**扩展管理（需手动开启，默认关闭）：**
仅在设置 `FLARUM_EXTENSIONS=1` 且论坛安装了官方的 [`flarum/extension-manager`](https://github.com/flarum/extension-manager) 时注册。这些工具驱动 Composer 在服务器上运行，因此需要管理员密钥和。请参阅 [](#%E7%AE%A1%E7%86%E6%89%8B%E5%%8A)。
工具 | 功能描述 |
| --- |
|_ext_search` | 在 Packagist 上搜索可安装的扩展、语言主题 |
| `flarum_ext_why_not` | 包的兼容性检查（不会更改任何内容） |
| `flarum_ext_install` | 安装扩展（可选启用） |
| `flarum_ext_update` | 更新一个扩展（`soft` 在范围内，或 `hard` 到最新版本） |
| `flarum_ext_remove` | 卸载| `flarum` | 启用/的扩展（无需 Composer；立即生效） |
| `flarum_ext_check | 检查可用的| `flarum_ext_bulk_update` | `minor``（带有 ``）或 `global` |
| `flarum_ext_configure_composer` | 读取/设置 `minimum-stability`、存储库或私有注册表身份验证 |
| `flarum_ext_tasks` | 列出安装/更新作业历史和 Composer 输出（轮询异步作业） |
**托管服务独有（自托管用户不可用）：**
两种功能仅在 Link Robins 的托管层级上存在。它们依赖于栈注入的环境`DIAG_URL `SNAPSHOT_URL`），而这些仅由 Link Rob基础设施提供。自托管用户它们，因此诊断工具注册，快照钩保持空操作。手动设置它们无效，因为没有后端| 功能 | 网关 | 功能描述 |
| --- | --- | --- |
| `flarum_diag` / `flarum_triage` | `DIAG_URL` + token | 只读的托管论坛故障排除（启动错误、更新后损坏、邮件/队列故障）通过托管控制面板，即使 Flarum 无法启动。 请参阅 [docs/managed-troubleshooting.md](docs/managed-troubleshooting.md)。 |
| 预更改快照 | `SNAPSHOT_URL` + token | 在会话的首次写入之前采取的最佳努力恢复点。 请参阅 [Hosting](#%E6%89%8B%E6%88%B8-http-%E9%9C%98%E6%8D%A2)。 |
上面部分（通用工具、便捷工具、文档、开发扩展管理工具）托管用户都可用功能仅在托管环境变量（`DIAG_URL` / `SN_URL`）设置时激活，这些变量指向 Link Robins 的托管平台，因此实际上它们仅限托管服务独有，但代码中没有任何部分是封闭的。MCP 采用 [MIT 许可](#%E8%BF%91%E6%9E%84%E6%89%8B%E6%9C%AF)。
## 配置
| 变量 | 是否必填 | 描述 |
| --- | --- | --- |
| `FLARUM_URL` | 是 | 您的论坛的基本 URL，例如 `https://discuss.example.com` |
| `FLARUM_API_KEY` | 用于写入/私有larum API来自 `api_keys` 表）。如果没有它，则只能访问公共读取内容。 |
| `FLARUM_USER_ID` | 可选 | 使用主 API 密钥时，模拟此用户 ID |
| `FLARUM_MODE` | 可选 | `write`（默认）或 `read`。在 `read` 模式下，服务器拒绝所有变更请求（创建/更新/删除和非 GET `flarum_request`）并且隐藏写入工具。`READ_ONLY=1` 具有相同的效果。将其用于指向一个真实论坛而无需冒险进行更改。 |
| `FLARUM_EXTENSIONS` | 可选 | `1`/`true` 注册扩展管理工具（通过 `flarum/extension-manager` 安装/更新/删除扩展）。默认关闭；需要写入模式和管理密钥。请参阅 [管理扩展](#%E7%AE%A1%E7%90%6%89%8B%E5%8A%8A)。 |
| `FLARUM_DOCS` | 可选 | 默认开启。设置为 `0`/`false`/`off` 以隐藏官方文档工具（`flarum_docs_search`/`get`/`list`）。它们只读取公共文档，从不读取您的论坛。 |
| `FLARUM_DEV`选 | 默认开启 `0false`/`off` 以隐藏扩展开发参考工具arum_dev`；从不触论坛。 |
FLARUM_TIMEOUT 可选 | 请求毫秒，默认 30000） |
| `FLARUM_USER_AGENT` | 可选 | 重写发送到您论坛的 ``。默认为 `-flarum/< (+repo url)`。请参阅 [Cloud WAF 后面](#%E5%90C%E4%%70%E5%8A%E5%90%8A%9C%98%E6%8D)。 |
### Cloudflare 或 WAF 后面larum 位于 Cloudflare 后一些 WAF 配置阻止了 `User-Agent`像是脚本或空的请求，返回 **Cloud 1010** （`browser_signature_banned在请求到达 Flarum 之前。服务器描述性的、可 User-Agent，正是为了这个原因，因此常见情况开箱即用。
如果您的阻止它，请允许工具而不是放松防火- **允许 User-Agent**。在 Cloudflare 中，添加一个 WAF 规则，例如-Agent contains "m-flarum"` →过* / *。默认 UA 是cp-for-flarum> (+https://github.com/linkrobins/mcp-for-flarum)`。
或者允许列出服务器 IP** （适用于托管/单一来源部署的最佳选择）。
- **或者使用自定义 UA** 与现有的允许规则匹配。
不要通过浏览器 User-Agent 来变通：它很脆使流量无法列审计。
### 获取密钥
Flarum 暂时没有 API 密钥的管理员界面。请直接在数据库中创建一个：
```sql
INSERT INTO api_keys (`key`, user_id_at)
VALUES (REPLACE(UUID(), '-', ''), 1, NOW());
```
将生成的 `key作 `FLARUM_API_KEY`。设置_id`（或 `FLARUM_USER_ID使密钥模拟该用户，因此其权限正是该用户的权限。
### 管理扩展
设置 `FLARUM_EXTENSIONS=1` 以允许 AI 安装、更新、删除、启用和禁用扩展。这**默认关闭**，因为它在您的服务器上运行 Composer，可以更改您的的代码，这比编辑强大。它需要以下所有条件：
-的 [`flarum/extension-manager`](https://github.com/flarum/extension-manager) 已安装并启用上。
- 写入模式（不是 `FLARUM_MODE=read`）和管理密钥，其用户是**管理员**。
- 可以实际运行 Composer 的服务器：PHP 函数 `proc_open` 和 `escapeshellarg` 可用，并且 `vendor/`、`storage/`、`composer.json` 和 `composer.lock` 可写。
长时间运行的安装的报告取决于您队列：
-队列**、数据库等，带有正在运行的工作进程在作业完成时返回。工具为您轮询管理器的任务列表并返回 Composer 输出。如果没有工作进程使用作业，调用超时并说明，而不是挂起。
- **同步** （`sync` 队列，或管理器的“在后台运行作业”设置关闭）：请求阻塞直到 Composer 完成并内联返回结果。非常大的更新可能会导致 PHP关超时，即使 Composer 仍在运行。
`flarum_ext_install` 除传递 `enable: true`，否则不会启用使用 `flarum_ext_why_not认包与您的 Flarum 版本兼容。对于更新，请先备份。
**启用可能会破坏** 管理器拒绝安装发布的 Flarum与您的版本不匹配的扩展，但该检查是尽力而为：它读取最新的稳定flarum/core束，当 Packagist 无法访问或包声明无效时，并且 Composer 实际安装的版本可能与检查的版本，扩展程序可能会通过检查，仍在启动失败，使整个站点崩溃（每个页面，包括管理面板和此工具的 API，都开始返回 500）。然后管理器无法为您禁用它：恢复意味着从数据库中的 `extensions_enabled` 设置和手动 `composer remove` 中删除扩展。这就是为什么安装默认不自动启用，以及在熟悉的扩展程序之前进行备份的原因。
## 安装和运行
使用官方的镜像自行托管，或从源代码构建**不**发布到 npm。）
### 选项 1：Docker（推荐）
对于 客户端（stdio）：
```bash
-i --rm \
-e FLARUM_URL=https://discuss.example.com \
-e FLARUM_API_KEY=xxxxx \
ghcr.io/linkrobins/mcp-for-flarum
```
Claude Code：
```bash
claude mcp add flarum -- docker run -i --rm -e FLARUM_URL=https://discuss.example.com -e FLARUM_API_KEY=xxxxx ghcr.io/linkrobins/mcp-for-flarum
```
Claude Desktop / Cursor / Windsurf（JSON 配置）：
```json
{
"mcpServers": {
"flarum": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "FLARUM_URL", "-e", "FLARUM_API_KEY", "ghcr.io/linkrobins/mcp-for-flarum"],
"env": {
"FLARUM_URL": "https://discuss.example.com",
"FLARUM_API_KEY": "xxxxx"
}
}
}
}
```
### 选项 2：从源代码（无 Docker）
```bash
git clone https://github.com/linkrobins/mcp-for-flarum.git
cd mcp-for-flarum
npm install && npm run build
FLARUM_URL=https://discuss.example.com FLARUM_API_KEY=xxxxx node dist/index.js
```
然后将客户端的 `command` 指向 `node /absolute/path/to/mcp-for-flarum/dist/index.js`。
### 不想运行任何东西？
Link Robins 提供了一个托管的托管版本，无需安装，无需密钥管理，可从 Web 客户端使用。请参阅 [linkrobins.com](https://linkrobins.com)。
## 托管（HTTP 传输）
同一个二进制文件可以作为长生存期的 Web 服务通过 **Streamable HTTP** 运行，因此您可以托管它而不是本地运行。这是基于 Web 的客户端（无法启动本地进程）连接到的服务。
使用 `--http` （或 `_TRANSPORT=http`）以 HTTP 模式
```bash
FLARUM_URL=https://discuss.example.com \
FLARUM_API_KEY \
MCP_AUTH_TOKEN=a-long-random-secret=3000 \
node dist/index.js --http
```
它提供：
- `POST /m，MCP 端点（Streamable HTTP）
- `GET /health`，负载/正常运行时间器的健康检查特定配置：
| 变量 | 默认 |
| --- | --- | --- |
MCP_TRANSPORT` | `stdio`为 `http` 以运行 Web 服务（http`） |
| `PORT` |0` | HTTP 端口 |
| ` `1270.1 绑定地址。**如果未设置 `_AUTH_TOKEN`，则拒绝绑定非本地**。要公开它（例如在 Docker设置 `HOST=0.0.0` 和令牌。 |
| `_TOKEN` | _(无)_ | 如果请求必须发送 `Authorization: Bearer <token>`。在公开非本地接口时需要。 |
| `SNAPSHOT_URL` | _(无)_ | 可选的托管钩子。当设置时，服务器在此会话的**首次写入**之前触发一个尽力而为的 `POST`，以便在 AI 驱动的编辑之前拍摄恢复点。失败从不阻止写入；自托管用户请取消设置。 |
| `SNAPSHOT_TOKEN` | `MCP_AUTH_TOKEN` | 与 `SNAPSHOT_URL` 相关的 Bearer 令牌。默认为 `MCP_AUTH_TOKEN`。 |
> 安全：托管实例可以读取、写入和删除论坛的目标密钥。始终在运行，设置CP_AUTH_TOKEN或使用自己的身份验证/OAuth 代理），并为 API 密钥的用户提供权限。Flarum API 密钥保留端，客户端从未公开。
### Docker模式）
```bash
docker run -3000:3000 \
-eSPORT=http \
-e HOST=0.0.0 \
-e FL_URL=https://discuss.example.com \
FLARUM_API_KEY=xxxxx \
MCP_AUTH_TOKEN=a-long-random-secret \
ghcr.io/linkrobins/mcp-for-flarum
```
`HOST=0.0.0` 是必要的，以便发布的端口可访问；服务器仅在设置 `MCP_AUTH_TOKEN` 时才允许这样做。
或者使用附带的 [`docker-compose.yml`](docker-compose.yml)：设置您的值并 `docker compose up -d`。
## 开发
```bash
npm install
npm run build
FLARUM_URL=... FLARUM_API_KEY=... node dist/index.js
```
## 许可证
[MIT](LICENSE) Link Robins。免费开源 - 自托管、修改并随意使用。
## 商标
Flarum 是 Flarum 基金会的商标。本项目是一个独立项目，通过其 API 与 Flarum 合作；它不隶属于、未得到 Flarum 基金会认可或赞助。
