rapidoc 11.0.0 → 12.0.0

package/src/utils/mcp/generators/python.js

@@ -0,0 +1,248 @@
+/**
+ * Single-file Python FastMCP Server Generator
+ * Uses fastmcp with zero external networking dependencies (urllib.request).
+ */
+import { toSnakeCase, estimateTokenCost } from "../common.js";
+
+export function generatePythonFastMcpServer(metadata, tools, resources, workflows, options = {}) {
+  const serverName = toSnakeCase(options.serverName || metadata.title || "rapidoc_mcp_server");
+  const budget = estimateTokenCost(tools, resources, workflows);
+  const defaultBaseUrl = metadata.servers?.[0]?.url || "http://localhost:3000";
+
+  const toolFunctions = tools
+    .map((t) => {
+      const pyArgs = t.parameters
+        .map((p) => {
+          let pyType = "str";
+          if (p.type === "integer") pyType = "int";
+          else if (p.type === "number") pyType = "float";
+          else if (p.type === "boolean") pyType = "bool";
+          else if (p.type === "array") {
+            const itemType = p.items?.type;
+            if (itemType === "integer") pyType = "List[int]";
+            else if (itemType === "number") pyType = "List[float]";
+            else if (itemType === "boolean") pyType = "List[bool]";
+            else if (itemType === "object") pyType = "List[Dict[str, Any]]";
+            else pyType = "List[str]";
+          } else if (p.type === "object") pyType = "Dict[str, Any]";
+
+          if (!p.required) {
+            return `${toSnakeCase(p.name)}: Optional[${pyType}] = None`;
+          }
+          return `${toSnakeCase(p.name)}: ${pyType}`;
+        })
+        .join(", ");
+
+      const allPyArgs = [pyArgs, "api_key: Optional[str] = None"].filter(Boolean).join(", ");
+      const pathParams = t.parameters.filter((p) => p.in === "path");
+      const safePathCode = pathParams
+        .map(
+          (p) =>
+            `    safe_${toSnakeCase(p.name)} = urllib.parse.quote(str(${toSnakeCase(p.name)}))`,
+        )
+        .join("\n");
+      const pathSub = t.path.replace(/\{([^}]+)\}/g, (match, p1) => `{safe_${toSnakeCase(p1)}}`);
+
+      return `
+@mcp.tool(
+    name="${t.name}",
+    description="${t.description.replace(/"/g, '\\"')}"
+)
+def ${t.name}(${allPyArgs}) -> str:
+    """${t.description}${t.isConsequential ? " (⚠️ Consequential action - requires confirmation)" : ""}"""
+${safePathCode ? safePathCode + "\n" : ""}    url = f"{BASE_URL.rstrip('/')}${pathSub}"
+    headers = {"Accept": "application/json"}
+${t.parameters
+  .filter((p) => p.in === "header")
+  .map(
+    (p) =>
+      `    if ${toSnakeCase(p.name)} is not None:\n        headers["${p.name}"] = str(${toSnakeCase(p.name)})`,
+  )
+  .join("\n")}
+    resolved_key = api_key or API_KEY
+    if resolved_key:
+        headers["Authorization"] = f"Bearer {resolved_key}"
+
+    params = {}
+${t.parameters
+  .filter((p) => p.in === "query")
+  .map(
+    (p) =>
+      `    if ${toSnakeCase(p.name)} is not None:\n        params["${p.name}"] = ${toSnakeCase(p.name)}`,
+  )
+  .join("\n")}
+    if params:
+        url += ("&" if "?" in url else "?") + urllib.parse.urlencode(params)
+
+    body_bytes = None
+${
+  ["POST", "PUT", "PATCH"].includes(t.method)
+    ? `    body_payload = {}
+${t.parameters
+  .filter((p) => p.in === "body")
+  .map(
+    (p) =>
+      `    if ${toSnakeCase(p.name)} is not None:\n        body_payload["${p.name}"] = ${toSnakeCase(p.name)}`,
+  )
+  .join("\n")}
+    if body_payload:
+        headers["Content-Type"] = "application/json"
+        body_bytes = json.dumps(body_payload).encode("utf-8")`
+    : ""
+}
+
+    req = urllib.request.Request(url, data=body_bytes, headers=headers, method="${t.method}")
+    try:
+        with urllib.request.urlopen(req, timeout=30.0) as resp:
+            return resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        return e.read().decode("utf-8")
+    except Exception as e:
+        return f"Error invoking ${t.name}: {str(e)}"
+`;
+    })
+    .join("\n");
+
+  const resourceFunctions = resources
+    .map((r) => {
+      return `
+@mcp.resource("${r.uri}")
+def ${toSnakeCase(r.name)}(uri: str = "") -> str:
+    """${r.description}"""
+    url = f"{BASE_URL.rstrip('/')}${r.path}"
+    headers = {"Accept": "${r.mimeType || "application/json"}"}
+
+    resolved_key = API_KEY
+    if uri and "?" in uri:
+        parsed_query = urllib.parse.parse_qs(urllib.parse.urlparse(uri).query)
+        passed_key = parsed_query.get("apiKey") or parsed_query.get("api_key")
+        if passed_key and passed_key[0].strip():
+            resolved_key = passed_key[0].strip()
+
+    if resolved_key:
+        headers["Authorization"] = f"Bearer {resolved_key}"
+
+    if uri and "?" in uri:
+        parsed_query = urllib.parse.parse_qs(urllib.parse.urlparse(uri).query)
+        params = {k: v[0] for k, v in parsed_query.items() if k.lower() not in ["apikey", "api_key"]}
+        if params:
+            url += ("&" if "?" in url else "?") + urllib.parse.urlencode(params)
+
+    req = urllib.request.Request(url, headers=headers, method="GET")
+    try:
+        with urllib.request.urlopen(req, timeout=30.0) as resp:
+            return resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        return e.read().decode("utf-8")
+    except Exception as e:
+        return f"Error loading resource: {str(e)}"
+`;
+    })
+    .join("\n");
+
+  const workflowFunctions = workflows
+    .map((w) => {
+      const paramKeys = w.parameters ? Object.keys(w.parameters) : [];
+      const pyArgs = paramKeys
+        .map((k) => `${toSnakeCase(k)}: str`)
+        .concat(["api_key: Optional[str] = None"])
+        .join(", ");
+
+      return `
+@mcp.tool(
+    name="${w.name}",
+    description="${(w.description || "Composite workflow").replace(/"/g, '\\"')}"
+)
+def ${toSnakeCase(w.name)}(${pyArgs}) -> str:
+    """Composite workflow: ${(w.description || "").replace(/"/g, '\\"')}"""
+    results = {}
+    headers = {"Accept": "application/json"}
+    resolved_key = api_key or API_KEY
+    if resolved_key:
+        headers["Authorization"] = f"Bearer {resolved_key}"
+
+    try:
+${(w.steps || [])
+  .map((s, idx) => {
+    const argKey = paramKeys[0] || "id";
+    return `        # Step ${idx + 1}: ${s.call}
+        step_url_${idx} = f"{BASE_URL.rstrip('/')}/api/{urllib.parse.quote(str(${toSnakeCase(argKey)}))}"
+        req_${idx} = urllib.request.Request(step_url_${idx}, headers=headers, method="GET")
+        with urllib.request.urlopen(req_${idx}, timeout=30.0) as resp_${idx}:
+            results["${s.call}"] = json.loads(resp_${idx}.read().decode("utf-8"))`;
+  })
+  .join("\n")}
+        return json.dumps(results, indent=2)
+    except Exception as e:
+        return f"Workflow ${w.name} failed: {str(e)}"
+`;
+    })
+    .join("\n");
+
+  return `"""
+Auto-generated by RapiDoc Curated MCP Generator
+Spec: ${metadata.title} (v${metadata.version})
+
+[MULTI-TENANCY & AUTHENTICATION]
+- Local Stdio Mode: Claude Desktop, Cursor, and local agents use API_KEY from environment.
+- Multi-Tenant / Agent Mode: When running in a shared service, the calling AI agent can pass
+  per-session credentials directly in the \`api_key\` parameter of any tool.
+
+[TOKEN BUDGET DIAGNOSTIC]
+- Total Tools: ${budget.totalTools}
+- Total Resources: ${budget.totalResources}
+- Total Workflows: ${budget.totalWorkflows}
+- Estimated Prompt Context Overhead: ~${budget.estimatedTokens.toLocaleString()} tokens/turn
+${budget.warnings.map((w) => `- ${w}`).join("\n")}
+
+[HOW TO RUN]
+1. pip install fastmcp
+2. fastmcp run server.py
+"""
+
+import os
+import json
+import urllib.request
+import urllib.parse
+import urllib.error
+from typing import Optional, List, Dict, Any
+from fastmcp import FastMCP
+
+API_KEY = os.environ.get("API_KEY", "")
+BASE_URL = os.environ.get("API_BASE_URL", "${defaultBaseUrl}")
+
+mcp = FastMCP("${serverName}")
+
+${resourceFunctions}
+${toolFunctions}
+${workflowFunctions}
+
+if __name__ == "__main__":
+    mcp.run()
+`;
+}
+
+export function generatePythonFiles(serverCode, metadata) {
+  const readme = `# ${metadata.title} - MCP Server (Python FastMCP)
+
+Auto-generated by RapiDoc Curated MCP Generator.
+
+Zero external networking dependencies: uses Python standard library (\`urllib.request\`) + FastMCP.
+
+### Prerequisites
+- Python 3.10+
+- \`pip install -r requirements.txt\`
+
+### Running the Server
+\`\`\`bash
+export API_KEY="your-api-key"
+fastmcp run server.py
+\`\`\`
+`;
+
+  return {
+    "server.py": serverCode,
+    "requirements.txt": "fastmcp>=0.4.0\n",
+    "README.md": readme,
+  };
+}

package/src/utils/mcp/generators/rust.js

@@ -0,0 +1,281 @@
+/**
+ * Single-file Rust MCP Server Generator
+ * Uses mcp_sdk / rmcp conventions.
+ */
+import { toSnakeCase, estimateTokenCost } from "../common.js";
+
+export function generateRustMcpServer(metadata, tools, resources, workflows, options = {}) {
+  const serverName = toSnakeCase(options.serverName || metadata.title || "rapidoc_mcp_server");
+  const budget = estimateTokenCost(tools, resources, workflows);
+  const defaultBaseUrl = metadata.servers?.[0]?.url || "http://localhost:3000";
+
+  const toolRegistrations = tools
+    .map((t) => {
+      const propCalls = t.parameters
+        .map((p) => {
+          let rustSchemaType = "string";
+          if (p.type === "integer" || p.type === "number") rustSchemaType = "number";
+          else if (p.type === "boolean") rustSchemaType = "boolean";
+          else if (p.type === "array") rustSchemaType = "array";
+          else if (p.type === "object") rustSchemaType = "object";
+          return `\n            .property("${toSnakeCase(p.name)}", "${rustSchemaType}", ${Boolean(p.required)}, ${JSON.stringify(p.description || "")})`;
+        })
+        .join("");
+
+      return `    server.add_tool(
+        Tool::new("${t.name}", ${JSON.stringify(t.description)})
+${propCalls ? propCalls + "\n" : ""}            .property("api_key", "string", false, "Optional Bearer API key override for multi-tenant sessions")
+    );`;
+    })
+    .join("\n\n");
+
+  const workflowRegistrations = workflows
+    .map((w) => {
+      const paramKeys = w.parameters ? Object.keys(w.parameters) : [];
+      const propCalls = paramKeys
+        .map(
+          (k) =>
+            `\n            .property("${toSnakeCase(k)}", "string", true, ${JSON.stringify(w.parameters[k].description || "")})`,
+        )
+        .join("");
+
+      return `    server.add_tool(
+        Tool::new("${w.name}", ${JSON.stringify(w.description || "Composite workflow")})
+${propCalls ? propCalls + "\n" : ""}            .property("api_key", "string", false, "Optional Bearer API key override for multi-tenant sessions")
+    );`;
+    })
+    .join("\n\n");
+
+  const toolArms = tools
+    .map((t) => {
+      const pathSub = t.path.replace(/\{[^}]+\}/g, "{}");
+      const pathParams = t.parameters.filter((p) => p.in === "path");
+      const queryParams = t.parameters.filter((p) => p.in === "query");
+      const bodyParams = t.parameters.filter((p) => p.in === "body");
+      const hasBody = ["POST", "PUT", "PATCH"].includes(t.method) && bodyParams.length > 0;
+
+      const pathArgs = pathParams
+        .map(
+          (p) =>
+            `urlencoding::encode(args.get("${toSnakeCase(p.name)}").and_then(|v| v.as_str()).unwrap_or("")).as_ref()`,
+        )
+        .join(", ");
+
+      const queryCode =
+        queryParams.length > 0
+          ? `                    let mut query_params: Vec<(&str, String)> = Vec::new();
+${queryParams
+  .map(
+    (p) => `                    if let Some(val) = args.get("${toSnakeCase(p.name)}") {
+                        let s = val.as_str().map(String::from).unwrap_or_else(|| val.to_string());
+                        query_params.push(("${p.name}", s));
+                    }`,
+  )
+  .join("\n")}
+                    if !query_params.is_empty() {
+                        req = req.query(&query_params);
+                    }\n`
+          : "";
+
+      const bodyCode = hasBody
+        ? `                    let mut body_map = serde_json::Map::new();
+${bodyParams
+  .map(
+    (p) => `                    if let Some(val) = args.get("${toSnakeCase(p.name)}") {
+                        body_map.insert("${p.name}".to_string(), val.clone());
+                    }`,
+  )
+  .join("\n")}
+                    if !body_map.is_empty() {
+                        req = req.json(&body_map);
+                    }\n`
+        : "";
+
+      return `                "${t.name}" => {
+                    let url = format!("{}${pathSub}", base_url.trim_end_matches('/')${pathArgs ? `, ${pathArgs}` : ""});
+                    let mut req = client.request(reqwest::Method::from_bytes(b"${t.method}")?, &url)
+                        .header("Accept", "application/json");
+${t.parameters
+  .filter((p) => p.in === "header")
+  .map(
+    (p) =>
+      `                    if let Some(h) = args.get("${p.name}").or_else(|| args.get("${toSnakeCase(p.name)}")).and_then(|v| v.as_str()) {\n                        req = req.header("${p.name}", h);\n                    }`,
+  )
+  .join("\n")}
+                    let resolved_key = args.get("api_key").and_then(|v| v.as_str()).map(String::from).or_else(|| api_key.clone());
+                    if let Some(ref key) = resolved_key {
+                        req = req.header("Authorization", format!("Bearer {}", key));
+                    }
+${queryCode}${bodyCode}                    let resp = req.send().await?;
+                    let text = resp.text().await?;
+                    Ok(ToolResponse::text(text))
+                }`;
+    })
+    .join("\n");
+
+  const workflowArms = workflows
+    .map((w) => {
+      const paramKeys = w.parameters ? Object.keys(w.parameters) : [];
+      const argKey = paramKeys[0] || "id";
+
+      return `                "${w.name}" => {
+                    let resolved_key = args.get("api_key").and_then(|v| v.as_str()).map(String::from).or_else(|| api_key.clone());
+                    let param_val = args.get("${toSnakeCase(argKey)}").and_then(|v| v.as_str()).unwrap_or("");
+                    let mut results = serde_json::Map::new();
+${(w.steps || [])
+  .map(
+    (s, idx) => `                    // Step ${idx + 1}: ${s.call}
+                    let step_url_${idx} = format!("{}/api/{}", base_url.trim_end_matches('/'), urlencoding::encode(param_val));
+                    let mut step_req_${idx} = client.get(&step_url_${idx}).header("Accept", "application/json");
+                    if let Some(ref key) = resolved_key {
+                        step_req_${idx} = step_req_${idx}.header("Authorization", format!("Bearer {}", key));
+                    }
+                    if let Ok(resp) = step_req_${idx}.send().await {
+                        if let Ok(json_res) = resp.json::<serde_json::Value>().await {
+                            results.insert("${s.call}".to_string(), json_res);
+                        }
+                    }`,
+  )
+  .join("\n")}
+                    Ok(ToolResponse::text(serde_json::to_string_pretty(&results)?))
+                }`;
+    })
+    .join("\n");
+
+  const resourceArms = resources
+    .map((r) => {
+      return `                "${r.uri}" => {
+                    let mut req = client.get(format!("{}{}", base_url.trim_end_matches('/'), "${r.path}")).header("Accept", "${r.mimeType}");
+                    if !query_params.is_empty() {
+                        req = req.query(&query_params);
+                    }
+                    if let Some(ref key) = resolved_key {
+                        req = req.header("Authorization", format!("Bearer {}", key));
+                    }
+                    let resp = req.send().await.map_err(|e| Box::new(e) as Box<dyn Error>)?;
+                    let text = resp.text().await.map_err(|e| Box::new(e) as Box<dyn Error>)?;
+                    Ok(vec![mcp_sdk::server::ResourceContents::text("${r.uri}", "${r.mimeType}", text)])
+                }`;
+    })
+    .join("\n");
+
+  const hasResources = resources.length > 0;
+  const resourceRegistration = hasResources
+    ? `
+    server.on_read_resource(move |uri| {
+        let client = client.clone();
+        let api_key = api_key.clone();
+        let base_url = base_url.clone();
+        async move {
+            let (base_uri, query_str) = uri.split_once('?').unwrap_or((uri.as_str(), ""));
+            let mut resolved_key = api_key.clone();
+            let mut query_params: Vec<(&str, &str)> = Vec::new();
+
+            if !query_str.is_empty() {
+                for pair in query_str.split('&') {
+                    if let Some((k, v)) = pair.split_once('=') {
+                        if k.eq_ignore_ascii_case("apikey") || k.eq_ignore_ascii_case("api_key") {
+                            if !v.is_empty() {
+                                resolved_key = Some(v.to_string());
+                            }
+                        } else if !k.is_empty() {
+                            query_params.push((k, v));
+                        }
+                    }
+                }
+            }
+
+            match base_uri {
+${resourceArms}
+                _ => Err(format!("Unknown resource: {}", uri).into()),
+            }
+        }
+    });`
+    : "";
+
+  return `/*
+Auto-generated by RapiDoc Curated MCP Generator
+Spec: ${metadata.title} (v${metadata.version})
+
+[MULTI-TENANCY & AUTHENTICATION]
+- Local Stdio Mode: Claude Desktop, Cursor, and local agents use API_KEY from environment.
+- Multi-Tenant / Agent Mode: When running in a shared service, the calling AI agent can pass
+  per-session credentials directly in the \`api_key\` parameter of any tool.
+
+[TOKEN BUDGET DIAGNOSTIC]
+- Total Tools: ${budget.totalTools}
+- Total Resources: ${budget.totalResources}
+- Total Workflows: ${budget.totalWorkflows}
+- Estimated Prompt Context Overhead: ~${budget.estimatedTokens.toLocaleString()} tokens/turn
+${budget.warnings.map((w) => `- ${w}`).join("\n")}
+
+[HOW TO RUN]
+1. cargo build --release
+2. cargo run
+*/
+
+use std::env;
+use std::error::Error;
+use mcp_sdk::server::{Server, StdioTransport, Tool, ToolResponse};
+use serde_json::Value;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn Error>> {
+    let api_key = env::var("API_KEY").ok();
+    let base_url = env::var("API_BASE_URL").unwrap_or_else(|_| "${defaultBaseUrl}".to_string());
+    let client = reqwest::Client::new();
+
+    let mut server = Server::new("${serverName}", "${metadata.version || "1.0.0"}");
+
+${toolRegistrations}
+${workflowRegistrations ? "\n" + workflowRegistrations : ""}
+
+    server.on_call_tool(move |name, args: Value| {
+        let client = client.clone();
+        let api_key = api_key.clone();
+        let base_url = base_url.clone();
+        async move {
+            let result: Result<ToolResponse, Box<dyn Error>> = async {
+                match name.as_str() {
+${toolArms}
+${workflowArms}
+                    _ => Err(format!("Unknown tool or workflow: {}", name).into()),
+                }
+            }.await;
+
+            match result {
+                Ok(resp) => Ok(resp),
+                Err(e) => Ok(ToolResponse::error(format!("Execution failed: {}", e))),
+            }
+        }
+    });${resourceRegistration}
+
+    server.listen(StdioTransport::new()).await?;
+    Ok(())
+}
+`;
+}
+
+export function generateRustFiles(serverCode, metadata, options = {}) {
+  const cargoToml = `[package]\nname = "${toSnakeCase(options.serverName || metadata.title || "rapidoc_mcp")}"\nversion = "0.1.0"\nedition = "2021"\n\n[dependencies]\nmcp-sdk = "0.1"\ntokio = { version = "1.0", features = ["full"] }\nreqwest = { version = "0.11", features = ["json"] }\nserde_json = "1.0"\nurlencoding = "2.1"\n`;
+  const readme = `# ${metadata.title} - MCP Server (Rust)
+
+Auto-generated by RapiDoc Curated MCP Generator.
+
+### Prerequisites
+- Rust & Cargo (1.75+)
+
+### Building & Running
+\`\`\`bash
+cargo build --release
+export API_KEY="your-api-key"
+./target/release/${toSnakeCase(options.serverName || metadata.title || "rapidoc_mcp")}
+\`\`\`
+`;
+
+  return {
+    "src/main.rs": serverCode,
+    "Cargo.toml": cargoToml,
+    "README.md": readme,
+  };
+}