Swagger JSON MCP Server

A powerful Model Context Protocol (MCP) server designed to efficiently query and process large Swagger/OpenAPI JSON documents. This server solves the common problem of LLMs being unable to process large API documentation files (typically 4000+ lines) by providing structured, intelligent query interfaces.

🚀 Features

Core Capabilities

• 📋 Multi-project Management: Seamlessly handle multiple Swagger/OpenAPI projects
• 🔍 Smart $ref Resolution: Automatically resolve JSON Schema references and handle circular dependencies
• 🔎 Intelligent Search: Advanced search capabilities for APIs and schemas with fuzzy matching
• ⚡ Efficient Querying: Get specific API or schema information without loading entire documents
• 🔄 Real-time Updates: Automatically detect and reload changes in Swagger files

MCP Tools

• list_swaggers: List all available Swagger projects
• get_swagger_overview: Get project overview and statistics
• get_api_info: Retrieve complete API information with resolved schemas
• get_schema: Get fully resolved schema definitions
• search_apis: Search API endpoints with advanced filtering
• search_schemas: Search schema definitions with type filtering

📁 Project Structure

swagger-json-mcp/
├── src/
│   ├── core/                    # Core functionality modules
│   │   ├── SwaggerParser.ts     # Swagger JSON parser
│   │   ├── SchemaResolver.ts    # $ref reference resolver
│   │   └── SwaggerManager.ts    # Multi-project manager
│   ├── mcp/                     # MCP server implementation
│   │   ├── tools/              # MCP tool definitions
│   │   └── types.ts            # TypeScript type definitions
│   ├── utils/                   # Utility functions
│   └── index.ts                # Main entry point
├── docs/                       # Swagger documentation directory
│   └── [project-name]/         # Individual project folders
│       └── swagger.json        # Swagger/OpenAPI JSON files
├── package.json
├── tsconfig.json
└── README.md

🛠️ Installation

Prerequisites

• Node.js >= 18.0.0
• pnpm >= 8.0.0

Setup

# Clone the repository
git clone <repository-url>
cd swagger-json-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

🚀 Quick Start

1. Prepare Your Swagger Files

Create project directories under docs/ and place your swagger.json files:

docs/
├── your-api-project/
│   └── swagger.json
└── another-project/
    └── swagger.json

2. Start the MCP Server

# Development mode
pnpm dev

# Production mode
pnpm start

3. Configure MCP Client

Add to your MCP client configuration:

{
  "mcpServers": {
    "swagger-json": {
      "command": "node",
      "args": ["path/to/swagger-json-mcp/dist/index.js"],
      "env": {}
    }
  }
}

📖 Usage Examples

List Available Projects

// MCP Tool Call
{
  "name": "list_swaggers",
  "arguments": {}
}

// Response
{
  "projects": [
    {
      "name": "your-api-project",
      "title": "Your API",
      "version": "1.0.0",
      "apiCount": 42,
      "schemaCount": 28
    }
  ]
}

Get API Information

// MCP Tool Call
{
  "name": "get_api_info",
  "arguments": {
    "swaggerName": "your-api-project",
    "path": "/api/users",
    "method": "post"
  }
}

// Response includes fully resolved schemas
{
  "path": "/api/users",
  "method": "post",
  "summary": "Create user",
  "requestBody": {
    // Fully resolved schema without $ref
  },
  "responses": {
    // Fully resolved response schemas
  }
}

Search APIs

// MCP Tool Call
{
  "name": "search_apis",
  "arguments": {
    "query": "user login",
    "swaggerName": "your-api-project",
    "method": "post"
  }
}

// Response
{
  "results": [
    {
      "path": "/auth/login",
      "method": "post",
      "summary": "User login",
      "score": 0.95
    }
  ]
}

Resolve Complex Schemas

// MCP Tool Call
{
  "name": "get_schema",
  "arguments": {
    "swaggerName": "your-api-project",
    "schemaName": "UserProfile",
    "maxDepth": 10
  }
}

// Response includes all nested schemas resolved
{
  "schema": {
    "type": "object",
    "properties": {
      // All $ref references resolved recursively
    }
  },
  "dependencies": ["Address", "ContactInfo"],
  "circularReferences": []
}

🧪 Development

Available Scripts

pnpm build      # Compile TypeScript
pnpm dev        # Development with hot reload
pnpm test       # Run test suite
pnpm lint       # Run ESLint
pnpm typecheck  # TypeScript type checking
pnpm prettier   # Format code
pnpm clean      # Clean build directory

Code Quality

• TypeScript: Strict mode enabled with comprehensive type definitions
• ESLint: Configured with TypeScript and Prettier rules
• Vitest: Fast unit testing with full coverage
• Prettier: Consistent code formatting

Testing

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Run tests with coverage
pnpm test --coverage

🏗️ Architecture

Core Components

SwaggerParser

• Validates and parses Swagger/OpenAPI JSON files
• Handles multiple OpenAPI versions (2.0, 3.0.x)
• Provides structured access to API definitions

SchemaResolver

• Recursively resolves $ref references
• Detects and handles circular dependencies
• Configurable resolution depth
• Caches resolved schemas for performance

SwaggerManager

• Manages multiple Swagger projects
• Automatic file discovery and loading
• Project lifecycle management
• Thread-safe operations

MCP Integration

• Full compliance with Model Context Protocol specification
• Structured tool definitions with comprehensive validation
• Error handling and logging
• Async/await throughout for optimal performance

🔧 Configuration

Environment Variables

# Optional: Set log level
LOG_LEVEL=info

# Optional: Custom docs directory
DOCS_DIR=./custom-docs

# Optional: Maximum schema resolution depth
MAX_SCHEMA_DEPTH=10

Customization

• Modify src/utils/logger.ts for custom logging
• Extend src/core/SwaggerManager.ts for additional project types
• Add new MCP tools in src/mcp/tools/

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes with tests
4. Run the test suite: pnpm test
5. Ensure code quality: pnpm lint && pnpm typecheck
6. Commit changes: git commit -m 'Add new feature'
7. Push to branch: git push origin feature/new-feature
8. Submit a pull request

Development Guidelines

• Follow existing code style and conventions
• Add tests for new functionality
• Update documentation for API changes
• Ensure TypeScript compliance
• Write clear, descriptive commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Troubleshooting

Common Issues

Project not loading

• Verify docs/ directory structure
• Check swagger.json file validity
• Ensure proper JSON formatting

$ref resolution failing

• Validate JSON Schema reference paths
• Check for circular references
• Verify component definitions exist

MCP connection issues

• Confirm server startup success
• Validate MCP client configuration
• Check Node.js version compatibility

Debug Mode

Enable detailed logging:

LOG_LEVEL=debug pnpm start

🌟 Acknowledgments

• Model Context Protocol - Protocol specification
• OpenAPI Specification - API documentation standard
• TypeScript - Type-safe JavaScript
• Vitest - Fast testing framework

---

Made with ❤️ for better API documentation accessibility