mcp-creator-python 1.0.0__py3-none-any.whl

mcp_creator/services/subprocess_runner.py

@@ -0,0 +1,51 @@
+"""Safe subprocess.run wrapper for uv build / uv publish."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def run_command(
+    cmd: list[str],
+    cwd: str | Path | None = None,
+    env: dict[str, str] | None = None,
+    timeout: int = 120,
+) -> dict:
+    """Run a subprocess and return structured output.
+
+    Returns:
+        dict with keys: success (bool), command (str), stdout, stderr, return_code
+    """
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=str(cwd) if cwd else None,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+        return {
+            "success": result.returncode == 0,
+            "command": " ".join(cmd),
+            "stdout": result.stdout.strip(),
+            "stderr": result.stderr.strip(),
+            "return_code": result.returncode,
+        }
+    except FileNotFoundError:
+        return {
+            "success": False,
+            "command": " ".join(cmd),
+            "stdout": "",
+            "stderr": f"Command not found: {cmd[0]}. Make sure it is installed and on your PATH.",
+            "return_code": -1,
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "success": False,
+            "command": " ".join(cmd),
+            "stdout": "",
+            "stderr": f"Command timed out after {timeout}s.",
+            "return_code": -1,
+        }

mcp_creator/tools/add_tool.py

@@ -0,0 +1,94 @@
+"""Add a new tool to an existing scaffolded MCP server project."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mcp_creator.services import codegen, file_writer
+
+
+def add_tool(project_dir: str, tool: str) -> str:
+    """Add a new tool to an existing scaffolded MCP server.
+
+    Args:
+        project_dir: Absolute path to the project root.
+        tool: JSON string — a single tool definition:
+              {"name": "get_forecast", "description": "...",
+               "parameters": [...], "returns": "..."}
+
+    Returns:
+        JSON string with created/modified files and next steps.
+    """
+    tool_def = json.loads(tool)
+    tool_name = tool_def["name"]
+    project = Path(project_dir).resolve()
+
+    # Detect module name from the src/ directory
+    src_dir = project / "src"
+    if not src_dir.exists():
+        return json.dumps({
+            "success": False,
+            "error": f"No src/ directory found at {project}. Is this a scaffolded MCP project?",
+        })
+
+    module_dirs = [d for d in src_dir.iterdir() if d.is_dir() and not d.name.startswith("_")]
+    if not module_dirs:
+        return json.dumps({
+            "success": False,
+            "error": "No module directory found under src/.",
+        })
+
+    module_name = module_dirs[0].name
+    package_name = module_name.replace("_", "-")
+
+    # 1. Create tool module
+    tool_file = f"src/{module_name}/tools/{tool_name}.py"
+    tool_content = codegen.render_tool_module(package_name, tool_def)
+
+    # 2. Create service stub
+    service_file = f"src/{module_name}/services/{tool_name}_service.py"
+    service_content = codegen.render_service_module(tool_def)
+
+    # 3. Create test
+    test_file = f"tests/test_{tool_name}.py"
+    test_content = codegen.render_test_tool(package_name, tool_def)
+
+    files_to_write = {
+        tool_file: tool_content,
+        service_file: service_content,
+        test_file: test_content,
+    }
+
+    written = file_writer.write_project_files(project, files_to_write)
+
+    # 4. Inject import into server.py
+    server_path = project / f"src/{module_name}/server.py"
+    import_line = codegen.render_add_tool_import(package_name, tool_name)
+    import_ok = file_writer.inject_after_sentinel(
+        server_path, "# --- IMPORTS ---", import_line
+    )
+
+    # 5. Inject tool registration into server.py
+    registration = codegen.render_add_tool_registration(tool_def)
+    reg_ok = file_writer.inject_after_sentinel(
+        server_path, "# --- END TOOLS ---", ""
+    )
+    # Actually inject before END TOOLS
+    reg_ok = file_writer.inject_after_sentinel(
+        server_path, "# --- TOOLS ---", registration
+    )
+
+    result = {
+        "success": True,
+        "tool_name": tool_name,
+        "files_created": [tool_file, service_file, test_file],
+        "server_updated": import_ok and reg_ok,
+        "next_steps": [
+            f"Tool '{tool_name}' added to the project.",
+            f"Implement your logic in src/{module_name}/services/{tool_name}_service.py",
+            "Run 'pytest -v' to verify it registers correctly.",
+        ],
+    }
+
+    return json.dumps(result, indent=2)

mcp_creator/tools/build_package.py

@@ -0,0 +1,50 @@
+"""Build an MCP server package with uv build."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mcp_creator.services.subprocess_runner import run_command
+
+
+def build_package(project_dir: str) -> str:
+    """Build the MCP server package using uv build.
+
+    Args:
+        project_dir: Absolute path to the project root.
+
+    Returns:
+        JSON string with build result and next steps.
+    """
+    project = Path(project_dir).resolve()
+
+    if not (project / "pyproject.toml").exists():
+        return json.dumps({
+            "success": False,
+            "error": f"No pyproject.toml found at {project}.",
+            "next_steps": ["Make sure you're pointing to the right project directory."],
+        })
+
+    result = run_command(["uv", "build"], cwd=project)
+
+    if result["success"]:
+        # Find built files
+        dist_dir = project / "dist"
+        built_files = []
+        if dist_dir.exists():
+            built_files = [f.name for f in dist_dir.iterdir()]
+
+        result["built_files"] = built_files
+        result["next_steps"] = [
+            "Build successful!",
+            f"Built files: {', '.join(built_files)}",
+            "Next: use publish_package to upload to PyPI, or test locally first.",
+        ]
+    else:
+        result["next_steps"] = [
+            "Build failed. Check the error output above.",
+            "Common fixes: make sure uv is installed, dependencies are correct, and there are no syntax errors.",
+        ]
+
+    return json.dumps(result, indent=2)

mcp_creator/tools/check_pypi_name.py

@@ -0,0 +1,37 @@
+"""Check if a package name is available on PyPI."""
+
+from __future__ import annotations
+
+import json
+
+from mcp_creator.services.pypi_client import check_name_available
+
+
+def check_pypi_name(package_name: str) -> str:
+    """Check if a PyPI package name is available.
+
+    Args:
+        package_name: The name to check (e.g. "my-cool-mcp").
+
+    Returns:
+        JSON string with availability info and next steps.
+    """
+    result = check_name_available(package_name)
+
+    if result.get("available"):
+        result["next_steps"] = [
+            f'Great — "{package_name}" is available on PyPI!',
+            "Next: define what tools your MCP server should have, then use scaffold_server to create the project.",
+        ]
+    elif result.get("available") is False:
+        result["next_steps"] = [
+            f'"{package_name}" is already taken on PyPI.',
+            result.get("suggestion", 'Try adding "-mcp" or a unique prefix.'),
+        ]
+    else:
+        result["next_steps"] = [
+            "Could not check PyPI right now.",
+            result.get("suggestion", "Try again in a moment."),
+        ]
+
+    return json.dumps(result, indent=2)

mcp_creator/tools/check_setup.py

@@ -0,0 +1,104 @@
+"""Check the user's environment for required tools and setup status."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+
+from mcp_creator.services.subprocess_runner import run_command
+
+
+def check_setup() -> str:
+    """Check what tools and accounts the user already has set up.
+
+    Detects: Python, uv, gh CLI, PyPI token, git.
+    Returns a status for each so the AI can skip setup steps the user
+    has already completed.
+
+    Returns:
+        JSON string with setup status and next steps.
+    """
+    checks: dict[str, dict] = {}
+
+    # Python
+    python_result = run_command(["python3", "--version"])
+    checks["python"] = {
+        "installed": python_result["success"],
+        "version": python_result["stdout"] if python_result["success"] else None,
+    }
+
+    # uv
+    checks["uv"] = {
+        "installed": shutil.which("uv") is not None,
+    }
+    if checks["uv"]["installed"]:
+        uv_ver = run_command(["uv", "--version"])
+        checks["uv"]["version"] = uv_ver["stdout"] if uv_ver["success"] else None
+
+    # git
+    checks["git"] = {
+        "installed": shutil.which("git") is not None,
+    }
+
+    # gh CLI
+    gh_installed = shutil.which("gh") is not None
+    gh_authed = False
+    gh_username = None
+    if gh_installed:
+        gh_auth = run_command(["gh", "auth", "status"])
+        gh_authed = gh_auth["success"]
+        if gh_authed:
+            whoami = run_command(["gh", "api", "user", "--jq", ".login"])
+            gh_username = whoami["stdout"].strip() if whoami["success"] else None
+    checks["github_cli"] = {
+        "installed": gh_installed,
+        "authenticated": gh_authed,
+        "username": gh_username,
+    }
+
+    # PyPI token
+    has_token = bool(os.environ.get("UV_PUBLISH_TOKEN"))
+    checks["pypi_token"] = {
+        "configured": has_token,
+    }
+
+    # Determine what's missing
+    missing = []
+    if not checks["uv"]["installed"]:
+        missing.append("Install uv: https://docs.astral.sh/uv/getting-started/installation/")
+    if not checks["git"]["installed"]:
+        missing.append("Install git: https://git-scm.com/downloads")
+    if not checks["github_cli"]["installed"]:
+        missing.append("Install GitHub CLI: https://cli.github.com/")
+    elif not checks["github_cli"]["authenticated"]:
+        missing.append("Authenticate GitHub CLI: run 'gh auth login'")
+    if not checks["pypi_token"]["configured"]:
+        missing.append(
+            "Set up PyPI token: get one at https://pypi.org/manage/account/token/ "
+            "then export UV_PUBLISH_TOKEN=pypi-..."
+        )
+
+    all_ready = len(missing) == 0
+
+    result = {
+        "checks": checks,
+        "all_ready": all_ready,
+        "missing_steps": missing,
+        "next_steps": [],
+    }
+
+    if all_ready:
+        result["next_steps"] = [
+            "Everything is set up! The user is ready to create MCP servers.",
+            "Skip all setup instructions — go straight to asking what they want to build.",
+            "Use check_pypi_name to verify their package name, then scaffold_server to create it.",
+        ]
+    else:
+        result["next_steps"] = [
+            f"The user needs to complete {len(missing)} setup step(s) before they can fully publish.",
+            "Walk them through only the missing steps listed above.",
+            "They can still scaffold and develop locally even without all steps complete.",
+        ]
+
+    return json.dumps(result, indent=2)

mcp_creator/tools/creator_profile.py

@@ -0,0 +1,106 @@
+"""Persistent creator profile — remembers setup state and project history."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+PROFILE_DIR = Path.home() / ".mcp-creator"
+PROFILE_FILE = PROFILE_DIR / "profile.json"
+
+
+def _load_profile() -> dict:
+    """Load or initialize the creator profile."""
+    if PROFILE_FILE.exists():
+        return json.loads(PROFILE_FILE.read_text(encoding="utf-8"))
+    return {
+        "setup_complete": False,
+        "github_username": None,
+        "pypi_username": None,
+        "default_output_dir": None,
+        "projects": [],
+    }
+
+
+def _save_profile(profile: dict) -> None:
+    """Save the creator profile to disk."""
+    PROFILE_DIR.mkdir(parents=True, exist_ok=True)
+    PROFILE_FILE.write_text(json.dumps(profile, indent=2), encoding="utf-8")
+
+
+def get_creator_profile() -> str:
+    """Load the creator's profile — their setup status and project history.
+
+    Call this at the start of every session to know the user's state.
+    If the profile exists, the user is returning — skip onboarding.
+
+    Returns:
+        JSON string with profile data and next steps.
+    """
+    profile = _load_profile()
+
+    if profile.get("setup_complete") and profile.get("projects"):
+        project_names = [p["name"] for p in profile["projects"]]
+        next_steps = [
+            f"Returning creator with {len(profile['projects'])} project(s): {', '.join(project_names)}.",
+            "Skip all setup — ask what they want to build next.",
+            "They can also add tools to existing projects or publish updates.",
+        ]
+    elif profile.get("setup_complete"):
+        next_steps = [
+            "Setup is complete but no projects yet.",
+            "Skip setup instructions — go straight to asking what they want to build.",
+        ]
+    else:
+        next_steps = [
+            "New creator — run check_setup to see what they need to install.",
+            "Walk them through any missing setup steps.",
+        ]
+
+    return json.dumps({"profile": profile, "next_steps": next_steps}, indent=2)
+
+
+def update_creator_profile(
+    setup_complete: bool | None = None,
+    github_username: str | None = None,
+    pypi_username: str | None = None,
+    default_output_dir: str | None = None,
+    add_project: str | None = None,
+) -> str:
+    """Update the creator's profile after setup steps or project creation.
+
+    Args:
+        setup_complete: Mark setup as done (all tools installed, accounts ready).
+        github_username: Their GitHub username.
+        pypi_username: Their PyPI username.
+        default_output_dir: Where they want projects created by default.
+        add_project: JSON string of a project to add to history:
+                     {"name": "my-mcp", "pypi_url": "...", "github_url": "...", "description": "..."}
+
+    Returns:
+        JSON string with updated profile.
+    """
+    profile = _load_profile()
+
+    if setup_complete is not None:
+        profile["setup_complete"] = setup_complete
+    if github_username is not None:
+        profile["github_username"] = github_username
+    if pypi_username is not None:
+        profile["pypi_username"] = pypi_username
+    if default_output_dir is not None:
+        profile["default_output_dir"] = default_output_dir
+    if add_project is not None:
+        project = json.loads(add_project)
+        # Don't duplicate
+        existing_names = [p["name"] for p in profile["projects"]]
+        if project["name"] not in existing_names:
+            profile["projects"].append(project)
+
+    _save_profile(profile)
+
+    return json.dumps({
+        "success": True,
+        "profile": profile,
+        "next_steps": ["Profile updated."],
+    }, indent=2)

mcp_creator/tools/generate_launchguide.py

@@ -0,0 +1,95 @@
+"""Generate a LAUNCHGUIDE.md for MCP Marketplace submission."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from mcp_creator.services.file_writer import write_project_files
+
+
+LAUNCHGUIDE_TEMPLATE = """\
+# {package_name}
+
+## Tagline
+{tagline}
+
+## Description
+{description}
+
+## Setup Requirements
+{setup_requirements}
+
+## Category
+{category}
+
+## Features
+{features}
+
+## Getting Started
+{getting_started}
+
+## Tags
+{tags}
+
+## Documentation URL
+{docs_url}
+"""
+
+
+def generate_launchguide(
+    project_dir: str,
+    package_name: str,
+    tagline: str,
+    description: str,
+    category: str,
+    features: str,
+    tools_summary: str,
+    tags: str,
+    setup_requirements: str = "No environment variables required.",
+    docs_url: str = "",
+) -> str:
+    """Generate a LAUNCHGUIDE.md for MCP Marketplace submission.
+
+    Args:
+        project_dir: Absolute path to the project root.
+        package_name: PyPI package name.
+        tagline: One-liner (max 100 chars).
+        description: What the server does, how it works, who it's for.
+        category: One of: Developer Tools, Data & Analytics, Productivity, etc.
+        features: Bullet-point features (one per line, prefixed with "- "). Max 30 items.
+        tools_summary: Tool descriptions for Getting Started (one per line).
+        tags: Comma-separated tags. Max 30.
+        setup_requirements: Env vars or setup steps (default: none required).
+        docs_url: Link to docs or README.
+
+    Returns:
+        JSON string with file path and next steps.
+    """
+    project = Path(project_dir).resolve()
+
+    content = LAUNCHGUIDE_TEMPLATE.format(
+        package_name=package_name,
+        tagline=tagline,
+        description=description,
+        setup_requirements=setup_requirements,
+        category=category,
+        features=features,
+        getting_started=tools_summary,
+        tags=tags,
+        docs_url=docs_url or f"https://pypi.org/project/{package_name}/",
+    )
+
+    written = write_project_files(project, {"LAUNCHGUIDE.md": content})
+
+    result = {
+        "success": True,
+        "file": str(project / "LAUNCHGUIDE.md"),
+        "next_steps": [
+            "LAUNCHGUIDE.md created!",
+            "Review it and make any final edits.",
+            f"Submit to MCP Marketplace at https://mcp-marketplace.io with this file.",
+        ],
+    }
+
+    return json.dumps(result, indent=2)

mcp_creator/tools/publish_package.py

@@ -0,0 +1,72 @@
+"""Publish an MCP server package to PyPI with uv publish."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from mcp_creator.services.subprocess_runner import run_command
+
+
+def publish_package(project_dir: str, token: str | None = None) -> str:
+    """Publish the built package to PyPI using uv publish.
+
+    Args:
+        project_dir: Absolute path to the project root.
+        token: Optional PyPI API token. If not provided, uses UV_PUBLISH_TOKEN
+               environment variable.
+
+    Returns:
+        JSON string with publish result and next steps.
+    """
+    project = Path(project_dir).resolve()
+    dist_dir = project / "dist"
+
+    if not dist_dir.exists() or not list(dist_dir.iterdir()):
+        return json.dumps({
+            "success": False,
+            "error": "No dist/ directory or it's empty. Run build_package first.",
+            "next_steps": ["Use build_package to build the project before publishing."],
+        })
+
+    # Build env with token if provided
+    env = dict(os.environ)
+    if token:
+        env["UV_PUBLISH_TOKEN"] = token
+
+    if not token and "UV_PUBLISH_TOKEN" not in env:
+        return json.dumps({
+            "success": False,
+            "error": "No PyPI token found. Set UV_PUBLISH_TOKEN or pass a token.",
+            "next_steps": [
+                "Get a PyPI API token at https://pypi.org/manage/account/token/",
+                "Then either: export UV_PUBLISH_TOKEN=pypi-... or pass it to this tool.",
+            ],
+        })
+
+    result = run_command(["uv", "publish"], cwd=project, env=env)
+
+    if result["success"]:
+        # Try to extract package name from pyproject.toml
+        pyproject_path = project / "pyproject.toml"
+        package_name = "your-package"
+        if pyproject_path.exists():
+            for line in pyproject_path.read_text().splitlines():
+                if line.strip().startswith("name"):
+                    package_name = line.split("=")[1].strip().strip('"').strip("'")
+                    break
+
+        result["next_steps"] = [
+            f"Published to PyPI! Install with: pip install {package_name}",
+            f"View at: https://pypi.org/project/{package_name}/",
+            "Next: use setup_github to create a GitHub repo and push the code.",
+            "Then use generate_launchguide to create a LAUNCHGUIDE.md for marketplace submission.",
+        ]
+    else:
+        result["next_steps"] = [
+            "Publish failed. Check the error output.",
+            "Common issues: invalid token, package name conflict, or network error.",
+        ]
+
+    return json.dumps(result, indent=2)