ServerFS v0.17.0

ServerFS v0.17.0

Overview

v0.17.0 adds optional static API Key authentication for remote Streamable HTTP while preserving OAuth 2.1, existing workdir authorization, and native Windows/macOS stdio. The feature is disabled by default, so existing v0.16.0 deployments are unchanged unless SERVERFS_HTTP_API_KEY is configured.

Highlights

• Optional SERVERFS_HTTP_API_KEY; empty or unset means disabled.
• Recommended Authorization: Bearer <key>, plus compatibility ?key=<key> for clients that require a single MCP URL, including DingTalk-style configuration.
• Missing, wrong, duplicate, empty, or ambiguous credentials fail closed; comparison uses constant-time semantics.
• Built-in OAuth and static API Key are mutually exclusive at startup.
• API Key is a pure HTTP/ASGI ingress boundary, not fake OAuth, and does not expose OAuth discovery metadata.
• The API-Key HTTP runner suppresses Uvicorn access logging so ServerFS itself does not emit a query secret; startup logs expose only the auth mode.
• Real loopback Streamable HTTP E2E covers initialize and tools-list via Bearer and query-key paths.
• English and Simplified Chinese docs and Windows CI coverage updated.

Security and compatibility

• Prefer Bearer headers. Query-string keys can still be captured by reverse proxies, browsers, or external observability infrastructure outside ServerFS; use HTTPS for remote transport.
• The key is one instance-level shared secret, not per-user RBAC. Existing workdir and mutation authorization remain unchanged.
• OAuth remains the identity-aware choice for public or multi-user deployments. The OpenAI Tunnel credential remains a separate secret and is not reused.
• Native stdio behavior is unchanged.

Validation

• Release commit: e63f4c676a88d594d20adafba97b6ef27ca4a012.
• VPS final root suite: 1586 passed / 316 skipped; focused HTTP/API-Key/OAuth matrix: 40 passed.
• Pre-tag exact-commit Container, Windows Native, Windows Agent, macOS Native and Pages gates passed. The first Windows Native attempt had one transient WinError 10053 in API-key loopback E2E; the single permitted rerun passed all steps on unchanged code.
• macOS local: 1414 passed / 370 skipped, plus 104 focused auth tests and stdio/service-manager acceptance.
• Windows local kernel: 48 passed / 0 failed / 3 intentionally ignored manual diagnostic probes.
• Five Compose deployment shapes and 27-page production docs build passed.
• Tag-triggered Container stable image workflow and Windows wheel-release workflow passed.

Windows installation assets (Python >= 3.12; no Rust/MSVC/Docker required)

The three release wheels install into two isolated environments, matching the
frozen ServerFS/Agent-Bridge process boundary (the supervisor selects the Bridge
interpreter through SERVERFS_BRIDGE_PYTHON; the packages never share one dependency
graph):

file	installs into	sha256
serverfs_mcp-0.17.0-py3-none-any.whl	ServerFS env	2ff5a1a3ac78ce0b66ca74e3e71691a2bdef54a84f4e660deda09304077dd61d
serverfs_windows_native-0.17.0-cp312-abi3-win_amd64.whl	ServerFS env	06ebaeb22c76b802cee894dc2f928d987dc5a1c6d3b2e420e0370f109926ea07
serverfs_agent_bridge-0.17.0-py3-none-any.whl	Agent Bridge env	921da704d019f1e041918cd010386d116c323c66eb58d6789d62cf739c3f14cc

ServerFS environment (product + native kernel):

uv venv --python 3.12 .venv-serverfs
uv pip install --python .venv-serverfs/Scripts/python.exe https://github.com/NTLx/ServerFS_MCP/releases/download/v0.17.0/serverfs_mcp-0.17.0-py3-none-any.whl https://github.com/NTLx/ServerFS_MCP/releases/download/v0.17.0/serverfs_windows_native-0.17.0-cp312-abi3-win_amd64.whl

Agent Bridge environment (Bridge + provider SDKs; it must NOT contain the product):

uv venv --python 3.12 .venv-bridge
uv pip install --python .venv-bridge/Scripts/python.exe https://github.com/NTLx/ServerFS_MCP/releases/download/v0.17.0/serverfs_agent_bridge-0.17.0-py3-none-any.whl

Point the ServerFS supervisor at the Bridge interpreter (set this in the environment
that starts serverfs supervisor; it is not a provider setting and does not belong in
[agent] config):

$env:SERVERFS_BRIDGE_PYTHON = "<path>\.venv-bridge\Scripts\python.exe"

Verified native-wheel storage alternative:

serverfs bootstrap native-wheel --url "https://github.com/NTLx/ServerFS_MCP/releases/download/v0.17.0/serverfs_windows_native-0.17.0-cp312-abi3-win_amd64.whl" --sha256 06ebaeb22c76b802cee894dc2f928d987dc5a1c6d3b2e420e0370f109926ea07