instantly-mcp: Instructions file for Codex

AGENTS.md

Stop and read this before you write code

This repo has conventions. Violating them wastes a review cycle. instantly-mcp is an MCP server wrapping the Instantly.ai v2 API — 40 tools for analytics, leads, campaigns, the Unibox, sender accounts, and webhooks — where every write is gated behind an explicit confirm and a code-enforced autonomy policy, not a prompt asking nicely.

Commands

• Install: pip install -e ".[dev]" (or uv sync — see README)
• Test: pytest -q
• Test with coverage: pytest -q --cov=src/instantly_mcp --cov-report=term-missing
• Lint: ruff check src tests
• Types: pyright
• All of it: ruff check src tests && pyright && pytest -q --cov=src/instantly_mcp --cov-report=term-missing
• Build: python -m build (produces dist/*.whl + dist/*.tar.gz)

ruff format --check is not part of this list. This codebase predates a formatter pass and has never been run through one; adopting it means reformatting every file in its own reviewed change, not a side effect of something else. Don't add it to CI or run ruff format across the tree without calling that out explicitly.

Layout

• src/instantly_mcp/server.py — the 40 @mcp.tool() definitions, the /login and /healthz routes, and main() (console entry point, instantly-mcp per [project.scripts]).
• src/instantly_mcp/client.py — InstantlyClient, the only thing that makes HTTP calls. New Instantly endpoint? It goes through here.
• src/instantly_mcp/policy.py — the autonomy-tier model. Read the section below before touching this file.
• src/instantly_mcp/auth.py / oauth.py — inbound auth for HTTP transports. See Credentials below.
• src/instantly_mcp/models.py — Pydantic input models + normalizers. Tool signatures accept plain dict/list[dict] on purpose (simpler JSON schemas for FastMCP) and validate through here.
• src/instantly_mcp/formatting.py — shapes raw API responses into compact, LLM-friendly summaries. Every list tool caps output here.
• tests/ mirrors src/instantly_mcp/, plus test_server.py for CLI/entry- point behavior. Never put tests inside the package.
• docs/ — tools.md, autonomy.md, configuration.md, hosting.md, api-notes.md. If you change behavior those describe, update the page, not just the README.