WeKnora/mcp-server
KennySimpson 69a7fd9931
fix(mcp): close legacy chat responses on HTTP errors (#3930)
2026-10-08 01:25:18 +08:00
..
tests fix(mcp-server): normalize shared KB list shape for name resolution 2026-08-03 15:50:33 +08:00
.gitignore feat: 添加了配套mcp服务器包 2025-09-08 19:43:45 +08:00
CHANGELOG.md feat(mcp): add manual knowledge update tool 2026-09-07 14:40:33 +08:00
Dockerfile fix(security): close remaining GHSA gaps from security triage 2026-07-02 15:03:53 +08:00
EXAMPLES.md feat(mcp): add manual knowledge update tool 2026-09-07 14:40:33 +08:00
INSTALL.md fix(mcp-server): adopt official PyPI package tencent-weknora-mcp [v1.1.1] 2026-07-30 15:52:28 +08:00
LICENSE feat: 添加了配套mcp服务器包 2025-09-08 19:43:45 +08:00
MANIFEST.in feat: 添加了配套mcp服务器包 2025-09-08 19:43:45 +08:00
MCP_CONFIG.md fix(mcp-server): adopt official PyPI package tencent-weknora-mcp [v1.1.1] 2026-07-30 15:52:28 +08:00
PROJECT_SUMMARY.md fix(mcp-server): adopt official PyPI package tencent-weknora-mcp [v1.1.1] 2026-07-30 15:52:28 +08:00
README.md fix(mcp): assemble multiline SSE events before parsing 2026-09-22 20:09:02 +08:00
__init__.py fix(mcp-server): adopt official PyPI package tencent-weknora-mcp [v1.1.1] 2026-07-30 15:52:28 +08:00
check_imports.py fix(mcp-server): migrate to MCPServer high-level API (mcp 2.x) [v1.1.0] 2026-07-30 15:52:28 +08:00
main.py fix(mcp-server): adopt official PyPI package tencent-weknora-mcp [v1.1.1] 2026-07-30 15:52:28 +08:00
pyproject.toml fix(mcp-server): adopt official PyPI package tencent-weknora-mcp [v1.1.1] 2026-07-30 15:52:28 +08:00
requirements.txt fix(mcp-server): migrate to MCPServer high-level API (mcp 2.x) [v1.1.0] 2026-07-30 15:52:28 +08:00
run.py fix(mcp-server): route diagnostics to stderr to fix stdio protocol crash (#2371) 2026-07-28 21:23:09 +08:00
run_server.py fix(mcp-server): route diagnostics to stderr to fix stdio protocol crash (#2371) 2026-07-28 21:23:09 +08:00
setup.py fix(mcp-server): adopt official PyPI package tencent-weknora-mcp [v1.1.1] 2026-07-30 15:52:28 +08:00
test_chat_sse.py fix(mcp): close legacy chat responses on HTTP errors (#3930) 2026-10-08 01:25:18 +08:00
test_create_knowledge_from_text.py feat(mcp-server): add create_knowledge_from_text tool 2026-08-05 19:25:25 +08:00
test_file_name_folder_passthrough.py feat(mcp): pass fileName and folder filters to knowledge APIs 2026-09-14 22:20:25 +08:00
test_file_path_security.py fix: align client sessions and integration request handling (#3305) 2026-09-16 16:20:57 +08:00
test_mcp_transports.py feat(mcp): add manual knowledge update tool 2026-09-07 14:40:33 +08:00
test_module.py fix(mcp-server): adopt official PyPI package tencent-weknora-mcp [v1.1.1] 2026-07-30 15:52:28 +08:00
test_stdio_stdout.py fix(mcp-server): route diagnostics to stderr to fix stdio protocol crash (#2371) 2026-07-28 21:23:09 +08:00
test_update_knowledge_from_text.py feat(mcp): add manual knowledge update tool 2026-09-07 14:40:33 +08:00
upload_paths.py fix: align client sessions and integration request handling (#3305) 2026-09-16 16:20:57 +08:00
uv.lock fix(mcp-server): adopt official PyPI package tencent-weknora-mcp [v1.1.1] 2026-07-30 15:52:28 +08:00
weknora_mcp_server.py fix(mcp): close legacy chat responses on HTTP errors (#3930) 2026-10-08 01:25:18 +08:00

README.md

WeKnora MCP Server

⚠️ 已弃用(Deprecated)

WeKnora 现已内置 MCP Server:在「设置 → 发布与集成 → MCP Server」中为空间创建端点即可,支持多个端点、按端点选择知识库范围和工具,客户端通过 Streamable HTTP 直接连接 /mcp/<endpoint_id>,无需再部署本目录的 Python 进程。本目录仅为兼容旧部署保留,后续版本将移除。

WeKnora now ships a built-in MCP server: create endpoints under "Settings → Publish & Integrations → MCP Server", each with its own token, knowledge-base scope and tool list, and connect clients to /mcp/<endpoint_id> over Streamable HTTP. This Python package is kept only for existing deployments and will be removed in a future release.

这是一个 Model Context Protocol (MCP) 服务器,提供对 WeKnora 知识管理 API 的访问。

快速开始

推荐直接参考 MCP配置说明,无需进行以下操作。

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。

开发模式安装

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

功能特性

该 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 - 从文本创建知识
  • update_knowledge_from_text - 更新手工 Markdown 知识,可重新索引或保存为草稿
  • list_knowledge - 列出知识
  • get_knowledge - 获取知识详情
  • delete_knowledge - 删除知识

模型管理

  • create_model - 创建模型
  • list_models - 列出模型
  • get_model - 获取模型详情

会话管理

  • create_session - 创建聊天会话
  • get_session - 获取会话详情
  • list_sessions - 列出会话
  • delete_session - 删除会话

聊天功能

  • chat - 发送聊天消息
  • agent_chat - 调用智能体完成多步检索与工具调用

两种聊天工具均按 SSE 空行边界组装事件,支持一个事件包含多行 data:。 连接结束时尚未遇到空行的事件会被丢弃;单个事件的数据缓冲上限为 8 MiB, 超过上限会返回错误并关闭响应连接。

块管理

  • list_chunks - 列出知识块
  • delete_chunk - 删除知识块

故障排除

如果遇到导入错误,请确保:

  1. 已安装所有必需的依赖包
  2. Python 版本兼容(推荐 3.10+)
  3. 没有文件名冲突(避免使用 mcp.py 作为文件名)

调用效果

118d078426f42f3d4983c13386085d7f

Local upload directory boundary

All transports, including stdio, restrict local file uploads to the working directory by default. Set MCP_ALLOWED_UPLOAD_DIRS to a comma-separated list of trusted absolute directories when additional roots are needed. Starting in a filesystem root requires an explicit directory configuration. Paths and symbolic links resolving outside the selected roots are rejected.