WeKnora/website-docs
lyingbug 76a19f14c4
feat(mcp): add built-in MCP server with per-workspace endpoints (#3371)
* feat(mcp): add built-in MCP server with per-workspace endpoints

WeKnora previously exposed itself to MCP clients only through the Python
package under mcp-server/, which binds one process to one API key and
therefore to one workspace, and mirrors the REST API tool-for-tool.

This adds a native MCP server surface to the Go backend:

- New mcp_endpoints table (PostgreSQL 000100, SQLite 000020). A workspace
  can publish any number of endpoints, each with its own bearer token
  (SHA-256 stored, rotatable, shown once), knowledge-base allowlist, tool
  allowlist, default agent and per-minute rate limit.
- Management API under /api/v1/mcp-endpoints (Viewer reads, Admin writes,
  API keys need manage_channels) plus a tool catalog endpoint.
- internal/mcpserver hosts one mcp-go Streamable HTTP server in stateless
  mode at /mcp/:endpoint_id. tools/list is filtered per endpoint and
  tools/call re-checks the allowlist, applies rate limiting and touches
  last_used_at. MCPEndpointAuth resolves the token and injects the
  workspace, an mcp_endpoint principal and an API-key style scope derived
  from the endpoint, so existing knowledge-base and capability checks
  apply unchanged.
- Redesigned tool set (12 tools in four groups): retrieval and reading
  reuse the agent's native tools; ask runs the default or a named agent
  synchronously and returns a cited answer with a session_id for
  follow-ups; wiki tools cover search, read and index; write tools are
  off by default. Knowledge bases accept ids or names.
- Frontend: new "MCP Server" integrations tab (tab id mcpserver, to
  avoid clashing with the existing MCP-client settings section) with
  endpoint cards, a create/edit drawer, a one-time token dialog and
  ready-to-paste snippets for Cursor/VS Code/Claude Desktop, Claude Code
  and mcp-remote. Locales updated in all five languages.
- Deployment capability integrations.mcpserver wired on both sides.
- Docs: website-docs MCP page now leads with the built-in server; the
  Python mcp-server README carries a deprecation notice.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(mcp): wire the MCP server into DI/router and tighten authorization

The previous commit lost eight staged files to the repo pre-commit hook,
which resolves ROOT to the main checkout and re-adds the main-checkout
copies of tracked files into the worktree index. This commit restores them
(container providers, RouterParams and route registration, context key,
principal, clone table entry, deployment capability key, SQLite parity
test) and addresses the review findings:

- Knowledge-base scope is authorized, not trusted: endpoint allowlists and
  every tool call resolve each knowledge base through access.ResolveKB for
  the calling principal (ownership or organization share). Foreign IDs are
  rejected on create/update and dropped at call time.
- Write tools mint explicit editor grants via access.KBAccess.WithGrant
  before calling the knowledge service, so add/update/delete go through the
  same RequireKBWrite path as the REST API. add_document also checks the
  grant itself.
- ask no longer accepts agent_id. It runs only the endpoint's configured
  agent; tenant-owned agents and user-facing builtins qualify, internal
  builtins (wiki fixer, skill installer) are refused both on save and at
  call time. Web search is forced off for MCP calls.
- Tool annotations match behaviour: ask is not read-only, add_document is
  a mutation.
- CORS allows MCP-Protocol-Version / Mcp-Session-Id / Last-Event-ID and
  exposes Mcp-Session-Id for browser-based MCP clients.
- Rate limiter runs its local cleanup goroutine; SQLite migration gains the
  deleted_at index for parity with PostgreSQL; non-ASCII endpoint names get
  unique mcpServers keys derived from the endpoint id.
- Swagger annotations on the management handler.
- Tests: KB isolation (service and server), write grants, endpoint-agent
  restriction, tool annotations, and a router test that mounts the public
  /mcp/:endpoint_id surface and checks the deployment capability.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* chore(mcp): renumber migrations after rebase onto main

main took 000100 / 000020 for chunks_index_diet, so the mcp_endpoints
migrations move to 000101 (PostgreSQL) and 000021 (SQLite); the SQLite
parity test and docs follow.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(mcp): run document tools under the knowledge base owner tenant

Shared knowledge bases resolved through access.ResolveKB were only half
usable: documents of an organization-shared knowledge base are stored under
the owner tenant, so the document-level tools that queried by the calling
tenant found nothing, and add_document would have created rows under the
caller's tenant inside someone else's knowledge base.

- knowledgeInScope loads documents tenant-agnostically and then requires
  the document to belong to an allowed knowledge base and to that base's
  tenant.
- scopedKBContext replaces grantContext: it resolves the grant, switches
  the execution tenant to the knowledge base owner (KBAccess.Context) and
  swaps TenantInfo to the owner so storage/model settings resolve there.
  list_documents, read_document and every write tool run under it.
- Locale text and docs no longer claim clients can pass agent_id.
- Go SDK gains MCP endpoint methods (client/mcp_endpoint.go) with docs, and
  the Swagger artifacts are regenerated.
- Tests: shared knowledge base read/write under the owner tenant, spoofed
  document tenant rejected, viewer share cannot write.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* chore(mcp): renumber migrations after rebase onto main

main now carries 000101 / 000021 (knowledge_profiles), so the
mcp_endpoints migrations move to 000102 (PostgreSQL) and 000022 (SQLite);
the SQLite parity test expects version 22 and the docs follow.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* fix(mcp): guard last_used touch without a repository and wrap SDK line

The transport tests build the server without a repository; the background
last_used_at write then dereferenced a nil interface and, on the slower CI
runner, took the test binary down. touchLastUsed now returns early when no
repository is wired, and the tests inject a recording repository and assert
the touch instead. Also wraps a 123-column SDK signature for the client
module's lll check.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-17 22:40:05 +08:00
..
.vitepress feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
01-getting-started feat(knowledge): derive knowledge base descriptions from document profiles (#3370) 2026-09-17 22:21:55 +08:00
02-architecture feat(knowledge): derive knowledge base descriptions from document profiles (#3370) 2026-09-17 22:21:55 +08:00
03-features feat(mcp): add built-in MCP server with per-workspace endpoints (#3371) 2026-09-17 22:40:05 +08:00
04-api feat(knowledge): derive knowledge base descriptions from document profiles (#3370) 2026-09-17 22:21:55 +08:00
05-clients feat(mcp): add built-in MCP server with per-workspace endpoints (#3371) 2026-09-17 22:40:05 +08:00
06-development feat(knowledge): derive knowledge base descriptions from document profiles (#3370) 2026-09-17 22:21:55 +08:00
deploy feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
homepage feat(website): add WeChat and Tencent Cloud usage options (#3314) 2026-09-16 17:55:09 +08:00
public feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
sample-data feat(website-docs): add quickstart sample data and local MCP demo 2026-08-06 19:54:40 +08:00
scripts feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
shared feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
.dockerignore feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
.gitignore feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
.nvmrc feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
Dockerfile feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
README.md feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
VERSION feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
index.md feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
package-lock.json feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00
package.json feat(website): add product homepage and unified docs deployment (#3297) 2026-09-16 11:58:37 +08:00

README.md

WeKnora 官网与文档

website-docs/ 包含官网、文档、共享样式和全部构建部署脚本,可独立复制和构建,不依赖仓库外层文件。官网和文档共用一个域名、一次构建和一份部署产物。

  • /:产品首页。
  • /docs/:直接进入“快速上手”。
  • /docs/…:完整文档,保留分类导航、搜索和侧栏。

顶栏高 64px、横向铺满。两边使用 README 原版商标,共用颜色、字体和深浅色偏好;Logo 在当前标签返回官网。官网和文档各自使用适合当前页面的导航。

发布方式:静态文件 + Nginx

1. 准备部署包

使用 Node.js 24,在仓库的 website-docs/ 目录执行。首次构建或依赖锁文件变更后,先安装依赖:

cd website-docs
npm run setup
npm run build
npm run package:site

build 会编译官网、检查文档链接和 Mermaid、编译文档,并校验合并后的资源路径。全部通过后更新 static-site/;package:site 将其打包到 releases/。

2. 上传并解压

只需把压缩包上传到服务器。服务器不需要 Node.js,也不需要 WeKnora 后端或独立文档服务。

每次发布使用一个新的空目录,避免混入旧站点文件。下面的 20260915-1 是示例发布编号,后续发布换一个编号:

sudo mkdir -p /srv/www/weknora/releases/20260915-1
sudo tar -xzf weknora-site-v0.8.0.tar.gz -C /srv/www/weknora/releases/20260915-1

解压后该目录下应直接有 index.html、docs/、_next/,无需再套一层 static-site/。

3. 配置域名根目录

以 deploy/nginx.conf 为模板添加站点配置,修改:

server_name 你的域名;
root /srv/www/weknora/releases/20260915-1;

如果域名已有 HTTPS 配置,保留原来的证书及监听设置,把模板中的 root、index 和 location 规则合入现有站点配置。域名应指向这台服务器。

必须保留文档的 .html 路由解析规则;不要把所有未知路径回退到官网 index.html。当前构建部署在域名根路径,不支持直接放进 /weknora/ 等子目录。

检查配置后重载:

sudo nginx -t
sudo nginx -s reload

4. 确认上线

访问以下路径:

  • /:官网。
  • /docs/:快速上手。
  • /docs/03-features/23-memory:长期记忆文档,直接打开和刷新均正常。
  • /docs/not-found:返回 404。

再确认搜索、深浅色切换和 Logo 返回官网正常。

后续更新重复构建、打包、上传到新目录,再修改 Nginx root 并重载。需要回滚时,将 root 改回上一发布目录。确认新版本稳定后再清理旧发布目录。

可选:Docker 部署

从干净源码即可构建,无需在宿主机安装 Node.js 或提前生成静态文件。Dockerfile 使用两个阶段:Node.js 24 按两份锁文件安装依赖并构建官网与文档,最终 Nginx 镜像只包含静态产物和服务配置。

在仓库根目录执行:

docker build -t weknora-site:0.8.0 website-docs
docker run -d --name weknora-site --restart unless-stopped -p 8080:80 weknora-site:0.8.0

访问 http://服务器地址:8080/。如使用域名和 HTTPS,让现有反向代理转发到该端口即可。镜像内已经包含官网、文档和 Nginx 路由配置。

也可以只复制 website-docs/ 目录,在该目录执行 docker build -t weknora-site:0.8.0 .。构建上下文必须是 website-docs/,宿主机的依赖、旧构建产物和部署包由 .dockerignore 排除。

从旧文档镜像迁移时,将容器端口映射或反向代理目标端口从 8081 改为 80(宿主机端口可自行选择,例如 -p 8081:80)。域名根路径 / 现在提供官网,/docs/ 提供文档,反向代理需覆盖整个站点并保留请求路径。容器使用 Nginx 官方镜像的默认入口,无需额外的 docker-entrypoint.sh。

构建后可在安装了 Node.js 24 和 Docker 的机器上执行以下检查,无需安装 npm 依赖。检查会临时启动容器并自动清理,验证两站路由、静态资源、404、压缩和响应头:

cd website-docs
npm run test:docker -- weknora-site:0.8.0

本地开发

使用 Node.js 24 LTS(目录内提供 .nvmrc,使用 nvm 时可执行 nvm use)。首次获取源码后安装依赖(分别按文档和官网的锁文件安装):

cd website-docs
npm run setup
npm run build
npm run preview

预览地址:http://127.0.0.1:3000/。修改源码后重新构建并刷新;可用 npm run preview -- --port 8080 指定其他端口。

npm run check
npm run test:integration

集成检查需要安装 Google Chrome,验证主题同步、两边导航、搜索、手机端控件及直达文档路由。可用 SITE_TEST_URL 指定待验证的站点。

开发时可分别使用 npm run dev:homepage(官网)和 npm run dev:docs(文档)获得热更新;完整站内跳转请使用统一构建后的 npm run preview。

npm run build:docs 只编译文档,npm run build:homepage 只编译官网;正式发布使用 npm run build,输出会同时包含两者。VERSION 是这份站点构建使用的发布版本。

工程目录(相对于 website-docs)

  • homepage/:Next.js 官网源码、品牌素材及独立依赖锁文件。
  • 01-getting-started/ 至 06-development/:文档正文,原有路径不变。
  • .vitepress/:文档站配置与主题。
  • public/、sample-data/:文档截图和示例。
  • shared/:品牌变量、顶栏样式及共用图标。
  • scripts/:统一构建、检查、预览和打包。
  • static-site/:唯一的部署目录,由构建生成。
  • deploy/、Dockerfile:Nginx 和 Docker 部署配置。
  • releases/:生成的部署压缩包。

品牌素材来源见 homepage/BRAND-ASSETS.md。产品视频使用 README 中的 GitHub 原始附件,播放需要访问 GitHub;页面、文档和截图随包部署。