内容
# xf-cli
`xf-cli` 是一个只读的 XenForo 前端客户端和 MCP 服务器，基于 Go 语言开发。
它以普通用户身份登录 XenForo 2.x 论坛，无需 `XF-Api-Key`，并通过以下方式公开论坛内容：
- 一个带有 MCP 对齐子命令的 CLI
- 一个用于 Claude、Codex 和其他 MCP 客户端的 MCP stdio 服务器
当前验证目标是：
- `https://www.rc-network.de`
## 功能范围
已实现：
- 浏览器样式的用户名/密码登录
- 从 `~/.config/xf-cli/session.json` 验证会话重用
- 论坛列表
- 线程列表
- 跨所有页面的完整线程读取
- 线程标题搜索
- 帖子内容搜索
- 公共个人资料读取
- 用户帖子和线程列表
- “我的线程”和“我参与的线程”
- 链接规范化
- 图片和附件解析
- 通过 `stdin` / `stdout` 的 MCP
不在范围内：
- 发布帖子
- 创建线程
- 编辑或删除
- 私人消息
- 使用 XenForo REST API
- 自动加载 `.env`
## 为什么使用前端登录
`rc-network.de` 暴露了 XenForo REST API，但仍需要 `XF-Api-Key`。
普通的浏览器会话 cookie 无法解锁 `/api/...`。
因此，该项目使用经过身份验证的前端并解析 HTML。
## 编译
```bash
go build ./...
```
## 安装
将 CLI 安装到您的 Go bin 目录：
```bash
go install github.com/sttts/xf-cli@latest
```
然后直接使用：
```bash
xf-cli --help
```
## 身份验证
优先级顺序：
1. `-u` / `-p`
2. `XF_USERNAME` / `XF_PASSWORD`
3. 交互式提示
示例：
```bash
export XF_USERNAME=sttts
export XF_PASSWORD='...'
xf-cli list_forums
```
`.env` 不会自动加载。
### `login` 持久化会话
此命令不仅测试凭证：
```bash
xf-cli login
```
成功的 `login` 会将身份验证会话写入：
```text
~/.config/xf-cli/session.json
```
存储的会话然后被以下命令重用：
- 后续 CLI 命令
- `xf-cli mcp`
因此，正常的设置流程是：
1. 运行 `xf-cli login`
2. 确认 `session.json` 存在
3. 使用其他 CLI 命令或启动 MCP 服务器
## 会话持久性
成功的登录存储在：
```text
~/.config/xf-cli/session.json
```
在后续运行中，`xf-cli` 尝试：
1. 加载存储的会话
2. 验证它是否与论坛前端一致
3. 如果仍然有效，则重用它
4. 如果已过期，则回退到新的登录
这适用于：
- `list_threads` 等 CLI 命令
- 通过 `xf-cli mcp` 的 MCP 模式
如果不存在有效的存储会话，`xf-cli` 需要再次提供凭证。
## CLI
顶级命令：
- `login`
- `list_forums`
- `list_threads`
- `read_thread`
- `search_threads`
- `search_posts`
- `read_profile`
- `list_user_posts`
- `list_user_threads`
- `list_my_threads`
- `list_threads_i_participated`
- `follow_link`
- `get_image`
- `mcp`
示例：
```bash
xf-cli login
xf-cli list_forums --json
xf-cli list_threads /forums/flugmodellbau-allgemein.31/ --limit=50
xf-cli read_thread /threads/eure-sch%C3%B6nsten-modelle.144946/ --json
xf-cli search_threads Fouga --limit=20
xf-cli search_posts Fouga --limit=20
xf-cli read_profile /members/sttts.31018/
xf-cli follow_link /threads/eure-sch%C3%B6nsten-modelle.144946/latest
xf-cli get_image /attachments/piper-tc-jpg.9277151/
```
### 逻辑分页
列表和搜索命令使用逻辑分页：
- `--limit=50` 是 CLI 默认值
- `--limit=0` 表示：收集所有页面
- 如果 `--page` 未设置，则页面会被收集，直到至少有 `limit` 个结果存在
- 响应包含 `next_page` 和 `next_page_url`
- 传递 `--page=<next_page>` 以继续
`read_thread` 不同：
- 它始终读取完整的线程
- 它没有分页标志
## 调试日志
`-v` 是一个计数器：
- `-v`：请求行
- `-vv`：请求表单数据、状态、头部、cookie
- `-vvv`：响应正文
示例：
```bash
xf-cli -v search_posts Fouga --limit=5
xf-cli -vv list_threads /forums/flugmodellbau-allgemein.31/ --limit=5
xf-cli -vvv read_thread /threads/eure-sch%C3%B6nsten-modelle.144946/
```
## MCP 模式
使用以下命令运行 stdio MCP 服务器：
```bash
xf-cli mcp
```
服务器通过 `stdin` / `stdout` 进行 MCP 通信。它不公开 HTTP 传输。
### MCP 身份验证
MCP 服务器使用与 CLI 相同的身份验证/会话逻辑。
推荐设置：
1. 创建会话：
```bash
xf-cli login
```
2. 启动 MCP 服务器：
```bash
xf-cli mcp
```
如果存储的会话仍然有效，MCP 将在无需提示的情况下启动。
如果存储的会话丢失或过期，MCP 需要来自以下位置的凭证：
- `XF_USERNAME`
- `XF_PASSWORD`
示例：
```bash
XF_USERNAME=sttts XF_PASSWORD='...' xf-cli mcp
```
重要：
- `.env` 不会自动加载
- MCP 不应依赖交互式提示在正常客户端设置中
- 为了可靠的 MCP 启动，请先创建会话或在 MCP 进程的环境中传递 `XF_USERNAME` / `XF_PASSWORD`
### Claude Desktop
`xf-cli` 是一个本地 stdio MCP 服务器。在 Claude Desktop 中，将其配置为基于命令的服务器，并通过环境变量传递凭证（如果您不想依赖持久会话）。
典型本地设置：
```json
{
"mcpServers": {
"xf-cli": {
"command": "/absolute/path/to/xf-cli",
"args": ["mcp"],
"env": {
"XF_USERNAME": "your-user",
"XF_PASSWORD": "your-password"
}
}
}
}
```
如果您已经使用 `xf-cli login` 创建了 `~/.config/xf-cli/session.json`，则通常可以省略 `env` 块，直到会话过期。
### Claude
对于支持本地 MCP stdio 服务器的 Claude 客户端，请使用相同的模式：
- 启动 `xf-cli mcp`
- 通过 `stdin` / `stdout` 保持连接
- 如果没有持久会话，请在服务器环境中提供 `XF_USERNAME` / `XF_PASSWORD`
确切的 UI 因 Claude 界面而异，但重要的部分是相同的命令：
```bash
/absolute/path/to/xf-cli mcp
```
### Codex
Codex 支持直接添加本地 stdio MCP 服务器。
示例：
```bash
codex mcp add xf-cli --env XF_USERNAME=your-user --env XF_PASSWORD=your-password -- /absolute/path/to/xf-cli mcp
```
然后使用以下命令验证：
```bash
codex mcp list
```
如果您想依赖持久会话，请先运行：
```bash
xf-cli login
```
然后添加 MCP 服务器而不带凭证环境变量。
当前 MCP 工具：
- `list_forums`
- `list_threads`
- `read_thread`
- `search_threads`
- `search_posts`
- `read_profile`
- `list_user_posts`
- `list_user_threads`
- `list_my_threads`
- `list_threads_i_participated`
- `follow_link`
- `get_image`
## 测试
单元测试和实时测试：
```bash
make test
```
实时测试针对 `rc-network.de` 运行，需要：
```bash
export XF_USERNAME=...
export XF_PASSWORD=...
```
测试套件验证：
- 登录
- 会话重用
- 论坛和线程读取
- 搜索工具
- 用户/个人资料工具
- 链接和图像工具
- MCP 工具注册和 MCP 工具调用
## 仓库
GitHub 仓库：
```text
git@github.com:sttts/xf-cli.git
```
