π The fast, Pythonic way to build MCP servers and clients.
Publish regular skill files for Mintlify discovery (#5956)
nate nowackd92276995f2f
diff --git a/.github/workflows/run-static.yml b/.github/workflows/run-static.ymlindex 68926334c..fe21b7932 100644--- a/.github/workflows/run-static.yml+++ b/.github/workflows/run-static.yml@@ -29,6 +29,9 @@ jobs:steps:- uses: actions/checkout@v7+ - name: Check published skills match their sources+ run: diff -ru skills docs/.mintlify/skills+- name: Setup uvuses: ./.github/actions/setup-uvwith:diff --git a/docs/.mintlify/skills/fastmcp-client-cli b/docs/.mintlify/skills/fastmcp-client-clideleted file mode 120000index 249b27419..000000000--- a/docs/.mintlify/skills/fastmcp-client-cli+++ /dev/null@@ -1 +0,0 @@-../../../skills/fastmcp-client-cli\ No newline at end of filediff --git a/docs/.mintlify/skills/fastmcp-client-cli/SKILL.md b/docs/.mintlify/skills/fastmcp-client-cli/SKILL.mdnew file mode 100644index 000000000..ae66a5e31--- /dev/null+++ b/docs/.mintlify/skills/fastmcp-client-cli/SKILL.md@@ -0,0 +1,114 @@+---+name: fastmcp-client-cli+description: Query and invoke tools on MCP servers using fastmcp list and fastmcp call. Use when you need to discover what tools a server offers, call tools, or integrate MCP servers into workflows.+---++# FastMCP CLI: List and Call++Use `fastmcp list` and `fastmcp call` to interact with any MCP server from the command line.++## Listing Tools++```bash+# Remote server+fastmcp list http://localhost:8000/mcp++# Local Python file (runs via fastmcp run automatically)+fastmcp list server.py++# MCPConfig with multiple servers+fastmcp list mcp.json++# Stdio command (npx, uvx, etc.)+fastmcp list --command 'npx -y @modelcontextprotocol/server-github'++# Include full input/output schemas+fastmcp list server.py --input-schema --output-schema++# Machine-readable JSON+fastmcp list server.py --json++# Include resources and prompts+fastmcp list server.py --resources --prompts+```++Default output shows tool signatures and descriptions. Use `--input-schema` or `--output-schema` to include full JSON schemas, `--json` for structured output.++## Calling Tools++```bash+# Key=value arguments (auto-coerced to correct types)+fastmcp call server.py greet name=World+fastmcp call server.py add a=3 b=4++# Single JSON object for complex/nested args+fastmcp call server.py create_item '{"name": "Widget", "tags": ["a", "b"]}'++# --input-json with key=value overrides+fastmcp call server.py search --input-json '{"query": "hello", "limit": 5}' limit=10++# JSON output for scripting+fastmcp call server.py add a=3 b=4 --json+```++Type coercion is automatic: `limit=5` becomes an integer, `verbose=true` becomes a boolean, based on the tool's input schema.++## Server Targets++All commands accept the same server targets:++| Target | Example |+|--------|---------|+| HTTP/HTTPS URL | `http://localhost:8000/mcp` |+| Python file | `server.py` |+| MCPConfig JSON | `mcp.json` (must have `mcpServers` key) |+| Stdio command | `--command 'npx -y @mcp/server'` |+| Discovered name | `weather` or `source:name` |++Servers configured in editor configs (Claude Desktop, Claude Code, Cursor, Gemini CLI, Goose) or project-level `mcp.json` can be referenced by name. Use `source:name` (e.g. `claude-code:my-server`, `cursor:weather`) to target a specific source. Run `fastmcp discover` to see available names.++For SSE servers, pass `--transport sse`:++```bash+fastmcp list http://localhost:8000/mcp --transport sse+```++## Auth++HTTP targets automatically use OAuth (no-ops if the server doesn't require auth). Disable with `--auth none`:++```bash+fastmcp call http://server/mcp tool --auth none+```++## Discovering Configured Servers++```bash+# See all MCP servers in editor/project configs+fastmcp discover++# Filter by source+fastmcp discover --source claude-code++# JSON output+fastmcp discover --json+```++Scans Claude Desktop, Claude Code, Cursor, Gemini CLI, Goose, and `./mcp.json`. Sources: `claude-desktop`, `claude-code`, `cursor`, `gemini`, `goose`, `project`.++## Workflow Pattern++Discover tools first, then call them:++```bash+# 1. See what servers are configured+fastmcp discover++# 2. See what tools a server has+fastmcp list weather++# 3. Call a tool+fastmcp call weather get_forecast city=London+```++If you call a nonexistent tool, FastMCP suggests close matches.diff --git a/docs/.mintlify/skills/fastmcp-server b/docs/.mintlify/skills/fastmcp-serverdeleted file mode 120000index a01de2ff8..000000000--- a/docs/.mintlify/skills/fastmcp-server+++ /dev/null@@ -1 +0,0 @@-../../../skills/fastmcp-server\ No newline at end of filediff --git a/docs/.mintlify/skills/fastmcp-server/SKILL.md b/docs/.mintlify/skills/fastmcp-server/SKILL.mdnew file mode 100644index 000000000..7b71de3f1--- /dev/null+++ b/docs/.mintlify/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.