feat(website-docs): add quickstart sample data and local MCP demo

Provide demo documents and FAQ import JSON for onboarding tests, plus a
minimal HTTP Streamable MCP server for validating WeKnora MCP integration.

examples/mcp-demo/.gitignore

@@ -0,0 +1 @@
+.venv/

examples/mcp-demo/README.md

@@ -0,0 +1,85 @@
+# WeKnora 本地 MCP Demo
+
+最小外部 MCP 服务，用来测试 WeKnora **作为 MCP 客户端**接入第三方工具。
+
+提供 6 个演示工具：
+
+| 工具 | 作用 |
+| --- | --- |
+| `echo` | 连通性自检 |
+| `add` | 两数相加 |
+| `server_time` | 返回服务器 UTC 时间 |
+| `lookup_policy` | 查询演示政策（保修、报销、POC 等，与 `website-docs/sample-data/` 一致） |
+| `list_team_contacts` | 列出演示项目团队成员 |
+| `send_demo_alert` | 模拟外发通知（适合测工具人工审批） |
+
+## 1. 启动
+
+```bash
+cd examples/mcp-demo
+chmod +x start.sh
+./start.sh
+```
+
+`start.sh` 会自动创建 `.venv` 并安装依赖。默认监听 `http://127.0.0.1:8010/mcp`，鉴权令牌 `weknora-demo-token`。
+
+自定义：
+
+```bash
+export MCP_SERVER_AUTH_TOKEN=my-secret
+export MCP_PORT=9000
+./start.sh
+```
+
+## 2. 自检
+
+另开终端：
+
+```bash
+cd examples/mcp-demo
+source .venv/bin/activate
+python test_tools.py
+```
+
+应列出 6 个工具。
+
+## 3. 接入 WeKnora
+
+1. 打开 **设置 → MCP 服务 → 新建**
+2. 填写：
+
+| 字段 | 值 |
+| --- | --- |
+| 名称 | `本地 MCP Demo` |
+| 传输 | **HTTP Streamable** |
+| URL | `http://127.0.0.1:8010/mcp` |
+| 认证 | **Bearer** |
+| 令牌 | `weknora-demo-token`（与 `MCP_SERVER_AUTH_TOKEN` 一致） |
+
+3. 保存后点 **测试连接**，应发现 6 个工具。
+4. 在 **智能体** 配置里勾选该 MCP 服务（或选全部工具）。
+5. （可选）对 `send_demo_alert` 开启**人工审批**，对话时 Agent 调用前会弹出确认。
+
+## 4. 建议试的问题
+
+在 Agent 对话里问：
+
+- 「调用 MCP 工具查一下智能家居中控保修多久」→ 应触发 `lookup_policy`
+- 「研发部 POC 负责人是谁」→ `lookup_policy` 或 `list_team_contacts`
+- 「现在 MCP Demo 服务器几点」→ `server_time`
+
+若同时导入了 `website-docs/sample-data/` 里的文档，可以对比 **知识库检索答案** 与 **MCP 工具返回** 是否一致。
+
+## 5. 注意事项
+
+- WeKnora UI **不支持 stdio** 传输；必须用 **HTTP Streamable** 或 **SSE**。
+- Demo 只绑定 `127.0.0.1`，不要暴露到公网。
+- `send_demo_alert` 不会真正发送消息，仅返回模拟结果。
+
+## 6. SSE 模式（可选）
+
+```bash
+MCP_TRANSPORT=sse MCP_PORT=8011 ./start.sh
+```
+
+WeKnora 里传输选 **SSE**，URL 填 `http://127.0.0.1:8011/sse`。

examples/mcp-demo/requirements.txt

@@ -0,0 +1,4 @@
+mcp>=2,<3
+starlette>=0.27.0
+uvicorn>=0.24.0
+httpx>=0.27.0

examples/mcp-demo/server.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""
+WeKnora 本地 MCP Demo Server
+
+最小可运行的外部 MCP 服务，用于在 WeKnora「设置 → MCP 服务」里测试客户端接入。
+默认以 Streamable HTTP 监听 http://127.0.0.1:8010/mcp
+
+启动：
+  export MCP_SERVER_AUTH_TOKEN=weknora-demo-token
+  python server.py
+
+WeKnora 配置：
+  传输：HTTP Streamable
+  URL：http://127.0.0.1:8010/mcp
+  认证：Bearer，令牌与 MCP_SERVER_AUTH_TOKEN 一致
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+import secrets
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+from mcp.server import MCPServer
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
+logger = logging.getLogger("mcp-demo")
+
+mcp = MCPServer("weknora-mcp-demo", version="0.1.0")
+
+# 与 website-docs/sample-data/ 配套的演示语料，方便 Agent 调用后对照知识库答案。
+DEMO_POLICIES: dict[str, str] = {
+    "warranty": "智能家居中控 Pro 整机保修 24 个月，电池类配件 12 个月；人为拆解、进水不在保修范围。",
+    "offline_voice": "若语音走云端识别，断外网后仅支持 App 与本地触摸屏；配置本地语音包后可继续使用基础指令。",
+    "device_limit": "个人版账号最多绑定 3 台中控；企业版按合同授权，默认 50 台。",
+    "travel_hotel_tier1": "一线城市（北上广深）出差住宿报销上限 600 元/晚（含税）。",
+    "travel_meal": "出差期间餐饮费不单独报销；一线城市差旅补贴 150 元/天。",
+    "poc_owner": "售后知识库 POC 技术负责人是研发部张明，产品对接人是李薇，测试负责人是赵磊。",
+    "poc_deadline": "售后知识库 POC 目标 2024-03-01 前完成内网演示。",
+    "matter_cert": "固件 3.5 计划在 2024 年 3 月底前发布灰度，完成 Matter 1.2 认证。",
+}
+
+DEMO_CONTACTS: list[dict[str, str]] = [
+    {"name": "陈浩", "role": "产品总监", "department": "产品部"},
+    {"name": "张明", "role": "知识库与 AI 模块负责人", "department": "研发部"},
+    {"name": "李薇", "role": "产品运营", "department": "产品部"},
+    {"name": "王雪", "role": "交互设计负责人", "department": "设计部"},
+    {"name": "赵磊", "role": "测试经理", "department": "测试部"},
+]
+
+
+def network_transport_auth_token() -> str:
+    return os.getenv("MCP_SERVER_AUTH_TOKEN", "").strip()
+
+
+def require_network_transport_auth(transport: str) -> str:
+    token = network_transport_auth_token()
+    if transport in ("sse", "http") and not token:
+        logger.error(
+            "MCP_SERVER_AUTH_TOKEN is required for %s transport. "
+            "Example: export MCP_SERVER_AUTH_TOKEN=weknora-demo-token",
+            transport,
+        )
+        sys.exit(1)
+    return token
+
+
+class MCPAuthMiddleware:
+    """SSE / HTTP 传输的 Bearer 鉴权中间件。"""
+
+    def __init__(self, app, token: str):
+        self.app = app
+        self.token = token
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = {
+            k.decode("latin-1").lower(): v.decode("latin-1")
+            for k, v in scope.get("headers", [])
+        }
+        provided = ""
+        auth = headers.get("authorization", "")
+        if auth.lower().startswith("bearer "):
+            provided = auth[7:].strip()
+        elif "x-mcp-auth-token" in headers:
+            provided = headers["x-mcp-auth-token"]
+
+        if not provided or not secrets.compare_digest(provided, self.token):
+            body = b'{"error":"unauthorized"}'
+            await send(
+                {
+                    "type": "http.response.start",
+                    "status": 401,
+                    "headers": [[b"content-type", b"application/json"]],
+                }
+            )
+            await send({"type": "http.response.body", "body": body})
+            return
+
+        await self.app(scope, receive, send)
+
+
+@mcp.tool()
+def echo(message: str) -> dict[str, Any]:
+    """回显一条消息，用于验证 MCP 连通性。"""
+    return {"echo": message}
+
+
+@mcp.tool()
+def add(a: float, b: float) -> dict[str, Any]:
+    """计算两个数字之和。"""
+    return {"a": a, "b": b, "sum": a + b}
+
+
+@mcp.tool()
+def server_time() -> dict[str, str]:
+    """返回 MCP Demo 服务器当前 UTC 时间。"""
+    now = datetime.now(timezone.utc)
+    return {
+        "iso": now.isoformat(),
+        "unix": str(int(now.timestamp())),
+    }
+
+
+@mcp.tool()
+def lookup_policy(topic: str) -> dict[str, Any]:
+    """查询演示政策/项目信息。topic 可用 warranty/offline_voice/device_limit/travel_hotel_tier1/travel_meal/poc_owner/poc_deadline/matter_cert，或中文关键词如「保修」「报销」「POC」。"""
+    key = topic.strip().lower().replace(" ", "_")
+    aliases = {
+        "保修": "warranty",
+        "质保": "warranty",
+        "离线": "offline_voice",
+        "语音": "offline_voice",
+        "设备数": "device_limit",
+        "住宿": "travel_hotel_tier1",
+        "报销": "travel_hotel_tier1",
+        "餐饮": "travel_meal",
+        "补贴": "travel_meal",
+        "负责人": "poc_owner",
+        "张明": "poc_owner",
+        "poc": "poc_owner",
+        "验收": "poc_deadline",
+        "matter": "matter_cert",
+        "认证": "matter_cert",
+    }
+    for alias, mapped in aliases.items():
+        if alias in topic:
+            key = mapped
+            break
+
+    if key in DEMO_POLICIES:
+        return {"topic": key, "answer": DEMO_POLICIES[key], "source": "mcp-demo/static"}
+
+    matches = {
+        k: v
+        for k, v in DEMO_POLICIES.items()
+        if key in k or any(ch in k for ch in key if len(key) >= 2)
+    }
+    if len(matches) == 1:
+        only_key = next(iter(matches))
+        return {"topic": only_key, "answer": matches[only_key], "source": "mcp-demo/static"}
+
+    return {
+        "topic": topic,
+        "available_topics": sorted(DEMO_POLICIES.keys()),
+        "hint": "传入 topic 为上述键名，或中文关键词如「保修」「报销」「POC」。",
+    }
+
+
+@mcp.tool()
+def list_team_contacts(department: str = "") -> dict[str, Any]:
+    """列出演示项目团队成员；可按部门名过滤（产品部 / 研发部 / 设计部 / 测试部）。"""
+    rows = DEMO_CONTACTS
+    if department.strip():
+        needle = department.strip()
+        rows = [c for c in rows if needle in c["department"]]
+    return {"count": len(rows), "contacts": rows}
+
+
+@mcp.tool()
+def send_demo_alert(channel: str, message: str) -> dict[str, Any]:
+    """模拟向外部渠道发送通知（演示用，不会真正外发）。
+
+    适合在 WeKnora 里测试 MCP 工具人工审批：建议把此工具标记为需要审批。
+    """
+    return {
+        "ok": True,
+        "simulated": True,
+        "channel": channel,
+        "message": message,
+        "sent_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+async def run_http(host: str, port: int) -> None:
+    auth_token = require_network_transport_auth("http")
+    try:
+        import uvicorn
+    except ImportError as e:
+        raise ImportError("HTTP transport requires: pip install starlette uvicorn") from e
+
+    starlette_app = MCPAuthMiddleware(
+        mcp.streamable_http_app(host=host, stateless_http=True),
+        auth_token,
+    )
+    logger.info("Streamable HTTP MCP demo listening on http://%s:%d/mcp", host, port)
+    config = uvicorn.Config(starlette_app, host=host, port=port, log_level="info")
+    server = uvicorn.Server(config)
+    await server.serve()
+
+
+async def run_sse(host: str, port: int) -> None:
+    auth_token = require_network_transport_auth("sse")
+    try:
+        import uvicorn
+    except ImportError as e:
+        raise ImportError("SSE transport requires: pip install starlette uvicorn") from e
+
+    starlette_app = MCPAuthMiddleware(
+        mcp.sse_app(host=host, message_path="/sse/messages/"),
+        auth_token,
+    )
+    logger.info("SSE MCP demo listening on http://%s:%d/sse", host, port)
+    config = uvicorn.Config(starlette_app, host=host, port=port, log_level="info")
+    server = uvicorn.Server(config)
+    await server.serve()
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="WeKnora local MCP demo server")
+    parser.add_argument(
+        "--transport",
+        choices=["http", "sse"],
+        default=os.getenv("MCP_TRANSPORT", "http"),
+        help="Network transport (default: http / Streamable HTTP)",
+    )
+    parser.add_argument("--host", default=os.getenv("MCP_HOST", "127.0.0.1"))
+    parser.add_argument("--port", type=int, default=int(os.getenv("MCP_PORT", "8010")))
+    return parser.parse_args()
+
+
+async def main() -> None:
+    args = parse_args()
+    if args.transport == "http":
+        await run_http(args.host, args.port)
+    else:
+        await run_sse(args.host, args.port)
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        logger.info("stopped")

examples/mcp-demo/start.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+export MCP_SERVER_AUTH_TOKEN="${MCP_SERVER_AUTH_TOKEN:-weknora-demo-token}"
+export MCP_HOST="${MCP_HOST:-127.0.0.1}"
+export MCP_PORT="${MCP_PORT:-8010}"
+export MCP_TRANSPORT="${MCP_TRANSPORT:-http}"
+
+VENV_DIR=".venv"
+if [[ ! -d "$VENV_DIR" ]]; then
+  echo "Creating virtualenv in $VENV_DIR ..."
+  python3 -m venv "$VENV_DIR"
+fi
+# shellcheck disable=SC1091
+source "$VENV_DIR/bin/activate"
+
+if ! python -c "import mcp" 2>/dev/null; then
+  echo "Installing dependencies..."
+  pip install -r requirements.txt
+fi
+
+echo "MCP Demo"
+echo "  transport : ${MCP_TRANSPORT}"
+echo "  endpoint  : http://${MCP_HOST}:${MCP_PORT}/$([ "$MCP_TRANSPORT" = http ] && echo mcp || echo sse)"
+echo "  auth token: ${MCP_SERVER_AUTH_TOKEN}"
+echo
+echo "WeKnora UI → 设置 → MCP 服务 → 新建"
+echo "  传输: HTTP Streamable"
+echo "  URL : http://${MCP_HOST}:${MCP_PORT}/mcp"
+echo "  认证: Bearer / ${MCP_SERVER_AUTH_TOKEN}"
+echo
+
+exec python server.py --transport "$MCP_TRANSPORT" --host "$MCP_HOST" --port "$MCP_PORT"

examples/mcp-demo/test_tools.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""列出 MCP Demo 暴露的工具（需先启动 server.py）。"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+import httpx
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+
+async def main() -> int:
+    base = os.getenv("MCP_DEMO_URL", "http://127.0.0.1:8010/mcp")
+    token = os.getenv("MCP_SERVER_AUTH_TOKEN", "weknora-demo-token")
+
+    async with httpx.AsyncClient(
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=30.0,
+    ) as http_client:
+        async with streamable_http_client(base, http_client=http_client) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                tools = await session.list_tools()
+                print(f"connected: {base}")
+                print(f"tools ({len(tools.tools)}):")
+                for tool in tools.tools:
+                    print(f"  - {tool.name}: {tool.description}")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(asyncio.run(main()))
+    except Exception as exc:  # noqa: BLE001
+        print(f"failed: {exc}", file=sys.stderr)
+        print("start the server first: ./start.sh", file=sys.stderr)
+        raise SystemExit(1) from exc