AutoMCP-Forge / app.py
Kashaf10's picture
Update app.py
cce6bd1 verified
Raw History Blame Contribute Delete
21.5 kB
"""
AutoMCP Forge - Phase 1 prototype
=================================
Upload an OpenAPI/Swagger or Postman collection (.json) and get a runnable
FastMCP server (server.py) generated through the OpenRouter API.
Pipeline: upload -> parse -> LLM code generation -> syntax check -> download
Run locally / on Colab : python app.py
Hugging Face Spaces : keep this file named app.py (Gradio SDK)
OpenRouter API key lookup order (get a key at https://openrouter.ai/settings/keys):
1. the optional "OpenRouter API Key" box in the UI
2. the OPENROUTER_API_KEY environment variable (HF Spaces secret)
3. Colab Secrets (key icon in the left sidebar) named OPENROUTER_API_KEY
"""
import ast
import json
import os
import re
import sys
import tempfile
import gradio as gr
import httpx
# Hugging Face ZeroGPU Spaces insist on at least one @spaces.GPU function at startup.
# This app never uses a GPU; this placeholder only satisfies that check and is
# silently skipped everywhere else (Colab, CPU Spaces).
try:
import spaces
@spaces.GPU
def _zero_gpu_placeholder():
return None
except Exception:
pass
# --------------------------------------------------------------------------- #
# Config
# --------------------------------------------------------------------------- #
# OpenRouter is OpenAI-compatible; the base URL must end with /api/v1.
BASE_URL = "https://openrouter.ai/api/v1"
# Free model router. Override with the OPENROUTER_MODEL env variable if needed.
MODEL = os.getenv("OPENROUTER_MODEL", "openrouter/free")
HTTP_METHODS = {"get", "post", "put", "patch", "delete", "head", "options"}
# --------------------------------------------------------------------------- #
# Small helpers
# --------------------------------------------------------------------------- #
def clip(text, limit=200):
"""Collapse whitespace and shorten long descriptions (saves tokens)."""
if not text:
return ""
return " ".join(str(text).split())[:limit]
def resolve_ref(root, node, depth=0):
"""Resolve a local '#/components/...' $ref (a few levels deep)."""
if not isinstance(node, dict) or depth > 6:
return node
ref = node.get("$ref")
if isinstance(ref, str) and ref.startswith("#/"):
target = root
for part in ref[2:].split("/"):
part = part.replace("~1", "/").replace("~0", "~")
if isinstance(target, dict) and part in target:
target = target[part]
else:
return {}
return resolve_ref(root, target, depth + 1)
return node
def schema_fields(root, schema):
"""Flatten an object schema into a list of body fields."""
schema = resolve_ref(root, schema)
if not isinstance(schema, dict):
return []
props = {}
required = set(schema.get("required", []) or [])
for sub in schema.get("allOf", []) or []:
sub = resolve_ref(root, sub)
if isinstance(sub, dict):
props.update(sub.get("properties", {}) or {})
required |= set(sub.get("required", []) or [])
props.update(schema.get("properties", {}) or {})
fields = []
for name, prop in props.items():
prop = resolve_ref(root, prop)
if not isinstance(prop, dict):
prop = {}
fields.append(
{
"name": name,
"in": "body",
"type": prop.get("type", "any"),
"required": name in required,
"description": clip(prop.get("description")),
}
)
return fields
# --------------------------------------------------------------------------- #
# Stage 1a - OpenAPI / Swagger parser
# --------------------------------------------------------------------------- #
def parse_openapi(spec):
info = spec.get("info", {}) or {}
if "openapi" in spec: # OpenAPI 3.x
servers = spec.get("servers") or []
base_url = ""
if servers and isinstance(servers[0], dict):
base_url = servers[0].get("url", "")
else: # Swagger 2.0
host = spec.get("host", "")
scheme = (spec.get("schemes") or ["https"])[0]
base_url = f"{scheme}://{host}{spec.get('basePath', '')}" if host else ""
endpoints = []
for path, item in (spec.get("paths") or {}).items():
item = resolve_ref(spec, item)
if not isinstance(item, dict):
continue
shared_params = item.get("parameters", []) or []
for method, op in item.items():
if method.lower() not in HTTP_METHODS or not isinstance(op, dict):
continue
params = []
for p in list(shared_params) + list(op.get("parameters", []) or []):
p = resolve_ref(spec, p)
if not isinstance(p, dict) or "name" not in p:
continue
if p.get("in") == "body": # Swagger 2 body parameter
params += schema_fields(spec, p.get("schema", {}))
continue
schema = resolve_ref(spec, p["schema"]) if "schema" in p else p
if not isinstance(schema, dict):
schema = {}
params.append(
{
"name": p["name"],
"in": p.get("in", "query"),
"type": schema.get("type", "string"),
"required": bool(p.get("required", False)),
"description": clip(p.get("description")),
}
)
body = resolve_ref(spec, op.get("requestBody")) if op.get("requestBody") else None
if isinstance(body, dict):
content = body.get("content") or {}
media = content.get("application/json") or next(iter(content.values()), {})
params += schema_fields(spec, (media or {}).get("schema", {}))
endpoints.append(
{
"method": method.upper(),
"path": path,
"operation_id": op.get("operationId", ""),
"summary": clip(op.get("summary"), 120),
"description": clip(op.get("description")),
"parameters": params,
}
)
return {
"title": info.get("title", "API"),
"version": info.get("version", ""),
"description": clip(info.get("description")),
"base_url": base_url,
"endpoints": endpoints,
}
# --------------------------------------------------------------------------- #
# Stage 1b - Postman collection parser
# --------------------------------------------------------------------------- #
def _desc(value):
if isinstance(value, dict):
value = value.get("content", "")
return clip(value)
def _py_type(value):
if isinstance(value, bool):
return "boolean"
if isinstance(value, int):
return "integer"
if isinstance(value, float):
return "number"
if isinstance(value, list):
return "array"
if isinstance(value, dict):
return "object"
return "string"
def _postman_url_parts(url):
"""Return (base_url, path, query_list) from a Postman url (str or dict)."""
if isinstance(url, str):
obj, raw = {}, url
else:
obj = url if isinstance(url, dict) else {}
raw = obj.get("raw", "") or ""
host = obj.get("host", "")
host = ".".join(map(str, host)) if isinstance(host, list) else (host or "")
protocol = obj.get("protocol", "") or ""
path = obj.get("path", "")
path = "/".join(map(str, path)) if isinstance(path, list) else (path or "")
query = obj.get("query") or []
if not host and raw:
m = re.match(r"^(?:([A-Za-z][\w+.-]*)://)?([^/?#]+)(/[^?#]*)?(?:\?(.*))?", raw)
if m:
protocol = protocol or (m.group(1) or "")
host = m.group(2)
path = path or (m.group(3) or "")
if not query and m.group(4):
query = [{"key": kv.split("=")[0]} for kv in m.group(4).split("&") if kv]
path = re.sub(r"(^|/):(\w+)", r"\1{\2}", path) # ":id" -> "{id}"
base = f"{protocol}://{host}" if protocol and host else host
return base, "/" + path.lstrip("/"), query
def parse_postman(coll):
info = coll.get("info", {}) or {}
variables = {
v.get("key"): v.get("value", "")
for v in (coll.get("variable") or [])
if isinstance(v, dict)
}
endpoints, bases = [], []
def subst(text):
return re.sub(
r"\{\{(\w+)\}\}",
lambda m: str(variables.get(m.group(1), m.group(0))),
text or "",
)
def walk(items):
for it in items or []:
if not isinstance(it, dict):
continue
if "item" in it: # folder
walk(it["item"])
continue
req = it.get("request")
if req is None:
continue
if isinstance(req, str):
req = {"method": "GET", "url": req}
base, path, query = _postman_url_parts(req.get("url"))
base, path = subst(base), subst(path)
bases.append(base)
params = []
for name in re.findall(r"(?<!\{)\{(\w+)\}(?!\})", path):
params.append(
{"name": name, "in": "path", "type": "string", "required": True, "description": ""}
)
for q in query:
if isinstance(q, dict) and q.get("key"):
params.append(
{
"name": q["key"],
"in": "query",
"type": "string",
"required": False,
"description": _desc(q.get("description")),
}
)
body = req.get("body") or {}
mode = body.get("mode")
if mode == "raw":
try:
data = json.loads(body.get("raw", ""))
except Exception:
data = None
if isinstance(data, dict):
for k, v in data.items():
params.append(
{"name": k, "in": "body", "type": _py_type(v), "required": False, "description": ""}
)
elif mode in ("urlencoded", "formdata"):
for f in body.get(mode, []) or []:
if isinstance(f, dict) and f.get("key"):
params.append(
{"name": f["key"], "in": "body", "type": "string", "required": False, "description": ""}
)
endpoints.append(
{
"method": str(req.get("method", "GET")).upper(),
"path": path,
"operation_id": "",
"summary": clip(it.get("name"), 120),
"description": _desc(req.get("description") or it.get("description")),
"parameters": params,
}
)
walk(coll.get("item"))
return {
"title": info.get("name", "Postman API"),
"version": "",
"description": _desc(info.get("description")),
"base_url": next((b for b in bases if b), ""),
"endpoints": endpoints,
}
def parse_api_file(path):
"""Detect the file type and return (kind, parsed_api)."""
with open(path, "r", encoding="utf-8") as f:
data = json.load(f)
if not isinstance(data, dict):
raise ValueError("The JSON root must be an object.")
if "openapi" in data or "swagger" in data:
return "OpenAPI/Swagger", parse_openapi(data)
if "item" in data and "info" in data:
return "Postman collection", parse_postman(data)
raise ValueError(
"Unrecognised file. Please upload an OpenAPI/Swagger spec or a Postman collection in JSON format."
)
# --------------------------------------------------------------------------- #
# Stage 2 - LLM code generation (OpenRouter)
# --------------------------------------------------------------------------- #
SYSTEM_PROMPT = """You are an expert Python engineer who writes Model Context Protocol (MCP) servers with FastMCP (the `fastmcp` package).
You receive a JSON summary of an API (title, base_url, endpoints with parameters). Produce ONE complete, runnable Python file named server.py.
Strict rules:
1. Output ONLY Python code. No markdown fences, no explanations.
2. Imports: `import os`, `import httpx`, `from fastmcp import FastMCP`.
3. Create `mcp = FastMCP("<API title>")`.
4. Define `BASE_URL = os.getenv("API_BASE_URL", "<base_url from input>")` and `API_KEY = os.getenv("API_KEY", "")`.
Add a helper `_headers()` that sends `Authorization: Bearer <API_KEY>` only when API_KEY is set.
5. Create exactly one `@mcp.tool()` function per endpoint. Use snake_case names (prefer operation_id when given; otherwise build one from method + path). Names must be unique.
6. Every tool needs full type hints (required arguments first, optional ones default to None) and a clear docstring that says what the tool does and describes each argument - an AI model reads this to decide when to call the tool.
7. If a parameter name is not a valid Python identifier, use a sanitized snake_case argument name and map it back to the original name when building the request.
8. Build the request with `httpx.request(...)`, `timeout=30`: substitute path parameters into the URL, send query parameters via `params=`, send body fields as JSON via `json=`, drop values that are None, call `response.raise_for_status()`, and return `response.json()` (fall back to `response.text` if the body is not JSON).
9. End the file with:
if __name__ == "__main__":
mcp.run()
10. The file must be valid Python. Do not invent endpoints that are not in the input."""
def get_api_key(typed_key):
if typed_key and typed_key.strip():
return typed_key.strip()
key = os.getenv("mcp")
if key:
return key
try: # Google Colab Secrets
from google.colab import userdata
return userdata.get("mcp")
except Exception:
return None
def make_client(api_key):
"""httpx version: the 'client' is simply the API key."""
return api_key
def call_llm(client, history):
"""history: list of (role, text) tuples where role is 'user' or 'assistant'."""
messages = [{"role": "system", "content": SYSTEM_PROMPT}] + [
{"role": role, "content": text} for role, text in history
]
resp = httpx.post(
BASE_URL + "/chat/completions",
headers={
"Authorization": f"Bearer {client}",
"Content-Type": "application/json",
"X-Title": "AutoMCP Forge",
},
json={"model": MODEL, "messages": messages, "temperature": 0.1, "max_tokens": 6000},
timeout=120,
)
resp.raise_for_status()
choices = resp.json().get("choices") or []
if not choices:
raise RuntimeError("OpenRouter returned no answer (the free model may be busy or rate-limited). Try again.")
return (choices[0].get("message") or {}).get("content") or ""
def clean_code(text):
"""Remove markdown fences if the model added them anyway."""
m = re.search(r"```(?:python|py)?\s*\n(.*?)```", text, re.S)
code = m.group(1) if m else text
return code.strip() + "\n"
def generate_server(client, api):
"""Ask the LLM for the server; auto-repair syntax errors up to 2 times."""
history = [("user", "API summary:\n" + json.dumps(api, ensure_ascii=False))]
code = clean_code(call_llm(client, history))
for attempt in range(3):
try:
ast.parse(code)
return code, True
except SyntaxError as err:
if attempt == 2:
break
history += [
("assistant", code),
("user", f"That code has a syntax error: {err}. Return the full corrected server.py only."),
]
code = clean_code(call_llm(client, history))
return code, False
# --------------------------------------------------------------------------- #
# Stage 3 - Gradio handler
# --------------------------------------------------------------------------- #
def forge(file_path, typed_key, max_endpoints):
if not file_path:
yield "⚠️ Please upload a `.json` file first.", [], "", None
return
# ---- Parse ------------------------------------------------------------
yield "⏳ **Step 1/3** - Parsing the file...", [], "", None
try:
kind, api = parse_api_file(file_path)
except json.JSONDecodeError:
yield "❌ That file is not valid JSON (YAML specs are not supported in Phase 1).", [], "", None
return
except Exception as e:
yield f"❌ {e}", [], "", None
return
total = len(api["endpoints"])
if total == 0:
yield "❌ No endpoints were found in this file.", [], "", None
return
limit = int(max_endpoints)
api["endpoints"] = api["endpoints"][:limit]
table = [
[e["method"], e["path"], e["summary"] or e["operation_id"], len(e["parameters"])]
for e in api["endpoints"]
]
note = f" (using the first {limit} of {total})" if total > limit else ""
yield (
f"βœ… Parsed **{api['title']}** as {kind}: {len(api['endpoints'])} endpoints{note}.\n\n"
"⏳ **Step 2/3** - Generating the MCP server with OpenRouter...",
table,
"",
None,
)
# ---- Generate ---------------------------------------------------------
key = get_api_key(typed_key)
if not key:
yield (
"❌ No OpenRouter API key found. Add `OPENROUTER_API_KEY` as a secret (or paste a key in the box on the left).",
table,
"",
None,
)
return
try:
code, valid = generate_server(make_client(key), api)
except Exception as e:
yield f"❌ OpenRouter API error: `{e}`\n\nCheck your API key. Free models are rate-limited, so wait a minute and retry.", table, "", None
return
# ---- Save & show ------------------------------------------------------
out_path = os.path.join(tempfile.mkdtemp(prefix="automcp_"), "server.py")
with open(out_path, "w", encoding="utf-8") as f:
f.write(code)
if valid:
status = (
f"βœ… **Done!** Generated `server.py` for **{api['title']}** ({len(api['endpoints'])} tools). "
"Syntax check passed. Review the code before using it."
)
else:
status = (
"⚠️ Code generated, but it **failed the Python syntax check** even after auto-repair. "
"Try again or lower the endpoint limit."
)
yield status, table, code, out_path
# --------------------------------------------------------------------------- #
# UI
# --------------------------------------------------------------------------- #
CSS = """
.gradio-container {max-width: 1150px !important; margin: auto;}
#title {text-align: center;}
"""
FORCE_DARK = "() => { document.body.classList.add('dark'); }"
# Gradio 6 moved theme/css/js from gr.Blocks() to launch(); support both.
try:
GRADIO_MAJOR = int(gr.__version__.split(".")[0])
except Exception:
GRADIO_MAJOR = 5
UI_OPTIONS = dict(
theme=gr.themes.Soft(primary_hue="indigo", neutral_hue="slate"),
css=CSS,
js=FORCE_DARK,
)
BLOCKS_KWARGS = {"title": "AutoMCP Forge"}
LAUNCH_KWARGS = {}
if GRADIO_MAJOR >= 6:
LAUNCH_KWARGS.update(UI_OPTIONS)
else:
BLOCKS_KWARGS.update(UI_OPTIONS)
with gr.Blocks(**BLOCKS_KWARGS) as demo:
gr.Markdown(
"# βš’οΈ AutoMCP Forge\n"
"**Phase 1 prototype** - upload an OpenAPI/Swagger or Postman `.json` file "
"and get a runnable FastMCP server.",
elem_id="title",
)
with gr.Row():
with gr.Column(scale=1):
file_in = gr.File(label="API definition (.json)", file_types=[".json"], type="filepath")
key_in = gr.Textbox(
label="OpenRouter API Key",
type="password",
placeholder="Leave empty to use the OPENROUTER_API_KEY secret",
)
max_in = gr.Slider(
1, 60, value=20, step=1,
label="Max endpoints to convert",
info="Keeps the prompt small and inside free-tier limits.",
)
run_btn = gr.Button("⚑ Forge MCP Server", variant="primary")
status_md = gr.Markdown("Waiting for a file...")
with gr.Column(scale=2):
table_out = gr.Dataframe(
headers=["Method", "Path", "Summary", "Params"],
interactive=False,
wrap=True,
label="Parsed endpoints",
)
code_out = gr.Code(label="Generated server.py", language="python", interactive=False, lines=24)
file_out = gr.File(label="Download server.py", interactive=False)
run_btn.click(
forge,
inputs=[file_in, key_in, max_in],
outputs=[status_md, table_out, code_out, file_out],
)
if __name__ == "__main__":
in_colab = "google.colab" in sys.modules
demo.queue().launch(share=in_colab, debug=in_colab, **LAUNCH_KWARGS)