""" 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"(?")`. 4. Define `BASE_URL = os.getenv("API_BASE_URL", "")` and `API_KEY = os.getenv("API_KEY", "")`. Add a helper `_headers()` that sends `Authorization: Bearer ` 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)