π The fast, Pythonic way to build MCP servers and clients.
Add `fastmcp generate-cli` command (#3065)
Jeremiah Lowin4262cfc16a0d
diff --git a/docs/clients/generate-cli.mdx b/docs/clients/generate-cli.mdxnew file mode 100644index 000000000..833637423--- /dev/null+++ b/docs/clients/generate-cli.mdx@@ -0,0 +1,129 @@+---+title: Generate CLI+sidebarTitle: Generate CLI+description: Turn any MCP server into a standalone, typed command-line tool.+icon: wand-magic-sparkles+---++import { VersionBadge } from '/snippets/version-badge.mdx'++<VersionBadge version="3.0.0" />++`fastmcp list` and `fastmcp call` let you poke at a server interactively, but they're developer tools β you always have to spell out the server spec, the tool name, and the arguments. `fastmcp generate-cli` takes the next step: it connects to a server, reads its schemas, and writes a standalone Python script where every tool is a proper subcommand with typed flags, help text, and tab completion. The result is a CLI that feels like it was hand-written for that specific server.++The key insight is that MCP tool schemas already contain everything a CLI framework needs: parameter names, types, descriptions, required/optional status, and defaults. `generate-cli` maps that schema into [cyclopts](https://cyclopts.readthedocs.io/) commands, so JSON Schema types become Python type annotations, descriptions become `--help` text, and required parameters become mandatory flags.++## Generating a Script++Point the command at any server spec β URLs, Python files, discovered server names, MCPConfig JSON β and it writes a CLI script:++```bash+fastmcp generate-cli weather+fastmcp generate-cli http://localhost:8000/mcp+fastmcp generate-cli server.py my_weather_cli.py+```++The second positional argument sets the output path. When omitted, it defaults to `cli.py`. If the file already exists, the command refuses to overwrite unless you pass `-f`:++```bash+fastmcp generate-cli weather -f+fastmcp generate-cli weather my_cli.py -f+```++Name-based resolution works here too, so if you have a server configured in Claude Desktop, Cursor, or any other supported editor, you can reference it by name. Run [`fastmcp discover`](/clients/cli#discovering-configured-servers) to see what's available.++```bash+fastmcp generate-cli claude-code:my-server output.py+```++The `--timeout` and `--auth` flags work the same way they do in `fastmcp list` and `fastmcp call`.++## What You Get++The generated script is a regular Python file β executable, editable, and yours. Here's what it looks like in practice:++```+$ python cli.py --help+Usage: weather-cli COMMAND++CLI for weather MCP server++Commands:+ call-tool Call a tool on the server+ list-tools List available tools.+ list-resources List available resources.+ read-resource Read a resource by URI.+ list-prompts List available prompts.+ get-prompt Get a prompt by name. Pass arguments as key=value pairs.+```++The `call-tool` subcommand is where the generated code lives. Each tool on the server becomes its own command:++```+$ python cli.py call-tool --help+Usage: weather-cli call-tool COMMAND++Call a tool on the server++Commands:+ get_forecast Get the weather forecast for a city.+ search_city Search for a city by name.+```++And each tool has typed parameters with help text pulled directly from the server's schema:++```+$ python cli.py call-tool get_forecast --help+Usage: weather-cli call-tool get_forecast [OPTIONS]++Get the weather forecast for a city.++Options:+ --city [str] City name (required)+ --days [int] Number of forecast days (default: 3)+```++Tool names are preserved exactly as the server defines them β underscores stay as underscores, so `call-tool get_forecast` matches what the server expects.++## How It Works++The generated script is a client, not a server. It doesn't bundle or embed the MCP server β it connects to it on every invocation. For URL-based servers, the server needs to be running. For stdio-based servers, the command specified in `CLIENT_SPEC` must be available on the system's `PATH`.++At the top of the generated file, a `CLIENT_SPEC` variable holds the resolved transport: either a URL string or a `StdioTransport` with the command and arguments baked in. Every invocation connects through this spec, so the script works without any external configuration.++### Parameter Handling++Parameters are mapped intelligently based on their complexity:++**Simple types** (`string`, `integer`, `number`, `boolean`) become typed Python parameters with clean flags:+```bash+python cli.py call-tool get_forecast --city London --days 3+```++**Arrays of simple types** (`array` with `string`/`integer`/`number`/`boolean` items) become `list[T]` parameters that accept multiple flags:+```bash+python cli.py call-tool tag_items --tags python --tags fastapi --tags mcp+```++**Complex types** (objects, nested arrays, or unions) accept JSON strings. The tool's `--help` displays the full JSON schema so you know exactly what structure to pass:+```bash+python cli.py call-tool create_user \+ --name John \+ --metadata '{"role": "admin", "dept": "engineering"}'+```++Required parameters are mandatory flags; optional ones default to their schema default or `None`. Empty values are filtered out before calling the server.++Beyond tool commands, the script includes generic commands that work regardless of what the server exposes: `list-tools`, `list-resources`, `read-resource`, `list-prompts`, and `get-prompt`. These connect to the server at runtime, so they always reflect the server's current state even if the tools have changed since generation.++## Editing the Output++The most common edit is changing `CLIENT_SPEC`. If you generated from a local dev server and want to point at production, just change the string. If you generated from a discovered name and want to pin the transport, replace it with an explicit URL or `StdioTransport`.++Beyond that, it's a regular Python file. You can add commands, change the output formatting, integrate it into a larger application, or strip out the parts you don't need. The helper functions (`_call_tool`, `_print_tool_result`) are thin wrappers around `fastmcp.Client` that are easy to adapt.++The generated script requires `fastmcp` as a dependency. If the script lives outside a project that already has fastmcp installed, `uv run` is the easiest way to run it without permanent installation:++```bash+uv run --with fastmcp python cli.py call-tool get_forecast --city London+```diff --git a/docs/docs.json b/docs/docs.jsonindex b7f26ab6b..916fa2640 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -169,6 +169,7 @@"pages": ["clients/client","clients/cli",+ "clients/generate-cli","clients/transports",{"group": "Core Operations",diff --git a/src/fastmcp/cli/cli.py b/src/fastmcp/cli/cli.pyindex 85b9d9ff5..147d9dc2d 100644--- a/src/fastmcp/cli/cli.py+++ b/src/fastmcp/cli/cli.py@@ -20,6 +20,7 @@ from rich.table import Tableimport fastmcpfrom fastmcp.cli import run as run_modulefrom fastmcp.cli.client import call_command, discover_command, list_command+from fastmcp.cli.generate import generate_cli_commandfrom fastmcp.cli.install import install_appfrom fastmcp.cli.tasks import tasks_appfrom fastmcp.utilities.cli import is_already_in_uv_subprocess, load_and_merge_config@@ -957,6 +958,7 @@ app.command(tasks_app)app.command(list_command, name="list")app.command(call_command, name="call")app.command(discover_command, name="discover")+app.command(generate_cli_command, name="generate-cli")if __name__ == "__main__":diff --git a/src/fastmcp/cli/generate.py b/src/fastmcp/cli/generate.pynew file mode 100644index 000000000..7fdc6cd8a--- /dev/null+++ b/src/fastmcp/cli/generate.py@@ -0,0 +1,634 @@+"""Generate a standalone CLI script from an MCP server's capabilities."""++import keyword+import re+import sys+import textwrap+from pathlib import Path+from typing import Annotated, Any+from urllib.parse import urlparse++import cyclopts+import mcp.types+import pydantic_core+from mcp import McpError+from rich.console import Console++from fastmcp.cli.client import _build_client, resolve_server_spec+from fastmcp.client.transports.base import ClientTransport+from fastmcp.client.transports.stdio import StdioTransport+from fastmcp.utilities.logging import get_logger++logger = get_logger("cli.generate")+console = Console()++# ---------------------------------------------------------------------------+# JSON Schema type β Python type string+# ---------------------------------------------------------------------------++_SIMPLE_TYPES = {"string", "integer", "number", "boolean", "null"}+++def _is_simple_type(schema: dict[str, Any]) -> bool:+ """Check if a schema represents a simple (non-complex) type."""+ schema_type = schema.get("type")+ if isinstance(schema_type, list):+ # Union of types - simple only if all are simple+ return all(t in _SIMPLE_TYPES for t in schema_type)+ return schema_type in _SIMPLE_TYPES+++def _is_simple_array(schema: dict[str, Any]) -> tuple[bool, str | None]:+ """Check if schema is an array of simple types.++ Returns (is_simple_array, item_type_str).+ """+ if schema.get("type") != "array":+ return False, None++ items = schema.get("items", {})+ if not _is_simple_type(items):+ return False, None++ # Map JSON Schema type to Python type+ item_type = items.get("type", "string")+ if isinstance(item_type, list):+ return False, None+ type_map = {+ "string": "str",+ "integer": "int",+ "number": "float",+ "boolean": "bool",+ }+ py_type = type_map.get(item_type)+ if py_type is None:+ return False, None+ return True, py_type+++def _schema_to_python_type(schema: dict[str, Any]) -> tuple[str, bool]:+ """Convert a JSON Schema to a Python type annotation.++ Returns (type_annotation, needs_json_parsing).+ """+ # Check for simple array first+ is_simple_arr, item_type = _is_simple_array(schema)+ if is_simple_arr:+ return f"list[{item_type}]", False++ # Check for simple type+ if _is_simple_type(schema):+ schema_type = schema.get("type", "string")+ if isinstance(schema_type, list):+ # Union of simple types+ type_map = {+ "string": "str",+ "integer": "int",+ "number": "float",+ "boolean": "bool",+ "null": "None",+ }+ parts = [type_map.get(t, "str") for t in schema_type]+ return " | ".join(parts), False++ type_map = {+ "string": "str",+ "integer": "int",+ "number": "float",+ "boolean": "bool",+ "null": "None",+ }+ return type_map.get(schema_type, "str"), False++ # Complex type - needs JSON parsing+ return "str", True+++def _format_schema_for_help(schema: dict[str, Any]) -> str:+ """Format a JSON schema for display in help text."""+ # Pretty print the schema, indented for help text+ schema_str = pydantic_core.to_json(schema, indent=2).decode()+ # Indent each line for help text alignment+ lines = schema_str.split("\n")+ indented = "\n ".join(lines)+ return f"JSON Schema: {indented}"+++# ---------------------------------------------------------------------------+# Transport serialization+# ---------------------------------------------------------------------------+++def serialize_transport(+ resolved: str | dict[str, Any] | ClientTransport,+) -> tuple[str, set[str]]:+ """Serialize a resolved transport to a Python expression string.++ Returns ``(expression, extra_imports)`` where *extra_imports* is a set of+ import lines needed by the expression.+ """+ if isinstance(resolved, str):+ return repr(resolved), set()++ if isinstance(resolved, StdioTransport):+ parts = [f"command={resolved.command!r}", f"args={resolved.args!r}"]+ if resolved.env:+ parts.append(f"env={resolved.env!r}")+ if resolved.cwd:+ parts.append(f"cwd={resolved.cwd!r}")+ expr = f"StdioTransport({', '.join(parts)})"+ imports = {"from fastmcp.client.transports import StdioTransport"}+ return expr, imports++ if isinstance(resolved, dict):+ return repr(resolved), set()++ # Fallback: try repr+ return repr(resolved), set()+++# ---------------------------------------------------------------------------+# Per-tool code generation+# ---------------------------------------------------------------------------+++def _to_python_identifier(name: str) -> str:+ """Sanitize a string into a valid Python identifier."""+ safe = re.sub(r"[^a-zA-Z0-9_]", "_", name)+ if safe and safe[0].isdigit():+ safe = f"_{safe}"+ safe = safe or "_unnamed"+ if keyword.iskeyword(safe):+ safe = f"{safe}_"+ return safe+++def _tool_function_source(tool: mcp.types.Tool) -> str:+ """Generate the source for a single ``@call_tool_app.command`` function."""+ schema = tool.inputSchema+ properties: dict[str, Any] = schema.get("properties", {})+ required = set(schema.get("required", []))++ # Build parameter lines and track which need JSON parsing+ param_lines: list[str] = []+ call_args: list[str] = []+ json_params: list[tuple[str, str]] = [] # (prop_name, safe_name)+ seen_names: dict[str, str] = {} # safe_name -> original prop_name++ for prop_name, prop_schema in properties.items():+ py_type, needs_json = _schema_to_python_type(prop_schema)+ help_text = prop_schema.get("description", "")+ is_required = prop_name in required+ safe_name = _to_python_identifier(prop_name)++ # Check for name collisions after sanitization+ if safe_name in seen_names:+ raise ValueError(+ f"Parameter name collision: '{prop_name}' and '{seen_names[safe_name]}' "+ f"both sanitize to '{safe_name}'"+ )+ seen_names[safe_name] = prop_name++ # For complex types, add schema to help text+ if needs_json:+ schema_help = _format_schema_for_help(prop_schema)+ help_text = f"{help_text}\\n{schema_help}" if help_text else schema_help+ json_params.append((prop_name, safe_name))++ # Escape special characters in help text+ help_escaped = (+ help_text.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")+ )++ # Build parameter annotation+ if is_required:+ annotation = (+ f'Annotated[{py_type}, cyclopts.Parameter(help="{help_escaped}")]'+ )+ param_lines.append(f" {safe_name}: {annotation},")+ else:+ default = prop_schema.get("default")+ if default is not None:+ # For complex types with defaults, serialize to JSON string+ if needs_json:+ default_str = pydantic_core.to_json(default, fallback=str).decode()+ annotation = f'Annotated[{py_type}, cyclopts.Parameter(help="{help_escaped}")]'+ param_lines.append(+ f" {safe_name}: {annotation} = {default_str!r},"+ )+ else:+ annotation = f'Annotated[{py_type}, cyclopts.Parameter(help="{help_escaped}")]'+ param_lines.append(f" {safe_name}: {annotation} = {default!r},")+ else:+ # For list types, default to empty list; others default to None+ if py_type.startswith("list["):+ annotation = f'Annotated[{py_type}, cyclopts.Parameter(help="{help_escaped}")]'+ param_lines.append(f" {safe_name}: {annotation} = [],")+ else:+ annotation = f'Annotated[{py_type} | None, cyclopts.Parameter(help="{help_escaped}")]'+ param_lines.append(f" {safe_name}: {annotation} = None,")++ call_args.append(f"{prop_name!r}: {safe_name}")++ # Function name: sanitize to valid Python identifier+ fn_name = _to_python_identifier(tool.name)++ # Docstring - use single-quoted docstrings to avoid triple-quote escaping issues+ description = (tool.description or "").replace("\\", "\\\\").replace("'", "\\'")++ lines = []+ lines.append("")+ # Always pass name= to preserve the original tool name (cyclopts+ # would otherwise convert underscores to hyphens).+ lines.append(f"@call_tool_app.command(name={tool.name!r})")+ lines.append(f"async def {fn_name}(")++ if param_lines:+ lines.append(" *,")+ lines.extend(param_lines)++ lines.append(") -> None:")+ lines.append(f" '''{description}'''")++ # Add JSON parsing for complex parameters+ if json_params:+ lines.append(" # Parse JSON parameters")+ for _prop_name, safe_name in json_params:+ lines.append(+ f" {safe_name}_parsed = json.loads({safe_name}) if isinstance({safe_name}, str) else {safe_name}"+ )+ lines.append("")++ # Build call arguments, using parsed versions for JSON params+ call_arg_parts = []+ for prop_name, _ in properties.items():+ safe_name = _to_python_identifier(prop_name)+ if any(pn == prop_name for pn, _ in json_params):+ call_arg_parts.append(f"{prop_name!r}: {safe_name}_parsed")+ else:+ call_arg_parts.append(f"{prop_name!r}: {safe_name}")++ dict_items = ", ".join(call_arg_parts)+ lines.append(f" await _call_tool({tool.name!r}, {{{dict_items}}})")+ lines.append("")++ return "\n".join(lines)+++# ---------------------------------------------------------------------------+# Full script generation+# ---------------------------------------------------------------------------+++def generate_cli_script(+ server_name: str,+ server_spec: str,+ transport_code: str,+ extra_imports: set[str],+ tools: list[mcp.types.Tool],+) -> str:+ """Generate the full CLI script source code."""++ # Determine app name from server_name - sanitize for use in string literal+ app_name = (+ server_name.replace(" ", "-").lower().replace("\\", "\\\\").replace('"', '\\"')+ )++ # --- Header ---+ lines: list[str] = []+ lines.append("#!/usr/bin/env python3")+ lines.append(f'"""CLI for {server_name} MCP server.')+ lines.append("")+ lines.append(f"Generated by: fastmcp generate-cli {server_spec}")+ lines.append('"""')+ lines.append("")++ # --- Imports ---+ lines.append("import json")+ lines.append("import sys")+ lines.append("from typing import Annotated")+ lines.append("")+ lines.append("import cyclopts")+ lines.append("import mcp.types")+ lines.append("from rich.console import Console")+ lines.append("")+ lines.append("from fastmcp import Client")+ for imp in sorted(extra_imports):+ lines.append(imp)+ lines.append("")++ # --- Transport config ---+ lines.append("# Modify this to change how the CLI connects to the MCP server.")+ lines.append(f"CLIENT_SPEC = {transport_code}")+ lines.append("")++ # --- App setup ---+ server_name_escaped = server_name.replace("\\", "\\\\").replace('"', '\\"')+ lines.append(+ f'app = cyclopts.App(name="{app_name}", help="CLI for {server_name_escaped} MCP server")'+ )+ lines.append(+ 'call_tool_app = cyclopts.App(name="call-tool", help="Call a tool on the server")'+ )+ lines.append("app.command(call_tool_app)")+ lines.append("")+ lines.append("console = Console()")+ lines.append("")+ lines.append("")++ # --- Shared helpers ---+ lines.append(+ textwrap.dedent("""\+ # ---------------------------------------------------------------------------+ # Helpers+ # ---------------------------------------------------------------------------+++ def _print_tool_result(result):+ if result.is_error:+ for block in result.content:+ if isinstance(block, mcp.types.TextContent):+ console.print(f"[bold red]Error:[/bold red] {block.text}")+ else:+ console.print(f"[bold red]Error:[/bold red] {block}")+ sys.exit(1)++ if result.structured_content is not None:+ console.print_json(json.dumps(result.structured_content))+ return++ for block in result.content:+ if isinstance(block, mcp.types.TextContent):+ console.print(block.text)+ elif isinstance(block, mcp.types.ImageContent):+ size = len(block.data) * 3 // 4+ console.print(f"[dim][Image: {block.mimeType}, ~{size} bytes][/dim]")+ elif isinstance(block, mcp.types.AudioContent):+ size = len(block.data) * 3 // 4+ console.print(f"[dim][Audio: {block.mimeType}, ~{size} bytes][/dim]")+++ async def _call_tool(tool_name: str, arguments: dict) -> None:+ # Filter out None values and empty lists (defaults for optional array params)+ filtered = {+ k: v+ for k, v in arguments.items()+ if v is not None and (not isinstance(v, list) or len(v) > 0)+ }+ async with Client(CLIENT_SPEC) as client:+ result = await client.call_tool(tool_name, filtered, raise_on_error=False)+ _print_tool_result(result)+ if result.is_error:+ sys.exit(1)""")+ )+ lines.append("")+ lines.append("")++ # --- Generic commands ---+ lines.append(+ textwrap.dedent("""\+ # ---------------------------------------------------------------------------+ # List / read commands+ # ---------------------------------------------------------------------------+++ @app.command+ async def list_tools() -> None:+ \"\"\"List available tools.\"\"\"+ async with Client(CLIENT_SPEC) as client:+ tools = await client.list_tools()+ if not tools:+ console.print("[dim]No tools found.[/dim]")+ return+ for tool in tools:+ sig_parts = []+ props = tool.inputSchema.get("properties", {})+ required = set(tool.inputSchema.get("required", []))+ for pname, pschema in props.items():+ ptype = pschema.get("type", "string")+ if pname in required:+ sig_parts.append(f"{pname}: {ptype}")+ else:+ sig_parts.append(f"{pname}: {ptype} = ...")+ sig = f"{tool.name}({', '.join(sig_parts)})"+ console.print(f" [cyan]{sig}[/cyan]")+ if tool.description:+ console.print(f" {tool.description}")+ console.print()+++ @app.command+ async def list_resources() -> None:+ \"\"\"List available resources.\"\"\"+ async with Client(CLIENT_SPEC) as client:+ resources = await client.list_resources()+ if not resources:+ console.print("[dim]No resources found.[/dim]")+ return+ for r in resources:+ console.print(f" [cyan]{r.uri}[/cyan]")+ desc_parts = [r.name or "", r.description or ""]+ desc = " β ".join(p for p in desc_parts if p)+ if desc:+ console.print(f" {desc}")+ console.print()+++ @app.command+ async def read_resource(uri: Annotated[str, cyclopts.Parameter(help="Resource URI")]) -> None:+ \"\"\"Read a resource by URI.\"\"\"+ async with Client(CLIENT_SPEC) as client:+ contents = await client.read_resource(uri)+ for block in contents:+ if isinstance(block, mcp.types.TextResourceContents):+ console.print(block.text)+ elif isinstance(block, mcp.types.BlobResourceContents):+ size = len(block.blob) * 3 // 4+ console.print(f"[dim][Blob: {block.mimeType}, ~{size} bytes][/dim]")+++ @app.command+ async def list_prompts() -> None:+ \"\"\"List available prompts.\"\"\"+ async with Client(CLIENT_SPEC) as client:+ prompts = await client.list_prompts()+ if not prompts:+ console.print("[dim]No prompts found.[/dim]")+ return+ for p in prompts:+ args_str = ""+ if p.arguments:+ parts = [a.name for a in p.arguments]+ args_str = f"({', '.join(parts)})"+ console.print(f" [cyan]{p.name}{args_str}[/cyan]")+ if p.description:+ console.print(f" {p.description}")+ console.print()+++ @app.command+ async def get_prompt(+ name: Annotated[str, cyclopts.Parameter(help="Prompt name")],+ *arguments: str,+ ) -> None:+ \"\"\"Get a prompt by name. Pass arguments as key=value pairs.\"\"\"+ parsed: dict[str, str] = {}+ for arg in arguments:+ if "=" not in arg:+ console.print(f"[bold red]Error:[/bold red] Invalid argument {arg!r} β expected key=value")+ sys.exit(1)+ key, value = arg.split("=", 1)+ parsed[key] = value++ async with Client(CLIENT_SPEC) as client:+ result = await client.get_prompt(name, parsed or None)+ for msg in result.messages:+ console.print(f"[bold]{msg.role}:[/bold]")+ if isinstance(msg.content, mcp.types.TextContent):+ console.print(f" {msg.content.text}")+ elif isinstance(msg.content, mcp.types.ImageContent):+ size = len(msg.content.data) * 3 // 4+ console.print(f" [dim][Image: {msg.content.mimeType}, ~{size} bytes][/dim]")+ else:+ console.print(f" {msg.content}")+ console.print()""")+ )+ lines.append("")+ lines.append("")++ # --- Generated tool commands ---+ if tools:+ lines.append(+ "# ---------------------------------------------------------------------------"+ )+ lines.append("# Tool commands (generated from server schema)")+ lines.append(+ "# ---------------------------------------------------------------------------"+ )++ for tool in tools:+ lines.append(_tool_function_source(tool))++ # --- Entry point ---+ lines.append("")+ lines.append('if __name__ == "__main__":')+ lines.append(" app()")+ lines.append("")++ return "\n".join(lines)+++# ---------------------------------------------------------------------------+# CLI command+# ---------------------------------------------------------------------------+++async def generate_cli_command(+ server_spec: Annotated[+ str,+ cyclopts.Parameter(+ help="Server URL, Python file, MCPConfig JSON, discovered name, or .js file",+ ),+ ],+ output: Annotated[+ str,+ cyclopts.Parameter(+ help="Output file path (default: cli.py)",+ ),+ ] = "cli.py",+ *,+ force: Annotated[+ bool,+ cyclopts.Parameter(+ name=["-f", "--force"],+ help="Overwrite output file if it exists",+ ),+ ] = False,+ timeout: Annotated[+ float | None,+ cyclopts.Parameter("--timeout", help="Connection timeout in seconds"),+ ] = None,+ auth: Annotated[+ str | None,+ cyclopts.Parameter(+ "--auth",+ help="Auth method: 'oauth', a bearer token string, or 'none' to disable",+ ),+ ] = None,+) -> None:+ """Generate a standalone CLI script from an MCP server.++ Connects to the server, reads its tools/resources/prompts, and writes+ a Python script that can invoke them directly.++ Examples:+ fastmcp generate-cli weather+ fastmcp generate-cli weather my_cli.py+ fastmcp generate-cli http://localhost:8000/mcp+ fastmcp generate-cli server.py output.py -f+ """+ output_path = Path(output)+ if output_path.exists() and not force:+ console.print(+ f"[bold red]Error:[/bold red] [cyan]{output_path}[/cyan] already exists. "+ f"Use [cyan]-f[/cyan] to overwrite."+ )+ sys.exit(1)++ # Resolve the server spec to a transport+ resolved = resolve_server_spec(server_spec)+ transport_code, extra_imports = serialize_transport(resolved)++ # Derive a human-friendly server name from the spec+ server_name = _derive_server_name(server_spec)++ # Connect and discover capabilities+ client = _build_client(resolved, timeout=timeout, auth=auth)++ try:+ async with client:+ tools = await client.list_tools()+ console.print(+ f"[dim]Discovered {len(tools)} tool(s) from {server_spec}[/dim]"+ )++ except (RuntimeError, TimeoutError, McpError, OSError) as exc:+ console.print(f"[bold red]Error:[/bold red] Could not connect: {exc}")+ sys.exit(1)++ # Generate and write the script+ script = generate_cli_script(+ server_name=server_name,+ server_spec=server_spec,+ transport_code=transport_code,+ extra_imports=extra_imports,+ tools=tools,+ )++ output_path.write_text(script)+ output_path.chmod(output_path.stat().st_mode | 0o111) # make executable++ console.print(+ f"[green]β[/green] Wrote [cyan]{output_path}[/cyan] "+ f"with {len(tools)} tool command(s)"+ )+ console.print(f"[dim]Run: python {output_path} --help[/dim]")+++def _derive_server_name(server_spec: str) -> str:+ """Derive a human-friendly name from a server spec."""+ # URL β use hostname+ if server_spec.startswith(("http://", "https://")):+ parsed = urlparse(server_spec)+ return parsed.hostname or "server"++ # File path β use stem+ if server_spec.endswith((".py", ".js", ".json")):+ return Path(server_spec).stem++ # Bare name or qualified name+ if ":" in server_spec:+ name = server_spec.split(":", 1)[1]+ return name or server_spec.split(":", 1)[0]++ return server_specdiff --git a/tests/cli/test_generate_cli.py b/tests/cli/test_generate_cli.pynew file mode 100644index 000000000..f513338d7--- /dev/null+++ b/tests/cli/test_generate_cli.py@@ -0,0 +1,638 @@+"""Tests for fastmcp generate-cli command."""++import sys+from pathlib import Path+from typing import Any+from unittest.mock import patch++import mcp.types+import pytest++from fastmcp import FastMCP+from fastmcp.cli import generate as generate_module+from fastmcp.cli.client import Client+from fastmcp.cli.generate import (+ _derive_server_name,+ _schema_to_python_type,+ _to_python_identifier,+ _tool_function_source,+ generate_cli_command,+ generate_cli_script,+ serialize_transport,+)+from fastmcp.client.transports.stdio import StdioTransport++# ---------------------------------------------------------------------------+# _schema_to_python_type+# ---------------------------------------------------------------------------+++class TestSchemaToPythonType:+ def test_simple_string(self):+ py_type, needs_json = _schema_to_python_type({"type": "string"})+ assert py_type == "str"+ assert needs_json is False++ def test_simple_integer(self):+ py_type, needs_json = _schema_to_python_type({"type": "integer"})+ assert py_type == "int"+ assert needs_json is False++ def test_simple_number(self):+ py_type, needs_json = _schema_to_python_type({"type": "number"})+ assert py_type == "float"+ assert needs_json is False++ def test_simple_boolean(self):+ py_type, needs_json = _schema_to_python_type({"type": "boolean"})+ assert py_type == "bool"+ assert needs_json is False++ def test_array_of_strings(self):+ py_type, needs_json = _schema_to_python_type(+ {"type": "array", "items": {"type": "string"}}+ )+ assert py_type == "list[str]"+ assert needs_json is False++ def test_array_of_integers(self):+ py_type, needs_json = _schema_to_python_type(+ {"type": "array", "items": {"type": "integer"}}+ )+ assert py_type == "list[int]"+ assert needs_json is False++ def test_complex_object(self):+ py_type, needs_json = _schema_to_python_type({"type": "object"})+ assert py_type == "str"+ assert needs_json is True++ def test_complex_nested_array(self):+ py_type, needs_json = _schema_to_python_type(+ {"type": "array", "items": {"type": "object"}}+ )+ assert py_type == "str"+ assert needs_json is True++ def test_union_of_simple_types(self):+ py_type, needs_json = _schema_to_python_type({"type": ["string", "null"]})+ assert py_type == "str | None"+ assert needs_json is False+++# ---------------------------------------------------------------------------+# _to_python_identifier+# ---------------------------------------------------------------------------+++class TestToPythonIdentifier:+ def test_plain_name(self):+ assert _to_python_identifier("hello") == "hello"++ def test_hyphens(self):+ assert _to_python_identifier("get-forecast") == "get_forecast"++ def test_dots_and_slashes(self):+ assert _to_python_identifier("a.b/c") == "a_b_c"++ def test_leading_digit(self):+ assert _to_python_identifier("3d_render") == "_3d_render"++ def test_spaces(self):+ assert _to_python_identifier("my tool") == "my_tool"++ def test_empty_string(self):+ assert _to_python_identifier("") == "_unnamed"+++# ---------------------------------------------------------------------------+# serialize_transport+# ---------------------------------------------------------------------------+++class TestSerializeTransport:+ def test_url_string(self):+ code, imports = serialize_transport("http://localhost:8000/mcp")+ assert code == "'http://localhost:8000/mcp'"+ assert imports == set()++ def test_stdio_transport_basic(self):+ transport = StdioTransport(command="fastmcp", args=["run", "server.py"])+ code, imports = serialize_transport(transport)+ assert "StdioTransport" in code+ assert "command='fastmcp'" in code+ assert "args=['run', 'server.py']" in code+ assert "from fastmcp.client.transports import StdioTransport" in imports++ def test_stdio_transport_with_env(self):+ transport = StdioTransport(+ command="python", args=["-m", "myserver"], env={"KEY": "val"}+ )+ code, imports = serialize_transport(transport)+ assert "env={'KEY': 'val'}" in code++ def test_dict_passthrough(self):+ d: dict[str, Any] = {"mcpServers": {"test": {"url": "http://localhost"}}}+ code, imports = serialize_transport(d)+ assert "mcpServers" in code+ assert imports == set()+++# ---------------------------------------------------------------------------+# _tool_function_source+# ---------------------------------------------------------------------------+++class TestToolFunctionSource:+ def test_required_param(self):+ tool = mcp.types.Tool(+ name="greet",+ inputSchema={+ "properties": {"name": {"type": "string", "description": "Who"}},+ "required": ["name"],+ },+ )+ source = _tool_function_source(tool)+ assert "async def greet(" in source+ assert "name: Annotated[str" in source+ assert "= None" not in source+ assert "_call_tool('greet', {'name': name})" in source++ def test_optional_param(self):+ tool = mcp.types.Tool(+ name="search",+ inputSchema={+ "properties": {+ "query": {"type": "string", "description": "Search query"},+ "limit": {"type": "integer", "description": "Max results"},+ },+ "required": ["query"],+ },+ )+ source = _tool_function_source(tool)+ assert "query: Annotated[str" in source+ assert "limit: Annotated[int | None" in source+ assert "= None" in source++ def test_param_with_default(self):+ tool = mcp.types.Tool(+ name="fetch",+ inputSchema={+ "properties": {+ "url": {"type": "string", "description": "URL"},+ "timeout": {+ "type": "integer",+ "description": "Timeout",+ "default": 30,+ },+ },+ "required": ["url"],+ },+ )+ source = _tool_function_source(tool)+ assert "timeout: Annotated[int" in source+ assert "= 30" in source++ def test_no_params(self):+ tool = mcp.types.Tool(+ name="ping",+ inputSchema={"properties": {}},+ )+ source = _tool_function_source(tool)+ assert "async def ping(" in source+ assert "_call_tool('ping', {})" in source++ def test_preserves_underscores(self):+ tool = mcp.types.Tool(+ name="get_forecast",+ inputSchema={+ "properties": {"city": {"type": "string"}},+ "required": ["city"],+ },+ )+ source = _tool_function_source(tool)+ assert "async def get_forecast(" in source++ def test_sanitizes_tool_name(self):+ tool = mcp.types.Tool(+ name="my.tool/v2",+ inputSchema={"properties": {}},+ )+ source = _tool_function_source(tool)+ assert "async def my_tool_v2(" in source+ assert "name='my.tool/v2'" in source++ def test_sanitizes_param_name(self):+ tool = mcp.types.Tool(+ name="fetch",+ inputSchema={+ "properties": {"content-type": {"type": "string", "description": "CT"}},+ "required": ["content-type"],+ },+ )+ source = _tool_function_source(tool)+ assert "content_type: Annotated[str" in source+ assert "'content-type': content_type" in source++ def test_description_in_docstring(self):+ tool = mcp.types.Tool(+ name="greet",+ description="Say hello to someone.",+ inputSchema={+ "properties": {"name": {"type": "string"}},+ "required": ["name"],+ },+ )+ source = _tool_function_source(tool)+ assert "'''Say hello to someone.'''" in source++ def test_description_with_quotes(self):+ tool = mcp.types.Tool(+ name="fetch",+ description="Fetch data from 'source' API.",+ inputSchema={+ "properties": {"url": {"type": "string"}},+ "required": ["url"],+ },+ )+ source = _tool_function_source(tool)+ # Should escape single quotes in the description+ assert r"Fetch data from \'source\' API." in source+ # Generated code should compile+ compile(source, "<test>", "exec")++ def test_array_of_strings_parameter(self):+ tool = mcp.types.Tool(+ name="tag_items",+ description="Tag multiple items.",+ inputSchema={+ "properties": {+ "item_id": {"type": "string"},+ "tags": {"type": "array", "items": {"type": "string"}},+ },+ "required": ["item_id"],+ },+ )+ source = _tool_function_source(tool)+ # Should use list[str] type with help metadata+ assert "tags: Annotated[list[str]" in source+ assert "= []" in source+ # Should not have JSON parsing for simple arrays+ assert "json.loads" not in source+ compile(source, "<test>", "exec")++ def test_complex_object_parameter(self):+ tool = mcp.types.Tool(+ name="create_user",+ description="Create a user.",+ inputSchema={+ "properties": {+ "name": {"type": "string"},+ "metadata": {+ "type": "object",+ "properties": {+ "role": {"type": "string"},+ "dept": {"type": "string"},+ },+ },+ },+ "required": ["name"],+ },+ )+ source = _tool_function_source(tool)+ # Should use str type for complex object+ assert "metadata: Annotated[str | None" in source+ # Should include JSON schema in help (with escaped quotes)+ assert "JSON Schema:" in source+ assert '\\"type\\": \\"object\\"' in source+ # Should have JSON parsing with isinstance check+ assert (+ "metadata_parsed = json.loads(metadata) if isinstance(metadata, str) else metadata"+ in source+ )+ # Should use parsed version in call+ assert "'metadata': metadata_parsed" in source+ compile(source, "<test>", "exec")++ def test_nested_array_parameter(self):+ tool = mcp.types.Tool(+ name="batch_process",+ description="Process batches.",+ inputSchema={+ "properties": {+ "batches": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {"id": {"type": "string"}},+ },+ },+ },+ "required": ["batches"],+ },+ )+ source = _tool_function_source(tool)+ # Nested arrays need JSON parsing+ assert "batches: Annotated[str" in source+ assert "JSON Schema:" in source+ assert (+ "batches_parsed = json.loads(batches) if isinstance(batches, str) else batches"+ in source+ )+ compile(source, "<test>", "exec")++ def test_complex_type_with_default(self):+ """Test that complex types with defaults are JSON-serialized."""+ tool = mcp.types.Tool(+ name="configure",+ inputSchema={+ "properties": {+ "options": {+ "type": "object",+ "default": {"timeout": 30, "retry": True},+ },+ },+ },+ )+ source = _tool_function_source(tool)+ # Default should be JSON string, not Python dict+ # pydantic_core.to_json produces compact JSON+ assert '= \'{"timeout":30,"retry":true}\'' in source+ # Should parse safely even with default+ assert "isinstance(options, str)" in source+ compile(source, "<test>", "exec")++ def test_name_collision_detection(self):+ """Test that parameter name collisions are detected."""+ tool = mcp.types.Tool(+ name="test",+ inputSchema={+ "properties": {+ "content-type": {"type": "string"},+ "content_type": {"type": "string"},+ },+ },+ )+ # Should raise ValueError for collision+ with pytest.raises(ValueError, match="both sanitize to 'content_type'"):+ _tool_function_source(tool)+++# ---------------------------------------------------------------------------+# _derive_server_name+# ---------------------------------------------------------------------------+++class TestDeriveServerName:+ def test_bare_name(self):+ assert _derive_server_name("weather") == "weather"++ def test_qualified_name(self):+ assert _derive_server_name("cursor:weather") == "weather"++ def test_python_file(self):+ assert _derive_server_name("server.py") == "server"++ def test_url(self):+ assert _derive_server_name("http://localhost:8000/mcp") == "localhost"++ def test_trailing_colon(self):+ assert _derive_server_name("source:") == "source"+++# ---------------------------------------------------------------------------+# generate_cli_script β produces compilable Python+# ---------------------------------------------------------------------------+++class TestGenerateCliScript:+ def _make_tools(self) -> list[mcp.types.Tool]:+ return [+ mcp.types.Tool(+ name="greet",+ description="Say hello",+ inputSchema={+ "properties": {+ "name": {"type": "string", "description": "Who to greet"},+ },+ "required": ["name"],+ },+ ),+ mcp.types.Tool(+ name="add_numbers",+ description="Add two numbers",+ inputSchema={+ "properties": {+ "a": {"type": "integer", "description": "First number"},+ "b": {"type": "integer", "description": "Second number"},+ },+ "required": ["a", "b"],+ },+ ),+ ]++ def test_compiles(self):+ script = generate_cli_script(+ server_name="test",+ server_spec="test",+ transport_code='"http://localhost:8000/mcp"',+ extra_imports=set(),+ tools=self._make_tools(),+ )+ compile(script, "<generated>", "exec")++ def test_contains_tool_functions(self):+ script = generate_cli_script(+ server_name="test",+ server_spec="test",+ transport_code='"http://localhost:8000/mcp"',+ extra_imports=set(),+ tools=self._make_tools(),+ )+ assert "async def greet(" in script+ assert "async def add_numbers(" in script++ def test_contains_generic_commands(self):+ script = generate_cli_script(+ server_name="test",+ server_spec="test",+ transport_code='"http://localhost:8000/mcp"',+ extra_imports=set(),+ tools=[],+ )+ assert "async def list_tools(" in script+ assert "async def list_resources(" in script+ assert "async def list_prompts(" in script+ assert "async def read_resource(" in script+ assert "async def get_prompt(" in script++ def test_embeds_transport(self):+ script = generate_cli_script(+ server_name="test",+ server_spec="test",+ transport_code="StdioTransport(command='fastmcp', args=['run', 'x.py'])",+ extra_imports={"from fastmcp.client.transports import StdioTransport"},+ tools=[],+ )+ assert "StdioTransport(command='fastmcp'" in script+ assert "from fastmcp.client.transports import StdioTransport" in script++ def test_no_tools_still_valid(self):+ script = generate_cli_script(+ server_name="empty",+ server_spec="empty",+ transport_code='"http://localhost"',+ extra_imports=set(),+ tools=[],+ )+ compile(script, "<generated>", "exec")+ assert "call_tool_app" in script++ def test_server_name_with_quotes(self):+ """Test that server names with quotes are properly escaped."""+ script = generate_cli_script(+ server_name='Test "Server" Name',+ server_spec="test",+ transport_code='"http://localhost"',+ extra_imports=set(),+ tools=[],+ )+ # Should compile without syntax errors+ compile(script, "<generated>", "exec")+ # App name should have escaped quotes+ assert r'app = cyclopts.App(name="test-\"server\"-name"' in script++ def test_compiles_with_unusual_names(self):+ tools = [+ mcp.types.Tool(+ name="my.tool/v2",+ description="A tool with dots and slashes",+ inputSchema={+ "properties": {+ "content-type": {"type": "string", "description": "CT"},+ },+ "required": ["content-type"],+ },+ ),+ ]+ script = generate_cli_script(+ server_name="test",+ server_spec="test",+ transport_code='"http://localhost:8000/mcp"',+ extra_imports=set(),+ tools=tools,+ )+ compile(script, "<generated>", "exec")++ def test_compiles_with_stdio_transport(self):+ transport = StdioTransport(command="fastmcp", args=["run", "server.py"])+ transport_code, extra_imports = serialize_transport(transport)+ script = generate_cli_script(+ server_name="test",+ server_spec="server.py",+ transport_code=transport_code,+ extra_imports=extra_imports,+ tools=self._make_tools(),+ )+ compile(script, "<generated>", "exec")+++# ---------------------------------------------------------------------------+# generate_cli_command β integration tests+# ---------------------------------------------------------------------------+++def _build_test_server() -> FastMCP:+ """Create a minimal FastMCP server for integration tests."""+ server = FastMCP("TestServer")++ @server.tool+ def greet(name: str) -> str:+ """Say hello to someone."""+ return f"Hello, {name}!"++ @server.tool+ def add(a: int, b: int) -> int:+ """Add two numbers."""+ return a + b++ @server.resource("test://greeting")+ def greeting_resource() -> str:+ """A static greeting resource."""+ return "Hello from resource!"++ @server.prompt+ def ask(topic: str) -> str:+ """Ask about a topic."""+ return f"Tell me about {topic}"++ return server+++def _patch_client():+ """Patch resolve_server_spec and _build_client to use an in-process server."""+ server = _build_test_server()++ def fake_resolve(server_spec: Any, **kwargs: Any) -> str:+ return "fake://server"++ def fake_build_client(resolved: Any, **kwargs: Any) -> Client:+ return Client(server)++ with (+ patch.object(generate_module, "resolve_server_spec", side_effect=fake_resolve),+ patch.object(generate_module, "_build_client", side_effect=fake_build_client),+ ):+ yield+++class TestGenerateCliCommand:+ @pytest.mark.usefixtures("_patch_client")+ async def test_writes_file(self, tmp_path: Path):+ output = tmp_path / "cli.py"+ await generate_cli_command("test-server", str(output))+ assert output.exists()+ content = output.read_text()+ compile(content, str(output), "exec")++ @pytest.mark.usefixtures("_patch_client")+ async def test_contains_tools(self, tmp_path: Path):+ output = tmp_path / "cli.py"+ await generate_cli_command("test-server", str(output))+ content = output.read_text()+ assert "async def greet(" in content+ assert "async def add(" in content++ @pytest.mark.usefixtures("_patch_client")+ async def test_default_output_path(+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+ ):+ monkeypatch.chdir(tmp_path)+ await generate_cli_command("test-server")+ assert (tmp_path / "cli.py").exists()++ @pytest.mark.usefixtures("_patch_client")+ async def test_error_if_exists(self, tmp_path: Path):+ output = tmp_path / "cli.py"+ output.write_text("existing")+ with pytest.raises(SystemExit):+ await generate_cli_command("test-server", str(output))++ @pytest.mark.usefixtures("_patch_client")+ async def test_force_overwrites(self, tmp_path: Path):+ output = tmp_path / "cli.py"+ output.write_text("existing")+ await generate_cli_command("test-server", str(output), force=True)+ content = output.read_text()+ assert content != "existing"+ assert "async def greet(" in content++ @pytest.mark.skipif(+ sys.platform == "win32", reason="Unix executable bits N/A on Windows"+ )+ @pytest.mark.usefixtures("_patch_client")+ async def test_file_is_executable(self, tmp_path: Path):+ output = tmp_path / "cli.py"+ await generate_cli_command("test-server", str(output))+ assert output.stat().st_mode & 0o111