WeKnora/mcp-server/test_stdio_stdout.py

54 lines
1.6 KiB
Python
Raw Normal View History

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
#!/usr/bin/env python3
"""Regression: MCP stdio entry scripts must not write diagnostics to stdout."""
import subprocess
import sys
import unittest
from pathlib import Path
MCP_SERVER_DIR = Path(__file__).resolve().parent
class StdioStdoutPurityTest(unittest.TestCase):
def test_main_check_only_keeps_stdout_empty(self):
result = subprocess.run(
[sys.executable, "main.py", "--check-only"],
capture_output=True,
timeout=10,
cwd=MCP_SERVER_DIR,
)
self.assertEqual(result.returncode, 0)
self.assertEqual(
result.stdout,
b"",
f"stdout must stay empty for MCP stdio compatibility, got: {result.stdout!r}",
)
self.assertTrue(
result.stderr,
"environment check output should appear on stderr",
)
def test_run_server_startup_keeps_stdout_empty(self):
proc = subprocess.Popen(
[sys.executable, "run_server.py"],
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
cwd=MCP_SERVER_DIR,
)
try:
stdout, stderr = proc.communicate(timeout=2)
except subprocess.TimeoutExpired:
proc.terminate()
stdout, stderr = proc.communicate(timeout=5)
self.assertEqual(
stdout,
b"",
f"run_server.py must not write to stdout before JSON-RPC, got: {stdout!r}",
)
self.assertTrue(stderr, "startup diagnostics should appear on stderr")
if __name__ == "__main__":
unittest.main()