内容
freshrss-mcp-go
基于 Go 的 MCP（模型上下文协议）服务器，适用于 FreshRSS，结合现有实现的优点，输出令牌效率高。
## 功能特点
- **15 种 MCP 工具**，用于完成 FreshRSS 管理
- **HTML 标签剥离**，去除标签，输出干净的文本
- **基于词边界的截断**，实现令牌高效摘要
- **紧凑的 JSON** 输出，相比缩进格式节省 20-30% 的令牌
- **401 认证重试**（自动重新认证）
- **健康检查端点**，位于 `/health`，用于 Docker 监控
- **可流式传输的 HTTP、SSE 和 stdio** 传输模式
- **约 32MB Docker 镜像**（Alpine 多阶段构建）
## 工具列表
| 工具 | 描述 | 类型 |
|------|-------------|------|
| `freshrss_list_subscriptions` | 列出所有订阅的源 | 读取 |
| `freshrss_list_folders` | 列出文件夹/标签 | 读取 |
| `freshrss_get_unread_count` | 按源获取未读文章数量 | 读取 |
| `freshrss_get_articles` | 获取文章，支持筛选和分页 | 读取 |
| `freshrss_search_articles` | 按关键词搜索文章（支持源/文件夹范围） | 读取 |
| `freshrss_get_article_detail` | 获取完整文章内容（无截断，直接 API 查询） | 读取 |
| `freshrss_mark_read` | 将文章标记为已读 | 写入 |
| `freshrss_mark_unread` | 将文章标记为未读 | 写入 |
| `freshrss_mark_all_read` | 将源/文件夹中的所有内容标记为已读 | 写入 |
| `freshrss_star_article` | 将文章标记为星标 | 写入 |
| `freshrss_unstar_article` | 取消文章的星标 | 写入 |
| `freshrss_add_label` | 为文章添加标签 | 写入 |
| `freshrss_remove_label` | 从文章中删除标签 | 写入 |
| `freshrss_subscribe` | 订阅源 | 写入 |
| `freshrss_unsubscribe` | 取消订阅源 | 写入 |
## 安装配置
### 环境变量
参见 `.env.example`。必填：
- `FRESHRSS_URL` — 您的 FreshRSS 实例 URL
- `FRESHRSS_EMAIL`（或 `FRESHRSS_USERNAME`）— 登录用户名
- `FRESHRSS_API_PASSWORD`（或 `FRESHRSS_PASSWORD`）— API 密码（在 FreshRSS 设置 → 认证中设置）
可选：
- `FRESHRSS_API_PATH` 路径（默认：`/api/greader.php`）
- `MCP_TRANSPORT` — `http`、`sse` 或空字符串（stdio）
- `MCP_PORT` — HTTP/SSE 模式下的端口（默认：`8080`）
### 使用 Go 运行
```bash
export FRESHRSS_URL=... FRESHRSS_EMAIL=... FRESHRSS_API_PASSWORD=...
go run . # stdio
MCP_TRANSPORT=http MCP_PORT=8080 go run . # 流式 HTTP
MCP_TRANSPORT=sse MCP_PORT=8080 go run . # SSE
```
### 使用 Docker 运行
```bash
docker build -t freshrss-mcp-go .
docker run --rm \
-e FRESHRSS_URL \
-e FRESHRSS_EMAIL \
-e FRESHRSS_API_PASSWORD \
-e MCP_TRANSPORT=http \
-p 8080:8080 \
freshrss-mcp-go
```
### Docker Compose
```bash
cp .env.example .env
# 使用您的凭证编辑 .env
docker compose up -d
```
## 健康检查
在 HTTP 模式下运行健康检查：
```bash
curl http://localhost:8080/health
# {"status":"healthy"}
```
当 FreshRSS有效时返回 200，否则返回 503，附带错误详情。
## MCP 客户端配置
### 流式 HTTP（Docker）
```json
{
"mcpServers": {
"fss": {
"type": "streamableHttp",
"url": "http://localhost:8080/mcp"
}
}
}
```
### stdio（本地二进制文件）
```json
{
"mcpServers": {
"freshrss": {
"command": "/path/to/freshrss-mcp-go",
"env": {
"FRESHRSS_URL": "https://rss.example.com",
"FRESHRSS_EMAIL": "user",
"FRESHRSS_API_PASSWORD": "api-password"
}
}
}
}
```
## 令牌效率
`get_articles` 和 `search_articles` 工具支持三种节省令牌的选项：
- `strip_html`（默认：true）— 删除 HTML 标签，合并空白字符
- `trim_content`（默认：true）— 在词边界处截断
- `max_summary_length`（默认：400）— 内容/摘要的最大字符数
所有 JSON 输出均使用紧凑格式（无缩进），以最小化令牌使用。典型节省：**与原始 HTML 内容相比，令牌使用量减少约 90%**。
