███╗ ███╗ ██████╗██████╗ ██╗ ██╗██╗ ██╗
████╗ ████║██╔════╝██╔══██╗██║ ██║╚██╗ ██╔╝
██╔████╔██║██║ ██████╔╝███████║ ╚████╔╝
██║╚██╔╝██║██║ ██╔═══╝ ██╔══██║ ╚██╔╝
██║ ╚═╝ ██║╚██████╗██║ ██║ ██║ ██║
╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝ ╚═╝ ╚═╝
🚀 Turn Any API into a Conversational AI Powerhouse
Transform your REST APIs into intelligent, chat-driven MCP servers with zero code changes
🚀 Ready to try? npm install -g mcphy • 🎯 Quick Start • 📖 API Docs • 🎨 Examples • ⭐ Star
Requirements
- Node.js >= 18.0.0
- npm >= 9.0.0
- An API specification file (Swagger/OpenAPI or Postman Collection)
- OpenAI API Key (optional, for enhanced AI-powered understanding)
Installation
# Option 1: Install globally
npm install -g mcphy
# Option 2: Try without installing
npx mcphy --help
Quick Start
# 1. Initialize with your API spec
mcphy init
# 2. Start the conversational server
mcphy serve
# 3. Open your browser
open http://localhost:3000
That's it! Start chatting with your API in plain English.
🚨 Initialization Issues?
If mcphy init fails, here are quick fixes:
❌ No API spec found?
# Specify your API spec file explicitly
mcphy init -f path/to/your/swagger.yaml
❌ Invalid specification?
# Validate your spec first
mcphy validate path/to/your/api.yaml
❌ File not found?
# Check the file exists and use absolute path
mcphy init -f /full/path/to/api.yaml
📖 See Full Troubleshooting Guide for detailed solutions
Try It Now
Want to test MCPhy immediately? Use our included example:
# Clone and test with example API
git clone https://github.com/sehmim/mcphy.git
cd mcphy
npm install
npm run build
npm link
# Test with example
cd examples
mcphy init -f sample-swagger.yaml
mcphy serve
Then open http://localhost:3000 and try:
- "Show me all pets"
- "Create a new pet named Max"
- "Get pet with ID 1"
What It Does
- 🧠 Natural Language Processing - Ask questions in plain English
- 🔌 Real API Calls - Actually makes requests to your backend
- ⚠️ Smart Guidance - Helps when information is missing
- 💬 Web Interface - Beautiful chat UI with real-time responses
- 📦 Export Ready - Create standalone packages
- 🤖 Smart Enhancement - Optional AI-powered API understanding 🆕
- LLM-Powered - GPT-4 enhances descriptions, parameters, and examples
- Pattern-Based Fallback - Smart enhancements even without AI
- OpenAPI/Swagger & Postman - Works with all major API formats
Example
You: "create booking for John Doe for oil change for 2025-01-15"
MCPhy: ✅ Matched POST /bookings
📤 Making API call...
📋 Response: {"id": "booking-123", "status": "created"}
Why Developers Love This
- Zero Code Changes - Works with existing APIs
- Natural Language - No need to remember endpoint names
- Real Responses - Actually calls your backend
- Smart Guidance - Helps when information is missing
- Beautiful UI - Professional chat interface
- Easy Export - Create standalone packages
Commands
| Command | Description |
|---|---|
mcphy init | Initialize project with API spec |
mcphy serve | Start the MCP server |
mcphy validate <file> | Validate API specification |
mcphy export | Create standalone package |
Supported Formats
- ✅ OpenAPI 3.0+
- ✅ Swagger 2.0
- ✅ Postman Collections (with LLM-powered parsing) 🆕
🚀 New: LLM-Powered API Parsing
MCPhy now uses GPT-4 to intelligently understand and enhance all API specifications!
OpenAPI/Swagger Enhancement
- 📝 Enhanced Descriptions - Generates user-friendly API descriptions
- 🔍 Better Parameter Docs - Adds context and examples to parameters
- 💡 Usage Examples - Provides practical endpoint usage guidance
- 🎯 Smart Summaries - Creates clear, concise operation summaries
- 🔗 Workflow Discovery - Identifies common API patterns
Postman Collection Support
- 🤖 Deep Understanding - Analyzes collection structure and intent
- 📦 Automatic Conversion - Transforms to OpenAPI-compatible format
- 🔍 Smart Detection - Auto-detects collections in your project
- 📝 Rich Parsing - Extracts parameters, headers, body schemas
- 🌐 Base URL Extraction - Finds API base URL from variables
Usage:
# Works with any format - OpenAPI, Swagger, or Postman
mcphy init -f api-spec.yaml
mcphy init -f swagger.json
mcphy init -f postman_collection.json
# Validate any format
mcphy validate your-api-file
💡 OpenAI API Key Benefits (Optional):
- 🤖 Enhanced Understanding - Powers intelligent API analysis
- 📝 Rich Descriptions - Generates comprehensive documentation
- 🔍 Smart Parameter Docs - Adds context-aware explanations
- 💡 Usage Examples - Provides practical guidance for endpoints
- 🚀 Works Without It - Basic parsing is fully functional
Documentation
- 📖 API Reference - Programmatic usage
- 🎨 Examples - Real-world examples
Development
git clone https://github.com/sehmim/mcphy.git
cd mcphy
npm install
npm run build
npm link
License
MIT © 2025 MCPhy
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request