mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-09 15:19:10 +02:00
Update AGENTS.md (#1471)
This commit is contained in:
Jeremiah Lowin
GitHub
parent
383a57c28a
commit
2946041152
1 changed files with 56 additions and 14 deletions
70
AGENTS.md
70
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 <repo>
|
||||
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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue