CONTRIBUTING.md

Contributing to Wordle MCP (Python)

Thanks for taking the time to contribute! This guide covers everything you need to get from a fresh clone to an open pull request.

Index

• Prerequisites
• Getting Set Up
  • Option A: GitHub Codespaces / Dev Container
  • Option B: Local Setup
• Project Structure
• Running the Server Locally
• Running Tests
• Making Changes
• Commit Messages
• Opening a Pull Request
• Releasing

---

Prerequisites

• Python 3.12 (see .python-version)
• uv for dependency management and running scripts
• Docker (optional, only needed if you're changing the Dockerfile or testing the container image)
• Git

Getting Set Up

Option A: GitHub Codespaces / Dev Container

The fastest way to start: click the "Open in GitHub Codespaces" badge in the README, or open the repo in VS Code with the Dev Containers extension. The .devcontainer config installs Python, uv, and syncs dependencies for you automatically.

Option B: Local Setup

1. Fork the repo, then clone your fork:

   git clone https://github.com/<your-username>/mcp-wordle-python.git
   cd mcp-wordle-python

2. Install dependencies (this creates a .venv and installs both runtime and dev dependencies):

   uv sync

3. Create a branch for your change:

   git checkout -b your-branch-name

Project Structure

.
├── src/mcp_wordle/main.py   # The MCP server: tool definitions and Wordle API logic
├── tests/                   # pytest regression tests
├── Dockerfile                # Multi-stage build used by the published image
├── fastmcp.json              # FastMCP CLI entrypoint config
└── .github/workflows/        # CI (tests/uvx/Docker validation) and release automation

The server itself is intentionally small: one FastMCP tool (get_wordle_solution) that validates a requested date and fetches the corresponding solution from the NYT Wordle API. Keep additions consistent with that — this project favors small, direct functions over added abstraction.

Running the Server Locally

You can run the server directly to confirm it starts:

uv run mcp-wordle

It communicates over stdio, so it won't print much beyond a startup banner until an MCP client (e.g. the MCP Inspector, Claude Desktop, or Claude Code) connects to it. To try it against a real client, point your MCP client config at your local checkout instead of the published package, e.g.:

{
  "mcpServers": {
    "Wordle MCP (dev)": {
      "command": "uv",
      "args": ["--directory", "/path/to/your/clone", "run", "mcp-wordle"]
    }
  }
}

Running Tests

uv run pytest

Tests use pytest with respx to mock the Wordle API's HTTP responses, so they run offline and don't hit the real API. If you add or change behavior in src/mcp_wordle/main.py, add or update a corresponding test in tests/test_main.py.

Every push and pull request also runs through the CI workflow, which runs the test suite, verifies the package installs and starts via uvx, and confirms the Docker image still builds. A pull request needs this to pass before it can be merged.

Making Changes

• Keep changes focused — unrelated cleanup or refactoring should be a separate PR.

• Match the existing style: plain functions over unnecessary classes, no comments explaining what code does (only why, when it's non-obvious).

• If you're changing the Dockerfile, validate it builds locally before pushing:

  docker build -t mcp-wordle:dev .

Commit Messages

This project follows Conventional Commits. Prefix your commit message with the type of change, e.g.:

• feat: add support for X
• fix: correct date validation off-by-one
• test: add coverage for Y
• docs: update README
• ci: adjust workflow trigger
• chore: bump dependency

Opening a Pull Request

1. Push your branch to your fork.
2. Open a Pull Request against master.
3. Describe what changed and why. Link any related issues.
4. Make sure CI is green before requesting review.

Releasing

Releases are maintainer-triggered via git tags, not part of a typical contribution — see the README's Releasing section if you need the details.