faceit-mcp: Instructions file for Codex

Agent guidelines for faceit-mcp

Generated code

Every file under src/faceit_mcp/tools/ (including __init__.py) is auto-generated from swagger.json by scripts/generate_tools.py. Do not hand-edit these files — your changes will be clobbered on the next regeneration.

To change a tool's signature or description:

1. Update scripts/generate_tools.py. The most common edits are:
   • TAG_HINTS — the "Use this when / Prefer X when" block that is appended to each tool description. This is the main lever for making tools easier to pick.
   • OPERATION_OVERRIDES — rename or re-summarise individual operations (keyed by (operationId, path)).
2. Place the current swagger.json at the repo root (it is gitignored).
3. Run python scripts/generate_tools.py.
4. Review the diff under src/faceit_mcp/tools/ and commit it together with the generator change.

Runtime code

src/faceit_mcp/{server,client,config,errors}.py are hand-written and safe to edit. Keep the HTTP client single-purpose — all API-specific behaviour belongs in the generator's hints, not in the client.

Secrets

swagger.json and .env are gitignored. Never commit a real FACEIT_API_KEY. When demonstrating the server, always substitute a placeholder such as YOUR_KEY_HERE.

Testing a change

After regenerating, assert that all 64 tools still register cleanly:

FACEIT_API_KEY=placeholder python -c "
import asyncio
from faceit_mcp.server import mcp
tools = asyncio.run(mcp.list_tools())
assert len(tools) == 64, len(tools)
print('OK', len(tools))
"