diff --git a/.github/workflows/frontend.yml b/.github/workflows/frontend.yml index 0b5eb594..51b62e42 100644 --- a/.github/workflows/frontend.yml +++ b/.github/workflows/frontend.yml @@ -6,11 +6,13 @@ on: paths: - "frontend/**" - "scripts/build_frontend_dist.sh" + - "scripts/test_embed_nginx.py" - ".github/workflows/frontend.yml" pull_request: paths: - "frontend/**" - "scripts/build_frontend_dist.sh" + - "scripts/test_embed_nginx.py" - ".github/workflows/frontend.yml" workflow_dispatch: @@ -68,3 +70,6 @@ jobs: --build-arg VITE_FRONTEND_COMMIT="${GITHUB_SHA::7}" \ -t weknora-ui:ci \ frontend/ + + - name: Test embed and MCP proxy routes + run: python3 scripts/test_embed_nginx.py weknora-ui:ci diff --git a/frontend/mcpProxy.test.ts b/frontend/mcpProxy.test.ts new file mode 100644 index 00000000..3c2bc742 --- /dev/null +++ b/frontend/mcpProxy.test.ts @@ -0,0 +1,111 @@ +import assert from 'node:assert/strict' +import { once } from 'node:events' +import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises' +import { createServer as createHttpServer } from 'node:http' +import type { AddressInfo } from 'node:net' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import test from 'node:test' +import { createServer, preview } from 'vite' + +for (const mode of ['dev', 'preview'] as const) { + test(`MCP requests and streaming responses pass through Vite ${mode}`, { timeout: 20_000 }, async () => { + let releaseStream: (() => void) | undefined + const upstream = createHttpServer(async (req, res) => { + if (req.headers.authorization !== 'Bearer test-token') { + res.writeHead(401, { 'Content-Type': 'application/json' }).end('{"error":"unauthorized"}') + return + } + res.setHeader('Mcp-Session-Id', 'test-session') + if (req.headers.accept === 'text/event-stream') { + res.writeHead(200, { 'Content-Type': 'text/event-stream' }) + await new Promise((resolve) => { + releaseStream = resolve + res.write('event: message\ndata: first\n\n') + }) + res.end('event: message\ndata: last\n\n') + return + } + let body = '' + for await (const chunk of req) body += chunk + res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify({ + method: req.method, path: req.url, body, + session: req.headers['mcp-session-id'], + protocol: req.headers['mcp-protocol-version'], + })) + }) + upstream.listen(0, '127.0.0.1') + await once(upstream, 'listening') + const root = await mkdtemp(join(tmpdir(), 'weknora-mcp-proxy-')) + const previousTarget = process.env.VITE_DEV_PROXY_TARGET + process.env.VITE_DEV_PROXY_TARGET = `http://127.0.0.1:${(upstream.address() as AddressInfo).port}` + let closeGateway: (() => Promise) | undefined + try { + await mkdir(join(root, 'dist')) + await writeFile(join(root, 'index.html'), 'main SPA') + await writeFile(join(root, 'dist/index.html'), 'main SPA') + const config = { + configFile: fileURLToPath(new URL('./vite.config.ts', import.meta.url)), + root, + logLevel: 'silent' as const, + } + let port: number + if (mode === 'dev') { + const gateway = await createServer({ + ...config, + server: { host: '127.0.0.1', port: 0, watch: null }, + optimizeDeps: { noDiscovery: true, include: [] }, + }) + closeGateway = () => gateway.close() + await gateway.listen() + port = (gateway.httpServer!.address() as AddressInfo).port + } else { + const gateway = await preview({ ...config, preview: { host: '127.0.0.1', port: 0 } }) + closeGateway = () => new Promise((resolve, reject) => { + gateway.httpServer.close((error) => error ? reject(error) : resolve()) + gateway.httpServer.closeAllConnections() + }) + port = (gateway.httpServer.address() as AddressInfo).port + } + const url = `http://127.0.0.1:${port}/mcp/test-endpoint?probe=1` + const headers = { + Authorization: 'Bearer test-token', + 'Mcp-Session-Id': 'test-session', + 'MCP-Protocol-Version': '2025-03-26', + 'Content-Type': 'application/json', + } + for (const method of ['POST', 'GET', 'DELETE']) { + const body = method === 'POST' ? '{"jsonrpc":"2.0","id":1,"method":"initialize"}' : undefined + const response = await fetch(url, { method, headers, body, signal: AbortSignal.timeout(5000) }) + assert.equal(response.status, 200) + assert.equal(response.headers.get('Mcp-Session-Id'), 'test-session') + assert.deepEqual(await response.json(), { + method, path: '/mcp/test-endpoint?probe=1', body: body ?? '', + session: 'test-session', protocol: '2025-03-26', + }) + } + const unauthorized = await fetch(url, { signal: AbortSignal.timeout(5000) }) + assert.equal(unauthorized.status, 401) + assert.deepEqual(await unauthorized.json(), { error: 'unauthorized' }) + const response = await fetch(url, { + headers: { ...headers, Accept: 'text/event-stream' }, signal: AbortSignal.timeout(5000), + }) + assert.equal(response.headers.get('Content-Type'), 'text/event-stream') + const reader = response.body!.getReader() + // The backend cannot finish until the first event reaches the client. + assert.equal(new TextDecoder().decode((await reader.read()).value), 'event: message\ndata: first\n\n') + releaseStream!() + assert.equal(new TextDecoder().decode((await reader.read()).value), 'event: message\ndata: last\n\n') + assert.equal((await reader.read()).done, true) + } finally { + releaseStream?.() + await closeGateway?.() + upstream.closeAllConnections() + await new Promise((resolve) => upstream.close(() => resolve())) + if (previousTarget === undefined) delete process.env.VITE_DEV_PROXY_TARGET + else process.env.VITE_DEV_PROXY_TARGET = previousTarget + await rm(root, { recursive: true, force: true }) + } + }) +} diff --git a/frontend/nginx-api-proxy.conf b/frontend/nginx-api-proxy.conf index 394bf737..a27fa6b3 100644 --- a/frontend/nginx-api-proxy.conf +++ b/frontend/nginx-api-proxy.conf @@ -1,10 +1,8 @@ -# Shared backend proxy settings for the /api/ locations. +# Shared backend proxy settings for the /api/ and /mcp/ locations. # -# Two locations proxy to the backend — the general one and the skill-upload one -# that raises client_max_body_size — and they must behave identically in every -# other respect, so the settings live here instead of being copied. Only -# proxy_pass stays in each location, since a regex location cannot carry a URI -# in it. +# The API, skill-upload and MCP locations share headers and streaming behavior. +# Only proxy_pass stays in each location, since a regex location cannot carry +# a URI in it. # # This file is copied verbatim, not run through envsubst, so $host and friends # survive as nginx variables. diff --git a/frontend/nginx.conf b/frontend/nginx.conf index a0c20134..4de1f597 100644 --- a/frontend/nginx.conf +++ b/frontend/nginx.conf @@ -192,6 +192,13 @@ server { include /etc/nginx/api-proxy.conf; } + # Public Streamable HTTP MCP endpoints use their own bearer-token auth. + # Preserve /mcp/ and the same streaming settings as the API. + location ^~ /mcp/ { + proxy_pass ${APP_SCHEME}://${APP_HOST}:${APP_PORT}; + include /etc/nginx/api-proxy.conf; + } + # API请求代理到后端服务 # APP_SCHEME 默认 http,远程 HTTPS 后端可设为 https location /api/ { diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts index f7a90799..1b6369f8 100644 --- a/frontend/vite.config.ts +++ b/frontend/vite.config.ts @@ -132,6 +132,14 @@ export default defineConfig({ host: true, // 代理配置,用于开发环境 proxy: { + '/mcp/': { + target: DEV_PROXY_TARGET, + changeOrigin: true, + secure: false, + // Streamable HTTP may keep an SSE response open for long-running tools. + timeout: 3_600_000, + proxyTimeout: 3_600_000, + }, '/api': { target: DEV_PROXY_TARGET, changeOrigin: true, @@ -158,6 +166,13 @@ export default defineConfig({ port: 4173, host: true, proxy: { + '/mcp/': { + target: DEV_PROXY_TARGET, + changeOrigin: true, + secure: false, + timeout: 3_600_000, + proxyTimeout: 3_600_000, + }, '/api': { target: DEV_PROXY_TARGET, changeOrigin: true, diff --git a/scripts/test_embed_nginx.py b/scripts/test_embed_nginx.py index efa2b364..eff2ada6 100644 --- a/scripts/test_embed_nginx.py +++ b/scripts/test_embed_nginx.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Exercise the production embed Nginx locations with a policy backend fixture. +"""Exercise production embed and MCP Nginx locations with backend fixtures. Requires Docker. Run: python3 scripts/test_embed_nginx.py [nginx-or-ui-image] """ @@ -52,6 +52,16 @@ def check(): return 204; } location /api/ { return 200 "$http_host"; } + location /mcp/ { + default_type application/json; + if ($http_authorization != "Bearer test-token") { return 401; } + add_header Mcp-Session-Id "test-session"; + return 200 '{"method":"$request_method","path":"$request_uri","host":"$http_host","session":"$http_mcp_session_id","protocol":"$http_mcp_protocol_version"}'; + } + location = /mcp/stream { + default_type text/event-stream; + return 200 "event: message\\ndata: test-event\\n\\n"; + } } """ (work / "nginx.conf").write_text( @@ -68,8 +78,8 @@ def check(): port = info["NetworkSettings"]["Ports"]["80/tcp"][0]["HostPort"] base = f"http://127.0.0.1:{port}" - def request(path, method="GET"): - req = urllib.request.Request(base + path, method=method) + def request(path, method="GET", headers=None): + req = urllib.request.Request(base + path, method=method, headers=headers or {}) try: return urllib.request.urlopen(req, timeout=3) except urllib.error.HTTPError as error: @@ -100,7 +110,25 @@ def check(): assert b"embed entry" not in response.read() with request("/api/probe") as response: assert response.read().decode() == f"127.0.0.1:{port}", "proxy lost public port" - print("Embed Nginx integration checks passed") + for method in ("POST", "GET", "DELETE"): + with request("/mcp/test-endpoint?probe=1", method, { + "Authorization": "Bearer test-token", + "Mcp-Session-Id": "test-session", + "MCP-Protocol-Version": "2025-03-26", + }) as response: + assert response.status == 200, (method, response.status) + assert response.headers["Mcp-Session-Id"] == "test-session" + assert json.load(response) == { + "method": method, "path": "/mcp/test-endpoint?probe=1", + "host": f"127.0.0.1:{port}", "session": "test-session", + "protocol": "2025-03-26", + } + with request("/mcp/test-endpoint") as response: + assert response.status == 401, response.status + with request("/mcp/stream") as response: + assert response.headers["Content-Type"] == "text/event-stream" + assert response.read() == b"event: message\ndata: test-event\n\n" + print("Embed and MCP Nginx integration checks passed") except Exception: print(docker("logs", cid), file=sys.stderr) raise diff --git a/website-docs/03-features/08-mcp.md b/website-docs/03-features/08-mcp.md index db5fff2f..88b21c39 100644 --- a/website-docs/03-features/08-mcp.md +++ b/website-docs/03-features/08-mcp.md @@ -28,6 +28,8 @@ OAuth 服务按调用者分别授权。工具需要审批时,在对话中检 在「设置 → 发布与集成 → MCP Server」新建端点:填写名称、选择可访问的知识库(留空为全部)、勾选要暴露的工具,需要问答时再指定默认 Agent。创建后会一次性展示令牌和地址 `/mcp/`,页面同时给出 Cursor / VS Code / Claude Desktop 的 `mcpServers` 配置、Claude Code 的一行命令,以及仅支持 stdio 的客户端通过 `mcp-remote` 桥接的写法。 +使用自定义反向代理时,除 `/api/` 外,还需将 `/mcp/` 原路径转发到 WeKnora 后端,保留 `Authorization` 和 MCP 协议头,并关闭响应缓冲、为长连接设置足够的读写超时。仓库自带的 Nginx、Vite 开发及预览配置已包含该代理,可直接使用网站域名连接,无需另行暴露后端 8080 端口。 + 一个空间可以创建多个端点。例如给客服团队一个只开检索和问答、只看两个知识库的端点,给内容团队另一个开了写入工具的端点。令牌可随时轮换,端点可随时停用,删除端点后使用它的客户端立即断开。 端点暴露的工具按四组勾选,默认只开只读工具: