π The fast, Pythonic way to build MCP servers and clients.
Clean up parameter documentation
Jeremiah Lowin44f14b1f7be1
diff --git a/docs/.cursor/rules/mintlify.mdc b/docs/.cursor/rules/mintlify.mdcnew file mode 100644index 000000000..503fe1647--- /dev/null+++ b/docs/.cursor/rules/mintlify.mdc@@ -0,0 +1,364 @@+---+description:+globs: *.mdx+alwaysApply: false+---+# Mintlify technical writing assistant++You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.++## Core writing principles++### Language and style requirements+- Use clear, direct language appropriate for technical audiences+- Write in second person ("you") for instructions and procedures+- Use active voice over passive voice+- Employ present tense for current states, future tense for outcomes+- Maintain consistent terminology throughout all documentation+- Keep sentences concise while providing necessary context+- Use parallel structure in lists, headings, and procedures++### Content organization standards+- Lead with the most important information (inverted pyramid structure)+- Use progressive disclosure: basic concepts before advanced ones+- Break complex procedures into numbered steps+- Include prerequisites and context before instructions+- Provide expected outcomes for each major step+- End sections with next steps or related information+- Use descriptive, keyword-rich headings for navigation and SEO++### User-centered approach+- Focus on user goals and outcomes rather than system features+- Anticipate common questions and address them proactively+- Include troubleshooting for likely failure points+- Provide multiple pathways when appropriate (beginner vs advanced), but offer an opinionated path for people to follow to avoid overwhelming with options++## Mintlify component reference++### Callout components++#### Note - Additional helpful information++<Note>+Supplementary information that supports the main content without interrupting flow+</Note>++#### Tip - Best practices and pro tips++<Tip>+Expert advice, shortcuts, or best practices that enhance user success+</Tip>++#### Warning - Important cautions++<Warning>+Critical information about potential issues, breaking changes, or destructive actions+</Warning>++#### Info - Neutral contextual information++<Info>+Background information, context, or neutral announcements+</Info>++#### Check - Success confirmations++<Check>+Positive confirmations, successful completions, or achievement indicators+</Check>++### Code components++#### Single code block++```javascript config.js+const apiConfig = {+baseURL: 'https://api.example.com',+timeout: 5000,+headers: {+ 'Authorization': `Bearer ${process.env.API_TOKEN}`+}+};+```++#### Code group with multiple languages++<CodeGroup>+```javascript Node.js+const response = await fetch('/api/endpoint', {+ headers: { Authorization: `Bearer ${apiKey}` }+});+```++```python Python+import requests+response = requests.get('/api/endpoint',+ headers={'Authorization': f'Bearer {api_key}'})+```++```curl cURL+curl -X GET '/api/endpoint' \+ -H 'Authorization: Bearer YOUR_API_KEY'+```+</CodeGroup>++#### Request/Response examples++<RequestExample>+```bash cURL+curl -X POST 'https://api.example.com/users' \+ -H 'Content-Type: application/json' \+ -d '{"name": "John Doe", "email": "[email protected]"}'+```+</RequestExample>++<ResponseExample>+```json Success+{+ "id": "user_123",+ "name": "John Doe",+ "email": "[email protected]",+ "created_at": "2024-01-15T10:30:00Z"+}+```+</ResponseExample>++### Structural components++#### Steps for procedures++<Steps>+<Step title="Install dependencies">+ Run `npm install` to install required packages.++ <Check>+ Verify installation by running `npm list`.+ </Check>+</Step>++<Step title="Configure environment">+ Create a `.env` file with your API credentials.++ ```bash+ API_KEY=your_api_key_here+ ```++ <Warning>+ Never commit API keys to version control.+ </Warning>+</Step>+</Steps>++#### Tabs for alternative content++<Tabs>+<Tab title="macOS">+ ```bash+ brew install node+ npm install -g package-name+ ```+</Tab>++<Tab title="Windows">+ ```powershell+ choco install nodejs+ npm install -g package-name+ ```+</Tab>++<Tab title="Linux">+ ```bash+ sudo apt install nodejs npm+ npm install -g package-name+ ```+</Tab>+</Tabs>++#### Accordions for collapsible content++<AccordionGroup>+<Accordion title="Troubleshooting connection issues">+ - **Firewall blocking**: Ensure ports 80 and 443 are open+ - **Proxy configuration**: Set HTTP_PROXY environment variable+ - **DNS resolution**: Try using 8.8.8.8 as DNS server+</Accordion>++<Accordion title="Advanced configuration">+ ```javascript+ const config = {+ performance: { cache: true, timeout: 30000 },+ security: { encryption: 'AES-256' }+ };+ ```+</Accordion>+</AccordionGroup>++### API documentation components++#### Parameter fields++<ParamField path="user_id" type="string" required>+Unique identifier for the user. Must be a valid UUID v4 format.+</ParamField>++<ParamField body="email" type="string" required>+User's email address. Must be valid and unique within the system.+</ParamField>++<ParamField query="limit" type="integer" default="10">+Maximum number of results to return. Range: 1-100.+</ParamField>++<ParamField header="Authorization" type="string" required>+Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`+</ParamField>++#### Response fields++<ResponseField name="user_id" type="string" required>+Unique identifier assigned to the newly created user.+</ResponseField>++<ResponseField name="created_at" type="timestamp">+ISO 8601 formatted timestamp of when the user was created.+</ResponseField>++<ResponseField name="permissions" type="array">+List of permission strings assigned to this user.+</ResponseField>++#### Expandable nested fields++<ResponseField name="user" type="object">+Complete user object with all associated data.++<Expandable title="User properties">+ <ResponseField name="profile" type="object">+ User profile information including personal details.++ <Expandable title="Profile details">+ <ResponseField name="first_name" type="string">+ User's first name as entered during registration.+ </ResponseField>++ <ResponseField name="avatar_url" type="string | null">+ URL to user's profile picture. Returns null if no avatar is set.+ </ResponseField>+ </Expandable>+ </ResponseField>+</Expandable>+</ResponseField>++### Interactive components++#### Cards for navigation++<Card title="Getting started guide" icon="rocket" href="/quickstart">+Complete walkthrough from installation to your first API call in under 10 minutes.+</Card>++<CardGroup cols={2}>+<Card title="Authentication" icon="key" href="/auth">+ Learn how to authenticate requests using API keys or JWT tokens.+</Card>++<Card title="Rate limiting" icon="clock" href="/rate-limits">+ Understand rate limits and best practices for high-volume usage.+</Card>+</CardGroup>++### Media and advanced components++#### Frames for images++Wrap all images in frames.++<Frame>+<img src="/images/dashboard.png" alt="Main dashboard showing analytics overview" />+</Frame>++<Frame caption="The analytics dashboard provides real-time insights">+<img src="/images/analytics.png" alt="Analytics dashboard with charts" />+</Frame>++#### Tooltips and updates++<Tooltip tip="Application Programming Interface - protocols for building software">+API+</Tooltip>++<Update label="Version 2.1.0" description="Released March 15, 2024">+## New features+- Added bulk user import functionality+- Improved error messages with actionable suggestions++## Bug fixes+- Fixed pagination issue with large datasets+- Resolved authentication timeout problems+</Update>++## Required page structure++Every documentation page must begin with YAML frontmatter:++```yaml+---+title: "Clear, specific, keyword-rich title"+description: "Concise description explaining page purpose and value"+---+```++## Content quality standards++### Code examples requirements+- Always include complete, runnable examples that users can copy and execute+- Show proper error handling and edge case management+- Use realistic data instead of placeholder values+- Include expected outputs and results for verification+- Test all code examples thoroughly before publishing+- Specify language and include filename when relevant+- Add explanatory comments for complex logic++### API documentation requirements+- Document all parameters including optional ones with clear descriptions+- Show both success and error response examples with realistic data+- Include rate limiting information with specific limits+- Provide authentication examples showing proper format+- Explain all HTTP status codes and error handling+- Cover complete request/response cycles++### Accessibility requirements+- Include descriptive alt text for all images and diagrams+- Use specific, actionable link text instead of "click here"+- Ensure proper heading hierarchy starting with H2+- Provide keyboard navigation considerations+- Use sufficient color contrast in examples and visuals+- Structure content for easy scanning with headers and lists++## AI assistant instructions++### Component selection logic+- Use **Steps** for procedures, tutorials, setup guides, and sequential instructions+- Use **Tabs** for platform-specific content or alternative approaches+- Use **CodeGroup** when showing the same concept in multiple languages+- Use **Accordions** for supplementary information that might interrupt flow+- Use **Cards and CardGroup** for navigation, feature overviews, and related resources+- Use **RequestExample/ResponseExample** specifically for API endpoint documentation+- Use **ParamField** for API parameters, **ResponseField** for API responses+- Use **Expandable** for nested object properties or hierarchical information++### Quality assurance checklist+- Verify all code examples are syntactically correct and executable+- Test all links to ensure they are functional and lead to relevant content+- Validate Mintlify component syntax with all required properties+- Confirm proper heading hierarchy with H2 for main sections, H3 for subsections+- Ensure content flows logically from basic concepts to advanced topics+- Check for consistency in terminology, formatting, and component usage++### Error prevention strategies+- Always include realistic error handling in code examples+- Provide dedicated troubleshooting sections for complex procedures+- Explain prerequisites clearly before beginning instructions+- Include verification and testing steps with expected outcomes+- Add appropriate warnings for destructive or security-sensitive actions+- Validate all technical information through testing before publication\ No newline at end of filediff --git a/docs/clients/logging.mdx b/docs/clients/logging.mdxindex 9c28a5d25..f9cc9fcf5 100644--- a/docs/clients/logging.mdx+++ b/docs/clients/logging.mdx@@ -11,7 +11,7 @@ import { VersionBadge } from '/snippets/version-badge.mdx'MCP servers can emit log messages to clients. The client can handle these logs through a log handler callback.-## Setting Up Log Handling+## Log HandlerProvide a `log_handler` function when creating the client:@@ -31,13 +31,27 @@ client = Client()```-## LogMessage Structure+### Handler Parameters-The `log_handler` receives a `LogMessage` object with:+The `log_handler` is called every time a log message is received. It receives a `LogMessage` object:-- **`level`**: Log level (e.g., "debug", "info", "warning", "error")-- **`logger`**: Logger name (optional, may be None)-- **`data`**: The actual log message content+<Card icon="code" title="Log Handler Parameters">+<ResponseField name="LogMessage" type="Log Message Object">+ <Expandable title="attributes">+ <ResponseField name="level" type='Literal["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"]'>+ The log level+ </ResponseField>++ <ResponseField name="logger" type="str | None">+ The logger name (optional, may be None)+ </ResponseField>++ <ResponseField name="data" type="Any">+ The actual log message content+ </ResponseField>+ </Expandable>+</ResponseField>+</Card>```pythonasync def detailed_log_handler(message: LogMessage):@@ -51,13 +65,12 @@ async def detailed_log_handler(message: LogMessage):## Default Log Handling-If you don't provide a custom `log_handler`, FastMCP uses a default handler that emits DEBUG level logs:+If you don't provide a custom `log_handler`, FastMCP uses a default handler that emits a DEBUG-level FastMCP log for every log message received from the server, which is useful for visibility without polluting your own logs.```python-# Without custom handler - uses default DEBUG loggingclient = Client("my_mcp_server.py")async with client:- # Server logs will be emitted at DEBUG level+ # Server logs will be emitted at DEBUG level automaticallyawait client.call_tool("some_tool")```\ No newline at end of filediff --git a/docs/clients/progress.mdx b/docs/clients/progress.mdxindex bd500fa26..ff3e0aa85 100644--- a/docs/clients/progress.mdx+++ b/docs/clients/progress.mdx@@ -11,7 +11,7 @@ import { VersionBadge } from '/snippets/version-badge.mdx'MCP servers can report progress during long-running operations. The client can receive these updates through a progress handler.-## Setting Up Progress Handling+## Progress HandlerSet a progress handler when creating the client:@@ -35,6 +35,26 @@ client = Client()```+### Handler Parameters++The progress handler receives three parameters:+++<Card icon="code" title="Progress Handler Parameters">+<ResponseField name="progress" type="float">+ Current progress value+</ResponseField>++<ResponseField name="total" type="float | None">+ Expected total value (may be None)+</ResponseField>++<ResponseField name="message" type="str | None">+ Optional status message (may be None)+</ResponseField>+</Card>++## Per-Call Progress HandlerOverride the progress handler for specific tool calls:@@ -48,12 +68,3 @@ async with client:progress_handler=my_progress_handler)```--## Handler Parameters--The progress handler receives:--- **`progress`** (float): Current progress value-- **`total`** (float | None): Expected total value (may be None)-- **`message`** (str | None): Optional status message (may be None)-diff --git a/docs/clients/sampling.mdx b/docs/clients/sampling.mdxindex 25d035478..0483a59b3 100644--- a/docs/clients/sampling.mdx+++ b/docs/clients/sampling.mdx@@ -5,13 +5,13 @@ description: Handle server-initiated LLM sampling requests.icon: robot----import { VersionBadge } from '/snippets/version-badge.mdx'+import { VersionBadge } from "/snippets/version-badge.mdx";<VersionBadge version="2.0.0" />MCP servers can request LLM completions from clients. The client handles these requests through a sampling handler callback.-## Setting Up Sampling Handling+## Sampling HandlerProvide a `sampling_handler` function when creating the client:@@ -38,26 +38,88 @@ client = Client()```-## Handler Parameters+### Handler ParametersThe sampling handler receives three parameters:-### SamplingMessage--- **`role`**: Message role (e.g., "user", "assistant", "system")-- **`content`**: Message content (usually has `.text` attribute)--### SamplingParams--- **`systemPrompt`**: System prompt string (optional)-- **`maxTokens`**: Maximum tokens to generate (optional)-- **`temperature`**: Sampling temperature (optional)-- **`topP`**: Top-p sampling parameter (optional)-- **`stopSequences`**: List of stop sequences (optional)--### RequestContext--- **`request_id`**: Unique identifier for the sampling request+<Card icon="code" title="Sampling Handler Parameters">+<ResponseField name="SamplingMessage" type="Sampling Message Object">+ <Expandable title="attributes">+ <ResponseField name="role" type='Literal["user", "assistant"]'>+ The role of the message.+ </ResponseField>++ <ResponseField name="content" type="TextContent | ImageContent | AudioContent">+ The content of the message.++ TextContent is most common, and has a `.text` attribute.+ </ResponseField>++ </Expandable>+</ResponseField>+<ResponseField name="SamplingParams" type="Sampling Parameters Object">+ <Expandable title="attributes">+ <ResponseField name="messages" type="list[SamplingMessage]">+ The messages to sample from+ </ResponseField>++ <ResponseField name="modelPreferences" type="ModelPreferences | None">+ The server's preferences for which model to select. The client MAY ignore+ these preferences.+ <Expandable title="attributes">+ <ResponseField name="hints" type="list[ModelHint] | None">+ The hints to use for model selection.+ </ResponseField>++ <ResponseField name="costPriority" type="float | None">+ The cost priority for model selection.+ </ResponseField>++ <ResponseField name="speedPriority" type="float | None">+ The speed priority for model selection.+ </ResponseField>++ <ResponseField name="intelligencePriority" type="float | None">+ The intelligence priority for model selection.+ </ResponseField>+ </Expandable>+ </ResponseField>++ <ResponseField name="systemPrompt" type="str | None">+ An optional system prompt the server wants to use for sampling.+ </ResponseField>++ <ResponseField name="includeContext" type="IncludeContext | None">+ A request to include context from one or more MCP servers (including the caller), to+ be attached to the prompt.+ </ResponseField>++ <ResponseField name="temperature" type="float | None">+ The sampling temperature.+ </ResponseField>++ <ResponseField name="maxTokens" type="int">+ The maximum number of tokens to sample.+ </ResponseField>++ <ResponseField name="stopSequences" type="list[str] | None">+ The stop sequences to use for sampling.+ </ResponseField>++ <ResponseField name="metadata" type="dict[str, Any] | None">+ Optional metadata to pass through to the LLM provider.+ </ResponseField>+ </Expandable>++</ResponseField>+<ResponseField name="RequestContext" type="Request Context Object">+ <Expandable title="attributes">+ <ResponseField name="request_id" type="RequestId">+ Unique identifier for the MCP request+ </ResponseField>+ </Expandable>+</ResponseField>+</Card>## Basic Example@@ -75,10 +137,10 @@ async def basic_sampling_handler(for message in messages:content = message.content.text if hasattr(message.content, 'text') else str(message.content)conversation.append(f"{message.role}: {content}")-+# Use the system prompt if providedsystem_prompt = params.systemPrompt or "You are a helpful assistant."-+# Here you would integrate with your preferred LLM service# This is just a placeholder responsereturn f"Response based on conversation: {' | '.join(conversation)}"@@ -88,4 +150,3 @@ client = Client(sampling_handler=basic_sampling_handler)```-diff --git a/docs/servers/auth/bearer.mdx b/docs/servers/auth/bearer.mdxindex 74344a02e..15df171f6 100644--- a/docs/servers/auth/bearer.mdx+++ b/docs/servers/auth/bearer.mdx@@ -61,13 +61,27 @@ mcp = FastMCP(name="My MCP Server", auth=auth)### Configuration Parameters-| Parameter | Type | Required | Description |-|-----------|------|----------|-------------|-| `public_key` | `str` | If `jwks_uri` is not provided | RSA public key in PEM format for static key validation |-| `jwks_uri` | `str` | If `public_key` is not provided | URL for JSON Web Key Set endpoint |-| `issuer` | `str` | No | Expected JWT `iss` claim value |-| `audience` | `str` | No | Expected JWT `aud` claim value |-| `required_scopes` | `list[str]` | No | Global scopes required for all requests |+<Card icon="code" title="BearerAuthProvider Configuration">+<ParamField body="public_key" type="str">+ RSA public key in PEM format for static key validation. Required if `jwks_uri` is not provided+</ParamField>++<ParamField body="jwks_uri" type="str">+ URL for JSON Web Key Set endpoint. Required if `public_key` is not provided+</ParamField>++<ParamField body="issuer" type="str | None">+ Expected JWT `iss` claim value+</ParamField>++<ParamField body="audience" type="str | None">+ Expected JWT `aud` claim value+</ParamField>++<ParamField body="required_scopes" type="list[str] | None">+ Global scopes required for all requests+</ParamField>+</Card>#### Public Key@@ -141,15 +155,35 @@ print(f"Test token: {token}")The `create_token()` method accepts these parameters:-| Parameter | Type | Default | Description |-|-----------|------|---------|-------------|-| `subject` | `str` | `"fastmcp-user"` | JWT subject claim (usually user ID) |-| `issuer` | `str` | `"https://fastmcp.example.com"` | JWT issuer claim |-| `audience` | `str` | `None` | JWT audience claim |-| `scopes` | `list[str]` | `None` | OAuth scopes to include |-| `expires_in_seconds` | `int` | `3600` | Token expiration time |-| `additional_claims` | `dict` | `None` | Extra claims to include |-| `kid` | `str` | `None` | Key ID for JWKS lookup |+<Card icon="code" title="create_token() Parameters">+<ParamField body="subject" type="str" default="fastmcp-user">+ JWT subject claim (usually user ID)+</ParamField>++<ParamField body="issuer" type="str" default="https://fastmcp.example.com">+ JWT issuer claim+</ParamField>++<ParamField body="audience" type="str | None">+ JWT audience claim+</ParamField>++<ParamField body="scopes" type="list[str] | None">+ OAuth scopes to include+</ParamField>++<ParamField body="expires_in_seconds" type="int" default="3600">+ Token expiration time in seconds+</ParamField>++<ParamField body="additional_claims" type="dict | None">+ Extra claims to include in the token+</ParamField>++<ParamField body="kid" type="str | None">+ Key ID for JWKS lookup+</ParamField>+</Card>## Accessing Token Claims@@ -179,10 +213,21 @@ async def get_my_data(ctx: Context) -> dict:### AccessToken Properties-| Property | Type | Description |-|----------|------|-------------|-| `token` | `str` | The raw JWT string |-| `client_id` | `str` | Authenticated principal identifier |-| `scopes` | `list[str]` | Granted scopes |-| `expires_at` | `datetime \| None` | Token expiration timestamp |+<Card icon="code" title="AccessToken Properties">+<ParamField body="token" type="str">+ The raw JWT string+</ParamField>++<ParamField body="client_id" type="str">+ Authenticated principal identifier+</ParamField>++<ParamField body="scopes" type="list[str]">+ Granted scopes+</ParamField>++<ParamField body="expires_at" type="datetime | None">+ Token expiration timestamp+</ParamField>+</Card>diff --git a/docs/servers/prompts.mdx b/docs/servers/prompts.mdxindex 80c799781..f296cb74e 100644--- a/docs/servers/prompts.mdx+++ b/docs/servers/prompts.mdx@@ -57,6 +57,41 @@ def generate_code_request(language: str, task_description: str) -> PromptMessageFunctions with `*args` or `**kwargs` are not supported as prompts. This restriction exists because FastMCP needs to generate a complete parameter schema for the MCP protocol, which isn't possible with variable argument lists.</Tip>+#### Decorator Arguments++While FastMCP infers the name and description from your function, you can override these and add additional metadata using arguments to the `@mcp.prompt` decorator:++```python+ name="analyze_data_request", # Custom prompt name+ description="Creates a request to analyze data with specific parameters", # Custom description+ tags={"analysis", "data"} # Optional categorization tags+)+def data_analysis_prompt(+ data_uri: str = Field(description="The URI of the resource containing the data."),+ analysis_type: str = Field(default="summary", description="Type of analysis.")+) -> str:+ """This docstring is ignored when description is provided."""+ return f"Please perform a '{analysis_type}' analysis on the data found at {data_uri}."+```++<Card icon="code" title="@prompt Decorator Arguments">+<ParamField body="name" type="str | None">+ Sets the explicit prompt name exposed via MCP. If not provided, uses the function name+</ParamField>++<ParamField body="description" type="str | None">+ Provides the description exposed via MCP. If set, the function's docstring is ignored for this purpose+</ParamField>++<ParamField body="tags" type="set[str] | None">+ A set of strings used to categorize the prompt. Clients might use tags to filter or group available prompts+</ParamField>++<ParamField body="enabled" type="bool" default="True">+ A boolean to enable or disable the prompt. See [Disabling Prompts](#disabling-prompts) for more information+</ParamField>+</Card>### Argument Types<VersionBadge version="2.9.0" />@@ -177,28 +212,6 @@ def data_analysis_prompt(In this example, the client *must* provide `data_uri`. If `analysis_type` or `include_charts` are omitted, their default values will be used.-### Prompt Metadata--While FastMCP infers the name and description from your function, you can override these and add tags using arguments to the `@mcp.prompt` decorator:--```python- name="analyze_data_request", # Custom prompt name- description="Creates a request to analyze data with specific parameters", # Custom description- tags={"analysis", "data"} # Optional categorization tags-)-def data_analysis_prompt(- data_uri: str = Field(description="The URI of the resource containing the data."),- analysis_type: str = Field(default="summary", description="Type of analysis.")-) -> str:- """This docstring is ignored when description is provided."""- return f"Please perform a '{analysis_type}' analysis on the data found at {data_uri}."-```--- **`name`**: Sets the explicit prompt name exposed via MCP.-- **`description`**: Provides the description exposed via MCP. If set, the function's docstring is ignored for this purpose.-- **`tags`**: A set of strings used to categorize the prompt. Clients *might* use tags to filter or group available prompts.-- **`enabled`**: A boolean to enable or disable the prompt (defaults to `True`). See [Disabling Prompts](#disabling-prompts) for more information.### Disabling Prompts<VersionBadge version="2.8.0" />diff --git a/docs/servers/resources.mdx b/docs/servers/resources.mdxindex f38834980..127f70805 100644--- a/docs/servers/resources.mdx+++ b/docs/servers/resources.mdx@@ -58,18 +58,9 @@ def get_config() -> dict:* Resource Name: Taken from the function name (`get_greeting`).* Resource Description: Taken from the function's docstring.-### Return Values--FastMCP automatically converts your function's return value into the appropriate MCP resource content:--- **`str`**: Sent as `TextResourceContents` (with `mime_type="text/plain"` by default).-- **`dict`, `list`, `pydantic.BaseModel`**: Automatically serialized to a JSON string and sent as `TextResourceContents` (with `mime_type="application/json"` by default).-- **`bytes`**: Base64 encoded and sent as `BlobResourceContents`. You should specify an appropriate `mime_type` (e.g., `"image/png"`, `"application/octet-stream"`).-- **`None`**: Results in an empty resource content list being returned.--### Resource Metadata+#### Decorator Arguments-You can customize the resource's properties using arguments in the decorator:+You can customize the resource's properties using arguments in the `@mcp.resource` decorator:```pythonfrom fastmcp import FastMCP@@ -89,12 +80,40 @@ def get_application_status() -> dict:return {"status": "ok", "uptime": 12345, "version": mcp.settings.version} # Example usage```-- **`uri`**: The unique identifier for the resource (required).-- **`name`**: A human-readable name (defaults to function name).-- **`description`**: Explanation of the resource (defaults to docstring).-- **`mime_type`**: Specifies the content type (FastMCP often infers a default like `text/plain` or `application/json`, but explicit is better for non-text types).-- **`tags`**: A set of strings for categorization, potentially used by clients for filtering.-- **`enabled`**: A boolean to enable or disable the resource (defaults to `True`). See [Disabling Resources](#disabling-resources) for more information.+<Card icon="code" title="@resource Decorator Arguments">+<ParamField body="uri" type="str" required>+ The unique identifier for the resource+</ParamField>++<ParamField body="name" type="str | None">+ A human-readable name. If not provided, defaults to function name+</ParamField>++<ParamField body="description" type="str | None">+ Explanation of the resource. If not provided, defaults to docstring+</ParamField>++<ParamField body="mime_type" type="str | None">+ Specifies the content type. FastMCP often infers a default like `text/plain` or `application/json`, but explicit is better for non-text types+</ParamField>++<ParamField body="tags" type="set[str] | None">+ A set of strings for categorization, potentially used by clients for filtering+</ParamField>++<ParamField body="enabled" type="bool" default="True">+ A boolean to enable or disable the resource. See [Disabling Resources](#disabling-resources) for more information+</ParamField>+</Card>++### Return Values++FastMCP automatically converts your function's return value into the appropriate MCP resource content:++- **`str`**: Sent as `TextResourceContents` (with `mime_type="text/plain"` by default).+- **`dict`, `list`, `pydantic.BaseModel`**: Automatically serialized to a JSON string and sent as `TextResourceContents` (with `mime_type="application/json"` by default).+- **`bytes`**: Base64 encoded and sent as `BlobResourceContents`. You should specify an appropriate `mime_type` (e.g., `"image/png"`, `"application/octet-stream"`).+- **`None`**: Results in an empty resource content list being returned.### Disabling Resourcesdiff --git a/docs/servers/server.mdx b/docs/servers/server.mdxindex f8c4eda21..df3dfd2b0 100644--- a/docs/servers/server.mdx+++ b/docs/servers/server.mdx@@ -31,13 +31,31 @@ mcp_with_instructions = FastMCP(The `FastMCP` constructor accepts several arguments:-* `name`: (Optional) A human-readable name for your server. Defaults to "FastMCP".-* `instructions`: (Optional) Description of how to interact with this server. These instructions help clients understand the server's purpose and available functionality.-* `lifespan`: (Optional) An async context manager function for server startup and shutdown logic.-* `tags`: (Optional) A set of strings to tag the server itself.-* `tools`: (Optional) A list of tools (or functions to convert to tools) to add to the server. In some cases, providing tools programmatically may be more convenient than using the `@mcp.tool` decorator.-* `**settings`: Keyword arguments corresponding to additional `ServerSettings` configuration-+<Card icon="code" title="FastMCP Constructor Parameters">+<ParamField body="name" type="str" default="FastMCP">+ A human-readable name for your server+</ParamField>++<ParamField body="instructions" type="str | None">+ Description of how to interact with this server. These instructions help clients understand the server's purpose and available functionality+</ParamField>++<ParamField body="lifespan" type="AsyncContextManager | None">+ An async context manager function for server startup and shutdown logic+</ParamField>++<ParamField body="tags" type="set[str] | None">+ A set of strings to tag the server itself+</ParamField>++<ParamField body="tools" type="list[Tool | Callable] | None">+ A list of tools (or functions to convert to tools) to add to the server. In some cases, providing tools programmatically may be more convenient than using the `@mcp.tool` decorator+</ParamField>++<ParamField body="**settings" type="Any">+ Keyword arguments corresponding to additional `ServerSettings` configuration+</ParamField>+</Card>## ComponentsFastMCP servers expose several types of components to the client:@@ -235,6 +253,34 @@ mcp = FastMCP()```+### Constructor Parameters++<Card icon="code" title="AdditionalFastMCP Constructor Parameters">+<ParamField body="dependencies" type="list[str] | None">+ Optional server dependencies list with package specifications+</ParamField>++<ParamField body="include_tags" type="set[str] | None">+ Only expose components with at least one matching tag+</ParamField>++<ParamField body="exclude_tags" type="set[str] | None">+ Hide components with any matching tag+</ParamField>++<ParamField body="on_duplicate_tools" type='Literal["error", "warn", "replace"]' default="error">+ How to handle duplicate tool registrations+</ParamField>++<ParamField body="on_duplicate_resources" type='Literal["error", "warn", "replace"]' default="warn">+ How to handle duplicate resource registrations+</ParamField>++<ParamField body="on_duplicate_prompts" type='Literal["error", "warn", "replace"]' default="replace">+ How to handle duplicate prompt registrations+</ParamField>+</Card>+### Global SettingsGlobal settings affect all FastMCP servers and can be configured via environment variables (prefixed with `FASTMCP_`) or in a `.env` file:diff --git a/docs/servers/tools.mdx b/docs/servers/tools.mdxindex 300a6c7dd..b136e9702 100644--- a/docs/servers/tools.mdx+++ b/docs/servers/tools.mdx@@ -49,9 +49,68 @@ The way you define your Python function dictates how the tool appears and behaveFunctions with `*args` or `**kwargs` are not supported as tools. This restriction exists because FastMCP needs to generate a complete parameter schema for the MCP protocol, which isn't possible with variable argument lists.</Tip>-### Parameters+#### Decorator Arguments-#### Annotations+While FastMCP infers the name and description from your function, you can override these and add additional metadata using arguments to the `@mcp.tool` decorator:++```python+ name="find_products", # Custom tool name for the LLM+ description="Search the product catalog with optional category filtering.", # Custom description+ tags={"catalog", "search"}, # Optional tags for organization/filtering+)+def search_products_implementation(query: str, category: str | None = None) -> list[dict]:+ """Internal function description (ignored if description is provided above)."""+ # Implementation...+ print(f"Searching for '{query}' in category '{category}'")+ return [{"id": 2, "name": "Another Product"}]+```++<Card icon="code" title="@tool Decorator Arguments">+<ParamField body="name" type="str | None">+ Sets the explicit tool name exposed via MCP. If not provided, uses the function name+</ParamField>++<ParamField body="description" type="str | None">+ Provides the description exposed via MCP. If set, the function's docstring is ignored for this purpose+</ParamField>++<ParamField body="tags" type="set[str] | None">+ A set of strings to categorize the tool. Clients might use tags to filter or group available tools+</ParamField>++<ParamField body="enabled" type="bool" default="True">+ A boolean to enable or disable the tool. See [Disabling Tools](#disabling-tools) for more information+</ParamField>++<ParamField body="exclude_args" type="list[str] | None">+ A list of argument names to exclude from the tool schema shown to the LLM. See [Excluding Arguments](#excluding-arguments) for more information+</ParamField>++<ParamField body="annotations" type="ToolAnnotations | dict | None">+ An optional `ToolAnnotations` object or dictionary to add additional metadata about the tool.+ <Expandable title="ToolAnnotations attributes">+ <ParamField body="title" type="str | None">+ A human-readable title for the tool.+ </ParamField>+ <ParamField body="readOnlyHint" type="bool | None">+ If true, the tool does not modify its environment.+ </ParamField>+ <ParamField body="destructiveHint" type="bool | None">+ If true, the tool may perform destructive updates to its environment.+ </ParamField>+ <ParamField body="idempotentHint" type="bool | None">+ If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment.+ </ParamField>+ <ParamField body="openWorldHint" type="bool | None">+ If true, this tool may interact with an "open world" of external entities. If false, the tool's domain of interaction is closed.+ </ParamField>+ </Expandable>+</ParamField>+</Card>+### Tool Parameters++#### Type AnnotationsType annotations for parameters are essential for proper tool functionality. They:1. Inform the LLM about the expected data types for each parameter@@ -150,28 +209,6 @@ def search_products(In this example, the LLM must provide a `query` parameter, while `max_results`, `sort_by`, and `category` will use their default values if not explicitly provided.-### Metadata--While FastMCP infers the name and description from your function, you can override these and add tags using arguments to the `@mcp.tool` decorator:--```python- name="find_products", # Custom tool name for the LLM- description="Search the product catalog with optional category filtering.", # Custom description- tags={"catalog", "search"}, # Optional tags for organization/filtering-)-def search_products_implementation(query: str, category: str | None = None) -> list[dict]:- """Internal function description (ignored if description is provided above)."""- # Implementation...- print(f"Searching for '{query}' in category '{category}'")- return [{"id": 2, "name": "Another Product"}]-```--- **`name`**: Sets the explicit tool name exposed via MCP.-- **`description`**: Provides the description exposed via MCP. If set, the function's docstring is ignored for this purpose.-- **`tags`**: A set of strings to categorize the tool. Clients *might* use tags to filter or group available tools.-- **`enabled`**: A boolean to enable or disable the tool (defaults to `True`). See [Disabling Tools](#disabling-tools) for more information.-- **`exclude_args`**: A list of argument names to exclude from the tool schema shown to the LLM. See [Excluding Arguments](#excluding-arguments) for more information.### Excluding Arguments