create-mcp 0.1.0__py3-none-any.whl

create_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""create-mcp — scaffold production-ready Python MCP servers in one command."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# The FastMCP release the generated projects are pinned to / tested against.
+FASTMCP_TARGET = "3.4"
+
+__all__ = ["__version__", "FASTMCP_TARGET"]

create_mcp/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m create_mcp``."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

create_mcp/cli.py

@@ -0,0 +1,193 @@
+"""The ``create-mcp`` command-line interface."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+from rich.text import Text
+
+from . import FASTMCP_TARGET, __version__
+from .generator import GeneratorError, ProjectConfig, generate, to_package_name
+from .presets import DEFAULT_PRESET, PRESETS, preset_choices
+
+console = Console()
+err_console = Console(stderr=True)
+
+TRANSPORTS = ["streamable-http", "stdio"]
+AUTH_MODES = ["none", "oauth"]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"create-mcp {__version__} [dim](targets FastMCP {FASTMCP_TARGET}.x)[/dim]")
+        raise typer.Exit()
+
+
+def _run(cmd: list[str], cwd: Path) -> bool:
+    """Run a command, streaming nothing; return True on success, False otherwise."""
+    try:
+        subprocess.run(cmd, cwd=cwd, check=True, capture_output=True)
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def _maybe_git_init(target: Path) -> None:
+    if shutil.which("git") is None:
+        console.print("  [yellow]›[/yellow] git not found — skipping repository init")
+        return
+    if _run(["git", "init", "-q"], target) and _run(["git", "add", "-A"], target):
+        _run(["git", "commit", "-q", "-m", "Initial commit (create-mcp)"], target)
+        console.print("  [green]✓[/green] initialised git repository")
+    else:
+        console.print("  [yellow]›[/yellow] could not initialise git repository")
+
+
+def _maybe_uv_sync(target: Path) -> None:
+    if shutil.which("uv") is None:
+        console.print("  [yellow]›[/yellow] uv not found — skipping dependency install")
+        return
+    console.print("  [dim]…[/dim] installing dependencies with uv")
+    if _run(["uv", "sync"], target):
+        console.print("  [green]✓[/green] installed dependencies (uv sync)")
+    else:
+        console.print("  [yellow]›[/yellow] uv sync failed — run it yourself later")
+
+
+def _maybe_precommit(target: Path) -> None:
+    if shutil.which("git") is None or not (target / ".git").exists():
+        return
+    if shutil.which("uv") is not None and _run(["uv", "run", "pre-commit", "install"], target):
+        console.print("  [green]✓[/green] installed pre-commit hooks")
+
+
+def _prompt_choice(label: str, choices: list[str], default: str) -> str:
+    return Prompt.ask(f"[bold]{label}[/bold]", choices=choices, default=default)
+
+
+def create(  # noqa: C901 - the CLI orchestration is intentionally linear
+    project_name: str = typer.Argument(None, help="Name of the project / directory to create."),
+    preset: str = typer.Option(
+        None, "--preset", "-p", help=f"Preset: {', '.join(preset_choices())}."
+    ),
+    transport: str = typer.Option(
+        None, "--transport", "-t", help="Transport: streamable-http or stdio."
+    ),
+    auth: str = typer.Option(
+        None, "--auth", "-a", help="Auth mode: none or oauth (OAuth 2.1 resource server)."
+    ),
+    package_name: str = typer.Option(
+        None, "--package-name", help="Override the derived Python package name."
+    ),
+    description: str = typer.Option(None, "--description", help="One-line project description."),
+    output_dir: Path = typer.Option(
+        None, "--output-dir", "-o", help="Directory to create the project in (default: cwd)."
+    ),
+    do_git: bool = typer.Option(True, "--git/--no-git", help="Initialise a git repository."),
+    do_install: bool = typer.Option(
+        True, "--install/--no-install", help="Run `uv sync` after scaffolding."
+    ),
+    do_precommit: bool = typer.Option(
+        True, "--precommit/--no-precommit", help="Install pre-commit hooks."
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite a non-empty target directory."),
+    yes: bool = typer.Option(
+        False, "--yes", "-y", help="Accept all defaults; never prompt (CI / scripting)."
+    ),
+    _version: bool = typer.Option(
+        None, "--version", callback=_version_callback, is_eager=True, help="Show version."
+    ),
+) -> None:
+    """Scaffold a production-ready Python MCP server."""
+    interactive = not yes
+    output_dir = output_dir or Path.cwd()
+
+    def choose(label: str, choices: list[str], default: str, current: str | None) -> str:
+        if current is not None:
+            return current
+        return _prompt_choice(label, choices, default) if interactive else default
+
+    if not project_name:
+        if interactive:
+            project_name = Prompt.ask("[bold]Project name[/bold]", default="my-mcp-server")
+        else:
+            err_console.print("[red]error:[/red] project name is required with --yes")
+            raise typer.Exit(code=2)
+
+    preset = choose("Preset", preset_choices(), DEFAULT_PRESET, preset)
+    transport = choose("Transport", TRANSPORTS, "streamable-http", transport)
+    auth = choose("Auth", AUTH_MODES, "none", auth)
+
+    if interactive:
+        do_git = Confirm.ask("Initialise a git repository?", default=do_git)
+        do_install = Confirm.ask("Install dependencies now (uv sync)?", default=do_install)
+        if do_git:
+            do_precommit = Confirm.ask("Install pre-commit hooks?", default=do_precommit)
+
+    try:
+        config = ProjectConfig(
+            project_name=project_name,
+            preset=preset,
+            transport=transport,
+            auth=auth,
+            description=description or "",
+        )
+        if package_name:
+            # Validate + override the derived package name.
+            config.package_name = to_package_name(package_name)
+        target = output_dir / project_name
+        generate(config, target, force=force)
+    except GeneratorError as exc:
+        err_console.print(f"[red]error:[/red] {exc}")
+        raise typer.Exit(code=1) from exc
+
+    console.print()
+    console.print(
+        f"[green]✓[/green] Scaffolded [bold]{project_name}[/bold] "
+        f"[dim]({PRESETS[preset].title} · {transport} · auth: {auth})[/dim]"
+    )
+
+    if do_git:
+        _maybe_git_init(target)
+    if do_install:
+        _maybe_uv_sync(target)
+    if do_precommit:
+        _maybe_precommit(target)
+
+    _print_next_steps(config, target, output_dir)
+
+
+def _print_next_steps(config: ProjectConfig, target: Path, output_dir: Path) -> None:
+    rel = target.relative_to(output_dir) if target.is_relative_to(output_dir) else target
+    pkg = config.package_name
+    run_cmd = f"uv run {pkg}"
+    body = Text()
+    body.append("Next steps\n\n", style="bold")
+    body.append(f"  cd {rel}\n")
+    body.append("  uv sync                  ", style="cyan")
+    body.append("# install dependencies\n", style="dim")
+    body.append(f"  {run_cmd}{' ' * max(1, 17 - len(run_cmd))}", style="cyan")
+    body.append(f"# run the server ({config.transport})\n", style="dim")
+    body.append("  uv run pytest            ", style="cyan")
+    body.append("# run the test suite\n\n", style="dim")
+    body.append("Inspect it with the MCP Inspector:\n")
+    body.append(f"  npx @modelcontextprotocol/inspector uv run {pkg}\n", style="cyan")
+    if config.auth_enabled:
+        body.append("\nAuth is on. ", style="bold yellow")
+        body.append("Set OAUTH_* vars in .env (see .env.example) and point them at\n")
+        body.append("your identity provider (Keycloak / WorkOS / Auth0 / Azure).")
+    console.print(Panel(body, border_style="green", expand=False))
+
+
+def main() -> None:
+    typer.run(create)
+
+
+if __name__ == "__main__":
+    main()

create_mcp/generator.py

@@ -0,0 +1,178 @@
+"""The scaffolding engine: turn a :class:`ProjectConfig` into a project on disk.
+
+Templates live under ``templates/{base,presets/<preset>,auth}`` and are rendered
+with Jinja using *non-default* delimiters (``[[ ]]`` / ``[% %]``) so the template
+files can freely contain ``{{ }}`` and GitHub Actions ``${{ }}`` expressions
+verbatim. Path segments are de-tokenised:
+
+* ``__pkg__``   -> the Python package name
+* ``dot-foo``   -> ``.foo``           (ship dotfiles without leading dots)
+* trailing ``.jinja`` is stripped from the output filename
+"""
+
+from __future__ import annotations
+
+import datetime
+import keyword
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import jinja2
+
+from . import FASTMCP_TARGET, __version__
+from . import templates as _templates
+from .presets import PRESETS, preset_dirname
+
+TEMPLATES_DIR = Path(_templates.__file__).parent
+
+
+class GeneratorError(Exception):
+    """Raised when a project cannot be generated (bad name, target exists, ...)."""
+
+
+@dataclass
+class ProjectConfig:
+    """Everything needed to render a project."""
+
+    project_name: str
+    preset: str = "minimal"
+    transport: str = "streamable-http"
+    auth: str = "none"  # "none" | "oauth"
+    description: str = ""
+    author: str = ""
+    python_version: str = "3.11"
+
+    # Derived / filled in __post_init__.
+    package_name: str = field(default="", init=False)
+
+    def __post_init__(self) -> None:
+        self.package_name = to_package_name(self.project_name)
+        if self.preset not in PRESETS:
+            raise GeneratorError(
+                f"Unknown preset {self.preset!r}. Choose from: {', '.join(PRESETS)}"
+            )
+        if self.transport not in ("streamable-http", "stdio"):
+            raise GeneratorError(f"Unknown transport {self.transport!r}.")
+        if self.auth not in ("none", "oauth"):
+            raise GeneratorError(f"Unknown auth mode {self.auth!r}.")
+        if not self.description:
+            self.description = "A Model Context Protocol server, scaffolded with create-mcp."
+
+    @property
+    def auth_enabled(self) -> bool:
+        return self.auth == "oauth"
+
+    @property
+    def http(self) -> bool:
+        return self.transport == "streamable-http"
+
+    @property
+    def context(self) -> dict[str, object]:
+        """The variables exposed to templates."""
+        return {
+            "project_name": self.project_name,
+            "package_name": self.package_name,
+            "preset": self.preset,
+            "transport": self.transport,
+            "http": self.http,
+            "auth": self.auth,
+            "auth_enabled": self.auth_enabled,
+            "description": self.description,
+            "author": self.author or "your name",
+            "python_version": self.python_version,
+            "fastmcp_target": FASTMCP_TARGET,
+            "create_mcp_version": __version__,
+            "year": datetime.date.today().year,
+            "extra_dependencies": list(PRESETS[self.preset].extra_dependencies),
+        }
+
+
+def to_package_name(project_name: str) -> str:
+    """Turn an arbitrary project name into a valid, importable package name."""
+    slug = project_name.strip().lower()
+    slug = re.sub(r"[^0-9a-z]+", "_", slug)
+    slug = re.sub(r"_+", "_", slug).strip("_")
+    if not slug:
+        raise GeneratorError(f"Cannot derive a package name from {project_name!r}.")
+    if slug[0].isdigit():
+        slug = f"_{slug}"
+    if keyword.iskeyword(slug):
+        slug = f"{slug}_"
+    return slug
+
+
+def _layers(config: ProjectConfig) -> list[Path]:
+    """The template directories to overlay, in order (later wins)."""
+    layers = [TEMPLATES_DIR / "base", TEMPLATES_DIR / "presets" / preset_dirname(config.preset)]
+    if config.auth_enabled:
+        layers.append(TEMPLATES_DIR / "auth")
+    return layers
+
+
+def _detokenise(rel: Path, package_name: str) -> Path:
+    parts: list[str] = []
+    for seg in rel.parts:
+        if seg == "__pkg__":
+            seg = package_name
+        elif seg.startswith("dot-"):
+            seg = "." + seg[len("dot-") :]
+        if seg.endswith(".jinja"):
+            seg = seg[: -len(".jinja")]
+        parts.append(seg)
+    return Path(*parts)
+
+
+def _make_env(searchpath: Path) -> jinja2.Environment:
+    return jinja2.Environment(
+        loader=jinja2.FileSystemLoader(str(searchpath)),
+        variable_start_string="[[",
+        variable_end_string="]]",
+        block_start_string="[%",
+        block_end_string="%]",
+        comment_start_string="[#",
+        comment_end_string="#]",
+        keep_trailing_newline=True,
+        trim_blocks=True,
+        lstrip_blocks=True,
+        undefined=jinja2.StrictUndefined,
+        autoescape=False,
+    )
+
+
+def render_to_mapping(config: ProjectConfig) -> dict[str, str]:
+    """Render every template to an in-memory ``{relative_path: content}`` mapping.
+
+    Kept separate from disk I/O so the generator is trivially unit-testable.
+    """
+    context = config.context
+    files: dict[str, str] = {}
+    for layer in _layers(config):
+        if not layer.is_dir():
+            raise GeneratorError(f"Missing template layer: {layer}")
+        env = _make_env(layer)
+        for path in sorted(layer.rglob("*")):
+            if path.is_dir():
+                continue
+            rel = path.relative_to(layer)
+            template = env.get_template(rel.as_posix())
+            rendered = template.render(**context)
+            out_rel = _detokenise(rel, config.package_name).as_posix()
+            files[out_rel] = rendered
+    return files
+
+
+def generate(config: ProjectConfig, target_dir: Path, *, force: bool = False) -> Path:
+    """Write the rendered project to ``target_dir`` and return the project root."""
+    target_dir = target_dir.resolve()
+    if target_dir.exists() and any(target_dir.iterdir()) and not force:
+        raise GeneratorError(
+            f"Target directory {target_dir} already exists and is not empty. "
+            "Use --force to overwrite."
+        )
+    files = render_to_mapping(config)
+    for rel, content in files.items():
+        dest = target_dir / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content, encoding="utf-8")
+    return target_dir

create_mcp/presets.py

@@ -0,0 +1,57 @@
+"""Preset definitions for the kind of MCP server to scaffold.
+
+Each preset maps to a directory under ``templates/presets/<key>/`` that is
+overlaid on top of ``templates/base/`` to provide a purpose-built starting set
+of tools/resources/prompts. The default project layout is identical across
+presets — only the example ``tools.py`` (and its declared extra dependencies)
+differ.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Preset:
+    key: str
+    title: str
+    description: str
+    # Extra runtime dependencies the generated project needs for this preset.
+    extra_dependencies: tuple[str, ...] = field(default_factory=tuple)
+
+
+PRESETS: dict[str, Preset] = {
+    "minimal": Preset(
+        key="minimal",
+        title="Minimal",
+        description="A clean, typed server with one example tool, resource and prompt.",
+    ),
+    "api-wrapper": Preset(
+        key="api-wrapper",
+        title="API wrapper",
+        description="Wrap an existing HTTP/JSON API as MCP tools, with typed models.",
+        extra_dependencies=("httpx>=0.27",),
+    ),
+    "db": Preset(
+        key="db",
+        title="Database",
+        description="Expose a SQLite-backed store as typed MCP tools (CRUD example).",
+    ),
+    "agent-tools": Preset(
+        key="agent-tools",
+        title="Agent tools",
+        description="A toolbox for autonomous agents: calculator, scratchpad memory, clock.",
+    ),
+}
+
+DEFAULT_PRESET = "minimal"
+
+
+def preset_dirname(key: str) -> str:
+    """Template directory name for a preset key (hyphens -> underscores)."""
+    return key.replace("-", "_")
+
+
+def preset_choices() -> list[str]:
+    return list(PRESETS)

create_mcp/templates/__init__.py

@@ -0,0 +1,7 @@
+"""Project templates rendered by the create-mcp generator.
+
+This package only exists so that the template tree ships inside the wheel and
+can be located at runtime via ``Path(create_mcp.templates.__file__).parent``.
+The files under ``base/``, ``presets/`` and ``auth/`` are Jinja templates, not
+importable Python.
+"""

create_mcp/templates/auth/src/__pkg__/auth.py.jinja

@@ -0,0 +1,34 @@
+"""OAuth 2.1 resource-server wiring for [[ project_name ]].
+
+This server validates JWT access tokens issued by an *external* Authorization
+Server and advertises its requirements via RFC 9728 Protected Resource Metadata
+(``/.well-known/oauth-protected-resource``). Unauthenticated requests get a 401
+with a ``WWW-Authenticate`` challenge pointing at that metadata, so MCP clients
+can discover the authorization server and complete the OAuth flow automatically.
+
+Point the ``MCP_OAUTH_*`` settings at your IdP (Keycloak, WorkOS AuthKit, Auth0,
+Microsoft Entra, ...). The defaults are placeholders that let the server boot
+and serve discovery metadata offline.
+"""
+
+from __future__ import annotations
+
+from fastmcp.server.auth import RemoteAuthProvider
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from pydantic import AnyHttpUrl
+
+from .settings import Settings
+
+
+def build_auth(settings: Settings) -> RemoteAuthProvider:
+    """Construct the resource-server auth provider from settings."""
+    token_verifier = JWTVerifier(
+        jwks_uri=settings.oauth_jwks_uri,
+        issuer=settings.oauth_issuer,
+        audience=settings.oauth_audience,
+    )
+    return RemoteAuthProvider(
+        token_verifier=token_verifier,
+        authorization_servers=[AnyHttpUrl(settings.oauth_issuer)],
+        base_url=settings.base_url,
+    )

create_mcp/templates/auth/tests/test_auth.py.jinja

@@ -0,0 +1,44 @@
+"""Tests for the OAuth 2.1 resource-server behaviour.
+
+These drive the ASGI app directly (via httpx's ASGITransport) so they are fast
+and deterministic — no real server, no network, no external identity provider.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from starlette.applications import Starlette
+
+from [[ package_name ]].server import mcp
+
+# RFC 9728 Protected Resource Metadata is served at the resource-path-aware
+# location; the MCP endpoint is mounted at /mcp.
+PRM_PATH = "/.well-known/oauth-protected-resource/mcp"
+
+
+@pytest.fixture
+def http_app() -> Starlette:
+    return mcp.http_app()
+
+
+async def test_protected_resource_metadata_is_served(http_app: Starlette) -> None:
+    transport = httpx.ASGITransport(app=http_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+        response = await client.get(PRM_PATH)
+    assert response.status_code == 200
+    data = response.json()
+    assert data["resource"]
+    assert data["authorization_servers"]
+
+
+async def test_unauthenticated_request_is_rejected(http_app: Starlette) -> None:
+    transport = httpx.ASGITransport(app=http_app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
+        response = await client.post(
+            "/mcp",
+            json={"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}},
+            headers={"Accept": "application/json, text/event-stream"},
+        )
+    assert response.status_code == 401
+    assert "WWW-Authenticate" in response.headers

create_mcp/templates/base/Dockerfile.jinja

@@ -0,0 +1,32 @@
+# syntax=docker/dockerfile:1
+#
+# uv-based image for [[ project_name ]]. Builds the locked environment and runs
+# the MCP server over Streamable HTTP. (uv.lock is optional here — it is picked
+# up automatically if you have committed it, which is recommended.)
+FROM ghcr.io/astral-sh/uv:python[[ python_version ]]-bookworm-slim
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=0
+
+WORKDIR /app
+
+# Install dependencies first for better layer caching.
+COPY pyproject.toml uv.lock* ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --no-dev --no-install-project
+
+# Then install the project itself.
+COPY . .
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --no-dev
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    MCP_TRANSPORT=http \
+    MCP_HOST=0.0.0.0 \
+    MCP_PORT=8000
+
+EXPOSE 8000
+
+# Runs the console script defined in pyproject ([[ package_name ]]).
+CMD ["[[ package_name ]]"]

create_mcp/templates/base/LICENSE.jinja

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [[ year ]] [[ author ]]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.