fastmcp-builder 0.3.0__py3-none-any.whl

fastmcp_builder-0.3.0.dist-info/METADATA

@@ -0,0 +1,125 @@
+Metadata-Version: 2.3
+Name: fastmcp-builder
+Version: 0.3.0
+Summary: Generate complete, runnable FastMCP 3.x MCP servers from plain-English descriptions
+Keywords: mcp,fastmcp,anthropic,claude,code-generation,llm
+Author: saagpatel
+Author-email: saagpatel <saagarpatel08@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: anthropic>=0.87.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastmcp>=3.2.3
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/saagpatel/mcpforge
+Project-URL: Repository, https://github.com/saagpatel/mcpforge
+Project-URL: Bug Tracker, https://github.com/saagpatel/mcpforge/issues
+Description-Content-Type: text/markdown
+
+# mcpforge
+
+[![Python](https://img.shields.io/badge/Python-3776ab?style=flat-square&logo=python)](#) [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](#)
+
+> One sentence. One command. A complete MCP server, ready to run.
+
+mcpforge generates production-ready FastMCP 3.x MCP servers from plain-English descriptions. You describe what you want; it produces tools, input validation, error handling, a pytest test suite, run configuration, and client setup docs — all wired together and ready to inspect, validate, and install.
+
+## Features
+
+- **Plain-English generation** — describe your server in natural language; Claude writes the implementation
+- **Complete project scaffold** — tools, Pydantic input models, error handling, `pyproject.toml`, and a pytest suite generated together
+- **FastMCP 3.x native** — output uses modern FastMCP decorators and transport configuration, not raw MCP protocol boilerplate
+- **Validate before running** — `mcpforge validate` runs syntax, security, lint, import, and pytest checks against generated servers
+- **Iterate safely** — `mcpforge update` modifies an existing generated server and backs up changed files before writing
+- **Discover generated servers** — `mcpforge list` finds mcpforge-generated projects in a workspace
+- **Inspect and diagnose** — `mcpforge inspect` summarizes generated server shape, while `mcpforge doctor` checks local readiness
+- **Machine-readable output** — status-like commands expose `--json` for agent workflows
+- **OpenAPI curation controls** — include/exclude tags, operation allowlists, and operation limits keep generated integrations focused
+- **Scaffold without an LLM** — `mcpforge init` creates a minimal FastMCP server skeleton for local iteration
+- **MCP server mode** — `mcpforge-server` exposes generation, planning, validation, inspection, doctor, and discovery tools so AI assistants can build safely
+
+## Quick Start
+
+### Prerequisites
+- Python 3.12+
+- `uv` (recommended)
+- Anthropic API key
+
+### Installation
+```bash
+uv tool install fastmcp-builder
+```
+
+The PyPI distribution is `fastmcp-builder`; the installed commands remain
+`mcpforge` and `mcpforge-server`.
+
+### Usage
+```bash
+# Generate a new MCP server
+mcpforge generate "A todo list manager with create, read, update, and delete operations"
+
+# Validate an existing generated server
+mcpforge validate ./my-server
+
+# Modify an existing generated server
+mcpforge update ./my-server "Add a tool to export todos as CSV"
+
+# Find generated servers in the current workspace
+mcpforge list . --recursive
+
+# Inspect a generated server without executing it
+mcpforge inspect ./my-server
+
+# Check local prerequisites and provider readiness
+mcpforge doctor
+```
+
+Useful generation flags:
+- `--dry-run` displays the structured plan without writing files.
+- `--no-execute` writes files but skips import and test execution.
+- `--strict` treats lint errors as hard validation failures.
+- `--from-openapi FILE` generates from an OpenAPI 3.x spec.
+- `--openapi-include-tag TAG`, `--openapi-exclude-tag TAG`, `--openapi-operation ID`, and `--openapi-limit N` curate OpenAPI conversion.
+- `--language python|typescript` chooses the target server language.
+- `--provider anthropic|openai` selects the generation provider. OpenAI is listed as planned and remains gated until deterministic structured-output smokes are implemented.
+
+Useful status flags:
+- `mcpforge list --json`
+- `mcpforge inspect PATH --json`
+- `mcpforge validate PATH --json`
+- `mcpforge doctor --json`
+- `mcpforge version --json`
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Language | Python 3.12+ |
+| Generation | Anthropic Claude via `anthropic` SDK |
+| MCP framework | FastMCP 3.x |
+| CLI | Click 8 |
+| Templates | Jinja2 |
+| Validation | Pydantic v2 |
+| Output | Rich |
+
+## Architecture
+
+The `generate` command sends the user's description to Claude with a structured prompt that includes FastMCP 3.x idioms and a tool-schema contract. Claude returns a JSON plan (tool names, signatures, and descriptions) that mcpforge validates against a Pydantic model before rendering through Jinja2 templates into a complete project directory. The generated project is then validated with syntax checks, security scanning, ruff linting, import checks, and pytest execution. The `update` command reads an existing generated server, asks Claude for a targeted modification, writes backups for changed files, and validates the result.
+
+## Current Status
+
+As of May 10, 2026, `main` is prepared as `0.3.0` for the `fastmcp-builder` PyPI distribution. The v0.3 builder lane expands mcpforge from runnable-server generation into a production integration builder with inspection, doctor checks, richer generated scaffolds, OpenAPI curation, MCP server parity, provider abstraction, and live generated fixture examples for REST API, filesystem, database, and TypeScript profiles. See `docs/CURRENT-STATE.md` and `docs/ROADMAP-v0.3.md`.
+
+## License
+
+MIT

fastmcp_builder-0.3.0.dist-info/RECORD

@@ -0,0 +1,50 @@
+mcpforge/__init__.py,sha256=wT-IwBzwKTWou8-EZp9HilBLiKvVihTkl_v_j5EhDY8,449
+mcpforge/api_client.py,sha256=-7fpLjexuchgYQPJXNv5xND_qQ1jAFRkUJQBZ2THuCY,5860
+mcpforge/cli.py,sha256=l9mKY1t35QYOpZQrJqXvBrstbw1G9fW0fldL_g8yBAo,32868
+mcpforge/discovery.py,sha256=zP21zm4RSXxx0At1_QYVQ2y-ebTUID7GybqWrqdGWc8,2386
+mcpforge/doctor.py,sha256=FLNcbsKwhkHHxr4UJf-wQWMUIVeeIhl3crizQHX5-u0,3379
+mcpforge/generator.py,sha256=c4AFaw4DpMJpNofH6wPl_4zuXZpOGEUw8aRTg08myKw,2141
+mcpforge/generator_ts.py,sha256=IXYyru0K_r6lobbQB2X6t-4zqXG0cd1w4mP--OqeZr4,1206
+mcpforge/inspection.py,sha256=YJZZnkqK8dTG0WFKfkemmbKQS31ZKippVK_Nbo7FFCg,4867
+mcpforge/mcp_server.py,sha256=FQclaxKmSihqCCb5A-OwvCdOVX8XvoMcuMI4gT_5owQ,9159
+mcpforge/models.py,sha256=i6X49xwYs7Z8oTAes3mUcGBROVPbdWkgIAQXESkz73k,5650
+mcpforge/openapi.py,sha256=l0PMWScd0FLdWSx6_-fAME-MSizxgwIHNxgr0Ue6YQo,8781
+mcpforge/planner.py,sha256=nPGYIIf3XuSmso2lKUNvA336Lt2txfC4K9_oMKTBnac,1995
+mcpforge/prompts/__init__.py,sha256=ECWc4caHwgAondA320i2LBY9xjH-nxe1ClCwMZK0t3Y,716
+mcpforge/prompts/generator.md,sha256=Oy8Kl12HGZn0dX7cMaxb2dEkcB0JNKm76xRJ4Jp0jn0,6658
+mcpforge/prompts/generator_multi.md,sha256=TLg0eDWUrvi5749oDmMHzvFa7ncBdmcYU7_aJDwFJIY,2170
+mcpforge/prompts/generator_ts.md,sha256=h80ppzWNNHfnlkTJ58bhZUMYQfkqSgqN5GZkr2c0Pzk,2070
+mcpforge/prompts/planner.md,sha256=01qkPCHN1Ki1lzaIoM3yn9ybwk6N9W9DFrxbg5-jK_E,6020
+mcpforge/prompts/self_heal.md,sha256=91eV8RAinqoXvx7hGhd_QmgYXUn7Ok6nVLCTgEToTUg,943
+mcpforge/prompts/test_gen.md,sha256=116Ww6DrNXFNy4i1KPH-DojjHYXKWufmC4kg2_yk1F8,2941
+mcpforge/prompts/test_gen_ts.md,sha256=vY5OVasQNj8g_XgdHFycEC3aBVL4HJizwpxFr5n1sE0,1886
+mcpforge/prompts/updater.md,sha256=8WSq6H-mcdqdflKFoIyHdYSVZoACNfz6lYNupaU7yb0,753
+mcpforge/providers.py,sha256=xYoiC7jiIAKLYmDixcpDtnoVqf6gj7jZJbmS9NNOK94,3178
+mcpforge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcpforge/sandbox.py,sha256=0x38jOtfATwxSdgQfLyIfpmWdoj1BWTssXPZgXbrxZs,2218
+mcpforge/security.py,sha256=iDhyfdKOG8krOqERwYfbD2u_HqZhMg_Z5nWI0Uq-lGQ,4496
+mcpforge/self_heal.py,sha256=C9ceTOBHF9nMGH_dYD_fhWrN2ioy_BP6OnqIkKNZdLk,7026
+mcpforge/template_hints.py,sha256=0KaKL54d1b1ES4lN8kUIU42sjAq2xHOod0Bfoo1C1CI,3028
+mcpforge/templates/README.md.j2,sha256=MTSNaGEK4wo2SyImTHaqoSXFtMLaWJVw-Ip8B5STYGs,2374
+mcpforge/templates/config.json.j2,sha256=Ex-xDWMyuzmuRGu07r6zyX-SY5SYl0apIpHsE456yGs,287
+mcpforge/templates/env.example.j2,sha256=lXUCyQwvi7Xltg27xgp1sAshMqTUEzB4stKwrKpjSSw,57
+mcpforge/templates/fastmcp.json.j2,sha256=tPLJTuj4lil3vNpTBaUyJ-7tk1lQun5UnptCu8pqn9k,742
+mcpforge/templates/init_server.py.j2,sha256=tlb10xY_EEu-tUzC9WWYMOWZr3H33x4W7TthKO_YyEI,316
+mcpforge/templates/init_test.py.j2,sha256=YtJLC6SSUWNfPpCivL3jdyUON-sRCl87U3-BORRfLLk,266
+mcpforge/templates/pyproject.toml.j2,sha256=KeD3OIIzEcczoMPEgcdPx9UrGEGbXsMvY2Bg3sfD4Zg,381
+mcpforge/templates/ts/README.md.j2,sha256=4J4TKB_4h59_YgTkNWMLRvjBNzj1_04YDRLZ6fXBKvA,548
+mcpforge/templates/ts/config.json.j2,sha256=7QIFtMEPQtSRlVATETEqaemydxVjCPZr64wqHWyaN0c,129
+mcpforge/templates/ts/env.example.j2,sha256=lXUCyQwvi7Xltg27xgp1sAshMqTUEzB4stKwrKpjSSw,57
+mcpforge/templates/ts/gitignore.j2,sha256=TWmWbLSs_Gv5On9EEDDrJRLuZuneiM_J7354ZLWGiPY,34
+mcpforge/templates/ts/package.json.j2,sha256=oTYakFCjI_OOoYLoEvAvMw7YQ5GffbYbwUwPBRKhYO8,503
+mcpforge/templates/ts/tsconfig.json.j2,sha256=bPNP99SGoUiKCUr7YWitD3istXcXdvUOLAAZYAE-3ls,326
+mcpforge/test_generator.py,sha256=o-ZKTw77W3MpCfq--mnq_oQfo0uXftHFHCJjJc1eBNk,869
+mcpforge/updater.py,sha256=Y5njvl5i-2ymYsA6E9HLCKWyXiqP27iubwfLEX2XREE,1853
+mcpforge/utils.py,sha256=DjMxtGMbzEfkKpYzU6eMuSu6F918wSC6lFsujAeIBBo,290
+mcpforge/validator.py,sha256=QawzWqLD4spXIpzfPItoOwwP9Pn8igj5PGFSzrYDFnE,11111
+mcpforge/validator_ts.py,sha256=KWxI-laizuL2fGxlxaHwTYGhop8SRuWF1gJSVGAw69M,4524
+mcpforge/writer.py,sha256=7zuDibuP6cfDp6YGLl6UmeO7T3KOz9S63mMSpt0WA3E,7286
+fastmcp_builder-0.3.0.dist-info/WHEEL,sha256=-unyBNsdNo6Y_XVO25zjvxasG_uUFN_fBd_kLyKE-Fk,81
+fastmcp_builder-0.3.0.dist-info/entry_points.txt,sha256=BtXe9KuwIOsuC9QT_mwUsc-PIxQzCo1MNT-_4Inqm_w,93
+fastmcp_builder-0.3.0.dist-info/METADATA,sha256=Y8rLZ3w24pe4qkbCeqBAKzODJEUmHjsvoZ5EJCTj25s,6109
+fastmcp_builder-0.3.0.dist-info/RECORD,,

fastmcp_builder-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.12
+Root-Is-Purelib: true
+Tag: py3-none-any

fastmcp_builder-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+mcpforge = mcpforge.cli:cli
+mcpforge-server = mcpforge.mcp_server:mcp.run
+

mcpforge/__init__.py

@@ -0,0 +1,23 @@
+"""mcpforge — Generate FastMCP 3.x MCP servers from plain-English descriptions."""
+
+from mcpforge.api_client import DEFAULT_MODEL
+from mcpforge.models import (
+    PromptDef,
+    ResourceDef,
+    ServerPlan,
+    ToolDef,
+    ToolParam,
+    ValidationResult,
+)
+
+__version__ = "0.3.0"
+__all__ = [
+    "PromptDef",
+    "ResourceDef",
+    "ServerPlan",
+    "ToolDef",
+    "ToolParam",
+    "ValidationResult",
+    "DEFAULT_MODEL",
+    "__version__",
+]

mcpforge/api_client.py

@@ -0,0 +1,158 @@
+"""Anthropic API client wrapper with retry logic.
+
+MODEL PIN: This module uses Sonnet 4.6 intentionally. Opus 4.7 rejects
+non-default `temperature` values (400 error), and mcpforge relies on
+`temperature=0` for deterministic JSON output in `generate_json()`.
+Do NOT upgrade the default model to Opus 4.7 (or any future model that
+rejects temperature) without first migrating `generate_json()` to tool
+use with a strict schema, which is the 4.7-era replacement for the
+`temperature=0` determinism lever.
+"""
+
+import asyncio
+import json
+import os
+import random
+import re
+from collections.abc import AsyncIterator
+
+import anthropic
+from pydantic import BaseModel, ValidationError
+
+DEFAULT_MODEL = "claude-sonnet-4-6"
+
+
+class AnthropicClient:
+    """Async wrapper around anthropic.AsyncAnthropic with exponential-backoff retry."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        model: str = DEFAULT_MODEL,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
+        if not resolved_key:
+            raise ValueError(
+                "Anthropic API key is required. "
+                "Set the ANTHROPIC_API_KEY environment variable or pass api_key= explicitly."
+            )
+        self._model = model
+        self._client = anthropic.AsyncAnthropic(api_key=resolved_key)
+
+    def __repr__(self) -> str:
+        return f"AnthropicClient(model={self._model!r})"
+
+    async def generate(
+        self,
+        system_prompt: str,
+        user_message: str,
+        max_tokens: int = 8192,
+        temperature: float = 0.0,
+    ) -> str:
+        """Send a message and return the text response.
+
+        Retries up to 3 times with exponential backoff on transient provider errors.
+        """
+        last_exc: Exception | None = None
+        for attempt in range(3):
+            try:
+                response = await self._client.messages.create(
+                    model=self._model,
+                    max_tokens=max_tokens,
+                    temperature=temperature,
+                    system=system_prompt,
+                    messages=[{"role": "user", "content": user_message}],
+                )
+                return response.content[0].text  # type: ignore[union-attr]
+            except anthropic.RateLimitError as exc:
+                last_exc = exc
+                if attempt == 2:
+                    raise
+                wait = (2**attempt) + random.uniform(0.0, 1.0)
+                await asyncio.sleep(wait)
+            except anthropic.APIConnectionError as exc:
+                last_exc = exc
+                if attempt == 2:
+                    raise
+                wait = (2**attempt) + random.uniform(0.0, 1.0)
+                await asyncio.sleep(wait)
+            except anthropic.APIStatusError as exc:
+                last_exc = exc
+                if exc.status_code >= 500 and attempt < 2:
+                    wait = (2**attempt) + random.uniform(0.0, 1.0)
+                    await asyncio.sleep(wait)
+                    continue
+                raise
+        raise RuntimeError("generate() exited retry loop unexpectedly") from last_exc
+
+    async def generate_json(
+        self,
+        system_prompt: str,
+        user_message: str,
+        response_model: type[BaseModel],
+        max_tokens: int = 8192,
+    ) -> BaseModel:
+        """Generate and parse a structured JSON response into a Pydantic model instance.
+
+        Uses temperature=0 for deterministic JSON output. Strips markdown fences
+        before parsing so the LLM can optionally wrap its response in ```json blocks.
+        """
+        text = await self.generate(
+            system_prompt=system_prompt,
+            user_message=user_message,
+            max_tokens=max_tokens,
+            temperature=0.0,
+        )
+        try:
+            data = _extract_json(text)
+            return response_model.model_validate(data)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"Response was not valid JSON for {response_model.__name__}.\n"
+                f"Raw response (first 500 chars): {text[:500]}"
+            ) from exc
+        except ValidationError as exc:
+            raise ValueError(
+                f"Response JSON did not match {response_model.__name__} schema: {exc}"
+            ) from exc
+
+    async def generate_stream(
+        self,
+        system_prompt: str,
+        user_message: str,
+        max_tokens: int = 16384,
+        temperature: float = 0.2,
+        chunk_timeout: float = 60.0,
+    ) -> AsyncIterator[str]:
+        """Stream text chunks as they arrive from the API.
+
+        Yields str chunks. No retry — streaming connections are not retryable.
+        Raises TimeoutError if no chunk arrives within chunk_timeout seconds.
+        """
+        async with self._client.messages.stream(
+            model=self._model,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            system=system_prompt,
+            messages=[{"role": "user", "content": user_message}],
+        ) as stream:
+            aiter = stream.text_stream.__aiter__()
+            while True:
+                try:
+                    text = await asyncio.wait_for(aiter.__anext__(), timeout=chunk_timeout)
+                    yield text
+                except StopAsyncIteration:
+                    break
+                except TimeoutError:
+                    raise TimeoutError(
+                        f"Streaming generation stalled — no data received for {chunk_timeout}s"
+                    ) from None
+
+
+def _extract_json(text: str) -> dict:
+    """Extract a JSON object from text, stripping optional markdown code fences."""
+    text = text.strip()
+    if text.startswith("```"):
+        text = re.sub(r"^```(?:json)?\s*\n?", "", text)
+        text = re.sub(r"\n?```\s*$", "", text)
+    return json.loads(text.strip())