mcpgen-cli 0.1.0__py3-none-any.whl

mcpgen/__init__.py

@@ -0,0 +1,5 @@
+"""mcpgen — Turn any API into an MCP server in 30 seconds."""
+
+__version__ = "0.1.0"
+__author__ = "JnanaSrota"
+__license__ = "MIT"

mcpgen/cli.py

@@ -0,0 +1,199 @@
+"""
+mcpgen CLI — main entry point.
+
+Usage:
+  mcpgen openapi.json
+  mcpgen https://petstore3.swagger.io/api/v3/openapi.json
+  mcpgen postman.json --output ./my-mcp
+  mcpgen openapi.yaml --dry-run
+"""
+
+from __future__ import annotations
+import time
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich import print as rprint
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+from rich import box
+
+from mcpgen import __version__
+from mcpgen.parser import load, LoaderError
+from mcpgen.generator import generate_python, generate_dry_run
+
+app = typer.Typer(
+    name="mcpgen",
+    help="Turn any API into an MCP server in 30 seconds.",
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+console = Console()
+
+
+def _version_callback(value: bool):
+    if value:
+        rprint(f"mcpgen v{__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+def main(
+    source: str = typer.Argument(
+        ...,
+        help="OpenAPI JSON/YAML file path, Postman collection, or URL",
+        metavar="INPUT",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output", "-o",
+        help="Output directory (default: current directory)",
+        metavar="DIR",
+    ),
+    name: Optional[str] = typer.Option(
+        None,
+        "--name", "-n",
+        help="Override the generated server name",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print generated code without writing files",
+    ),
+    no_color: bool = typer.Option(
+        False,
+        "--no-color",
+        help="Disable colored output",
+    ),
+    version: Optional[bool] = typer.Option(
+        None,
+        "--version", "-v",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit",
+    ),
+):
+    """
+    [bold cyan]mcpgen[/bold cyan] — Turn any API into an MCP server in 30 seconds.
+
+    Examples:
+      mcpgen openapi.json
+      mcpgen https://petstore3.swagger.io/api/v3/openapi.json
+      mcpgen stripe.yaml --output ./stripe-mcp
+      mcpgen postman.json --dry-run
+    """
+    
+    if no_color:
+        console._color_system = None
+    
+    # Header
+    console.print()
+    console.print(Panel(
+        f"[bold cyan]mcpgen[/bold cyan] [dim]v{__version__}[/dim]",
+        box=box.ROUNDED,
+        expand=False,
+        border_style="cyan",
+    ))
+    console.print()
+    
+    start = time.monotonic()
+    
+    # Step 1: Parse
+    with console.status("[cyan]Parsing[/cyan] " + source + " ..."):
+        try:
+            spec = load(source)
+        except LoaderError as e:
+            console.print(f"  [red]✗ Error:[/red] {e}")
+            raise typer.Exit(1)
+        except Exception as e:
+            console.print(f"  [red]✗ Unexpected error:[/red] {e}")
+            raise typer.Exit(1)
+    
+    console.print(f"  [dim]Parsed[/dim]   {source}")
+    
+    # Apply name override
+    if name:
+        spec = spec.model_copy(update={"name": name})
+    
+    # Step 2: Report what was found
+    console.print(f"  [dim]Found[/dim]    [bold]{len(spec.tools)}[/bold] tool{'s' if len(spec.tools) != 1 else ''} → MCP tools")
+    
+    if spec.auth_type != "none":
+        auth_display = {
+            "bearer": f"Bearer token  [dim](set [bold]{spec.auth_env_var}[/bold] env var)[/dim]",
+            "api_key": f"API Key       [dim](set [bold]{spec.auth_env_var}[/bold] env var)[/dim]",
+            "basic": f"Basic Auth    [dim](set [bold]{spec.auth_env_var}[/bold] env var)[/dim]",
+        }.get(spec.auth_type, spec.auth_type)
+        console.print(f"  [dim]Auth[/dim]     {auth_display}")
+    else:
+        console.print(f"  [dim]Auth[/dim]     None detected")
+    
+    # Step 3: Dry run or generate
+    if dry_run:
+        console.print()
+        console.print("[bold]Generated server.py:[/bold]")
+        console.print()
+        code = generate_dry_run(spec)
+        console.print(Syntax(code, "python", theme="monokai", line_numbers=True))
+        raise typer.Exit(0)
+    
+    # Step 4: Write files
+    output_dir = output or Path.cwd()
+    
+    with console.status("[cyan]Writing[/cyan] " + str(output_dir / spec.slug) + " ..."):
+        created = generate_python(spec, output_dir)
+    
+    console.print(f"  [dim]Wrote[/dim]    [bold]{output_dir / spec.slug}/[/bold]")
+    
+    # Step 5: Summary
+    elapsed = time.monotonic() - start
+    console.print()
+    
+    # Tool list (up to 10)
+    if spec.tools:
+        table = Table(box=box.SIMPLE, show_header=False, padding=(0, 1))
+        table.add_column("", style="dim")
+        table.add_column("")
+        for tool in spec.tools[:10]:
+            table.add_row("→", f"[bold]{tool.name}[/bold]  [dim]{tool.description[:60]}[/dim]")
+        if len(spec.tools) > 10:
+            table.add_row("", f"[dim]... and {len(spec.tools) - 10} more[/dim]")
+        console.print(table)
+        console.print()
+    
+    # Claude Desktop config snippet
+    server_path = output_dir / spec.slug / "server.py"
+    config_dict = {
+        "command": "python",
+        "args": [str(server_path)],
+    }
+    if spec.auth_env_var:
+        config_dict["env"] = {spec.auth_env_var: "your-key-here"}
+    
+    import json
+    config_json = json.dumps(
+        {spec.slug: config_dict},
+        indent=4
+    )
+    
+    console.print(Panel(
+        f"[bold]Add to Claude Desktop config:[/bold]\n\n"
+        f"[dim]~/Library/Application Support/Claude/claude_desktop_config.json[/dim]\n\n"
+        f'[green]{{"mcpServers": {{\n'
+        + "\n".join(f"  {line}" for line in config_json.splitlines())
+        + "\n}}}[/green]",
+        box=box.ROUNDED,
+        border_style="green",
+        expand=False,
+    ))
+    
+    console.print()
+    console.print(
+        f"  [bold green]Done[/bold green] in {elapsed:.1f}s  →  "
+        f"[dim]cd {spec.slug} && pip install -r requirements.txt && python server.py[/dim]"
+    )
+    console.print()

mcpgen/generator/__init__.py

@@ -0,0 +1,3 @@
+from .python import generate_python, generate_dry_run
+
+__all__ = ["generate_python", "generate_dry_run"]

mcpgen/generator/python.py

@@ -0,0 +1,90 @@
+"""
+Python MCP server generator.
+
+Consumes an MCPSpec (IR) and renders the Jinja2 templates
+into a complete, standalone Python MCP server directory.
+"""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from mcpgen.ir import MCPSpec
+
+# Path to templates dir relative to this file
+TEMPLATES_DIR = Path(__file__).parent.parent / "templates" / "python"
+
+# Module-level cached Jinja environment (created lazily)
+_JINJA_ENV: Optional[Environment] = None
+
+def _get_jinja_env() -> Environment:
+    global _JINJA_ENV
+    if _JINJA_ENV is None:
+        env = Environment(
+            loader=FileSystemLoader(str(TEMPLATES_DIR)),
+            autoescape=select_autoescape(["html"]),  # only for .html, not .py
+            trim_blocks=True,
+            lstrip_blocks=True,
+        )
+        # Custom filter: convert OpenAPI type to Python type hint
+        env.filters["python_type"] = _openapi_to_python_type
+        _JINJA_ENV = env
+    return _JINJA_ENV
+
+
+def _openapi_to_python_type(openapi_type: str) -> str:
+    mapping = {
+        "string": "str",
+        "integer": "int",
+        "number": "float",
+        "boolean": "bool",
+        "object": "dict",
+        "array": "list",
+    }
+    return mapping.get(openapi_type, "str")
+
+
+def generate_python(spec: MCPSpec, output_dir: Path) -> list[Path]:
+    """
+    Generate a Python MCP server from an MCPSpec.
+
+    Creates output_dir/{slug}/ with:
+      - server.py
+      - requirements.txt
+
+    Returns list of created file paths.
+    """
+    env = _get_jinja_env()
+
+    server_dir = output_dir / spec.slug
+    server_dir.mkdir(parents=True, exist_ok=True)
+
+    created_files: list[Path] = []
+
+    # Convert spec to a plain dict to reduce attribute lookup overhead inside Jinja
+    spec_dict = spec.model_dump()
+
+    # Render server.py
+    server_template = env.get_template("server.py.jinja2")
+    server_code = server_template.render(spec=spec_dict)
+    server_path = server_dir / "server.py"
+    server_path.write_text(server_code, encoding="utf-8")
+    created_files.append(server_path)
+
+    # Render requirements.txt
+    req_template = env.get_template("requirements.txt.jinja2")
+    req_text = req_template.render(spec=spec_dict)
+    req_path = server_dir / "requirements.txt"
+    req_path.write_text(req_text, encoding="utf-8")
+    created_files.append(req_path)
+
+    return created_files
+
+
+def generate_dry_run(spec: MCPSpec) -> str:
+    """Return the generated server.py as a string without writing to disk."""
+    env = _get_jinja_env()
+    template = env.get_template("server.py.jinja2")
+    return template.render(spec=spec.model_dump())

mcpgen/ir/__init__.py

@@ -0,0 +1,3 @@
+from .models import MCPSpec, Tool, Param
+
+__all__ = ["MCPSpec", "Tool", "Param"]

mcpgen/ir/models.py

@@ -0,0 +1,87 @@
+"""
+Internal Representation (IR) for mcpgen.
+
+Every parser (OpenAPI, Postman, etc.) outputs an MCPSpec.
+The generator consumes MCPSpec. Nothing else crosses that boundary.
+"""
+
+from __future__ import annotations
+from typing import Literal, Optional
+from pydantic import BaseModel, field_validator
+import re
+
+
+class Param(BaseModel):
+    """A single parameter for an API tool call."""
+
+    name: str                   # Python-safe identifier, snake_case
+    location: Literal["query", "path", "header", "body", "cookie"]
+    required: bool = False
+    type: str = "string"        # OpenAPI primitive: string, integer, number, boolean, object, array
+    description: Optional[str] = None
+    default: Optional[str] = None
+    enum: Optional[list[str]] = None
+
+    @field_validator("name")
+    @classmethod
+    def sanitize_name(cls, v: str) -> str:
+        """Ensure name is a valid Python identifier."""
+        v = re.sub(r"[^a-zA-Z0-9_]", "_", v)
+        if v and v[0].isdigit():
+            v = "_" + v
+        return v or "param"
+
+
+class Tool(BaseModel):
+    """Represents one MCP tool, derived from one API endpoint."""
+
+    name: str           # snake_case MCP tool name, e.g. get_users_id
+    description: str    # Shown to Claude when it decides which tool to call
+    method: str         # HTTP method: GET, POST, PUT, DELETE, PATCH
+    path: str           # URL path template, e.g. /users/{id}
+    params: list[Param] = []
+    base_url: str
+    auth_type: Literal["bearer", "api_key", "basic", "none"] = "none"
+    auth_header: Optional[str] = None   # For api_key auth: the header name e.g. "X-API-Key"
+    content_type: str = "application/json"
+
+    @field_validator("method")
+    @classmethod
+    def uppercase_method(cls, v: str) -> str:
+        return v.upper()
+
+    @field_validator("name")
+    @classmethod
+    def sanitize_tool_name(cls, v: str) -> str:
+        # Replace non-alphanumeric with underscore, collapse multiples, strip leading/trailing
+        v = re.sub(r"[^a-zA-Z0-9]+", "_", v)
+        v = v.strip("_")
+        return v.lower() or "unknown_tool"
+
+
+class MCPSpec(BaseModel):
+    """
+    The complete specification for one MCP server.
+    
+    This is what parsers produce and what the generator consumes.
+    """
+
+    name: str           # Human-readable name, e.g. "Stripe API"
+    description: str    # Server-level description shown to Claude
+    base_url: str       # API base URL, e.g. https://api.stripe.com
+    tools: list[Tool]
+    auth_type: Literal["bearer", "api_key", "basic", "none"] = "none"
+    auth_env_var: Optional[str] = None   # e.g. "STRIPE_TOKEN"
+    version: str = "0.1.0"
+
+    @property
+    def slug(self) -> str:
+        """URL/directory-safe name, e.g. 'stripe_api_mcp'."""
+        s = re.sub(r"[^a-zA-Z0-9]+", "_", self.name)
+        s = s.strip("_").lower()
+        return s + "_mcp"
+
+    @property
+    def env_prefix(self) -> str:
+        """Env var prefix, e.g. 'STRIPE_API'."""
+        return re.sub(r"[^A-Z0-9]+", "_", self.name.upper()).strip("_")

mcpgen/parser/__init__.py

@@ -0,0 +1,3 @@
+from .loader import load, LoaderError
+
+__all__ = ["load", "LoaderError"]

mcpgen/parser/loader.py

@@ -0,0 +1,144 @@
+"""
+Loader: detects input format and routes to the correct parser.
+
+Accepts:
+- File path: .json, .yaml, .yml
+- URL: fetches content then detects format
+
+Detects:
+- OpenAPI 3.x (has "openapi" key starting with "3.")
+- Postman Collection v2.1 (has "info._postman_id" key)
+"""
+
+from __future__ import annotations
+import re
+from pathlib import Path
+from typing import Optional
+
+# Prefer a fast JSON library when available
+try:
+    import orjson as _orjson
+    def _loads_json(s: str):
+        return _orjson.loads(s)
+except Exception:
+    import json as _json
+    def _loads_json(s: str):
+        return _json.loads(s)
+
+import httpx
+import yaml
+
+from mcpgen.ir import MCPSpec
+from .openapi import parse_openapi
+from .postman import parse_postman
+
+
+class LoaderError(Exception):
+    """Raised when the input cannot be loaded or format is unrecognized."""
+    pass
+
+
+# Lazy, shared HTTPX client to enable connection reuse across fetches.
+_HTTPX_CLIENT: Optional[httpx.Client] = None
+
+
+def _get_http_client() -> httpx.Client:
+    global _HTTPX_CLIENT
+    if _HTTPX_CLIENT is None:
+        # Set a sensible default timeout here; callers may override per-request.
+        _HTTPX_CLIENT = httpx.Client(timeout=15.0)
+    return _HTTPX_CLIENT
+
+
+def load(source: str) -> MCPSpec:
+    """
+    Main entry point. Takes a file path or URL string.
+    Returns an MCPSpec ready for code generation.
+
+    Raises LoaderError if format is unrecognized or fetch fails.
+    """
+    raw = _fetch(source)
+    data = _parse_raw(raw, source)
+    if source.startswith(("http://", "https://")):
+        return parse_openapi(data, source_url=source)
+    else:
+        return parse_openapi(data)
+
+
+def _fetch(source: str) -> str:
+    """Fetch raw text from a file path or HTTP URL.
+
+    Uses a shared httpx.Client for connection reuse.
+    """
+    if source.startswith(("http://", "https://")):
+        try:
+            client = _get_http_client()
+            response = client.get(source, follow_redirects=True)
+            response.raise_for_status()
+            return response.text
+        except httpx.HTTPError as e:
+            raise LoaderError(f"Failed to fetch URL: {e}") from e
+
+    path = Path(source)
+    if not path.exists():
+        raise LoaderError(f"File not found: {source}")
+    return path.read_text(encoding="utf-8")
+
+
+def _parse_raw(raw: str, source: str) -> dict:
+    """
+    Parse raw text into a dict.
+    Tries JSON first (fast), then YAML. YAML safe_load can also parse JSON,
+    so there's no need to re-run JSON a second time.
+    """
+    src_lower = source.lower()
+
+    # Try JSON first when likely; fall back to YAML. Use a faster JSON loader when available.
+    if src_lower.endswith('.json') or not src_lower.endswith(('.yaml', '.yml')):
+        try:
+            return _loads_json(raw)
+        except Exception:
+            # fall through to YAML attempt
+            pass
+
+    # Try YAML (YAML is a superset of JSON so this will also succeed for JSON content)
+    try:
+        result = yaml.safe_load(raw)
+        if isinstance(result, dict):
+            return result
+    except yaml.YAMLError:
+        pass
+
+    # If we got here, parsing failed
+    raise LoaderError(
+        f"Could not parse '{source}' as JSON or YAML. "
+        "Check that the file is a valid OpenAPI spec or Postman collection."
+    )
+
+
+def _route(data: dict) -> MCPSpec:
+    """Detect format and route to the correct parser."""
+
+    # OpenAPI 3.x detection
+    openapi_version = data.get("openapi", "")
+    if isinstance(openapi_version, str) and openapi_version.startswith("3."):
+        return parse_openapi(data)
+
+    # Swagger 2.x detection — give a helpful error
+    if "swagger" in data:
+        raise LoaderError(
+            "Swagger 2.x detected. mcpgen currently supports OpenAPI 3.x only. "
+            "Convert your spec at https://converter.swagger.io/ and try again."
+        )
+
+    # Postman Collection v2.1 detection
+    info = data.get("info", {})
+    if "_postman_id" in info or data.get("item"):
+        return parse_postman(data)
+
+    raise LoaderError(
+        "Unrecognized format. mcpgen supports:\n"
+        "  - OpenAPI 3.x JSON/YAML\n"
+        "  - Postman Collection v2.1\n"
+        "Check that your file has the correct structure."
+    )