Fix PATTERNS.md drift from Python MCP server template

[JoeCardoso13]

Summary

build-mcpb/references/PATTERNS.md has drifted from its source-of-truth, NimbleBrainInc/mcp-server-template-python. Several discrepancies affect the build-mcpb pipeline — specifically Phase 2 (structural fallback) and Phase 3 (implementation/test reference).

Findings

Structural (Phase 2 fallback)

1. mpak.json listed in directory tree but doesn't exist in template repo
PATTERNS.md line 37 lists mpak.json in the Python directory structure, and Phase 4 validates it exists — but the template repo doesn't actually include it. Either the template needs it added, or the directory tree in PATTERNS.md should remove it and note it's created during Phase 4.

2. server.json exists in template repo but missing from PATTERNS.md directory tree
The template includes server.json for registry metadata. Phase 2 checks for it, but PATTERNS.md's directory structure omits it — so the fallback path can't create it.

3. .mcpbignore missing CONTRIBUTING.md
Template excludes CONTRIBUTING.md from bundles. PATTERNS.md's .mcpbignore doesn't list it.

Implementation patterns (Phase 3 code generation)

4. api_client.py missing async context manager (__aenter__/__aexit__)
Template client supports async with Client(...) as c:, which the integration test conftest uses. PATTERNS.md omits these methods.

5. api_client.py missing User-Agent header
Template includes "User-Agent": "mcp-server-example/0.1.0" in session headers. PATTERNS.md omits it.

6. api_client.py error parsing is oversimplified
PATTERNS.md shows result.get("message", "Unknown error"). Template handles nested error objects (result["error"] as dict or string). Agent-generated clients from PATTERNS.md will have less robust error handling.

7. api_models.py field structure has diverged

• Pagination: nextLink alias in PATTERNS.md vs nextCursor/hasMore in template
• Main model: customFieldValues in PATTERNS.md vs description/updatedAt/metadata in template
• List response: nested Data class in PATTERNS.md that the template doesn't use

Test patterns (Phase 3 verify) — highest impact

8. Mocking strategy is wrong
PATTERNS.md shows:

monkeypatch.setattr("mcp_<name>.server._client", mock_client)

Template actually does:

with patch("mcp_example.server.get_client", return_value=mock_client):

Patching get_client (template) is more robust than patching the _client global (PATTERNS.md). An agent following PATTERNS.md produces tests using the wrong approach.

CI workflows (Phase 2 fallback)

9. ci.yml missing the bundle job
Template has a third CI job (bundle) that tests bundle creation after lint+test. PATTERNS.md only shows lint and test.

10. build-bundle.yml missing server.json version update
Template updates both manifest.json and server.json from the release tag. PATTERNS.md only shows manifest.json, causing version drift on release.

11. scan.yml scanner install method differs
PATTERNS.md uses uvx mpak-scanner scan. Template uses pip install mpak-scanner with a graceful fallback when unavailable.

Minor version drift

12. ty version — PATTERNS.md pins >=0.0.17, template has >=0.0.20.

13. Missing pytest-cov dev dep — Template includes pytest-cov>=6.0.0, PATTERNS.md doesn't. The Makefile test-cov target needs it.

Context

PATTERNS.md serves as a fallback reference for the build-mcpb agent when code wasn't scaffolded from the template. It's referenced in:

• Phase 2 — create missing files from PATTERNS.md
• Phase 3 — code examples for implementation and test patterns

It doesn't need to be a 1:1 mirror of the template, but the structural patterns, mocking strategy, and CI workflows need to match so the agent produces compatible code.

Suggested fix

Update PATTERNS.md to match the current template for items 1-11. Items 12-13 are minor version bumps.