← Back to ProjectsView Architecture
GitHub

MCPForge

MCPForge

Project Overview

  • Name: MCPForge
  • Type: Personal, open-source web application
  • Built for: TestSprite Hackathon
  • Purpose: Convert any OpenAPI specification into a production-ready MCP (Model Context Protocol) server, entirely from the browser
  • One-liner: A visual OpenAPI-to-MCP server generator that imports a spec, lets you classify each endpoint into MCP types, and exports a working, ready-to-run server package

MCPForge closes a real gap in the MCP tooling space: there was no visual tool that lets you import an OpenAPI spec, see all your endpoints at a glance, classify them into MCP types, and generate a working MCP server without manual CLI work. MCPForge turns that whole flow into a few clicks in the browser.

Key Features

  • Spec import from anywhere - load an OpenAPI 3.x spec as JSON, YAML, or a remote URL. A server-side fetch route proxies URL imports to avoid CORS issues.
  • Visual endpoint explorer - every path and operation is parsed into a searchable, filterable table showing method, path, operationId, summary, parameter counts, and whether the operation has a request body.
  • MCP type assignment - assign each endpoint to one of four MCP types (Tool, Resource, Resource Template, or Excluded) via dropdowns, with sensible defaults inferred from the spec (GET with path params becomes a resource template, GET without becomes a resource, everything else becomes a tool). Bulk assignment is supported.
  • Server configuration panel - choose the server name and version, base URL, port, transport, and auth method before generating.
  • Production-grade code generation - emits a complete Node.js/TypeScript MCP server with JSON Schema validation, Zod runtime checks, and an axios HTTP client.
  • Three transports - generated servers support stdio, Server-Sent Events (SSE), and Streamable HTTP.
  • One-click ZIP export - download a ready-to-run server package built in the browser with JSZip.
  • Version history - snapshots of project configuration are stored so earlier generation states can be revisited.
  • Multi-project dashboard - manage multiple specs/projects per authenticated user.
  • Comprehensive test coverage - 70 automated test files (63 frontend scripts across 3 TestSprite runs plus 7 backend API tests) covering auth, navigation, project CRUD, and endpoint management.

Architecture / How It Works

The application follows a single Next.js 16 App Router codebase with API route handlers acting as the backend.

  1. Import and parse - the OpenAPI parser (src/lib/openapi-parser.ts) detects JSON vs YAML, validates required OpenAPI 3.x fields (info, paths, openapi), strips external $ref pointers, and uses @apidevtools/swagger-parser to dereference internal refs. It iterates every path and method, merging path-level and operation-level parameters and extracting request-body and security metadata.
  2. Persist - parsed projects, per-endpoint mappings, server config, and version snapshots are stored via Prisma ORM on SQLite. The data model centers on User, Project, EndpointMapping, ServerConfig, and ProjectVersion, with cascade-delete relations from project to its children.
  3. Classify - the project detail UI lets the user review endpoints and override the inferred MCP type per endpoint, persisted through the mappings API routes.
  4. Generate - the code generator (src/lib/code-generator.ts) builds a full MCP server project (src/index.ts, package.json, tsconfig.json, .env.example, README.md). It implements the low-level MCP Server API, exposing endpoints as tools through ListTools and CallTool handlers, validating arguments with Zod (via json-schema-to-zod), and mapping path params, query strings, headers, and bodies onto axios HTTP calls. Security schemes from the spec (API key, Bearer, Basic, OAuth2, OpenID Connect) drive the generated auth and required environment variables.
  5. Export - the download route assembles the generated files into a ZIP with JSZip for the user to run locally.

API Surface

  • /api/fetch-spec - server-side proxy for URL spec imports
  • /api/projects and /api/projects/[id] - project CRUD
  • /api/projects/[id]/config - server configuration
  • /api/projects/[id]/mappings (+ /[mappingId], /bulk) - endpoint-to-MCP-type mappings
  • /api/projects/[id]/generate and /download - code generation and ZIP export
  • /api/projects/[id]/versions - configuration version snapshots
  • /api/auth/[...nextauth] and /api/auth/signup - authentication

Technical Stack

  • Framework: Next.js 16 (App Router) with React 19 and TypeScript 5
  • Styling/UI: Tailwind CSS v4, shadcn/ui, Base UI, lucide-react icons, Sonner toasts, next-themes
  • Auth: Auth.js (NextAuth v5 beta) with credentials and bcryptjs password hashing
  • Database/ORM: Prisma 6 on SQLite
  • OpenAPI handling: @apidevtools/swagger-parser, yaml
  • Validation: Zod 4 (with json-schema-to-zod in generated servers)
  • Code display/export: react-syntax-highlighter, JSZip
  • HTTP (generated servers): axios
  • Testing: TestSprite-generated end-to-end and API test suites (70 files total)

Architecture Diagram

Drag to pan, scroll to zoom