OpenAPI Control Panel MCP Server

MCP server for OpenAPI/Swagger specification management with version control, LLM-driven editing, and a beautiful web UI.

🎨 Features

Backend (MCP Server)

• 10 MCP Tools for complete OpenAPI management
• Multi-Workspace Organization with folder-based spec management
• Version Control with diff tracking and breaking change detection
• Audit Trail with LLM reasoning capture
• Validation with Spectral and SwaggerParser
• Storage Abstraction for easy backend switching
• REST API for UI integration

Frontend (Nuxt.js UI)

• 📊 Dashboard with Apache ECharts visualizations
• 📁 Multi-Workspace Management with folder organization
• 📝 Specs List with search and filters
• 🔍 OpenAPI Viewer with endpoint rendering
• 📜 Version History with change tracking
• 📋 Audit Log with advanced filtering
• 💾 LocalStorage Persistence for workspace preferences
• 🎨 Voicenter Red Branding throughout

🚀 Quick Start

Prerequisites

• Node.js >= 20.0.0
• npm or yarn

Installation

# Install backend dependencies
npm install

# Install UI dependencies
cd ui && npm install && cd ..

Development

# Run backend only (API server on port 3001)
npm run dev

# Run UI only (dev server on port 3000)
npm run dev:ui

# Run both backend and UI concurrently
npm run dev:all

Visit:

• UI: http://localhost:3000
• API: http://localhost:3001

Production

# Build everything
npm run build:all

# Start production server
npm start

The production server serves both API and UI on the same port (default: 3001).

📁 Project Structure

openapi-control-plane-mcp/
├── src/                      # Backend source
│   ├── config/              # Configuration
│   ├── services/            # Core services
│   │   ├── folder-manager.ts    # Workspace/folder management
│   │   ├── spec-manager.ts      # Spec CRUD operations
│   │   └── version-manager.ts   # Version control
│   ├── storage/             # Storage layer
│   ├── tools/               # MCP tools (10 tools)
│   ├── types/               # TypeScript types
│   │   └── metadata.ts          # Including FolderMetadata
│   └── utils/               # Utilities
│       └── migrate-to-folders.ts # Migration utility
├── ui/                       # Frontend Nuxt.js app
│   ├── assets/              # CSS and theme
│   ├── components/          # Vue components
│   │   ├── FolderSidebar.vue    # Workspace navigation
│   │   ├── FolderCreateModal.vue # Create workspace dialog
│   │   └── SpecMoveDialog.vue   # Move spec dialog
│   ├── composables/         # Data fetching
│   │   ├── useFolders.ts        # Workspace management
│   │   └── useSpecs.ts          # Spec management
│   ├── layouts/             # Page layouts
│   ├── pages/               # 5 main pages
│   ├── public/              # Static assets
│   └── types/               # Frontend types
│       └── api.ts               # Including FolderMetadata
├── tests/                    # Backend tests (434 passing!)
└── docs/                     # Documentation

📁 Multi-Workspace Organization

Organize your API specifications into workspaces/folders for better project management:

• Default Workspaces: "Active Projects" and "Recycle Bin"
• Custom Workspaces: Create unlimited custom workspaces with titles, descriptions, colors, and icons
• Spec Migration: Move specs between workspaces with full version history preservation
• UI Integration: Sidebar navigation with visual workspace indicators
• LocalStorage Persistence: Remembers your last viewed workspace across sessions

Workspace Features

• Create/read/update/delete workspaces via MCP tools or UI
• Move specs between workspaces while preserving all version history
• Filter specs by workspace for focused development
• Visual workspace indicators with custom colors and icons
• Automatic migration of existing specs to default "active" workspace

🛠️ MCP Tools

1. spec_read - Read OpenAPI specs with custom extensions
2. spec_validate - Validate with Spectral
3. metadata_update - Update spec metadata
4. schema_manage - Manage schemas (add/update/delete)
5. endpoint_manage - Manage endpoints
6. version_control - Version management and diffing
7. parameters_configure - Configure parameters
8. responses_configure - Configure responses
9. security_configure - Configure security
10. references_manage - Manage $refs

🎨 UI Pages

1. Dashboard (/) - Stats and charts with ECharts
2. Specs List (/specs) - Browse all API specs
3. OpenAPI Viewer (/specs/:apiId) - View spec details
4. Versions (/specs/:apiId/versions) - Version history
5. Audit Log (/audit) - Full audit trail

🔧 Configuration

Environment Variables

# Backend
PORT=3001
HOST=0.0.0.0
DATA_DIR=./
LOG_LEVEL=info
NODE_ENV=development

# Custom x- attributes
X_ATTRIBUTE_ENDPOINT_LOGO=Logo URL for endpoint
X_ATTRIBUTE_ENDPOINT_DEPRECATED_REASON=Deprecation reason

Voicenter Branding

The UI uses official Voicenter brand colors:

• Primary Red: #F52222 (hsl(0, 85%, 50%))
• Light Red: #FABDBD (hsl(0, 85%, 85%))
• Dark Red: #750B0B (hsl(0, 85%, 25%))

See docs/voicenter-brand-colors.md for details.

📚 API Endpoints

UI REST API

Workspace/Folder Management

• GET /api/folders - List all folders
• POST /api/folders - Create new folder
• GET /api/folders/:folderName - Get folder metadata
• PUT /api/folders/:folderName - Update folder metadata
• DELETE /api/folders/:folderName - Delete empty folder
• GET /api/folders/:folderName/specs - List specs in folder
• POST /api/folders/:folderName/move-spec - Move spec to different folder

Spec Management

• GET /api/specs - List all specs (across all folders)
• GET /api/specs/:apiId?folder=name - Get spec details
• GET /api/specs/:apiId/versions?folder=name - List versions
• GET /api/specs/:apiId/versions/:version?folder=name - Get specific version
• PUT /api/specs/:apiId - Update spec
• DELETE /api/specs/:apiId?folder=name - Delete spec

Audit & Stats

• GET /api/audit - Get audit log
• GET /api/audit/:apiId - Get API-specific audit log
• GET /api/stats - Dashboard statistics

MCP Endpoints

• GET /health - Health check
• GET /tools - List MCP tools
• POST /tools/:toolName - Execute tool
• GET /mcp/sse - SSE connection
• POST /mcp/sse - MCP protocol messages

🧪 Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

# Integration tests only
npm run test:integration

Current Status: 434 tests passing! 🎉

🐳 Docker

# Build
npm run docker:build

# Run
npm run docker:run

# Stop
npm run docker:stop

# Logs
npm run docker:logs

📖 Documentation

• AGENTS.md - Developer guide
• Tool Documentation - Each tool documented
• Architecture - System design
• Voicenter Branding - Brand colors

🤝 Contributing

1. Read docs/AGENTS.md
2. Follow Uncle Bob's principles
3. Add JSDoc with humor
4. Write tests (maintain 80%+ coverage)
5. Use conventional commit messages

📝 License

MIT

🎯 Roadmap

• 10 MCP tools complete
• SSE/HTTP transport
• Beautiful Nuxt.js UI with Voicenter branding
• Dashboard with ECharts
• OpenAPI viewer
• Version history
• Audit log
• Multi-workspace/folder organization
• LocalStorage workspace persistence
• Authentication
• Multi-user support
• S3 storage backend
• Redis caching
• Kubernetes deployment

💡 Credits

Built with:

• Fastify - Fast backend framework
• Nuxt.js - Vue 3 framework
• Apache ECharts - Data visualization
• @nuxt/ui - TailwindCSS components
• MCP SDK - Model Context Protocol

Voicenter - VoIP/Telecom Platform Branding

---

Made with ❤️ and lots of ☕