mimic-mcp

Transform Swagger/OpenAPI specs into AI-executable MCP tools with stateful mocking

mimic-mcp (Code Name: The Bridge) is an intelligent AI Middleware that eliminates the dependency bottleneck between Frontend and Backend development. Transform static Swagger/OpenAPI documentation into dynamic, executable tools for AI Coding Assistants (Cursor/Claude), enabling Frontend teams to complete UI and logic implementation before the Backend API exists.

✨ Features

🚀 Zero-Install CLI

• Execute directly via npx - no global installation required
• Auto-detect and load Swagger from local files or URLs
• Instant startup (< 1 second)
• Cross-platform: macOS, Linux, Windows

🎭 Holographic Mode (Stateful Mocking)

• Generate realistic mock data from OpenAPI schemas
• Full CRUD support - POST → GET roundtrip works!
• In-memory state persistence during session
• Smart faker integration for realistic data (emails, names, addresses, etc.)

🛡️ Smart Security

• Traffic Light Protocol - Confirm dangerous operations (DELETE, bulk updates)
• Auto-redact secrets - Tokens never appear in logs
• Context Injection - Auto-inject auth tokens from .env
• Safe for AI agents - prevents accidental destructive actions

🔄 Self-Healing

• Hot Reload - Detects Swagger changes and updates tools automatically
• Actionable Error Hints - AI-friendly error messages with suggestions
• Intelligent Routing - Auto-fallback to mock when backend unavailable

🔌 MCP Integration

• Native Model Context Protocol support
• Works with Cursor, Claude Desktop, and all MCP-compatible clients
• Automatic tool generation from OpenAPI endpoints
• Both stdio and HTTP transport modes

🎯 The "Aha!" Moment

The defining moment is when you perform a data mutation and immediately see it persist:

// 1. Create a user via AI
POST /users { "name": "Alice", "email": "[email protected]" }
// ✅ Response: { "id": "abc123", "name": "Alice", "email": "[email protected]" }

// 2. Immediately query it back
GET /users
// ✅ Response: [{ "id": "abc123", "name": "Alice", ... }]  ← IT'S THERE!

No backend required. This is the "Phantom Roundtrip" - your AI can test complete CRUD flows without waiting for anyone.

📦 Installation

Zero-Install (Recommended)

npx mimic-mcp --spec ./api/swagger.json

Global Install

npm install -g mimic-mcp
mimic-mcp --spec ./api/swagger.json

As a Dependency

npm install mimic-mcp

🚀 Quick Start

1. Basic Usage

# Local Swagger file
npx mimic-mcp --spec ./openapi.yaml

# Remote Swagger URL
npx mimic-mcp --spec https://petstore3.swagger.io/api/v3/openapi.json

# With authentication
npx mimic-mcp --spec ./api.yaml --token "Bearer sk-your-token"

2. IDE Integration (Cursor/VS Code/Windsurf)

Add to your IDE's mcpServers config:

{
  "mcpServers": {
    "mimic-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mimic-mcp@latest", "--spec", "./api/swagger.json"]
    }
  }
}

The tool will display the exact config when it starts. Just copy-paste! 📋

💡 New: No Swagger spec yet? Just add the config without --spec. The AI will ask you for the Swagger path when needed and save it automatically!

{
  "mcpServers": {
    "mimic-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mimic-mcp@latest"]
    }
  }
}

Then in your AI chat:

You: "I want to work with my API"
AI: "I need your Swagger spec. Please provide the path or URL."
You: "./api/openapi.yaml"
AI: *Uses set_swagger_spec tool*
AI: "✅ Configured! Your API has 24 endpoints. What would you like to do?"

3. With Environment Variables

Create a .env file:

# Authentication
AUTH_TOKEN=Bearer sk-your-api-token
API_KEY=your-api-key-here

# Proxy to real backend (optional)
REAL_API_URL=https://api.example.com
PROXY_TIMEOUT=5000

# Security
SWAGGER_MCP_AUTO_APPROVE=false

Then run:

npx mimic-mcp --spec ./api.yaml

🎮 Usage Examples

Example 1: Pure Mock Mode (No Backend)

# Start the server
npx mimic-mcp --spec ./swagger.json

# Now in your AI chat (Cursor/Claude):
# "Create a new user named Bob with email [email protected]"
# → AI calls post_users tool
# → Mock data persists in memory

# "Show me all users"
# → AI calls get_users tool
# → Bob appears in the list! ✨

Example 2: Proxy Mode (Fallback to Mock)

# Start with real backend URL
npx mimic-mcp --spec ./swagger.json \
  --proxy-url https://api.staging.company.com \
  --token "Bearer $AUTH_TOKEN"

# Behavior:
# - If backend responds → use real data
# - If backend returns 404/503 → fallback to mock
# - If backend unreachable → fallback to mock

Example 3: HTTP Mode (Non-MCP Clients)

# Start HTTP server on port 3000
npx mimic-mcp --spec ./api.yaml --mode http --port 3000

# Access via HTTP:
curl http://localhost:3000/api/users

Example 4: Watch Mode (Hot Reload)

# Auto-reload when Swagger file changes
npx mimic-mcp --spec ./swagger.json --watch

# Edit your swagger.json file → tools update automatically!

🛠️ CLI Options

Usage: mimic-mcp [options]

Options:
  -V, --version              output the version number
  -s, --spec <path|url>      Path or URL to OpenAPI/Swagger specification (required)
  -t, --token <token>        Bearer token for API authentication
  -k, --api-key <key>        API key for authentication
  -e, --env-file <path>      Path to .env file (default: ".env")
  -m, --mode <stdio|http>    Transport mode: stdio or http (default: "stdio")
  -p, --port <number>        HTTP server port (default: 3000)
  -w, --watch                Watch Swagger file for changes and hot reload
  --proxy-url <url>          Real backend URL for proxy mode
  --proxy-timeout <ms>       Proxy request timeout in milliseconds (default: 5000)
  --allow-destructive        Allow DELETE operations without confirmation
  --debug                    Enable verbose debug logging
  -h, --help                 display help for command

Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | AUTH_TOKEN | Bearer token for authentication | Bearer sk-1234... | | API_KEY | API key for X-API-Key header | abc123secret | | REAL_API_URL | Real backend URL for proxy mode | https://api.example.com | | PROXY_TIMEOUT | Proxy timeout in ms | 5000 | | SWAGGER_MCP_AUTO_APPROVE | Skip confirmation prompts | true or false | | SWAGGER_MCP_DEBUG | Enable debug logging | true |

🎨 Features in Detail

Traffic Light Protocol 🚦

Safety mechanism to prevent accidental data destruction:

• 🟢 GREEN (Safe): GET, POST → Execute immediately
• 🟡 YELLOW (Caution): PUT, PATCH → Optional confirmation
• 🔴 RED (Danger): DELETE, bulk operations → Requires confirmation

# Example: DELETE operation
AI: "Delete all users"
System: ⚠️ DANGER - Delete ALL users? This cannot be undone. (y/N):
User: y
System: ✅ Deleted 42 users

Skip confirmations (for CI/testing):

npx mimic-mcp --spec ./api.yaml --allow-destructive
# or
export SWAGGER_MCP_AUTO_APPROVE=true

Secret Redaction 🔒

All sensitive data is automatically redacted from logs:

# Input:  Authorization: Bearer sk-1234567890abcdef
# Output: Authorization: Bearer [REDACTED]

# Input:  { "token": "abc123secret", "user": "bob" }
# Output: { "token": "[REDACTED]", "user": "bob" }

Patterns redacted: sk-*, Bearer *, *_token, *_key, *_secret, password

Error Hinting 🎯

AI-friendly error messages with actionable suggestions:

# Bad field name
❌ Field 'userId' not found. Did you mean 'user_id'?

# Missing required field
❌ Missing required field: 'email'. Add it to your request body.

# Wrong data type
❌ Field 'age' must be number, got string. Try: { "age": 25 }

# Unknown endpoint
❌ Tool 'get_product' not found. Available: get_products, get_users...

Realistic Mock Data 🎭

Smart field name detection for realistic data:

| Field Name | Example Generated Value | |------------|------------------------| | email, *_email | [email protected] | | firstName, first_name | John | | phone, phoneNumber | +1-555-123-4567 | | address, street | 123 Main Street | | city | San Francisco | | country | United States | | zipCode, zip_code | 94102 | | createdAt, *_at | 2026-01-08T10:30:00Z | | *_id, id | abc123-def456-... (UUID) |

🔧 Development

Prerequisites

• Node.js 18+ (LTS recommended)
• npm or pnpm

Setup

# Clone repository
git clone https://github.com/yourusername/mimic-mcp.git
cd mimic-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev -- --spec ./tests/fixtures/petstore.json

# Run tests
npm test

# Build
npm run build

# Lint
npm run lint

Project Structure

mimic-mcp/
├── bin/cli.js              # CLI entry point
├── src/
│   ├── cli.ts              # Commander argument parsing
│   ├── index.ts            # Main entry
│   ├── mcp/                # MCP Server implementation
│   │   ├── server.ts       # MCP Server setup
│   │   ├── adapter.ts      # Hono-MCP bridge
│   │   ├── tool-handler.ts # Tool execution logic
│   │   └── errors.ts       # McpError with hints
│   ├── lib/
│   │   ├── swagger/        # Swagger parsing & watching
│   │   ├── hologram/       # Mock data generation
│   │   ├── store/          # In-memory state (Lowdb)
│   │   ├── proxy/          # Proxy mode routing
│   │   └── security/       # Auth, TLP, redaction
│   └── utils/
│       ├── logger.ts       # Stderr-safe logging
│       └── redactor.ts     # Secret redaction
├── tests/                  # Test suites
└── package.json

🧪 Testing

# Run all tests
npm test

# Run tests in CI mode
npm run test:run

# Run specific test file
npm test -- adapter.test.ts

# Watch mode
npm test -- --watch

Test Coverage: 450 tests passing ✅

📖 Use Cases

1. Frontend Development Without Backend

# Backend team provides Swagger spec but API isn't ready
npx mimic-mcp --spec https://api-docs.company.com/swagger.json

# You can now:
# - Build entire UI
# - Test all user flows
# - Demo to stakeholders
# - Complete sprint without waiting

2. API Contract Testing

# Verify frontend code matches API contract
npx mimic-mcp --spec ./openapi.yaml

# AI generates integration code that's guaranteed to match schema
# Zero rework when backend deploys

3. Onboarding New Developers

# Junior dev day 1:
npx mimic-mcp --spec ./company-api.yaml

# They get:
# - Working mock API
# - AI that knows all endpoints
# - Safe playground (can't break production)
# - Instant productivity

4. Integration Testing

# Test with mock data first
npx mimic-mcp --spec ./api.yaml

# Then verify with real backend
npx mimic-mcp --spec ./api.yaml \
  --proxy-url https://api.staging.company.com

🗺️ Roadmap

✅ MVP (Current - v0.1.0)

• [x] Zero-install CLI (npx execution)
• [x] Holographic Mode with stateful CRUD
• [x] Traffic Light Protocol
• [x] Secret redaction
• [x] Error hinting
• [x] Hot reload (watch mode)
• [x] MCP stdio transport
• [x] HTTP transport mode

🚧 Post-MVP (v0.2.0)

• [ ] Persistent mock database (SQLite)
• [ ] Self-healing Level 2 (auto-retry with schema adaptation)
• [ ] OAuth2 flow support
• [ ] Multiple spec file support
• [ ] VS Code extension

🔮 Vision (v1.0.0+)

• [ ] GraphQL support
• [ ] gRPC support
• [ ] Team config sync (cloud collaboration)
• [ ] CI/CD integration (contract testing)
• [ ] Advanced analytics

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

Coding Standards

• TypeScript strict mode
• All output to stderr (stdout reserved for MCP JSON-RPC)
• MCP tool names: snake_case
• Comprehensive tests for new features
• Error messages must include hints

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

• Built with MCP SDK
• Powered by Hono framework
• Mock data by Faker.js
• OpenAPI parsing via swagger-parser

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

🌟 Star History

If this project helps you, please ⭐ star it on GitHub!

Made with ❤️ for developers who refuse to wait

"Backend isn't written yet, but this runs like real life!" - A satisfied Frontend Developer