{
  "openapi": "3.1.0",
  "info": {
    "title": "MCPConfigForge Deterministic MCP Compiler & Validator API",
    "version": "1.0.0",
    "summary": "Compile, validate, and normalize Model Context Protocol (MCP) configurations across Cursor, Claude Desktop, Claude Code CLI, and VS Code.",
    "description": "Public REST API v1 for deterministic MCP schema compilation, Windows cmd /c npx normalization, and environment secret auditing. Returns RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and X-API-Version headers on all responses, and RFC 9457 Problem Details (application/problem+json) on 400/404/429/500 errors.",
    "contact": {
      "name": "MCPConfigForge Engineering",
      "url": "https://neatjar.com/mcp-forge/contact",
      "email": "sunxg5512@gmail.com"
    },
    "license": {
      "name": "Proprietary Commercial & Free Community API",
      "url": "https://neatjar.com/mcp-forge/privacy"
    }
  },
  "servers": [
    {
      "url": "https://neatjar.com/mcp-forge/",
      "description": "Cloudflare Workers Global Edge Production Endpoint"
    }
  ],
  "paths": {
    "/api/v1/forge": {
      "get": {
        "operationId": "forgeMcpConfigGet",
        "summary": "Compile 5 client MCP configurations for a server slug or npm package",
        "parameters": [
          {
            "name": "server",
            "in": "query",
            "required": false,
            "description": "Server slug (e.g. postgres, github, playwright, stripe) or npm package name (@modelcontextprotocol/server-postgres)",
            "schema": {
              "type": "string",
              "default": "postgres"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Compiled MCP configurations for Cursor, Claude Desktop (macOS/Windows), Claude Code CLI, VS Code, and install-mcp.sh",
            "headers": {
              "RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                },
                "description": "Requests allowed per 60s window"
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                },
                "description": "Remaining requests in current window"
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds until rate limit window resets"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForgeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid server parameter (RFC 9457 Problem Details)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorProblem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (RFC 9457 Problem Details)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorProblem"
                }
              }
            }
          },
          "500": {
            "description": "Internal compiler error (RFC 9457 Problem Details)",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorProblem"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "forgeMcpConfigPost",
        "summary": "Validate custom raw MCP JSON or compile an npm/GitHub server specifier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "server": {
                    "type": "string",
                    "description": "Server slug, npm package, or GitHub URL"
                  },
                  "rawJson": {
                    "type": "string",
                    "description": "Optional raw mcp.json string to validate and repair"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validated and compiled MCP client artifacts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForgeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed request payload",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorProblem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorProblem"
                }
              }
            }
          },
          "500": {
            "description": "Internal compiler error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorProblem"
                }
              }
            }
          }
        }
      }
    },
    "/api/telemetry": {
      "get": {
        "operationId": "getTelemetry",
        "summary": "Retrieve durable Cloudflare KV telemetry counters for EXP-005 MCPConfigForge",
        "responses": {
          "200": {
            "description": "Durable KV telemetry snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "siteId",
                    "storage",
                    "persisted",
                    "pv",
                    "audits",
                    "downloads",
                    "checkoutClicks"
                  ],
                  "properties": {
                    "siteId": {
                      "type": "string"
                    },
                    "storage": {
                      "type": "string",
                      "enum": [
                        "cloudflare-kv"
                      ]
                    },
                    "persisted": {
                      "type": "boolean"
                    },
                    "pv": {
                      "type": "integer"
                    },
                    "audits": {
                      "type": "integer"
                    },
                    "downloads": {
                      "type": "integer"
                    },
                    "checkoutClicks": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ForgeResponse": {
        "type": "object",
        "required": [
          "ok",
          "serverSlug",
          "serverName",
          "npmPackage",
          "readinessScore",
          "cursorJson",
          "claudeDesktopMacJson",
          "claudeDesktopWinJson",
          "claudeCodeCli",
          "vscodeJson",
          "installScriptSh"
        ],
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "serverSlug": {
            "type": "string"
          },
          "serverName": {
            "type": "string"
          },
          "npmPackage": {
            "type": "string"
          },
          "transport": {
            "type": "string"
          },
          "readinessScore": {
            "type": "integer"
          },
          "cursorJson": {
            "type": "string"
          },
          "claudeDesktopMacJson": {
            "type": "string"
          },
          "claudeDesktopWinJson": {
            "type": "string"
          },
          "claudeCodeCli": {
            "type": "string"
          },
          "vscodeJson": {
            "type": "string"
          },
          "installScriptSh": {
            "type": "string"
          }
        }
      },
      "ErrorProblem": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code",
          "message"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}