Skip to main content
Glama

MCPHy

by sehmim
GitHub
JavaScript
MIT License
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue
███╗ ███╗ ██████╗██████╗ ██╗ ██╗██╗ ██╗ ████╗ ████║██╔════╝██╔══██╗██║ ██║╚██╗ ██╔╝ ██╔████╔██║██║ ██████╔╝███████║ ╚████╔╝ ██║╚██╔╝██║██║ ██╔═══╝ ██╔══██║ ╚██╔╝ ██║ ╚═╝ ██║╚██████╗██║ ██║ ██║ ██║ ╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝ ╚═╝ ╚═╝

🚀 Turn Any API into a Conversational AI Powerhouse

Transform your REST APIs into intelligent, chat-driven MCP servers with zero code changes

npm version License: MIT Node Version TypeScript

🎯 Quick Start • 📖 Documentation • ✨ Features • 🎨 Demo

🎬 What is MCPHy?

MCPHy is a revolutionary CLI tool and Node.js library that bridges the gap between traditional REST APIs and conversational AI. Simply point it at your Swagger/OpenAPI specification, and watch your API transform into an intelligent Model Context Protocol (MCP) server with natural language understanding.

TL;DR: Feed it an API spec → Get a conversational AI interface. Ask questions in plain English → Get precise API calls.

# Three commands to conversational AI npm install -g mcphy mcphy init mcphy serve

🎯 Now ask questions like: "Get all users created after January 1st" "Create a new product with name and price" "Delete order with ID abc-123"

🌟 What Makes MCPHy Special?

🧠 AI-Powered Intelligence

Natural language → API endpoints Powered by GPT-4-mini with fallback support

💬 Beautiful Web Chat

Sleek, responsive browser interface Real-time query processing & results

⚡ Zero Configuration

Auto-detects API specs Interactive CLI prompts

🔌 Plug & Play

Works with existing APIs No code changes required

🎯 Intelligent Matching

Parameter extraction Confidence scoring & reasoning

📦 Export Ready

Standalone packages Multi-platform deployment

🎯 Quick Start

📥 Installation

# Global installation for CLI npm install -g mcphy # Or add to your project npm install mcphy

🚀 Three Steps to AI-Powered APIs

Step 1️⃣: Initialize

cd your-api-project mcphy init

MCPHy will:

  • 🔍 Auto-detect your API spec (swagger.yaml, openapi.json, etc.)

  • ✅ Validate the specification

  • 📝 Generate MCP manifest

  • ⚙️ Create .mcphy.json config

Step 2️⃣: Add OpenAI Key (Optional)

For AI-powered query matching, add your OpenAI API key:

# Create .env file echo "OPENAI_API_KEY=sk-your-key-here" > .env

No OpenAI key? No problem! MCPHy falls back to keyword-based matching.

Step 3️⃣: Launch

mcphy serve
🚀 MCPHy running at http://localhost:3000 💬 Open in your browser to chat with your backend

🎉 That's It! Your API is now conversational!

🎨 Try It Now

Open http://localhost:3000 and start chatting with your API:

You: "Get all pets created after October 14, 2025" MCPHy: ✅ Found endpoint! 📍 GET /pets 🔧 Parameters: { created_after: "2025-10-14" } 🎯 Confidence: 85%

💡 Sample Queries to Try:

Query

What It Does

"Get all users created after January 1st"

Retrieves filtered users

"Create a new pet named Fluffy"

POST request with params

"Update user with ID 123"

PUT/PATCH request

"Delete the product with code ABC"

DELETE request

🛠️ CLI Commands

🎬 mcphy init

Initialize a new MCPHy project

mcphy init [options] Options: -f, --file <path> Path to API specification file -o, --output <path> Output path for config (default: .mcphy.json)

Example:

mcphy init -f ./api/swagger.yaml

🚀 mcphy serve

Start the MCP server

mcphy serve [options] Options: -c, --config <path> Config file path (default: .mcphy.json) -p, --port <number> Server port (default: 3000)

Example:

mcphy serve -p 8080

Available Endpoints:

Endpoint

Description

http://localhost:3000/

💬

Web Chat Interface

http://localhost:3000/.well-known/mcp/manifest.json

📋 MCP Manifest

http://localhost:3000/mcp/query

🧠 Query Endpoint (GET/POST)

http://localhost:3000/api/info

ℹ️ API Information

http://localhost:3000/api/endpoints

📚 List All Endpoints

http://localhost:3000/health

❤️ Health Check

✅ mcphy validate

Validate an API specification

mcphy validate <file>

Example:

mcphy validate ./swagger.yaml

📦 mcphy export

Export as a standalone package

mcphy export [options] Options: -o, --output <dir> Output directory (default: mcphy-export) -c, --config <file> Config file (default: .mcphy.json) --include-node-modules Include node_modules for offline use

Example:

mcphy export -o my-api-package --include-node-modules

What's Included:

  • ✅ Complete MCPHy runtime

  • ✅ Your API spec & config

  • ✅ Startup scripts (.sh + .bat)

  • ✅ Custom README

  • ✅ Package.json

🔥 Advanced Usage

💻 Programmatic API

Use MCPHy as a library in your Node.js projects:

import { MCPServer, SwaggerAPIParser, ManifestGenerator } from 'mcphy'; // Parse API specification const apiSpec = await SwaggerAPIParser.parse('./swagger.yaml'); // Generate MCP manifest const manifest = await ManifestGenerator.generateFromSwagger(apiSpec); // Create and start server const server = new MCPServer({ port: 3000, manifest, openaiApiKey: process.env.OPENAI_API_KEY }); await server.start(); console.log('🚀 Server running on port 3000');

🌐 Query API via REST

Using cURL (POST):

curl -X POST http://localhost:3000/mcp/query \ -H "Content-Type: application/json" \ -d '{"query": "Get all pets created after October 14, 2025"}'

Using cURL (GET):

curl "http://localhost:3000/mcp/query?q=Get%20all%20pets"

Response:

{ "endpoint": "/pets", "method": "GET", "params": { "created_after": "2025-10-14" }, "confidence": 0.85, "reasoning": "Matched GET /pets endpoint based on temporal query" }

🧪 Test with Sample API

MCPHy includes a sample Pet Store API:

cd examples mcphy init -f sample-swagger.yaml mcphy serve

Visit http://localhost:3000 and try queries like:

  • "Show me all available pets"

  • "Create a new pet"

  • "Get pet by ID 123"

⚙️ Configuration

📄 .mcphy.json

{ "name": "My Awesome API", "description": "AI-powered API server", "version": "1.0.0", "apiSpecPath": "swagger.yaml", "manifestPath": ".mcphy-manifest.json", "port": 3000, "openaiApiKey": "sk-your-key-here" }

🔑 Environment Variables

Create a .env file:

# OpenAI API Key (optional but recommended) OPENAI_API_KEY=sk-your-openai-api-key-here # Server Port (optional) PORT=3000

Get an OpenAI key: platform.openai.com/api-keys

🏗️ Project Structure

mcphy/ ├── 📁 bin/ │ └── mcphy.js # CLI entry point ├── 📁 src/ │ ├── cli.ts # CLI commands │ ├── index.ts # Library exports │ ├── 📁 parser/ │ │ ├── swaggerParser.ts # Swagger/OpenAPI parser │ │ └── postmanParser.ts # Postman support (WIP) │ ├── 📁 server/ │ │ ├── mcpServer.ts # Express MCP server │ │ ├── manifest.ts # Manifest generator │ │ ├── queryMatcher.ts # NLP query matcher │ │ └── 📁 ui/ │ │ ├── index.html # Chat interface │ │ ├── script.js # Frontend logic │ │ └── style.css # Styles │ └── 📁 utils/ │ └── logger.ts # Console logger ├── 📁 examples/ │ └── sample-swagger.yaml # Example API ├── 📁 templates/ │ └── manifest-template.json └── .env.example

🛠️ Development

Build from Source

# Clone the repository git clone https://github.com/yourusername/mcphy.git cd mcphy # Install dependencies npm install # Build TypeScript npm run build # Link for local development npm link # Start in watch mode npm run dev

Available Scripts

Script

Description

npm run build

Compile TypeScript + copy UI files

npm run copy-ui

Copy UI assets to dist

npm run dev

Watch mode for development

npm start

Run compiled server

npm run export

Export standalone package

🧠 How Natural Language Matching Works

MCPHy uses a two-tier intelligent matching system:

🤖 Tier 1: AI-Powered (with OpenAI)

  • Uses GPT-4-mini for semantic understanding

  • Extracts intent, method, parameters from natural language

  • Returns confidence scores and reasoning

🔍 Tier 2: Keyword Fallback (no API key needed)

  • Pattern matching on endpoint paths

  • Keyword extraction from descriptions

  • Basic parameter inference

Example Flow:

User Query: "Get all users created after January 1st" ↓ Query Matcher ↓ ┌──────┴──────┐ │ AI Mode │ (if OpenAI key present) └──────┬──────┘ ↓ Semantic Analysis ↓ ✅ Matched Endpoint ↓ 📍 GET /users 🔧 { created_after: "2025-01-01" } 🎯 Confidence: 92%

📊 Supported Specifications

Format

Status

Notes

OpenAPI 3.0+

✅

Fully Supported

All features available

Swagger 2.0

✅

Fully Supported

Complete compatibility

Postman Collections

⏳

Coming Soon

In development

GraphQL Schemas

📋

Planned

On roadmap

🗺️ Roadmap

  • 🧠 Natural language query matching

  • 💬 Interactive web chat interface

  • 🔍 Auto-detect API specifications

  • 🤖 OpenAI GPT-4-mini integration

  • 📦 Standalone export functionality

  • 🔌 Full API request proxying

  • 🔐 Authentication/authorization middleware

  • 📮 Postman collection support

  • 🎨 GraphQL schema support

  • 🧩 Custom middleware plugins

  • 🐳 Docker deployment templates

  • 📊 Analytics & usage tracking

  • 🌍 Multi-language support

🤝 Contributing

We welcome contributions! Here's how you can help:

  1. 🍴 Fork the repository

  2. 🌿 Create a feature branch (git checkout -b feature/amazing-feature)

  3. 💾 Commit your changes (git commit -m 'Add amazing feature')

  4. 📤 Push to the branch (git push origin feature/amazing-feature)

  5. 🎉 Open a Pull Request

Development Guidelines

  • ✅ Write TypeScript with strict mode

  • ✅ Add tests for new features

  • ✅ Update documentation

  • ✅ Follow existing code style

📋 Requirements

Requirement

Version

Node.js

>= 18.0.0

npm

>= 9.0.0

TypeScript

>= 5.0.0

(dev only)

🎓 Use Cases

🚀 For API Developers

  • Rapid prototyping & testing

  • Interactive API documentation

  • Developer experience enhancement

🤖 For AI Integration

  • Voice assistant backends

  • Chatbot API interfaces

  • Conversational automation

📚 For Documentation

  • Living API examples

  • Interactive tutorials

  • User-friendly demos

🧪 For Testing

  • Natural language test cases

  • QA automation

  • Exploratory testing

🎁 Example Projects

Check out these examples to get started:

# Pet Store API (included) cd examples mcphy init -f sample-swagger.yaml mcphy serve # Try queries: # - "Show all pets" # - "Create a new pet named Max" # - "Get pet with ID 1"

Want to see your project here? Submit a PR!

❓ FAQ

No! MCPHy works without an OpenAI key using keyword-based fallback matching. However, for best results, we recommend using GPT-4-mini for intelligent query understanding.

MCPHy is currently in active development (v0.1.0). It's great for development, testing, and prototyping. For production use, we recommend waiting for v1.0.0 or implementing additional security measures.

Not yet! GraphQL support is on our roadmap. Currently, MCPHy supports REST APIs via Swagger/OpenAPI specifications.

Yes! The UI files are located in src/server/ui/. You can modify index.html, script.js, and style.css to customize the look and feel.

With OpenAI: ~85-95% accuracy depending on query complexity Without OpenAI: ~60-75% accuracy using keyword matching

📜 License

MIT © 2025 MCPHy

💖 Support

Love MCPHy? Here's how you can help:

  • ⭐ Star this repository

  • 🐛 Report bugs via GitHub Issues

  • 💡 Suggest features

  • 📣 Share with your network

  • 🤝 Contribute code

🚀 Ready to Make Your APIs Conversational?

npm install -g mcphy && mcphy init

Get Started • View Examples • Read Docs • Report Issues

Made with ❤️ by developers, for developers

Follow on GitHub Twitter

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Transform REST APIs into intelligent, chat-driven MCP servers with zero code changes. Simply point it at your Swagger/OpenAPI specification to get natural language querying capabilities powered by AI.

  1. 🎬 What is MCPHy?
    1. 🌟 What Makes MCPHy Special?
      1. 🧠 AI-Powered Intelligence
      2. 💬 Beautiful Web Chat
      3. ⚡ Zero Configuration
      4. 🔌 Plug & Play
      5. 🎯 Intelligent Matching
      6. 📦 Export Ready
    2. 🎯 Quick Start
      1. 📥 Installation
      2. 🚀 Three Steps to AI-Powered APIs
      3. 🎉 That's It! Your API is now conversational!
    3. 🎨 Try It Now
      1. 🛠️ CLI Commands
        1. 🎬 mcphy init
        2. 🚀 mcphy serve
        3. ✅ mcphy validate
        4. 📦 mcphy export
      2. 🔥 Advanced Usage
        1. 💻 Programmatic API
        2. 🌐 Query API via REST
        3. 🧪 Test with Sample API
      3. ⚙️ Configuration
        1. 📄 .mcphy.json
        2. 🔑 Environment Variables
      4. 🏗️ Project Structure
        1. 🛠️ Development
          1. Build from Source
          2. Available Scripts
        2. 🧠 How Natural Language Matching Works
          1. 🤖 Tier 1: AI-Powered (with OpenAI)
          2. 🔍 Tier 2: Keyword Fallback (no API key needed)
        3. 📊 Supported Specifications
          1. 🗺️ Roadmap
            1. 🤝 Contributing
              1. Development Guidelines
            2. 📋 Requirements
              1. 🎓 Use Cases
                1. 🚀 For API Developers
                2. 🤖 For AI Integration
                3. 📚 For Documentation
                4. 🧪 For Testing
              2. 🎁 Example Projects
                1. ❓ FAQ
                  1. 📜 License
                    1. 💖 Support
                      1. 🚀 Ready to Make Your APIs Conversational?

                    New MCP Servers

                    MCP directory API

                    We provide all the information about MCP servers via our MCP API.

                    curl -X GET 'https://glama.ai/api/mcp/v1/servers/sehmim/mcphy'

                    If you have feedback or need assistance with the MCP directory API, please join our Discord server