[CI] Add Windows and macOS to the test matrix and publish a platform support statement
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 9
- Forks
- 17
- Avg merge
- 21h 36m
- Merged PRs (30d)
- 22
Description
Summary
CI currently runs on ubuntu-latest only (all jobs in ci.yml), while
the primary adoption paths — Claude Desktop, Cursor, VS Code recipes —
run heavily on macOS and Windows. Add both platforms to the test matrix
(scoped to keep CI cost sane), fix whatever falls out, and publish an
explicit platform support statement in the docs.
Why this matters
- The gateway's stdio lifecycle (SIGINT/EOF handling), path handling in
stores (JsonFileArtifactStore, SQLite paths), and console behavior
(Rich on legacy Windows terminals) are exactly the things that differ
across platforms — and exactly what a Claude Desktop user on Windows
hits first. - "Tested on Windows/macOS" removes a silent adoption objection for
desktop users and enterprises; an explicit support statement belongs
next to the Python-version policy indocs/stability.md. - Recipes that say "works with Claude Desktop" implicitly promise
macOS/Windows support today, without CI backing.
Proposed scope
- Extend the
testjob matrix: full Python matrix on Ubuntu (as today),
pluswindows-latestandmacos-lateston the newest and oldest
supported Python (4 added cells, not 8) —fail-fast: false
preserved. - Keep the heavier jobs (drift checks, benchmarks, floor-deps,
examples/demo) Ubuntu-only; runmake test(+make demoif cheap)
on the new cells. - Fix discovered issues: likely suspects are path separators in stores
and fixtures,signalhandling differences in_mcp_cli.py
(SIGINTvsCTRL_BREAK_EVENT), tmpfile semantics in store tests,
and line-ending assumptions in golden files (.gitattributesmay be
needed). docs/stability.md: add a platform support table (Tier 1: Linux;
Tier 1 after this issue: macOS/Windows for library + stdio gateway).- README badge/bullet update once green.
Implementation notes
- Workflow:
.github/workflows/ci.ymltest job (currently
runs-on: ubuntu-latestwith a 3.10–3.13 matrix); convert to an
os/python-versionmatrix withinclude/excludeto get the
4-cell expansion. - Golden/byte-identical tests (cards, scorecard fixtures) are the most
likely cross-platform failures — normalize newlines at comparison
time rather than weakening the determinism claims. - tiktoken wheels exist for win/mac; the offline fallback covers any
gap. - Windows runners are slow: keep their job to
pytest -qwithout
coverage to bound wall time.
Acceptance criteria
- CI green on
windows-latestandmacos-latestfor oldest and
newest supported Python. - Any platform-specific fixes covered by tests (not just skipped
on the failing platform — skips need a written rationale). - Platform support statement published in
docs/stability.md. - CI wall-time impact measured and documented on the PR.
Out of scope
- Platform-specific packaging (MSI/Homebrew).
- Windows-specific gateway features (e.g. named-pipe transports).
- Running the full drift-check suite on non-Linux.
References
- GitHub Actions matrix docs:
https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs - Current workflow:
.github/workflows/ci.yml - Related: #359 (Python 3.14),
docs/stability.mdPython policy
Priority: P1 · Effort: M · Impact: Medium
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with .github/workflows/ci.yml and its test job, then run make test on the oldest and newest supported Python versions for the added Windows and macOS cells. Check platform-specific failures in the store, CLI, signal, fixture, and golden-file tests; done means CI is green, fixes have test coverage, docs/stability.md has the support table, and the README and CI timing are updated.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, python
- Domain
- ci-cd, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100