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

安装与构建

npm install
npm run build

启动服务

不启用 MCP 层 token 校验：

npm start -- --host 127.0.0.1 --port 19829

启用 MCP 层 token 校验：

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 为：

http://127.0.0.1:19829/mcp

健康检查 endpoint 为：

http://127.0.0.1:19829/health

Web UI 地址为：

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

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

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。

搜索示例：

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 校验时：

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 示例：

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

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

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

启用 MCP token 校验

服务端启动示例：

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

客户端需要带上 bearer token。

通用 JSON 示例：

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

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

Authorization: Bearer client-secret

连接局域网地址

默认只监听本机：

npm start -- --host 127.0.0.1 --port 19829

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

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

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

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，不会绕过桌面端权限模型。