How janwilmake/openapi-mcp-server works
Project type and purpose
• This is a Node.js–based, open-source “Model Context Protocol” (MCP) server that exposes a tool interface for Claude/Cursor (and other MCP clients) to explore OpenAPI specs.
• Its goal is to let an LLM–driven client ask “Tell me about Stripe’s API” (for example) and have the server fetch the spec, summarize it, and drill into individual endpoints.
File structure
• Top-level files only: there is no separate “frontend” folder. Instead, this is purely a backend/service:
• index.js ← main entrypoint, defines the MCP tool handlers
• package.json ← dependencies and npm scripts
• context.json ← default metadata or prompt templates for MCP
• smithery.yaml ← configuration for publishing as a Smithery tool
• Dockerfile ← containerization definition
• README.md ← user-facing documentation
• No database folder or “lib” subdirs—everything lives in index.js (it likely imports from a few npm modules at runtime).
README for additional insights
• “3 step process”:
1. Resolve the OpenAPI identifier (e.g. URL or registry key)
2. Summarize the entire spec in simple language
3. For each requested endpoint, retrieve detailed operation info
• Integrations: oapis.org (for spec hosting), Claude/Cursor (as an LLM client), Smithery (for install/publish).
Main components
a. MCP Client
• e.g. Claude Desktop, Cursor, any custom MCP-capable client
b. MCP Server (this project)
• Node.js runtime (index.js)
• Smithery tool wrapper (smithery.yaml)
c. OpenAPI Spec Provider
• oapis.org or any remote registry from which the server fetches the spec
d. LLM Service
• Claude API (or other LLM endpoint) invoked via Smithery’s built-in mechanisms
e. (Optional) Container / Deployment
• Docker container running Node.js
• Any orchestration (if deployed to Kubernetes, AWS ECS, etc.)
Relationships and data flows
1. Client → MCP Server
• “I want an overview of the GitHub API.”
• This arrives as an MCP invocation to the tool’s entrypoint in index.js.
2. MCP Server → Spec Provider
• Fetch the raw OpenAPI JSON/YAML from oapis.org.
3. MCP Server → LLM Service (Summarizer)
• Send the full spec and prompt to get a human-friendly summary.
4. MCP Server → Client
• Return the summary.
5. Client → MCP Server (follow-up)
• “Now tell me about the /repos endpoint.”
6. MCP Server → LLM Service (Operation Explainer)
• Extract that endpoint’s details and ask the LLM to explain.
7. MCP Server → Client
• Return the endpoint description.
Architectural patterns and design principles
• Thin request router: index.js implements individual “tool handlers” for each MCP action.
• Stateless design: each request fetches spec anew (no persistent storage).
• Adapter pattern: Smithery acts as an adapter between generic MCP calls and your handler functions.
• Clear separation of concerns: fetching, summarizing, and deep-dive are each isolated steps.
Call out important files/technologies
• index.js: entrypoint and handler implementations
• smithery.yaml: maps tool name/commands to index.js handlers
• Dockerfile: defines how to containerize the Node.js runtime
• context.json: default prompt templates or metadata used by handlers
• package.json: Node.js dependencies (e.g. axios for HTTP, @smithery/core for MCP)
Detail without overthinking
• External integrations (oapis.org, LLM endpoint, client)
• Every distinct handler or step in the three-step process
• Clearly separates the MCP client, MCP server, and external services
• Visualizes request/response flows for each of the three main steps
• Highlights where new contributors can plug in additional handlers or integrations