# 404K Knowledge Planet MCP Server

[![CI](https://github.com/wlhtea/zsxq-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/wlhtea/zsxq-mcp-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

通过 Model Context Protocol（MCP）让 Claude Desktop、Codex、Cursor 和其他
MCP 客户端读取 `404k.wlhtea.xyz` 上的私有知识星球归档。

MCP Server 不持有知识星球 Cookie，也不直接访问知识星球。它只使用独立的
API Token 请求：

```text
https://404k.wlhtea.xyz/api/v1
```

## 功能

- 查看最近同步状态和当前话题数量；
- 分页浏览历史话题；
- 搜索标题、正文和标签，并排除指定关键词；
- 精确匹配一个或多个标签，支持任一/全部匹配；
- 排除指定标签；
- 按北京时间今天、最近 24 小时、3 天、7 天或自定义日期筛选；
- 独立组合精华、图片和附件条件；
- 按最新、最早、阅读量或点赞量排序；
- 按话题 ID 获取完整正文；
- 返回本站受保护的图片、PDF 和附件地址；
- 所有请求通过 `Authorization: Bearer` 鉴权。

提供的工具（当前版本 `1.1.0`）：

```text
zsxq_status
zsxq_list_topics
zsxq_search_topics
zsxq_get_topic
```

## 安装

要求 Node.js 20 或更高版本。

从 GitHub 安装：

```bash
git clone https://github.com/wlhtea/zsxq-mcp-server.git
cd zsxq-mcp-server
npm ci
npm link
```

从发布的 `.tgz` 安装：

```bash
npm install -g ./wlhtea-zsxq-mcp-server-1.1.0.tgz
```

本仓库内直接运行：

```bash
cd mcp-server
npm ci
ZSXQ_API_TOKEN="YOUR_API_TOKEN" npm start
```

## 环境变量

| 名称 | 必填 | 默认值 | 说明 |
|---|---:|---|---|
| `ZSXQ_API_TOKEN` | 是 | 无 | 朋友专用 API Token |
| `ZSXQ_API_BASE_URL` | 否 | `https://404k.wlhtea.xyz` | 数据 API 所在网站 |
| `ZSXQ_API_TIMEOUT_MS` | 否 | `30000` | 单次请求超时 |

不要把真实 Token 提交到 Git；`.env.example` 只保留占位符。

## Claude Desktop 配置

```json
{
  "mcpServers": {
    "zsxq-404k": {
      "command": "node",
      "args": ["/ABSOLUTE_PATH/zsxq-mcp-server/src/index.js"],
      "env": {
        "ZSXQ_API_BASE_URL": "https://404k.wlhtea.xyz",
        "ZSXQ_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}
```

## Codex 配置

安装后可以直接注册到 Codex：

```bash
codex mcp add zsxq-404k \
  --env ZSXQ_API_BASE_URL=https://404k.wlhtea.xyz \
  --env ZSXQ_API_TOKEN=YOUR_API_TOKEN \
  -- zsxq-mcp-server
```

也可以在 `~/.codex/config.toml` 中添加：

```toml
[mcp_servers.zsxq-404k]
command = "node"
args = ["/ABSOLUTE_PATH/zsxq-mcp-server/src/index.js"]

[mcp_servers.zsxq-404k.env]
ZSXQ_API_BASE_URL = "https://404k.wlhtea.xyz"
ZSXQ_API_TOKEN = "YOUR_API_TOKEN"
```

验证：

```bash
codex mcp get zsxq-404k
codex mcp list
```

## API 调试

```bash
curl 'https://404k.wlhtea.xyz/api/v1/status' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

curl 'https://404k.wlhtea.xyz/api/v1/topics?offset=0&limit=20' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

curl 'https://404k.wlhtea.xyz/api/v1/topics?q=AI&limit=20' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

curl --get 'https://404k.wlhtea.xyz/api/v1/topics' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  --data-urlencode 'q=AI' \
  --data-urlencode 'tag=大模型' \
  --data-urlencode 'tag=算力' \
  --data-urlencode 'tagMode=all' \
  --data-urlencode 'excludeTag=广告' \
  --data-urlencode 'timeRange=7d' \
  --data-urlencode 'hasFiles=true' \
  --data-urlencode 'sort=readers' \
  --data-urlencode 'limit=20'
```

## 搜索和筛选

`zsxq_search_topics` 接受以下参数；除 `query` 外，其余参数也可用于
`zsxq_list_topics`：

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `query` | string | 必填 | 搜索标题、正文和标签 |
| `excludeQuery` | string | 无 | 排除搜索文本中包含该关键词的话题 |
| `tags` | string[] | `[]` | 精确标签，最多 20 个 |
| `tagMode` | `any \| all` | `any` | 多标签匹配任意一个或全部 |
| `excludeTags` | string[] | `[]` | 命中任一精确标签即排除 |
| `timeRange` | `all \| today \| 24h \| 3d \| 7d` | `all` | 北京时间今天或滚动时间窗口 |
| `startDate` | string | 无 | `YYYY-MM-DD` 或带时区 ISO 8601 时间 |
| `endDate` | string | 无 | 日期格式包含北京时间当天 |
| `filter` | `all \| digest \| image \| file \| image_and_file` | `all` | 兼容的快捷类型筛选 |
| `digested` | boolean | 无 | 可与图片、附件条件组合 |
| `hasImages` | boolean | 无 | 要求包含或不包含图片 |
| `hasFiles` | boolean | 无 | 要求包含或不包含 PDF/附件 |
| `sort` | `newest \| oldest \| readers \| likes` | `newest` | 排序方式 |
| `offset` | integer | `0` | 分页偏移 |
| `limit` | integer | `20` | 返回数量，最大 50 |

`startDate` 和 `endDate` 会覆盖 `timeRange` 对应的同侧边界。日期值
`YYYY-MM-DD` 按 `Asia/Shanghai` 解释；`endDate` 会包含当天
`23:59:59.999`。

示例自然语言请求：

```text
搜索近 7 天标签同时包含“大模型”和“算力”、带附件的内容，按阅读量排序。
搜索“英伟达”，排除“广告”标签和“推广”关键词，只看精华且同时有图片和附件。
列出 2026-07-01 到 2026-07-31 的半导体标签内容，按最早时间排序。
```

OpenAPI 3.1 文档：

```text
https://404k.wlhtea.xyz/api/v1/openapi.json
```

OpenAPI 文档本身也需要相同的 Bearer Token。

## 测试

```bash
npm test
```

## License

MIT

## Security

MCP Server 只需要 `ZSXQ_API_TOKEN`，不需要也不接受知识星球 Cookie。不要把
真实 Token 提交到 Git、Issue、日志或截图中，详见 [SECURITY.md](SECURITY.md)。