WeKnora/mcp-server
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
..
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 feat(mcp): add built-in MCP server with per-workspace endpoints (#3371) 2026-09-17 22:40:05 +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_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 feat(mcp): pass fileName and folder filters to knowledge APIs 2026-09-14 22:20:25 +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 - 发送聊天消息

块管理

  • 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.