feat: introduce fastmcp.json configuration system (#1517)

examples/atproto_mcp/fastmcp.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
+  "entrypoint": "src/atproto_mcp/server.py",
+  "environment": {
+    "dependencies": [
+      "atproto_mcp@git+https://github.com/jlowin/fastmcp.git#subdirectory=examples/atproto_mcp"
+    ]
+  }
+}

examples/atproto_mcp/src/atproto_mcp/server.py

@@ -22,12 +22,7 @@ from atproto_mcp.types import (
 )
 from fastmcp import FastMCP
 
-atproto_mcp = FastMCP(
-    "ATProto MCP Server",
-    dependencies=[
-        "atproto_mcp@git+https://github.com/jlowin/fastmcp.git#subdirectory=examples/atproto_mcp",
-    ],
-)
+atproto_mcp = FastMCP("ATProto MCP Server")
 
 
 # Resources - read-only operations

examples/fastmcp_config/env_interpolation_example.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
+  "entrypoint": "src/server.py:app",
+  "environment": {
+    "python": "3.12",
+    "dependencies": ["fastmcp", "httpx", "pandas"]
+  },
+  "deployment": {
+    "transport": "http",
+    "host": "0.0.0.0",
+    "port": 8000,
+    "env": {
+      "API_BASE_URL": "https://api.${ENVIRONMENT}.example.com",
+      "DATABASE_URL": "postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}",
+      "CACHE_PREFIX": "myapp_${ENVIRONMENT}_v1",
+      "LOG_LEVEL": "${LOG_LEVEL}",
+      "FEATURE_FLAGS": "${FEATURE_FLAGS}"
+    }
+  }
+}

examples/fastmcp_config/fastmcp.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp/v1.json",
+  "entrypoint": "server.py",
+  "environment": {
+    "python": "3.12",
+    "dependencies": ["requests"]
+  },
+  "deployment": {
+    "transport": "stdio"
+  }
+}

examples/fastmcp_config/full_example.fastmcp.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
+  "entrypoint": {
+    "file": "server.py",
+    "object": "mcp"
+  },
+  "environment": {
+    "python": "3.12",
+    "dependencies": [
+      "requests>=2.31.0",
+      "httpx"
+    ],
+    "requirements": null,
+    "project": null,
+    "editable": null
+  },
+  "deployment": {
+    "transport": "http",
+    "host": "127.0.0.1",
+    "port": 8000,
+    "path": "/mcp/",
+    "log_level": "INFO",
+    "env": {
+      "DEBUG": "false",
+      "API_TIMEOUT": "30"
+    },
+    "cwd": null,
+    "args": null
+  }
+}

examples/fastmcp_config/server.py

@@ -0,0 +1,39 @@
+"""Example FastMCP server for demonstrating fastmcp.json configuration."""
+
+from fastmcp import FastMCP
+
+# Create the FastMCP server instance
+mcp = FastMCP("Config Example Server")
+
+
+@mcp.tool
+def echo(text: str) -> str:
+    """Echo the provided text back to the user."""
+    return f"You said: {text}"
+
+
+@mcp.tool
+def add(a: int, b: int) -> int:
+    """Add two numbers together."""
+    return a + b
+
+
+@mcp.resource("config://example")
+def get_example_config() -> str:
+    """Return an example configuration."""
+    return """
+    This server is configured using fastmcp.json.
+    
+    The configuration file specifies:
+    - Python version
+    - Dependencies
+    - Transport settings
+    - Other runtime options
+    """
+
+
+# This allows the server to run with: fastmcp run server.py
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(mcp.run_async())

examples/fastmcp_config/simple.fastmcp.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp/v1.json",
+  "entrypoint": "server.py",
+  "deployment": {
+    "transport": "stdio"
+  }
+}

examples/fastmcp_config_demo/README.md

@@ -0,0 +1,55 @@
+# FastMCP Configuration Demo
+
+This example demonstrates the recommended way to configure FastMCP servers using `fastmcp.json`.
+
+## Migration from Dependencies Parameter
+
+Previously (deprecated as of FastMCP 2.11.4), you would specify dependencies in the Python code:
+
+```python
+mcp = FastMCP("Demo Server", dependencies=["pyautogui", "Pillow"])
+```
+
+Now, dependencies are declared in `fastmcp.json`:
+
+```json
+{
+  "environment": {
+    "dependencies": ["pyautogui", "Pillow"]
+  }
+}
+```
+
+## Running the Server
+
+With the configuration file in place, you can run the server in several ways:
+
+```bash
+# Auto-detect fastmcp.json in current directory
+cd examples/fastmcp_config_demo
+fastmcp run
+
+# Or specify the config file explicitly
+fastmcp run examples/fastmcp_config_demo/fastmcp.json
+
+# Or use development mode with the Inspector UI
+fastmcp dev examples/fastmcp_config_demo/fastmcp.json
+```
+
+## Benefits
+
+- **Single source of truth**: All configuration in one place
+- **Environment isolation**: Dependencies are installed in an isolated UV environment
+- **No import-time issues**: Dependencies are installed before the server is imported
+- **IDE support**: JSON schema provides autocomplete and validation
+- **Shareable**: Easy to share complete server configuration with others
+
+## Configuration Structure
+
+The `fastmcp.json` file supports three main sections:
+
+1. **entrypoint** (required): The Python file containing your server
+2. **environment** (optional): Python version and dependencies
+3. **deployment** (optional): Runtime settings like transport and logging
+
+See the [full documentation](https://gofastmcp.com/docs/deployment/server-configuration) for more details.

examples/fastmcp_config_demo/fastmcp.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
+  "entrypoint": "server.py",
+  "environment": {
+    "python": "3.11",
+    "dependencies": [
+      "pyautogui",
+      "Pillow"
+    ]
+  },
+  "deployment": {
+    "transport": "stdio",
+    "log_level": "INFO"
+  }
+}

examples/fastmcp_config_demo/server.py

@@ -0,0 +1,70 @@
+"""
+Example server demonstrating fastmcp.json configuration.
+
+This server previously would have used the deprecated dependencies parameter:
+    mcp = FastMCP("Demo Server", dependencies=["pyautogui", "Pillow"])
+
+Now dependencies are declared in fastmcp.json alongside this file.
+"""
+
+import io
+
+from fastmcp import FastMCP
+from fastmcp.utilities.types import Image
+
+# Create server - dependencies are now in fastmcp.json
+mcp = FastMCP("Screenshot Demo")
+
+
+@mcp.tool
+def take_screenshot() -> Image:
+    """
+    Take a screenshot of the user's screen and return it as an image.
+
+    Use this tool anytime the user wants you to look at something on their screen.
+    """
+    import pyautogui
+
+    buffer = io.BytesIO()
+
+    # Capture and compress the screenshot to stay under size limits
+    screenshot = pyautogui.screenshot()
+    screenshot.convert("RGB").save(buffer, format="JPEG", quality=60, optimize=True)
+
+    return Image(data=buffer.getvalue(), format="jpeg")
+
+
+@mcp.tool
+def analyze_colors() -> dict:
+    """
+    Analyze the dominant colors in the current screen.
+
+    Returns a dictionary with color statistics from the screen.
+    """
+    import pyautogui
+    from PIL import Image as PILImage
+
+    screenshot = pyautogui.screenshot()
+    # Convert to smaller size for faster analysis
+    small = screenshot.resize((100, 100), PILImage.Resampling.LANCZOS)
+
+    # Get colors
+    colors = small.getcolors(maxcolors=10000)
+    if not colors:
+        return {"error": "Too many colors to analyze"}
+
+    # Sort by frequency
+    sorted_colors = sorted(colors, key=lambda x: x[0], reverse=True)[:10]
+
+    return {
+        "top_colors": [
+            {"count": count, "rgb": color} for count, color in sorted_colors
+        ],
+        "total_pixels": sum(c[0] for c in colors),
+    }
+
+
+if __name__ == "__main__":
+    import asyncio
+
+    asyncio.run(mcp.run_async())

examples/memory.fastmcp.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
+  "entrypoint": "memory.py",
+  "environment": {
+    "dependencies": [
+      "pydantic-ai-slim[openai]",
+      "asyncpg",
+      "numpy",
+      "pgvector"
+    ]
+  }
+}

examples/mount_example.fastmcp.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
+  "entrypoint": "mount_example.py"
+}

examples/mount_example.py

@@ -54,9 +54,7 @@ async def news_data():
 
 
 # Main application
-app = FastMCP(
-    "Main App", dependencies=["fastmcp@git+https://github.com/jlowin/fastmcp.git"]
-)
+app = FastMCP("Main App")
 
 
 @app.tool

examples/screenshot.fastmcp.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
+  "entrypoint": "screenshot.py",
+  "environment": {
+    "dependencies": ["pyautogui", "Pillow"]
+  }
+}

examples/smart_home/hub.fastmcp.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
+  "entrypoint": "src/smart_home/hub.py",
+  "environment": {
+    "dependencies": [
+      "smart_home@git+https://github.com/jlowin/fastmcp.git#subdirectory=examples/smart_home"
+    ]
+  }
+}

examples/smart_home/lights.fastmcp.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://gofastmcp.com/schemas/fastmcp_config/v1.json",
+  "entrypoint": "src/smart_home/lights/server.py",
+  "environment": {
+    "dependencies": [
+      "smart_home@git+https://github.com/jlowin/fastmcp.git#subdirectory=examples/smart_home"
+    ]
+  }
+}