Improve fastmcp.json environment configuration and project-based deployments (#1631)

Author: jlowin

docs/deployment/server-configuration.mdx

@@ -165,10 +165,14 @@ These settings leverage standard `uv` arguments for environment creation. When a
       ```
     </ParamField>
 
-    <ParamField body="editable" type="string">
-      Path to a package to install in editable/development mode. Useful for local development when you want changes to be reflected immediately.
+    <ParamField body="editable" type="list[string]">
+      List of paths to packages to install in editable/development mode. Useful for local development when you want changes to be reflected immediately. Supports multiple packages for monorepo setups or shared libraries.
       ```json
-      "editable": "."
+      "editable": ["."]
+      ```
+      Or with multiple packages:
+      ```json
+      "editable": [".", "../shared-lib", "/path/to/another-package"]
       ```
     </ParamField>
   </Expandable>
@@ -312,6 +316,20 @@ fastmcp run fastmcp.json --skip-source
 fastmcp run fastmcp.json --skip-env --skip-source
 ```
 
+### Pre-building Environments
+
+You can use `fastmcp project prepare` to create a persistent uv project with all dependencies pre-installed:
+
+```bash
+# Create a persistent environment
+fastmcp project prepare fastmcp.json --output-dir ./env
+
+# Use the pre-built environment to run the server
+fastmcp run fastmcp.json --project ./env
+```
+
+This pattern separates environment setup (slow) from server execution (fast), useful for deployment scenarios.
+
 ### Using an Existing Environment
 
 By default, FastMCP creates an isolated environment with `uv` based on your configuration. When you already have a suitable Python environment, use the `--skip-env` flag to skip environment creation:

docs/patterns/cli.mdx

@@ -22,6 +22,7 @@ fastmcp --help
 | `dev` | Run a server with the MCP Inspector for testing | **Supports:** Local files and fastmcp.json configs. **Deps:** Always runs via `uv run` subprocess (never uses your local environment); dependencies must be specified or available in a uv-managed project. With fastmcp.json: Uses configured dependencies |
 | `install` | Install a server in MCP client applications | **Supports:** Local files and fastmcp.json configs. **Deps:** Creates an isolated environment; dependencies must be explicitly specified with `--with` and/or `--with-editable`. With fastmcp.json: Uses configured dependencies |
 | `inspect` | Generate a JSON report about a FastMCP server | **Supports:** Local files and fastmcp.json configs. **Deps:** Uses your current environment; you are responsible for ensuring all dependencies are available |
+| `project prepare` | Create a persistent uv project from fastmcp.json environment config | **Supports:** fastmcp.json configs only. **Deps:** Creates a uv project directory with all dependencies pre-installed for reuse with `--project` flag |
 | `version` | Display version information | N/A |
 
 ## `fastmcp run`
@@ -473,6 +474,37 @@ fastmcp inspect server.py:my_server
 fastmcp inspect server.py --output analysis.json
 ```
 
+## `fastmcp project prepare`
+
+Create a persistent uv project directory from a fastmcp.json file's environment configuration. This allows you to pre-install all dependencies once and reuse them with the `--project` flag.
+
+```bash
+fastmcp project prepare fastmcp.json --output-dir ./env
+```
+
+### Options
+
+| Option | Flag | Description |
+| ------ | ---- | ----------- |
+| Output Directory | `--output-dir` | **Required.** Directory where the persistent uv project will be created |
+
+### Usage Pattern
+
+```bash
+# Step 1: Prepare the environment (installs dependencies)
+fastmcp project prepare fastmcp.json --output-dir ./my-env
+
+# Step 2: Run using the prepared environment (fast, no dependency installation)
+fastmcp run fastmcp.json --project ./my-env
+```
+
+The prepare command creates a uv project with:
+- A `pyproject.toml` containing all dependencies from the fastmcp.json
+- A `.venv` with all packages pre-installed
+- A `uv.lock` file for reproducible environments
+
+This is useful when you want to separate environment setup from server execution, such as in deployment scenarios where dependencies are installed once and the server is run multiple times.
+
 ## `fastmcp version`
 
 Display version information about FastMCP and related components.

src/fastmcp/cli/claude.py

@@ -101,7 +101,7 @@ def update_claude_config(
         # Build uv run command using Environment.build_uv_args()
         env_config = Environment(
             dependencies=deduplicated_packages,
-            editable=str(with_editable) if with_editable else None,
+            editable=[str(with_editable)] if with_editable else None,
         )
         args = env_config.build_uv_args()
 

src/fastmcp/cli/cli.py

@@ -229,9 +229,11 @@ async def dev(
                 if config.environment.requirements
                 else None
             )
+            # Note: config.environment.editable is a list, but CLI only supports single path
+            # Take the first editable path if available
             with_editable = with_editable or (
-                Path(config.environment.editable)
-                if config.environment.editable
+                Path(config.environment.editable[0])
+                if config.environment.editable and config.environment.editable[0]
                 else None
             )
 
@@ -303,7 +305,7 @@ async def dev(
             dependencies=with_packages if with_packages else None,
             requirements=str(with_requirements) if with_requirements else None,
             project=str(project) if project else None,
-            editable=str(with_editable) if with_editable else None,
+            editable=[str(with_editable)] if with_editable else None,
         )
         uv_cmd = ["uv"] + env_config.build_uv_args(["fastmcp", "run", server_spec])
 
@@ -415,19 +417,19 @@ async def run(
             help="Requirements file to install dependencies from",
         ),
     ] = None,
-    skip_env: Annotated[
+    skip_source: Annotated[
         bool,
         cyclopts.Parameter(
-            "--skip-env",
-            help="Skip environment setup with uv (use when already in a uv environment)",
+            "--skip-source",
+            help="Skip source preparation step (use when source is already prepared)",
             negative="",
         ),
     ] = False,
-    skip_source: Annotated[
+    skip_env: Annotated[
         bool,
         cyclopts.Parameter(
-            "--skip-source",
-            help="Skip source preparation step (use when source is already prepared)",
+            "--skip-env",
+            help="Skip environment configuration (for internal use when already in a uv environment)",
             negative="",
         ),
     ] = False,
@@ -509,7 +511,8 @@ async def run(
                             )
 
                         # Merge environment config with CLI values (CLI takes precedence)
-                        if config.environment:
+                        # BUT: Skip this if --skip-env is set
+                        if config.environment and not skip_env:
                             python = python or config.environment.python
                             project = project or (
                                 Path(config.environment.project)
@@ -552,12 +555,10 @@ async def run(
     )
 
     # Check if we need to use uv run (either from CLI args or config)
-    # Skip if --skip-env flag is set (we're already in a uv environment)
-    needs_uv = not skip_env and (
-        python or with_packages or with_requirements or project or editable
-    )
-    if not skip_env and not needs_uv and config and config.environment:
-        # Check if config's environment needs uv
+    # When --skip-env is set, we ignore config.environment entirely
+    needs_uv = python or with_packages or with_requirements or project or editable
+    if not needs_uv and config and config.environment and not skip_env:
+        # Check if config's environment needs uv (but only if not skipping env)
         needs_uv = config.environment.needs_uv()
 
     if needs_uv:
@@ -818,6 +819,101 @@ async def inspect(
         sys.exit(1)
 
 
+# Create project subcommand group
+project_app = cyclopts.App(name="project", help="Manage FastMCP projects")
+
+
+@project_app.command
+async def prepare(
+    config_path: Annotated[
+        str | None,
+        cyclopts.Parameter(help="Path to fastmcp.json configuration file"),
+    ] = None,
+    output_dir: Annotated[
+        str | None,
+        cyclopts.Parameter(help="Directory to create the persistent environment in"),
+    ] = None,
+    skip_source: Annotated[
+        bool,
+        cyclopts.Parameter(help="Skip source preparation (e.g., git clone)"),
+    ] = False,
+) -> None:
+    """Prepare a FastMCP project by creating a persistent uv environment.
+
+    This command creates a persistent uv project with all dependencies installed:
+    - Creates a pyproject.toml with dependencies from the config
+    - Installs all Python packages into a .venv
+    - Prepares the source (git clone, download, etc.) unless --skip-source
+
+    After running this command, you can use:
+    fastmcp run <config> --project <output-dir>
+
+    This is useful for:
+    - CI/CD pipelines with separate build and run stages
+    - Docker images where you prepare during build
+    - Production deployments where you want fast startup times
+
+    Example:
+        fastmcp project prepare myserver.json --output-dir ./prepared-env
+        fastmcp run myserver.json --project ./prepared-env
+    """
+    from pathlib import Path
+
+    from fastmcp.utilities.fastmcp_config import FastMCPConfig
+
+    # Require output-dir
+    if output_dir is None:
+        logger.error(
+            "The --output-dir parameter is required.\n"
+            "Please specify where to create the persistent environment."
+        )
+        sys.exit(1)
+
+    # Auto-detect fastmcp.json if not provided
+    if config_path is None:
+        found_config = FastMCPConfig.find_config()
+        if found_config:
+            config_path = str(found_config)
+            logger.info(f"Using configuration from {config_path}")
+        else:
+            logger.error(
+                "No configuration file specified and no fastmcp.json found.\n"
+                "Please specify a configuration file or create a fastmcp.json."
+            )
+            sys.exit(1)
+
+    config_file = Path(config_path)
+    if not config_file.exists():
+        logger.error(f"Configuration file not found: {config_path}")
+        sys.exit(1)
+
+    output_path = Path(output_dir)
+
+    try:
+        # Load the configuration
+        config = FastMCPConfig.from_file(config_file)
+
+        # Prepare environment and source
+        await config.prepare(
+            skip_source=skip_source,
+            output_dir=output_path,
+        )
+
+        console.print(
+            f"[bold green]✓[/bold green] Project prepared successfully in {output_path}!\n"
+            f"You can now run the server with:\n"
+            f"  [cyan]fastmcp run {config_path} --project {output_dir}[/cyan]"
+        )
+
+    except Exception as e:
+        logger.error(f"Failed to prepare project: {e}")
+        console.print(f"[bold red]✗[/bold red] Failed to prepare project: {e}")
+        sys.exit(1)
+
+
+# Add project subcommand group
+app.command(project_app)
+
 # Add install subcommands using proper Cyclopts pattern
 app.command(install_app)
 

src/fastmcp/cli/install/claude_code.py

@@ -121,7 +121,7 @@ def install_claude_code(
         dependencies=deduplicated_packages,
         requirements=str(with_requirements) if with_requirements else None,
         project=str(project) if project else None,
-        editable=str(with_editable) if with_editable else None,
+        editable=[str(with_editable)] if with_editable else None,
     )
     args = env_config.build_uv_args()
 

src/fastmcp/cli/install/claude_desktop.py

@@ -86,7 +86,7 @@ def install_claude_desktop(
         dependencies=deduplicated_packages,
         requirements=str(with_requirements) if with_requirements else None,
         project=str(project) if project else None,
-        editable=str(with_editable) if with_editable else None,
+        editable=[str(with_editable)] if with_editable else None,
     )
     args = env_config.build_uv_args()
 

src/fastmcp/cli/install/cursor.py

@@ -120,7 +120,7 @@ def install_cursor_workspace(
         dependencies=deduplicated_packages,
         requirements=str(with_requirements.resolve()) if with_requirements else None,
         project=str(project.resolve()) if project else None,
-        editable=str(with_editable.resolve()) if with_editable else None,
+        editable=[str(with_editable.resolve())] if with_editable else None,
     )
     args = env_config.build_uv_args()
 
@@ -200,7 +200,7 @@ def install_cursor(
         dependencies=deduplicated_packages,
         requirements=str(with_requirements.resolve()) if with_requirements else None,
         project=str(project.resolve()) if project else None,
-        editable=str(with_editable.resolve()) if with_editable else None,
+        editable=[str(with_editable.resolve())] if with_editable else None,
     )
     args = env_config.build_uv_args()
 

src/fastmcp/cli/install/mcp_json.py

@@ -61,7 +61,7 @@ def install_mcp_json(
             dependencies=deduplicated_packages,
             requirements=str(with_requirements) if with_requirements else None,
             project=str(project) if project else None,
-            editable=str(with_editable) if with_editable else None,
+            editable=[str(with_editable)] if with_editable else None,
         )
         args = env_config.build_uv_args()