π The fast, Pythonic way to build MCP servers and clients.
Add server authoring guidance through the docs site (#5703)
nate nowack144014d3ff93
diff --git a/README.md b/README.mdindex ec4bf0d80..ed16fd664 100644--- a/README.md+++ b/README.md@@ -117,6 +117,8 @@ Documentation is also available in [llms.txt format](https://llmstxt.org/), whic- [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.- [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.+Give your coding agent [`llms.txt`](https://gofastmcp.com/llms.txt) as its starting point. See [Coding Agents](https://gofastmcp.com/getting-started/ai-assisted-development) for version-matched documentation and the optional server authoring skill.+**Community:** Join our [Discord server](https://discord.gg/uu8dJCgttd) to connect with other FastMCP developers and share what you're building.## Contributingdiff --git a/docs/.mintlify/skills b/docs/.mintlify/skillsnew file mode 120000index 000000000..5dcab58e1--- /dev/null+++ b/docs/.mintlify/skills@@ -0,0 +1 @@+../../skills\ No newline at end of filediff --git a/docs/docs.json b/docs/docs.jsonindex f7f7073c9..e0f2e2519 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -94,6 +94,7 @@"getting-started/welcome","getting-started/installation","getting-started/quickstart",+ "getting-started/ai-assisted-development","getting-started/whats-new"]},diff --git a/docs/getting-started/ai-assisted-development.mdx b/docs/getting-started/ai-assisted-development.mdxnew file mode 100644index 000000000..6a9fbb468--- /dev/null+++ b/docs/getting-started/ai-assisted-development.mdx@@ -0,0 +1,48 @@+---+title: AI-assisted Development+sidebarTitle: Coding Agents+description: Give your coding agent FastMCP authoring guidance and documentation matched to your project.+icon: robot+---++Give your coding agent [llms.txt](https://gofastmcp.com/llms.txt) as its starting point for FastMCP. This index links to the documentation as Markdown. Ask the agent to check your project's installed version and read the relevant pages before writing code.++## Read version-matched documentation++For FastMCP 3, use the index entries under `/v3/`; unversioned pages describe FastMCP 4. Every page is available as Markdown by appending `.md` to its URL, such as [the tools guide](https://gofastmcp.com/servers/tools.md). Read the pages relevant to the task; [llms-full.txt](https://gofastmcp.com/llms-full.txt) contains the entire documentation and may exceed your agent's context window.++Agents with MCP support can also search the documentation at `https://gofastmcp.com/mcp`. See [LLM-friendly docs](/getting-started/welcome#llm-friendly-docs) for a client example.++## Add authoring guidance++The optional `fastmcp-server` skill adds a workflow for building, extending, and reviewing servers: choose suitable MCP interfaces, preserve useful schemas and errors, consult version-matched documentation, and verify behavior through a real client. The documentation index helps the agent find API information; installing the skill makes this authoring guidance available for the agent to select across tasks.++Install it with the [Skills CLI](https://github.com/vercel-labs/skills), which lets you choose your coding agent:++```bash+npx skills add https://gofastmcp.com --skill fastmcp-server+```++The site's [skill discovery index](https://gofastmcp.com/.well-known/skills/index.json) lists the available skills. The [skill source](https://github.com/PrefectHQ/fastmcp/tree/main/skills/fastmcp-server) lives alongside FastMCP's client CLI skill; the site publishes those same files. You can also install from the repository with `npx skills add PrefectHQ/fastmcp --skill fastmcp-server`. The skill uses the agent's documentation access and code execution tools.++Start a new agent session after installing. Ask it to use the `fastmcp-server` skill when working on your server. For example:++```text+Use the fastmcp-server skill to build an MCP server for this issue tracker.+Expose paginated search and issue details, preserve upstream failures as errors,+and test the interface through a FastMCP client. Keep the project's FastMCP version.+```++The skill is maintained in the FastMCP repository and evolves separately from package releases. Update your installed copy to pick up changes, or install from a Git revision when you need reproducible instructions. Your project's dependency constraints still determine which FastMCP APIs the agent should use.++<Tip>+ For an agent that needs to discover and call an existing server, use the [client CLI skill](https://github.com/PrefectHQ/fastmcp/tree/main/skills/fastmcp-client-cli). The server authoring skill is for writing server code.+</Tip>++## Verify the generated server++Run the server's tests and inspect the schemas and results that clients receive. A successful import or the agent's final message does not establish that the server works. The [testing guide](/development/tests#test-through-an-in-memory-client) shows how to connect `fastmcp.Client` directly to your server without starting a network listener.++For deployment work, also test the intended transport and authentication. Use local fixtures or a test account for operations that change data.++If your server's users need guidance for workflows spanning several operations, consider supplying skills with the server. The [Skills Provider](/servers/providers/skills) serves skill files as resources; the [Experimental Skills Extension](/servers/providers/experimental-skills) adds standard skills discovery. Check the installed FastMCP version and target host's support, and verify that the host actually reads and uses the skill. Discovery alone does not activate it.diff --git a/skills/fastmcp-server/SKILL.md b/skills/fastmcp-server/SKILL.mdnew file mode 100644index 000000000..7b71de3f1--- /dev/null+++ b/skills/fastmcp-server/SKILL.md@@ -0,0 +1,96 @@+---+name: fastmcp-server+description: Build, extend, or review MCP servers with Python FastMCP, using documentation matched to the project's version.+---++# Authoring MCP servers with FastMCP++## Find the current API++Check the project's installed FastMCP version and dependency constraints.+Fetch [the documentation index](https://gofastmcp.com/llms.txt) and read the+relevant pages for that version. The index includes versioned documentation;+select `/v3/` pages for FastMCP 3 and unversioned pages for FastMCP 4. Read+individual pages through their `.md` URLs instead of loading `llms-full.txt`.+For APIs newer than the installed release, check that release's source or+signatures. Preserve the project's dependency constraints unless an upgrade is+part of the request. For a new project, check the current stable release before+choosing a dependency.++Use the standalone `fastmcp` package. Its API differs from+`mcp.server.fastmcp` in the Python MCP SDK.++## Author the server++Choose the MCP interface to suit what the server exposes: tools for callable+operations, resources for addressable content, and prompts for reusable message+templates. FastMCP derives tool schemas from Python annotations and descriptions;+use `Literal` or enums for finite choices and `Field` descriptions for parameter+semantics. SDK wrappers need to preserve signatures and docstrings, for example+with `functools.wraps`, or discovery loses that information. Inspect the schema+the client receives, especially after transforms or custom discovery rendering:+requiredness, enum values, and nested fields can disappear from a summary.++Let the intended client tasks guide tool boundaries, descriptions, and result+shape. Give clients enough context to use results and recover from errors.+The right granularity depends on the service; generated API tools, custom tools,+and compositions can all be appropriate.++For paginated or bounded results, expose whether the answer is complete and how+to continue. An upstream failure is not an empty result. Return useful recovery+information through tool errors rather than a successful-looking payload. Use+`ToolError`, `ResourceError`, or `PromptError` from `fastmcp.exceptions` for+intentional client-facing messages. With `mask_error_details=True`, ordinary+exceptions such as `ValueError` lose their messages; do not put sensitive backend+details in the explicit error types, whose messages remain visible.++When using tool search or code mode, make exact named operations discoverable+and explain the execution contract: what persists between calls and what becomes+the result. A short fetch/filter/return example can prevent repeated empty+outputs. Check the installed implementation before describing that behavior.++Look up FastMCP's relevant facilities as needed: context and dependencies,+lifespan, authentication, composition, and transports. Use the project's runtime+and hosting choices to determine configuration.++When clients need a repeatable workflow across the server's capabilities,+consider shipping a skill alongside those capabilities. Put task selection,+operation sequencing, and recovery guidance in the skill; keep tool descriptions+focused on their individual contracts. Read the version-matched Skills Provider+and Experimental Skills Extension docs from the index before implementing it.+`SkillsDirectoryProvider` exposes skill files as resources; the experimental+extension adds `skills/list` and `skills/get` discovery. Check the installed+release and target host's support before selecting either interface. Discovery+does not activate a skill: verify that the host reads and uses it in the intended+workflow. The experimental extension currently requires directly registered+providers and does not support mounted or transformed skill sources.++Verify the server through FastMCP's `Client`, which can connect directly to a+server instance for in-process testing. Check a representative operation, its+client-visible schema and result, and a meaningful failure. For composed or+transformed servers, verify the public names and URIs through the outer server,+including resource references returned by prompts. Namespace transforms change+component names and resource URIs, but do not rewrite URI text inside prompt+messages. When a prompt must work both standalone and mounted, direct the client+to discover the resource template instead of hardcoding the child's URI.+Exercise the chosen transport when connection or deployment behavior is part+of the change.++## Evaluate agent workflows++When the task includes evaluating how agents use the server, test a representative+workflow using the project's existing evaluation harness when available.+Protocol tests show that a tool works; an agent task shows whether the+interface is usable. Start from a known condition, give an agent a user-level request,+and check the outcome against independent API or database evidence. For writes,+check both the intended change and what should remain unchanged. A normal agent+exit or a plausible final answer is not proof of success.++Use the target client's actual capabilities; exposing resources, sampling, or+elicitation does not mean that client uses them. To measure the server alone,+give the agent only that server's capabilities supported by the client. To measure+the user's workflow, include the other+capabilities the client really has. Inspect traces for discovery misses, invalid+arguments, partial-data assumptions, and repeated recovery attempts before+changing tool descriptions or structure. Compare task success alongside calls,+latency, and context size; fewer tools or tokens alone is not the objective.