# snaggle-ai/openapi-mcp-server architecture

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

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

## Overview

Key Components to Include:

##### Core System Components
- OpenAPI MCP Server (Main Proxy)
- Claude Desktop Integration
- Target API Endpoints
- File System Interface (for file uploads)

##### Main Processing Flows
a. OpenAPI Specification Processing Flow:
- Spec Parser
- Tool Generation
- MCP Protocol Conversion

b. Request Processing Flow:
- Claude Request Handling
- Parameter Validation
- File Upload Processing
- API Call Execution

##### Top Level (External Interfaces)
- Target API(s) at the bottom
- OpenAPI MCP Server in the middle

##### Internal Components (Left to Right)
- OpenAPI Parser Module (src/openapi/parser.ts)
- MCP Proxy Module (src/mcp/proxy.ts)
- HTTP Client Module (src/client/http-client.ts)
- File Upload Handler (src/openapi/file-upload.ts)

Use these visual elements:

##### Component Representations
- Rectangles: Main system components
- Hexagons: External services (Claude, Target APIs)
- Rounded rectangles: Internal processing modules

##### Connection Types

- Blue: Core proxy components
- Green: External interfaces (Claude, Target APIs)
- Orange: File handling components
- Gray: Support services

Specific Implementation Details to Show:

##### Request Flow
**Claude Desktop -> MCP Server -> Parser -> HTTP Client -> Target API**

##### File Upload Flow
**Local Files -> File Upload Handler -> Multipart Processor -> HTTP Client -> Target API**

##### Tool Generation Flow
**OpenAPI Spec -> Parser -> MCP Protocol Converter -> Claude Tools**

Important Elements to Highlight:

##### Configuration Points
- OpenAPI spec input
- Claude Desktop configuration
- File system permissions

##### Security Boundaries
- File system access restrictions
- API authentication handling
- Request validation

##### Integration Points
- MCP protocol interface
- File system interface
- API client interface

Annotations:

##### Security Notes: "File Access Restrictions"

Keep these aspects in mind:

##### Modularity
- Clear separation between components
- Extensibility points
- Optional features

##### Error Handling
- Validation points
- Error flow paths
- Retry mechanisms

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    Claude["Claude Desktop"]:::external
    TargetAPI["Target APIs"]:::external

    %% Main Components
    subgraph Server["OpenAPI MCP Server"]
        direction TB
        Proxy["MCP Proxy"]
        Parser["OpenAPI Parser"]
        HTTPClient["HTTP Client"]
        FileHandler["File Upload Handler"]
        
        %% Internal Flows
        Proxy --> Parser
        Parser --> HTTPClient
        FileHandler --> HTTPClient
    end

    %% Processing Components
    subgraph Processing["Processing Layer"]
        direction TB
        SpecParser["Spec Parser"]
        ToolGen["Tool Generation"]
        MCPConv["MCP Protocol Converter"]
        
        SpecParser --> ToolGen
        ToolGen --> MCPConv
    end

    %% File System
    FileSystem[(Local File System)]:::storage

    %% Connections
    Claude --> Proxy
    HTTPClient --> TargetAPI
    FileSystem --> FileHandler
    Processing --> Proxy

    %% Annotations
    note["Notes:
    - OpenAPI v3.1 Only
    - Local Files Only
    - JSON/Text Optimized
    - File Access Restrictions"]:::note

    %% Styling
    classDef external fill:#90EE90,stroke:#333,stroke-width:2px
    classDef storage fill:#FFE4B5,stroke:#333,stroke-width:2px
    classDef note fill:#F0F0F0,stroke:#333,stroke-width:1px

    %% Click Events
    click Proxy "https://github.com/snaggle-ai/openapi-mcp-server/blob/main/src/mcp/proxy.ts"
    click Parser "https://github.com/snaggle-ai/openapi-mcp-server/blob/main/src/openapi/parser.ts"
    click FileHandler "https://github.com/snaggle-ai/openapi-mcp-server/blob/main/src/openapi/file-upload.ts"
    click HTTPClient "https://github.com/snaggle-ai/openapi-mcp-server/blob/main/src/client/http-client.ts"
    click SpecParser "https://github.com/snaggle-ai/openapi-mcp-server/blob/main/scripts/parse-openapi.ts"
    click Server "https://github.com/snaggle-ai/openapi-mcp-server/blob/main/scripts/start-proxy.ts"
    click Processing "https://github.com/snaggle-ai/openapi-mcp-server/blob/main/examples/petstore-server.cjs"
    click ToolGen "https://github.com/snaggle-ai/openapi-mcp-server/blob/main/scripts/build.ts"
    click MCPConv "https://github.com/snaggle-ai/openapi-mcp-server/blob/main/dist/cli.cjs"
```
