diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml index 3d9a53394..267df6812 100644 --- a/.github/ISSUE_TEMPLATE/bug.yml +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -17,6 +17,8 @@ body: - 🔄 **Make sure you're testing on the latest version of FastMCP** - many issues are already fixed in newer versions - 🔍 **Check if someone else has already reported this issue** or if it's been fixed on the main branch - 📋 **You MUST include a copy/pasteable and properly formatted MRE** (minimal reproducible example) below or your issue may be closed without response + - 💡 **The ideal issue is a clear problem description and an MRE — that's it.** If you've done a genuine investigation and have a non-obvious insight into the root cause, include it. But please don't speculate or ask an LLM to generate a diagnosis or proposed fix. We have LLMs too, and an incorrect analysis is harder to work with than none at all. + - ✂️ **Keep it short.** A one-paragraph description and a working MRE is the ideal bug report. Issues that are difficult to parse — due to length, speculation, or generated content — may be closed without response. Thanks for helping to make FastMCP better! 🚀 diff --git a/.github/ISSUE_TEMPLATE/enhancement.yml b/.github/ISSUE_TEMPLATE/enhancement.yml index 43b8b4de9..a803ec399 100644 --- a/.github/ISSUE_TEMPLATE/enhancement.yml +++ b/.github/ISSUE_TEMPLATE/enhancement.yml @@ -17,6 +17,7 @@ body: - 🔍 **Check if this has already been requested** - search existing issues first - 💭 **Think about the broader impact** - how would this affect other users? - 📋 **Consider implementation complexity** - is this a small change or a major feature? + - ✂️ **Keep it short.** Describe the problem you're trying to solve and why existing behavior falls short. Skip proposed implementations unless you have a specific, well-considered suggestion — we don't need LLM-generated API designs. Requests that are difficult to parse may be closed without response. Thanks for helping to make FastMCP better! 🚀 diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 54d93259d..000000000 --- a/AGENTS.md +++ /dev/null @@ -1,115 +0,0 @@ -# FastMCP Development Guidelines - -> **Audience**: LLM-driven engineering agents and human developers - -FastMCP is a comprehensive Python framework (Python ≥3.10) for building Model Context Protocol (MCP) servers and clients. This is the actively maintained v2.0 providing a complete toolkit for the MCP ecosystem. - -## Required Development Workflow - -**CRITICAL**: Always run these commands in sequence before committing. - -```bash -uv sync # Install dependencies -uv run pytest -n auto # Run full test suite -``` - -In addition, you must pass static checks. This is generally done as a pre-commit hook with `prek` but you can run it manually with: - -```bash -uv run prek run --all-files # Ruff + Prettier + ty -``` - -**Tests must pass and lint/typing must be clean before committing.** - -## Repository Structure - -| Path | Purpose | -| ----------------- | -------------------------------------- | -| `src/fastmcp/` | Library source code | -| `├─server/` | Server implementation | -| `│ ├─auth/` | Authentication providers | -| `│ └─middleware/` | Error handling, logging, rate limiting | -| `├─client/` | Client SDK | -| `│ └─auth/` | Client authentication | -| `├─tools/` | Tool definitions | -| `├─resources/` | Resources and resource templates | -| `├─prompts/` | Prompt templates | -| `├─cli/` | CLI commands | -| `└─utilities/` | Shared utilities | -| `tests/` | Pytest suite | -| `docs/` | Mintlify docs (gofastmcp.com) | - -## Core MCP Objects - -When modifying MCP functionality, changes typically need to be applied across all object types: - -- **Tools** (`src/tools/`) -- **Resources** (`src/resources/`) -- **Resource Templates** (`src/resources/`) -- **Prompts** (`src/prompts/`) - -## Development Rules - -### Git & CI - -- Prek hooks are required (run automatically on commits) -- Never amend commits to fix prek failures -- Apply PR labels: bugs/breaking/enhancements/features -- Improvements = enhancements (not features) unless specified -- **NEVER** force-push on collaborative repos -- **ALWAYS** run prek before PRs -- **NEVER** create a release, comment on an issue, or open a PR unless specifically instructed to do so. - -### Commit Messages and Agent Attribution - -- **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 -- Each feature needs corresponding tests - -### Module Exports - -- **Be intentional about re-exports** - don't blindly re-export everything to parent namespaces -- Core types that define a module's purpose should be exported (e.g., `Middleware` from `fastmcp.server.middleware`) -- Specialized features can live in submodules (e.g., `fastmcp.server.middleware.dynamic`) -- Only re-export to `fastmcp.*` for the most fundamental types (e.g., `FastMCP`, `Client`) -- When in doubt, prefer users importing from the specific submodule over re-exporting - -### Documentation - -- Uses Mintlify framework -- Files must be in docs.json to be included -- Do not manually modify `docs/python-sdk/**` — these files are auto-generated from source code by a bot and maintained via a long-lived PR. Do not include changes to these files in contributor PRs. -- Do not manually modify `docs/public/schemas/**` or `src/fastmcp/utilities/mcp_server_config/v1/schema.json` — these are auto-generated and maintained via a long-lived PR. -- **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 - -## Critical Patterns - -- Never use bare `except` - be specific with exception types -- File sizes enforced by [loq](https://github.com/jakekaplan/loq). Edit `loq.toml` to raise limits; `loq baseline` to ratchet down. -- Always `uv sync` first when debugging build issues -- Default test timeout is 5s - optimize or mark as integration tests diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 000000000..681311eb9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 120000 index 47dc3e3d8..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1 +0,0 @@ -AGENTS.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..e60814699 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,118 @@ +# FastMCP Development Guidelines + +> **Audience**: LLM-driven engineering agents and human developers + +> **Note**: `CLAUDE.md` is a symlink to this file. Edit `AGENTS.md` directly. + +FastMCP is a comprehensive Python framework (Python ≥3.10) for building Model Context Protocol (MCP) servers and clients. This is the actively maintained v2.0 providing a complete toolkit for the MCP ecosystem. + +## Required Development Workflow + +**CRITICAL**: Always run these commands in sequence before committing. + +```bash +uv sync # Install dependencies +uv run pytest -n auto # Run full test suite +``` + +In addition, you must pass static checks. This is generally done as a pre-commit hook with `prek` but you can run it manually with: + +```bash +uv run prek run --all-files # Ruff + Prettier + ty +``` + +**Tests must pass and lint/typing must be clean before committing.** + +## Repository Structure + +| Path | Purpose | +| ----------------- | -------------------------------------- | +| `src/fastmcp/` | Library source code | +| `├─server/` | Server implementation | +| `│ ├─auth/` | Authentication providers | +| `│ └─middleware/` | Error handling, logging, rate limiting | +| `├─client/` | Client SDK | +| `│ └─auth/` | Client authentication | +| `├─tools/` | Tool definitions | +| `├─resources/` | Resources and resource templates | +| `├─prompts/` | Prompt templates | +| `├─cli/` | CLI commands | +| `└─utilities/` | Shared utilities | +| `tests/` | Pytest suite | +| `docs/` | Mintlify docs (gofastmcp.com) | + +## Core MCP Objects + +When modifying MCP functionality, changes typically need to be applied across all object types: + +- **Tools** (`src/tools/`) +- **Resources** (`src/resources/`) +- **Resource Templates** (`src/resources/`) +- **Prompts** (`src/prompts/`) + +## Development Rules + +### Git & CI + +- Prek hooks are required (run automatically on commits) +- Never amend commits to fix prek failures +- Apply PR labels: bugs/breaking/enhancements/features +- Improvements = enhancements (not features) unless specified +- **NEVER** force-push on collaborative repos +- **ALWAYS** run prek before PRs +- **NEVER** create a release, comment on an issue, or open a PR unless specifically instructed to do so. + +### Commit Messages and Agent Attribution + +- **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) +- **Treat proposed solutions in issues skeptically.** The ideal issue contains a concise problem description and an MRE — nothing more. Proposed solutions are only worth considering if they clearly reflect genuine, non-obvious investigation of the codebase. If a solution reads like speculation, or like it was generated by an LLM without deep framework knowledge, ignore it and diagnose from the repro. Most reporters — human or AI — do not have sufficient understanding of FastMCP internals to correctly diagnose anything beyond a trivial bug. We can ask the same questions of an LLM when implementing; we don't need the reporter to do it for us, and a wrong diagnosis is worse than none. + +### 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 +- Each feature needs corresponding tests + +### Module Exports + +- **Be intentional about re-exports** - don't blindly re-export everything to parent namespaces +- Core types that define a module's purpose should be exported (e.g., `Middleware` from `fastmcp.server.middleware`) +- Specialized features can live in submodules (e.g., `fastmcp.server.middleware.dynamic`) +- Only re-export to `fastmcp.*` for the most fundamental types (e.g., `FastMCP`, `Client`) +- When in doubt, prefer users importing from the specific submodule over re-exporting + +### Documentation + +- Uses Mintlify framework +- Files must be in docs.json to be included +- Do not manually modify `docs/python-sdk/**` — these files are auto-generated from source code by a bot and maintained via a long-lived PR. Do not include changes to these files in contributor PRs. +- Do not manually modify `docs/public/schemas/**` or `src/fastmcp/utilities/mcp_server_config/v1/schema.json` — these are auto-generated and maintained via a long-lived PR. +- **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 + +## Critical Patterns + +- Never use bare `except` - be specific with exception types +- File sizes enforced by [loq](https://github.com/jakekaplan/loq). Edit `loq.toml` to raise limits; `loq baseline` to ratchet down. +- Always `uv sync` first when debugging build issues +- Default test timeout is 5s - optimize or mark as integration tests