Bugs, Coverage, and SDK Wave 1 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate

Part of the 2026-07-28 Spec Refactor tracker #4857. This is the first step, and has no dependencies. It can run in parallel with Part 1 (#4854).

Goal

Before any SDK or spec changes, build an extensive pytest suite that pins down the current behavior of every Python server (fetch, git, time) on mcp 1.x. The suite must pass the coverage quality gate from #4474.

This suite is the regression net for Part 4 (#4851). The SDK v2 migration is supposed to be transparent on the wire, and there is no codemod for Python, so the test suite is the only safety net for a port done by hand. Existing tests may be deleted where the new suite covers them better.

Test design

Test through the protocol, in-process.
- Connect an mcp ClientSession to each server over in-memory streams, and assert on the wire-level results: tool lists, call results and errors.
- Refactor server construction so it can run in-process, if it can't already. Keep at most a thin smoke test that runs the uvx/console-script entry point as a subprocess.
Stay migration-proof.
- Keep assertions independent of SDK internals.
- v2 renames type fields to snake_case (e.g. inputSchema → input_schema) and moves types to mcp_types. Where practical, compare against the wire JSON (e.g. model_dump(by_alias=True, mode="json")) rather than Python attribute names, so Part 4 doesn't have to rewrite assertions.
- Any assertion that has to change during Part 4 must be justified in that PR.
Coverage by server:
- fetch:
  - URL validation and robots.txt handling. Mock HTTP; no network in CI.
  - Markdown extraction, pagination (start_index / max_length) and raw mode.
  - The prompt.
  - Every error path.
- git:
  - Every tool against a temporary repository.
  - Repository path validation and restriction, including the bypass concerns in [Security] mcp-server-git: validate_repo_path opt-in bypass (architectural complement of CVE-2025-68145) #4550.
  - Behavior with and without Roots.
- time: timezone lookup and conversion, DST edges, invalid input.
Use pytest-asyncio consistently. Standardize the test directory name: time currently uses test/, the others use tests/.

Quality gate (from #4474, modeled on the inspector's `v2/main` AGENTS.md)

Threshold: ≥ 90 per file on lines, statements, functions and branches, using the closest equivalent coverage.py can measure. Enable branch coverage.
Per-file enforcement: add pytest-cov/coverage.py. coverage.py's fail_under is global, not per-file, so it isn't enough on its own. Implement per-file enforcement, e.g. coverage json plus a small check script with the same semantics as the TS gate.
Unreachable code: don't lower the gate for it. Mark it with a justified inline # pragma: no cover # <reason> instead.
Separate coverage command: coverage is its own documented command per server, not part of the fast uv run pytest loop. CI posture (amended): CI enforces the per-file gate in a parallel coverage job, matching Part 1 (Bugs, Coverage, and SDK Wave 1 Part 1: TypeScript servers: extensive unit tests + per-file 90% coverage gate #4854) as amended. Maintainers decided this on PR docs: agentic software factory inception (docs/agent-guidance-inception.md) #4861. This issue wires it in (changed from the earlier plan, which left the wiring to Add local:gate, pre-push-gate skill #4871): besides the command and the per-file check script, add the parallel coverage job to python.yml and a Python coverage stage to local:gate, and record the stage in docs/quality-gate.md and the pre-push-gate skill. Add local:gate, pre-push-gate skill #4871 builds local:gate first, without coverage, so that it does not have to wait for this suite.

Acceptance criteria

Every Python server passes the per-file 90% gate, enforced by config and script rather than convention.
A PR that drops any Python file below 90 fails CI, and npm run local:gate fails on it too.
Every pragma carries a reason.
pyright and ruff are clean.
The suite passes on current main (mcp 1.x) in CI.
Removed tests are listed in the PR with the reason.

Carried over from #4474, which this issue supersedes

Document the Python coverage command per server, the equivalent of npm run coverage.
Add the Python half of the coverage rule to AGENTS.md under "Always test new or modified code", in this issue's PR: per-file ≥ 90 on lines and branches (the dimensions coverage.py measures; it has no native function dimension), and a reason on every # pragma: no cover. Bugs, Coverage, and SDK Wave 1 Part 1: TypeScript servers: extensive unit tests + per-file 90% coverage gate #4854 adds the TypeScript half.

docs: record the maintainer decisions from the PR #4861 review

Amended: the CI posture is now "CI enforces the per-file coverage gate in a parallel job", replacing "coverage stays local". Maintainers decided this on PR #4861, matching the Inspector's CI (inspector#2159). Wiring it into CI and local:gate is #4871; this issue still provides the coverage command.

Here is a coverage baseline for the three Python servers to size this work, from main at f46d957 on 2026-09-28. Every file in every server is below the 90% gate. The gap in each server.py is serve(), and the pure functions underneath are well tested. serve() can be driven in-process today with no refactor. The git suite fails on Windows, and its fixture fix should go first.

Baseline

Server	Tests passing	`server.py` lines / funcs / branches	Uncovered in `serve()`
fetch	20	52.3 / 50.0 / 50.0	193-288
git	47 (40 error at teardown on Windows)	71.7 / 75.0 / 58.5	442-581 plus the dead `list_repos`
time	38	69.7 / 62.5 / 42.9	124-131, 182-220

Per-file tables (uv run --with pytest-cov pytest --cov=src --cov-branch, Python 3.10 and 3.11, coverage.py per-function regions for Funcs)

Bold is below the gate.

fetch

File	Lines	Funcs	Branches
`server.py`	52.3	50.0	50.0
`__init__.py`	25.0	50.0	50.0
`__main__.py`	0	0	100

git

File	Lines	Funcs	Branches
`server.py`	71.7	75.0	58.5
`__init__.py`	52.6	50.0	16.7
`__main__.py`	0	0	100

time

File	Lines	Funcs	Branches
`server.py`	69.7	62.5	42.9
`__init__.py`	30.0	50.0	50.0
`__main__.py`	0	0	100

git's 442-581 is list_tools and call_tool. The well-tested pure functions are fetch_url, the git_* helpers with their flag-injection guards, and TimeServer.

Fix first: git fixture on Windows

test_repository calls shutil.rmtree while GitPython's git cat-file processes still have their cwd inside the repo. 40 of 47 tests then error at teardown with PermissionError: [WinError 32]. Calling test_repo.close() before the rmtree fixes it (verified). This also unblocks #1149.

Running `serve()` in-process

Patch mcp_server_<name>.server.stdio_server with an asynccontextmanager that yields the server side of mcp.shared.memory.create_client_server_memory_streams(). Then run serve(...) in an anyio task group and open ClientSession on the client side. This works for all three servers today. The create_server(...) -> Server split this issue asks for can follow without changing those tests.

What the new suites should pin

All verified against the source on main, most by driving serve() in-process.

fetch

call_tool never checks name (line 224), so call_tool("nope", {"url": ...}) fetches the URL.
Redirects are followed with no private-IP guard (mcp-server-fetch follows redirects with no private-IP / metadata SSRF guard | #4838).
Two timeouts are hard-coded (fetch: hardcoded 30s timeout with no CLI/env/per-request override #4448).
Proxy configuration errors reach the client as bare text (Fetch extension fails with "Unknown scheme for proxy URL URL('socks://127.0.0.1:2080/')" #767, Using SOCKS proxy, but the 'socksio' package is not installed. #1401).

fetch details

Characterize mcp-server-fetch follows redirects with no private-IP / metadata SSRF guard | #4838 so the fix has a test to change.
fetch: hardcoded 30s timeout with no CLI/env/per-request override #4448: 30s on the page and httpx's 5s default on robots.txt.
Proxy errors are raised at AsyncClient() construction, outside the except HTTPError.
Also cover the list_tools schema with exclusiveMaximum/exclusiveMinimum ([bug] mcp-server-fetch tool json schema can‘t use in Google Gemini 2.5 pro #1624), call_tool with only url (fetch fails without optional settings #2035), pagination with start_index/max_length, raw, and the fetch prompt.
Error branches: invalid URL, robots disallow, HTTP error, empty content, and the robots.txt connection failure at 82-83. That last one is the cheapest uncovered path in the file.
Dead branches at 231-232 and 245-246 will hold the file below 100% branches and can go.

git

call_tool for all 12 tools, and the error text for a bad repo_path.
Success messages that lie: git_commit reports success and creates an empty commit when nothing is staged #4762 (PR fix(git): refuse to commit when nothing is staged #4761), git_add reports 'Files staged successfully' when nothing was staged #4763, git_checkout reports "Switched to branch 'X'" when the checkout actually detached HEAD #4804 (PR fix(git): report a detached HEAD from git_checkout #4805), and git_branch with an unknown branch_type.
A nonexistent --repository kills the server with a traceback.
A --repository pointing at a subdirectory returns early (mcp-server-git: Make --repository . auto-detect git root like standard git commands #3029).
list_repos is dead code, although Enforce current roots on every git tool call #3613 assumes otherwise. Delete it or wire it up, then test.
Regression guards for .git folder staged by running 'git add .' #628 and [Git MCP] Blob or Tree named 'XXX.py^0' not found #1682.

git details

git_commit with nothing staged creates an empty commit (git_commit reports success and creates an empty commit when nothing is staged #4762). git_add stages nothing (git_add reports 'Files staged successfully' when nothing was staged #4763). git_checkout detaches HEAD (git_checkout reports "Switched to branch 'X'" when the checkout actually detached HEAD #4804).
git_branch returns "Invalid branch type" as a non-error result (282-283).
serve() 294-300 catches only InvalidGitRepositoryError. A nonexistent path raises NoSuchPathError.
The by_roots/by_commandline branches of list_repos are dead too. Nothing ever sends roots/list.
.git folder staged by running 'git add .' #628 (git add . staging .git) is fixed at db96050.
[Git MCP] Blob or Tree named 'XXX.py^0' not found #1682 (git_show with HEAD:path) and lines 228/232 need a rename-only or binary commit.

time

list_tools names and descriptions ([Feature]: Unify the names of the Time MCP server tools #3201 and mcp-server-time: Default Time Zone #2853 request changes to them), call_tool for both tools, and the error branches.

time details

Error branches: timezone: "" and a bad timezone or time string. The SDK catches an absent key.
convert_time's missing-key branch at 197-201 is unreachable through the protocol.

all three

serverInfo.version is the mcp SDK version, not the package version (Sync reported server versions with package.json and pyproject.toml #360 applies here too).
main() is coverable in-process by patching serve. Only __main__.py needs a subprocess.

Not gaps after all

[Security] mcp-server-git: validate_repo_path opt-in bypass (architectural complement of CVE-2025-68145) #4550 (no --repository case) and the symlink escape already have unit tests.
mcp-server-fetch hard-codes use_readability=True which requires Node.js (undeclared); fails silently when Node is unavailable or misconfigured #4199: readabilipy already falls back to pure Python when Node is absent. Only a hanging Node subprocess is untestable.
error with mcp-server-time #1501 is an mcpo proxy issue. get_local_tz is fully tested.

The scan is scripted and can be rerun against v2/main as slices land, with per-file deltas against this baseline.

Scan and verification done with help from Claude Code. The coverage numbers come from a real run; the per-issue verdicts were checked against the source but are a starting point, not a review.

test(git): close the fixture repository before removing it

refactor(git): remove the unreachable list_repos helper

test(time): characterize serve() through the protocol, per-file coverage

test(git): characterize serve() through the protocol, gate coverage p…

test(git): close the fixture repository before removing it

refactor(git): remove the unreachable list_repos helper

test(git): characterize serve() through the protocol, gate coverage p…

test(time): characterize serve() through the protocol, per-file coverage

test(git): close the fixture repository before removing it

refactor(git): remove the unreachable list_repos helper

test(git): characterize serve() through the protocol, gate coverage p…

test(time): characterize serve() through the protocol, per-file coverage

Merge pull request #4976 from modelcontextprotocol/v2/chore/4855-py-c…

feat: local:gate, the gate lease, boot smoke and the pre-push-gate skill

feat: add the project-structure, local-dev, testing and client-smoke …

Navigation Menu

Repository navigation

Bugs, Coverage, and SDK Wave 1 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate #4855

Goal

Test design

Quality gate (from #4474, modeled on the inspector's `v2/main` AGENTS.md)

Acceptance criteria

Carried over from #4474, which this issue supersedes

Baseline

Fix first: git fixture on Windows

Running `serve()` in-process

What the new suites should pin

Not gaps after all

4 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Bugs, Coverage, and SDK Wave 1 Part 2: Python servers: extensive unit tests + per-file 90% coverage gate #4855

Description

Goal

Test design

Quality gate (from #4474, modeled on the inspector's v2/main AGENTS.md)

Acceptance criteria

Carried over from #4474, which this issue supersedes

Activity

cliffhall commented on Sep 28, 2026

olaservo commented on Sep 29, 2026

Baseline

Fix first: git fixture on Windows

Running serve() in-process

What the new suites should pin

Not gaps after all

4 remaining items

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Quality gate (from #4474, modeled on the inspector's `v2/main` AGENTS.md)

Running `serve()` in-process