From 3730b7e1062bce8b2edbfcec1cd60e353f22214c Mon Sep 17 00:00:00 2001
From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com>
Date: Fri, 8 Aug 2025 13:33:23 -0400
Subject: [PATCH] Update agents.md; add github instructinos (#1410)

---
 .github/copilot-instructions.md |  1 +
 AGENTS.md                       | 65 +++++++++++++++++++++++++++++----
 2 files changed, 59 insertions(+), 7 deletions(-)
 create mode 120000 .github/copilot-instructions.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 120000
index 000000000..be77ac83a
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1 @@
+../AGENTS.md
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index c0a72bc4f..f1ebd1ce3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,13 +1,21 @@
 # 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 pre-commit run --all-files    # Ruff + Prettier + Pyright
 uv run pytest                        # Run full test suite
 ```
 
+**All three must pass** - this is enforced by CI. Alternative: `just build && just typecheck && just test`
+
 **Tests must pass and lint/typing must be clean before committing.**
 
 ## Repository Structure
@@ -15,14 +23,21 @@ uv run pytest                        # Run full test suite
 | Path             | Purpose                                                |
 | ---------------- | ------------------------------------------------------ |
 | `src/fastmcp/`   | Library source code (Python ≥ 3.10)                   |
-| `  └─server/`    | Server implementation, `FastMCP`, auth, networking    |
-| `  └─client/`    | High-level client SDK + helpers                       |
-| `  └─resources/` | MCP resources and resource templates                  |
-| `  └─prompts/`   | Prompt templates                                      |
-| `  └─tools/`     | Tool implementations                                  |
-| `tests/`         | Pytest test suite                                     |
+| `  ├─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/`      | Minimal runnable demos                                |
+| `examples/`      | Runnable demo servers (echo, smart_home, atproto)     |
 
 ## Core MCP Objects
 
@@ -81,3 +96,39 @@ async with Client(transport=StreamableHttpTransport(server_url)) as client:
 - Uses Mintlify framework
 - Files must be in docs.json to be included
 - Never modify `docs/python-sdk/**` (auto-generated)
+
+## Key Tools & Commands
+
+### Environment Setup
+```bash
+git clone <repo>
+cd fastmcp
+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`
+
+## 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
+4. **Test timeouts**: Default 3s - optimize or mark as integration tests