WeKnora MCP Dispatch

这是面向 WeKnora v0.7.2 的多用户 MCP 网关，基于官方 MCP Server 1.1.1 （MCP Python SDK 2.x 高层 API）改造。一个 Streamable HTTP 服务实例可以接收 多个客户端请求，并以每个客户端提交的 WeKnora API Key 决定其可访问的空间和知识库。

定制能力

• MCP_AUTH_MODE=weknora_api_key：将 Bearer Token 作为 WeKnora API Key 验证。

• API Key 仅绑定到当前 MCP 请求上下文，异步任务和同步工具工作线程均保持租户隔离。

• 动态 Key 模式不会回退到服务端静态 WEKNORA_API_KEY，上下文丢失时失败关闭。

• 验证缓存只保存 SHA-256 指纹；缓存容量、TTL 和验证并发均有上限。

• MCP_READ_ONLY=true：从 MCP 2.x 工具注册表移除写入、会话和聊天工具。

• 保留上游 shared_secret 和 stdio 模式，便于兼容原有部署。

请求链路：

MCP client
  ├─ 可选：外层网关鉴权请求头
  └─ Authorization: Bearer <WeKnora API Key>
          ↓
WeKnora MCP Dispatch
  ├─ GET /knowledge-bases 验证 Key
  ├─ 绑定当前请求身份
  └─ X-API-Key 转发至 WeKnora API

Related MCP server: mcp-streamable-http-bridge

生产 Docker 配置

使用本仓库构建镜像，并参考 production.request-scoped.override.yml 覆盖 WeKnora 官方 Compose 的 mcp 服务。请求级模式下应保持 WEKNORA_API_KEY 和 MCP_SERVER_AUTH_TOKEN 为空。

docker build -t local/weknora-mcp-dispatch:v0.7.2 .

关键环境变量：

WorkBuddy 配置示例

写入用户级 ~/.workbuddy/mcp.json 或项目级 .workbuddy/mcp.json：

{
  "mcpServers": {
    "weknora": {
      "type": "http",
      "url": "https://kb.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${WEKNORA_SPACE_API_KEY}",
        "CF-Access-Client-Id": "${CF_ACCESS_CLIENT_ID}",
        "CF-Access-Client-Secret": "${CF_ACCESS_CLIENT_SECRET}"
      }
    }
  }
}

如果入口没有 Cloudflare Access，删除两个 CF-Access-* 请求头即可。

Codex 配置示例

在 ~/.codex/config.toml 中加入：

[mcp_servers.weknora]
url = "https://kb.example.com/mcp"
bearer_token_env_var = "WEKNORA_SPACE_API_KEY"
env_http_headers = { "CF-Access-Client-Id" = "CF_ACCESS_CLIENT_ID", "CF-Access-Client-Secret" = "CF_ACCESS_CLIENT_SECRET" }

如果入口没有 Cloudflare Access，删除 env_http_headers。不要把 WeKnora API Key 或外层网关 Secret 明文提交到配置仓库。

快速开始

推荐直接参考 MCP配置说明，无需进行以下操作。 本节沿用上游 stdio/静态 Key 用法；多用户 HTTP 生产部署请使用上面的请求级配置。

1. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

# Linux/macOS
export WEKNORA_BASE_URL="http://localhost:8080/api/v1"
export WEKNORA_API_KEY="your_api_key_here"

# Windows PowerShell
$env:WEKNORA_BASE_URL="http://localhost:8080/api/v1"
$env:WEKNORA_API_KEY="your_api_key_here"

# Windows CMD
set WEKNORA_BASE_URL=http://localhost:8080/api/v1
set WEKNORA_API_KEY=your_api_key_here

3. 运行服务器

推荐方式 - 使用主入口点：

python main.py

其他运行方式：

# 使用原始启动脚本
python run_server.py

# 使用便捷脚本
python run.py

# 直接运行服务器模块
python weknora_mcp_server.py

# 作为 Python 模块运行
python -m weknora_mcp_server

4. 命令行选项

python main.py --help                 # 显示帮助信息
python main.py --check-only           # 仅检查环境配置
python main.py --verbose              # 启用详细日志
python main.py --version              # 显示版本信息

安装为 Python 包

从 PyPI 安装

pip install tencent-weknora-mcp
# 或使用 uvx 直接运行（无需预安装）
uvx --from tencent-weknora-mcp weknora-mcp-server

官方 PyPI 包名为 tencent-weknora-mcp（Tencent/WeKnora 维护，Trusted Publishing 发布）。 旧社区包 weknora-mcp 请不要再使用。 安装后命令行入口仍为 weknora-mcp-server / weknora-server。 官方 PyPI 包不包含本仓库的请求级多用户派发功能；生产部署该功能时应构建本仓库。

开发模式安装

pip install -e .

安装后可以使用命令行工具：

weknora-mcp-server
# 或
weknora-server

生产模式安装

pip install .

构建分发包

# 使用 setuptools
python setup.py sdist bdist_wheel

# 使用现代构建工具
pip install build
python -m build

测试模组

运行测试脚本验证模组是否正常工作：

python test_module.py
pytest -q tests

功能特性

该 MCP 服务器提供以下工具：

空间管理

• create_tenant - 创建新空间

• list_tenants - 列出所有空间

知识库管理

• create_knowledge_base - 创建知识库

• list_knowledge_bases - 列出知识库

• get_knowledge_base - 获取知识库详情

• delete_knowledge_base - 删除知识库

• hybrid_search - 混合搜索

知识管理

• create_knowledge_from_file - 从本地文件创建知识

• create_knowledge_from_url - 从 URL 创建知识

• create_knowledge_from_text - 从文本创建知识

• list_knowledge - 列出知识

• get_knowledge - 获取知识详情

• delete_knowledge - 删除知识

模型管理

• create_model - 创建模型

• list_models - 列出模型

• get_model - 获取模型详情

会话管理

• create_session - 创建聊天会话

• get_session - 获取会话详情

• list_sessions - 列出会话

• delete_session - 删除会话

聊天功能

• chat - 发送聊天消息

块管理

• list_chunks - 列出知识块

• delete_chunk - 删除知识块

故障排除

如果遇到导入错误，请确保：

1. 已安装所有必需的依赖包

2. Python 版本兼容（推荐 3.10+）

3. 没有文件名冲突（避免使用 mcp.py 作为文件名）

调用效果