# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Install dependencies (requires Python 3.10+)
uv venv --python 3.11 && source .venv/bin/activate
uv pip install -e .

# Run the server locally (waits on stdin — Ctrl+C to exit)
AFFINITY_API_KEY=your_key python -m ecs_mcp

# Interactive MCP inspector (test tools without Claude Desktop)
AFFINITY_API_KEY=your_key uvx mcp dev src/ecs_mcp/server.py

# Build for PyPI
uv build

# Publish to PyPI
uv publish --token YOUR_PYPI_TOKEN
```

## Architecture

This is a Python MCP server distributed via `uvx ecs-mcp`. It uses the `src/` layout with `hatchling` as the build backend.

**Key design: shared `mcp` instance**
`src/ecs_mcp/__init__.py` creates the single `FastMCP("ecs-mcp")` instance. All tool modules import it from there and register tools via `@mcp.tool()`. `server.py` imports `ecs_mcp.tools` (which imports each tool module as a side effect), then calls `mcp.run(transport="stdio")`.

**Adding a new integration:**
1. Create `src/ecs_mcp/tools/mytool.py` — import `mcp` from `ecs_mcp`, define `@mcp.tool()` functions
2. Add `from ecs_mcp.tools import mytool  # noqa: F401` to `src/ecs_mcp/tools/__init__.py`

No changes to `server.py` needed.

## Affinity API

- Base URL: `https://api.affinity.co`
- Auth: HTTP Basic Auth with empty username and `AFFINITY_API_KEY` as password
- Only add tools explicitly listed in `mcp.specification` — do not add extras
