MCPHy

███╗ ███╗ ██████╗██████╗ ██╗ ██╗██╗ ██╗ ████╗ ████║██╔════╝██╔══██╗██║ ██║╚██╗ ██╔╝ ██╔████╔██║██║ ██████╔╝███████║ ╚████╔╝ ██║╚██╔╝██║██║ ██╔═══╝ ██╔══██║ ╚██╔╝ ██║ ╚═╝ ██║╚██████╗██║ ██║ ██║ ██║ ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝ ╚═╝ ╚═╝

🚀 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

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

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Made with ❤️ by developers, for developers

GitHub • Issues • NPM