* 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> |
||
|---|---|---|
| .. | ||
| tests | ||
| .gitignore | ||
| CHANGELOG.md | ||
| Dockerfile | ||
| EXAMPLES.md | ||
| INSTALL.md | ||
| LICENSE | ||
| MANIFEST.in | ||
| MCP_CONFIG.md | ||
| PROJECT_SUMMARY.md | ||
| README.md | ||
| __init__.py | ||
| check_imports.py | ||
| main.py | ||
| pyproject.toml | ||
| requirements.txt | ||
| run.py | ||
| run_server.py | ||
| setup.py | ||
| test_create_knowledge_from_text.py | ||
| test_file_name_folder_passthrough.py | ||
| test_file_path_security.py | ||
| test_mcp_transports.py | ||
| test_module.py | ||
| test_stdio_stdout.py | ||
| test_update_knowledge_from_text.py | ||
| upload_paths.py | ||
| uv.lock | ||
| weknora_mcp_server.py | ||
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- 删除知识块
故障排除
如果遇到导入错误,请确保:
- 已安装所有必需的依赖包
- Python 版本兼容(推荐 3.10+)
- 没有文件名冲突(避免使用
mcp.py作为文件名)
调用效果
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.