# janwilmake/openapi-mcp-server architecture

> Architecture diagram of the GitHub repository janwilmake/openapi-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/janwilmake/openapi-mcp-server
- Repository: https://github.com/janwilmake/openapi-mcp-server

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% MCP Client
    subgraph "MCP Client"
        Client["MCP Client\n(Claude, Cursor, etc.)"]:::external
    end

    %% MCP Server
    subgraph "MCP Server\n(Node.js Runtime)"
        indexJS["index.js\n(Handlers & Router)"]:::internal
        smithery["smithery.yaml"]:::file
        context["context.json"]:::file
        pkg["package.json"]:::file
        dockerfile["Dockerfile"]:::file
        readme["README.md"]:::file
        license["LICENSE"]:::file
        gitignore[".gitignore"]:::file
    end

    %% External Services
    subgraph "External Services"
        spec["OpenAPI Spec Provider\noapis.org"]:::external
        llm["LLM Service\n(Claude API)"]:::external
        dockerHost["Docker Host\n/ Orchestrator"]:::external
    end

    %% Flows
    Client -->|MCP invocation| indexJS
    indexJS -.->|Fetch spec| spec
    indexJS -.->|Summarize spec| llm
    indexJS -.->|Explain endpoint| llm
    indexJS -->|Return response| Client
    indexJS -.->|Container deploy| dockerHost

    %% Click events
    click indexJS "https://github.com/janwilmake/openapi-mcp-server/blob/main/index.js"
    click smithery "https://github.com/janwilmake/openapi-mcp-server/blob/main/smithery.yaml"
    click context "https://github.com/janwilmake/openapi-mcp-server/blob/main/context.json"
    click pkg "https://github.com/janwilmake/openapi-mcp-server/blob/main/package.json"
    click dockerfile "https://github.com/janwilmake/openapi-mcp-server/tree/main/Dockerfile"
    click readme "https://github.com/janwilmake/openapi-mcp-server/blob/main/README.md"
    click license "https://github.com/janwilmake/openapi-mcp-server/tree/main/LICENSE"
    click gitignore "https://github.com/janwilmake/openapi-mcp-server/blob/main/.gitignore"

    %% Styles
    classDef internal fill:#E8F1FA,stroke:#0366D6,stroke-width:2px;
    classDef external fill:#F0F0F0,stroke:#555555,stroke-width:2px,stroke-dasharray: 5 5;
    classDef file fill:#FAF3E0,stroke:#D4A017,stroke-width:1px;
```
