2025-10-30 08:00:28 +00:00
|
|
|
# 使用 uv 运行 WeKnora MCP 服务器
|
|
|
|
|
|
|
|
|
|
> 更推荐使用`uv`来运行基于python的MCP服务。
|
fix(mcp-server): route diagnostics to stderr to fix stdio protocol crash (#2371)
* fix(mcp-server): route diagnostics to stderr to fix stdio protocol crash
Entry scripts (run_server.py, main.py, run.py) printed diagnostics to
stdout via bare print(). Under the stdio transport (the default and the
path used by all MCP clients per MCP_CONFIG.md: `uv run run_server.py`),
stdout is the JSON-RPC channel, so the plain-text lines emitted before
the initialize handshake corrupted the protocol stream. Strict MCP clients
(Claude Desktop / Cursor / ZCode / VS Code Copilot) treated this as a
fatal protocol error and reported the server as failed-to-start.
Redirect all diagnostic print() to sys.stderr (per MCP spec, only
JSON-RPC may use stdout). weknora_mcp_server.py already routes through
logging (stderr) and is unchanged.
Verified against a live backend (initialize -> tools/list (28 tools) ->
tools/call list_knowledge_bases); stdout first byte is now '{' with all
diagnostics on stderr.
* chore(mcp-server): publish package name as weknora-mcp
Rename the PyPI distribution name from weknora-mcp-server to weknora-mcp
(tools used: pyproject [project].name + setup.py name). The installed
console-script commands (weknora-mcp-server, weknora-server) and the
Python module (weknora_mcp_server) are unchanged for backward compatibility.
* fix(mcp-server): include upload_paths in wheel + bump to 1.0.1
The 1.0.0 wheel was missing upload_paths.py: it was absent from the
[tool.setuptools] py-modules list (and setup.py py_modules), so setuptools
never packed it. weknora_mcp_server.py line 26 does
`from upload_paths import resolve_upload_file_path, set_active_transport`,
so any path that fully imports the module — i.e. the MCP client initialize
handshake — crashed with ModuleNotFoundError. `--version` survived only
because argparse exits before that import runs.
Fix: add 'upload_paths' to py-modules (pyproject.toml + setup.py) and bump
to 1.0.1 (1.0.0 is immutable on PyPI). Also sync the user-facing version
strings (__version__, server_version, main --version) to 1.0.1.
* ci(mcp-server): add workflow.yml to build & publish to PyPI via OIDC
Adds .github/workflows/workflow.yml adapted from annopick/tuomin's ci.yml:
- test: matrix Python 3.10–3.13 (matches requires-python >=3.10), runs the
flat test_*.py suite in mcp-server/
- build: on mcp-server-v* tags, builds sdist + wheel via uv build, and
guards against the 1.0.0 regression by asserting upload_paths.py is in
the wheel before publishing
- publish: PyPI Trusted Publishing (OIDC, id-token: write) to weknora-mcp,
no API token needed
Publishing is gated on tags named mcp-server-v* to decouple from the Go
release workflow that already targets v* tags.
* fix(mcp-server): route diagnostics to stderr and fix packaging/CI
Prevent MCP stdio startup crashes by sending entry-script diagnostics to
stderr, package upload_paths in the wheel, and add unittest-based CI with
stdout purity regression tests.
---------
Co-authored-by: wizardchen <wizardchen@tencent.com>
2026-07-28 13:23:09 +00:00
|
|
|
>
|
|
|
|
|
> 也可通过 PyPI 安装:`pip install weknora-mcp`(包名 `weknora-mcp`,非 `weknora-mcp-server`)。
|
2025-10-30 08:00:28 +00:00
|
|
|
|
|
|
|
|
## 1. 安装 uv
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
# macOS/Linux
|
|
|
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
|
|
|
|
|
|
# 或使用 Homebrew (macOS)
|
|
|
|
|
brew install uv
|
|
|
|
|
|
|
|
|
|
# Windows
|
|
|
|
|
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## 2. MCP 客户端配置
|
|
|
|
|
|
|
|
|
|
### Claude Desktop 配置
|
|
|
|
|
|
|
|
|
|
在 Claude Desktop 设置中添加:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"mcpServers": {
|
|
|
|
|
"weknora": {
|
|
|
|
|
"args": [
|
|
|
|
|
"--directory",
|
|
|
|
|
"/path/WeKnora/mcp-server",
|
|
|
|
|
"run",
|
|
|
|
|
"run_server.py"
|
|
|
|
|
],
|
|
|
|
|
"command": "uv",
|
|
|
|
|
"env": {
|
|
|
|
|
"WEKNORA_API_KEY": "your_api_key_here",
|
|
|
|
|
"WEKNORA_BASE_URL": "http://localhost:8080/api/v1"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Cursor 配置
|
|
|
|
|
|
|
|
|
|
在 Cursor 中,编辑 MCP 配置文件 (通常在 `~/.cursor/mcp-config.json`):
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"mcpServers": {
|
|
|
|
|
"weknora": {
|
|
|
|
|
"command": "uv",
|
|
|
|
|
"args": [
|
|
|
|
|
"--directory",
|
|
|
|
|
"/path/WeKnora/mcp-server",
|
|
|
|
|
"run",
|
|
|
|
|
"run_server.py"
|
|
|
|
|
],
|
|
|
|
|
"env": {
|
|
|
|
|
"WEKNORA_API_KEY": "your_api_key_here",
|
|
|
|
|
"WEKNORA_BASE_URL": "http://localhost:8080/api/v1"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### KiloCode 配置
|
|
|
|
|
|
|
|
|
|
对于 KiloCode 或其他支持 MCP 的编辑器,配置如下:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"mcpServers": {
|
|
|
|
|
"weknora": {
|
|
|
|
|
"command": "uv",
|
|
|
|
|
"args": [
|
|
|
|
|
"--directory",
|
|
|
|
|
"/path/WeKnora/mcp-server",
|
|
|
|
|
"run",
|
|
|
|
|
"run_server.py"
|
|
|
|
|
],
|
|
|
|
|
"env": {
|
|
|
|
|
"WEKNORA_API_KEY": "your_api_key_here",
|
|
|
|
|
"WEKNORA_BASE_URL": "http://localhost:8080/api/v1"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### 其他 MCP 客户端
|
|
|
|
|
|
|
|
|
|
对于一般 MCP 客户端配置:
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"mcpServers": {
|
|
|
|
|
"weknora": {
|
|
|
|
|
"command": "uv",
|
|
|
|
|
"args": [
|
|
|
|
|
"--directory",
|
|
|
|
|
"/path/WeKnora/mcp-server",
|
|
|
|
|
"run",
|
|
|
|
|
"run_server.py"
|
|
|
|
|
],
|
|
|
|
|
"env": {
|
|
|
|
|
"WEKNORA_API_KEY": "your_api_key_here",
|
|
|
|
|
"WEKNORA_BASE_URL": "http://localhost:8080/api/v1"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|