# LLM Wiki Streamable HTTP MCP Server

这是一个独立的 LLM Wiki MCP 服务端项目，通过官方 **Streamable HTTP** transport 暴露 LLM Wiki 桌面端能力。

本项目与 LLM Wiki 当前的 stdio MCP 包解耦：不会扫描项目目录，不会 import LLM Wiki 桌面端源码，也不会 import 现有 stdio MCP 实现。所有工具能力都通过 LLM Wiki 桌面端本地 HTTP API 调用。

## 功能

- 官方 MCP Streamable HTTP endpoint：`/mcp`
- 内置 Web UI：`/`
- Web JSON API：`/api/*`
- 可配置监听 IP 和端口
- 可开关 MCP / Web API token 校验
- 支持 LLM Wiki 桌面端 API token
- 工具能力对齐当前 LLM Wiki stdio MCP

## 环境要求

- Node.js 20+
- LLM Wiki 桌面端正在运行
- LLM Wiki 设置中启用本地 HTTP API
- LLM Wiki 设置中启用 MCP access
- 满足以下任一条件：
  - LLM Wiki 设置中允许无 token 访问本地 API
  - 设置 `LLM_WIKI_API_TOKEN` 为桌面端 API token

## 安装与构建

```bash
npm install
npm run build
```

## 启动服务

不启用 MCP 层 token 校验：

```bash
npm start -- --host 127.0.0.1 --port 19829
```

启用 MCP 层 token 校验：

```bash
LLM_WIKI_MCP_REQUIRE_TOKEN=true \
LLM_WIKI_MCP_TOKEN=client-secret \
LLM_WIKI_API_TOKEN=desktop-api-token \
npm start -- --host 127.0.0.1 --port 19829
```

启动后 MCP endpoint 为：

```text
http://127.0.0.1:19829/mcp
```

健康检查 endpoint 为：

```text
http://127.0.0.1:19829/health
```

Web UI 地址为：

```text
http://127.0.0.1:19829/
```

## 配置项

命令行参数优先级高于环境变量。

| 配置 | 命令行参数 | 环境变量 | 默认值 |
| --- | --- | --- | --- |
| 监听地址 | `--host` | `LLM_WIKI_MCP_HOST` | `127.0.0.1` |
| 监听端口 | `--port` | `LLM_WIKI_MCP_PORT` | `19829` |
| 是否要求 MCP token | `--require-token` | `LLM_WIKI_MCP_REQUIRE_TOKEN` | `false` |
| MCP token | `--auth-token` | `LLM_WIKI_MCP_TOKEN` | 无 |
| LLM Wiki API 地址 | `--api-base-url` | `LLM_WIKI_API_BASE_URL` | `http://127.0.0.1:19828` |
| LLM Wiki API token | 无 | `LLM_WIKI_API_TOKEN` | 无 |

这里有两层 token：

- `LLM_WIKI_MCP_TOKEN`：保护本 Streamable HTTP MCP 服务和 Web JSON API，供 MCP 客户端或 Web UI 访问时使用。
- `LLM_WIKI_API_TOKEN`：本服务访问 LLM Wiki 桌面端本地 HTTP API 时使用。

如果启用了 MCP token 校验，但没有配置 `LLM_WIKI_MCP_TOKEN`，服务会启动失败。

## Web UI

启动服务后，浏览器打开：

```text
http://127.0.0.1:19829/
```

Web UI 和 MCP endpoint 运行在同一个 Node 服务内，调用同一组 Web JSON API，并最终转发到 LLM Wiki 桌面端本地 HTTP API。

Web UI 提供以下功能：

- 查看 LLM Wiki 连接状态和项目列表
- 搜索当前项目内容
- 浏览 wiki / sources 文件并读取文件内容
- 查看 Review tab 项
- 查询知识图谱节点和关系
- 触发 Source Watch 重新扫描

鉴权行为和 MCP 服务保持一致：

- 如果启动服务时未启用 `LLM_WIKI_MCP_REQUIRE_TOKEN`，Web UI 不要求 token。
- 如果启动服务时启用了 `LLM_WIKI_MCP_REQUIRE_TOKEN=true`，Web UI 会显示 token 输入框，请填写 `LLM_WIKI_MCP_TOKEN`。
- token 仅保存在当前浏览器会话的 `sessionStorage` 中，请求 Web JSON API 时以 `Authorization: Bearer <token>` header 发送。

## Web JSON API

Web UI 使用以下 JSON API；你也可以直接调用这些接口：

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/api/config` | 返回 Web / MCP 服务是否要求 token |
| `GET` | `/api/status` | 返回 LLM Wiki 健康状态和项目列表 |
| `GET` | `/api/projects` | 列出项目 |
| `GET` | `/api/projects/:projectId/files` | 列出文件，query 支持 `root`、`recursive`、`maxFiles` |
| `GET` | `/api/projects/:projectId/files/content` | 读取文件内容，query 参数 `path` 必填 |
| `GET` | `/api/projects/:projectId/reviews` | 列出 Review 项，query 支持 `status`、`type`、`limit` |
| `POST` | `/api/projects/:projectId/search` | 搜索，JSON body 支持 `query`、`topK`、`includeContent` |
| `GET` | `/api/projects/:projectId/graph` | 查询知识图谱，query 支持 `q`、`nodeType`、`limit` |
| `POST` | `/api/projects/:projectId/sources/rescan` | 触发 Source Watch 重新扫描 |

除 `/api/config` 外，其他 `/api/*` 路由在启用 `LLM_WIKI_MCP_REQUIRE_TOKEN=true` 时都需要 bearer token。

搜索示例：

```bash
curl -sS http://127.0.0.1:19829/api/projects/current/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"agent","topK":5,"includeContent":false}'
```

启用 token 校验时：

```bash
curl -sS http://127.0.0.1:19829/api/projects/current/search \
  -H 'Authorization: Bearer client-secret' \
  -H 'Content-Type: application/json' \
  -d '{"query":"agent","topK":5,"includeContent":false}'
```

## MCP 客户端配置

不同 MCP 客户端的配置字段名可能不同，但核心配置相同：

- transport 类型：Streamable HTTP / HTTP
- URL：`http://127.0.0.1:19829/mcp`
- 如果启用了 token 校验，请发送 HTTP header：`Authorization: Bearer <LLM_WIKI_MCP_TOKEN>`

### 无 MCP token 校验

如果服务启动时没有启用 `LLM_WIKI_MCP_REQUIRE_TOKEN`，客户端只需要配置 URL。

通用 JSON 示例：

```json
{
  "mcpServers": {
    "llm-wiki": {
      "type": "http",
      "url": "http://127.0.0.1:19829/mcp"
    }
  }
}
```

如果你的客户端使用 `transport` 字段，可以写成：

```json
{
  "mcpServers": {
    "llm-wiki": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:19829/mcp"
    }
  }
}
```

### 启用 MCP token 校验

服务端启动示例：

```bash
LLM_WIKI_MCP_REQUIRE_TOKEN=true \
LLM_WIKI_MCP_TOKEN=client-secret \
npm start -- --host 127.0.0.1 --port 19829
```

客户端需要带上 bearer token。

通用 JSON 示例：

```json
{
  "mcpServers": {
    "llm-wiki": {
      "type": "http",
      "url": "http://127.0.0.1:19829/mcp",
      "headers": {
        "Authorization": "Bearer client-secret"
      }
    }
  }
}
```

如果你的客户端将 headers 放在 transport 配置内，可以按客户端要求调整字段位置；关键是最终请求 `/mcp` 时包含：

```http
Authorization: Bearer client-secret
```

### 连接局域网地址

默认只监听本机：

```bash
npm start -- --host 127.0.0.1 --port 19829
```

如果需要让同一局域网内的 MCP 客户端访问，可以显式监听局域网地址或所有地址：

```bash
LLM_WIKI_MCP_REQUIRE_TOKEN=true \
LLM_WIKI_MCP_TOKEN=client-secret \
npm start -- --host 0.0.0.0 --port 19829
```

客户端 URL 改为运行机器的局域网 IP：

```text
http://192.168.1.10:19829/mcp
```

监听局域网或公网地址时，建议始终启用 MCP token 校验。

## 可用工具

- `llm_wiki_status`：检查 LLM Wiki 桌面端本地 API 状态和当前项目
- `llm_wiki_projects`：列出 LLM Wiki 已知项目
- `llm_wiki_files`：列出项目文件
- `llm_wiki_read_file`：读取允许访问的项目文本文件
- `llm_wiki_reviews`：列出 Review tab 项
- `llm_wiki_search`：调用 LLM Wiki 搜索能力
- `llm_wiki_graph`：查询 LLM Wiki 知识图谱
- `llm_wiki_rescan_sources`：触发 Source Watch 重新扫描

## 安全说明

- 默认监听地址是 `127.0.0.1`。
- 监听局域网或 wildcard 地址需要显式配置 `--host` 或 `LLM_WIKI_MCP_HOST`。
- token 推荐通过环境变量传入，避免出现在 shell 历史中。
- 文件读取经过 LLM Wiki 桌面端 API allow-list，不会绕过桌面端权限模型。