From 2946041152096a38e9a3581b028418337364b3bc Mon Sep 17 00:00:00 2001 From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com> Date: Tue, 12 Aug 2025 12:55:19 -0400 Subject: [PATCH] Update AGENTS.md (#1471) --- AGENTS.md | 70 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 56 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f1ebd1ce3..bc38bab05 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,18 +23,18 @@ uv run pytest # Run full test suite | Path | Purpose | | ---------------- | ------------------------------------------------------ | | `src/fastmcp/` | Library source code (Python ≥ 3.10) | -| ` ├─server/` | Server implementation, `FastMCP`, auth, networking | -| ` │ ├─auth/` | Authentication providers (Bearer, JWT, WorkOS) | -| ` │ └─middleware/` | Error handling, logging, rate limiting | -| ` ├─client/` | High-level client SDK + transports | -| ` │ └─auth/` | Client authentication (Bearer, OAuth) | -| ` ├─tools/` | Tool implementations + `ToolManager` | -| ` ├─resources/` | Resources, templates + `ResourceManager` | -| ` ├─prompts/` | Prompt templates + `PromptManager` | -| ` ├─cli/` | FastMCP CLI commands (`run`, `dev`, `install`) | -| ` ├─contrib/` | Community contributions (bulk caller, mixins) | -| ` ├─experimental/` | Experimental features (new OpenAPI parser) | -| ` └─utilities/` | Shared utilities (logging, JSON schema, HTTP) | +| `├─server/` | Server implementation, `FastMCP`, auth, networking | +| `│ ├─auth/` | Authentication providers (Bearer, JWT, WorkOS) | +| `│ └─middleware/` | Error handling, logging, rate limiting | +| `├─client/` | High-level client SDK + transports | +| `│ └─auth/` | Client authentication (Bearer, OAuth) | +| `├─tools/` | Tool implementations + `ToolManager` | +| `├─resources/` | Resources, templates + `ResourceManager` | +| `├─prompts/` | Prompt templates + `PromptManager` | +| `├─cli/` | FastMCP CLI commands (`run`, `dev`, `install`) | +| `├─contrib/` | Community contributions (bulk caller, mixins) | +| `├─experimental/` | Experimental features (new OpenAPI parser) | +| `└─utilities/` | Shared utilities (logging, JSON schema, HTTP) | | `tests/` | Comprehensive pytest suite with markers | | `docs/` | Mintlify documentation (published to gofastmcp.com) | | `examples/` | Runnable demo servers (echo, smart_home, atproto) | @@ -42,6 +42,7 @@ uv run pytest # Run full test suite ## Core MCP Objects When modifying MCP functionality, changes typically need to be applied across all object types: + - **Tools** (`src/tools/` + `ToolManager`) - **Resources** (`src/resources/` + `ResourceManager`) - **Resource Templates** (`src/resources/` + `ResourceManager`) @@ -49,6 +50,15 @@ When modifying MCP functionality, changes typically need to be applied across al ## Testing Best Practices +### Testing Standards + +- Every test: atomic, self-contained, single functionality +- Use parameterization for multiple examples of same functionality +- Use separate tests for different functionality pieces +- Put imports at the top of the file, not in the test body +- **NEVER** add `@pytest.mark.asyncio` to tests - `asyncio_mode = "auto"` is set globally +- **ALWAYS** run pytest after significant changes + ### Always Use In-Memory Transport Pass FastMCP servers directly to clients for testing: @@ -66,6 +76,7 @@ async with Client(mcp) as client: ``` Only use HTTP transport when explicitly testing network features: + ```python # Network testing only async with Client(transport=StreamableHttpTransport(server_url)) as client: @@ -75,31 +86,57 @@ async with Client(transport=StreamableHttpTransport(server_url)) as client: ## Development Rules ### Git & CI + - Pre-commit hooks are required (run automatically on commits) - Never amend commits to fix pre-commit failures - Apply PR labels: bugs/breaking/enhancements/features - Improvements = enhancements (not features) unless specified +- **NEVER** force-push on collaborative repos +- **ALWAYS** run pre-commit before PRs ### Commit Messages and Agent Attribution -- **NEVER** include agent attribution in commit messages or PR titles/descriptions (no "🤖 Generated with [tool]", "with Claude", etc.) -- Agent attribution is ONLY allowed in Co-authored-by lines in commits + +- **Agents NOT acting on behalf of @jlowin MUST identify themselves** (e.g., "🤖 Generated with Claude Code" in commits/PRs) - Keep commit messages brief - ideally just headlines, not detailed messages - Focus on what changed, not how or why +- Always read issue comments for follow-up information (treat maintainers as authoritative) + +### PR Messages - Required Structure + +- 1-2 paragraphs: problem/tension + solution (PRs are documentation!) +- Focused code example showing key capability +- **Avoid:** bullet summaries, exhaustive change lists, verbose closes/fixes, marketing language +- **Do:** Be opinionated about why change matters, show before/after scenarios +- Minor fixes: keep body short and concise +- No "test plan" sections or testing summaries ### Code Standards + - Python ≥ 3.10 with full type annotations - Follow existing patterns and maintain consistency +- **Prioritize readable, understandable code** - clarity over cleverness +- Avoid obfuscated or confusing patterns even if they're shorter - Use `# type: ignore[attr-defined]` in tests for MCP results instead of type assertions - Each feature needs corresponding tests ### Documentation + - Uses Mintlify framework - Files must be in docs.json to be included - Never modify `docs/python-sdk/**` (auto-generated) +- **Core Principle:** A feature doesn't exist unless it is documented! + +### Documentation Guidelines + +- **Code Examples:** Explain before showing code, make blocks fully runnable (include imports) +- **Structure:** Headers form navigation guide, logical H2/H3 hierarchy +- **Content:** User-focused sections, motivate features (why) before mechanics (how) +- **Style:** Prose over code comments for important information ## Key Tools & Commands ### Environment Setup + ```bash git clone cd fastmcp @@ -107,16 +144,19 @@ uv sync # Installs all deps including dev tools ``` ### Validation Commands (Run Frequently) + - **Linting**: `uv run ruff check` (or with `--fix`) - **Type Checking**: `uv run pyright` - **All Checks**: `uv run pre-commit run --all-files` ### Testing + - **Standard**: `uv run pytest` - **Integration**: `uv run pytest -m "integration"` - **Excluding markers**: `uv run pytest -m "not integration and not client_process"` ### CLI Usage + - **Run server**: `uv run fastmcp run server.py` - **Development**: `uv run fastmcp dev server.py` (with Inspector UI) - **Help**: `uv run fastmcp --help` @@ -124,10 +164,12 @@ uv sync # Installs all deps including dev tools ## Critical Patterns ### Error Handling + - Never use bare `except` - be specific with exception types - Use `# type: ignore[attr-defined]` in tests for MCP results ### Build Issues (Common Solutions) + 1. **Dependencies**: Always `uv sync` first 2. **Pre-commit fails**: Run `uv run pre-commit run --all-files` to see failures 3. **Type errors**: Use `uv run pyright` directly, check `pyproject.toml` config