Contributing

Help build MapleStats

MapleStats is open source and grows one source at a time. You can help without writing any code: report a wrong number, suggest a source, or share how you used it. If you do write code, this page walks through the whole process, from the first issue to the live site.

Ways to help

Report a wrong or missing number

Open an issue with the question you asked, the tool call and the source URL from the result's provenance. A wrong number is the most useful bug report there is.

Report a number

Suggest a source

Name the agency or portal and link to where its data lives. The roadmap lists every source checked so far, including the ones that could not be added and why.

Suggest a source · Roadmap

Share a case study

Used MapleStats for real work? Open an issue with the question, what the agent found and the calls it made. Good ones join the case studies.

Share a case study

French speakers help too: every tool carries French search keywords and every page is bilingual. If a phrase reads like a translation, open an issue or send a fix.

The process for code

Open an issue first

Say what you want to add or fix before you write code, so nobody duplicates work and the approach is agreed early. For a new source, link its API documentation or data page.

Set up and read AGENTS.md

Fork the repository, clone it and install with uv. Then read AGENTS.md: it is the working guide for people and agents alike. It explains how a module is laid out, the response contract every tool follows, and three lines that look removable but are not.

Terminal

git clone https://github.com/dsanchezp18/maplestats-mcp.git
cd maplestats-mcp
uv sync

Build against the real API

A new source starts as a copy of modules/_example/: typed responses that carry their provenance, errors that are raised rather than returned, and a docstring with English and French search keywords. Before calling a client done, call every function it exports against the live API with realistic arguments. Mocked tests only prove the code does what you assumed the API does; an audit of this project that called every tool live found nine bugs the mocks had missed.

Test it, and list it

Add mocked unit tests for the client (with pytest-httpx), covering the quirks the real API has, and a live smoke step for every tool in scripts/smoke_test_modules.py. Then add the module to SOURCES in scripts/build_site.py, so the website can name it. A test fails if either is missing.

Run the checks

The same four checks that run in CI. All four must pass before a pull request is reviewed.

Terminal

uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run pyright
uv run pytest -q

Open a pull request

Describe what changed and how you checked it against the live source. CI runs the checks on Python 3.12 and 3.13, and a maintainer reviews the change. Small, focused pull requests are reviewed and merged faster.

After the merge

Once the merge lands on the main branch, CI runs the checks again, and when they pass the website rebuilds and redeploys, so a new tool appears on the Tools page and in the search. The case-study data is different: it changes only when someone runs scripts/capture_cases.py and commits the new captures. Every Monday, a scheduled job runs the live smoke tests against the real APIs, so an upstream change is caught even when no code changed.

With a coding agent

The repository is set up for coding agents. Point yours at AGENTS.md first (CLAUDE.md in the repository points there too), and it follows the same process and runs the same checks.

Read AGENTS.md in this repository, then add a module for [the source] following it.

Ground rules

Contributions are released under the project's MIT licence.
The data stays with its publishers. MapleStats centralizes the interface, not the data, so do not commit copies of a source's data.
No API keys or credentials in the code. Every source so far works without one.
English and French together: a tool without French keywords cannot be found by a French query.