bring-mcp-server: Instructions file for Codex

Repository Guidelines

Project Structure & Module Organization

• server.py contains the async stdio MCP server, Bring! client lifecycle, tool dispatch, resources, and prompts.
• tests/test_server.py contains unit tests and fake Bring clients/sessions.
• tests/test_mcp_protocol.py exercises MCP validation and responses through an in-memory client/server connection with mocked Bring access.
• requirements.txt lists runtime dependencies; .env.example documents required credentials.
• bring-mcp-server.spec, requirements-build.txt and scripts/ build, package and smoke-test standalone downloads; .github/workflows/release.yml publishes them after all four targets pass.
• .github/workflows/tests.yml runs CI checks. README.md covers setup; this file is the shared contributor and agent guide.

Build, Test, and Development Commands

Use Python 3.11+ and a local virtual environment:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python server.py

Configure credentials before starting the server. It communicates over stdio and is normally launched by an MCP client.

• .venv/bin/python -m py_compile server.py — check source syntax.
• .venv/bin/python -m PyInstaller --noconfirm --clean bring-mcp-server.spec — build a standalone executable after installing requirements-build.txt.
• .venv/bin/python -m unittest discover -s tests -v — run the unit suite.
• npx @modelcontextprotocol/inspector .venv/bin/python server.py — inspect MCP tools, resources, and prompts interactively.

Coding Style & Naming Conventions

Follow existing Python style: four-space indentation, snake_case functions/variables, PascalCase classes, and uppercase module constants. Use type annotations in server code and async/await for network operations. Keep tool descriptions and user-facing messages in English. No formatter or linter is configured.

Keep logging configuration inside main() so imports do not override the test runner's logging.