sreenubodanapati/mcp-server-with-openapi-spec
If you are the rightful owner of mcp-server-with-openapi-spec and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Model Context Protocol (MCP) server is a Python-based server designed to facilitate advanced AI model interactions using the FastMCP framework.
Product CRUD API with MCP Server
A complete Product Management API built with Node.js, Express.js, MongoDB, and a Model Context Protocol (MCP) server integration.
๐ Project Structure
โโโ mcp-server/ # Model Context Protocol server
โ โโโ main.py # MCP server implementation
โ โโโ pyproject.toml # Python project configuration
โ โโโ README.md # MCP server documentation
โ โโโ uv.lock # Python dependencies lock file
โโโ test-node-app/ # Node.js REST API
โ โโโ controllers/ # API controllers
โ โโโ models/ # MongoDB models
โ โโโ routes/ # Express routes
โ โโโ server.js # Main server file
โ โโโ package.json # Node.js dependencies
โ โโโ openapi.yaml # OpenAPI specification
โ โโโ API_DOCUMENTATION.md # API documentation
โโโ README.md # This file
๐ Features
REST API Features
- โ Create, Read, Update, Delete (CRUD) operations for products
- โ MongoDB integration with Mongoose
- โ Input validation and error handling
- โ CORS support for cross-origin requests
- โ OpenAPI 3.0 specification
- โ Interactive API documentation with Swagger UI
- โ Environment configuration with dotenv
MCP Server Features
- โ Model Context Protocol server implementation
- โ Integration with FastMCP framework
- โ Python-based server for advanced AI model interactions
๐ Prerequisites
For Node.js API
- Node.js (version 16 or higher)
- MongoDB (local installation or MongoDB Atlas)
- npm or yarn package manager
For MCP Server
- Python 3.12 or higher
- UV package manager (recommended) or pip
๐ ๏ธ Installation & Setup
1. Clone the Repository
git clone <your-repository-url>
cd OpenAPI_mcp
2. Set up the Node.js API
cd test-node-app
npm install
Create a .env
file in the test-node-app
directory:
PORT=3000
MONGODB_URI=mongodb://localhost:27017/productdb
NODE_ENV=development
3. Set up the MCP Server
cd ../mcp-server
# If using UV (recommended)
uv sync
# Or if using pip
pip install -r requirements.txt
๐โโ๏ธ Running the Application
Start the Node.js API Server
cd test-node-app
# Development mode (with auto-reload)
npm run dev
# Production mode
npm start
The API will be available at: http://localhost:3000
Start the MCP Server
cd mcp-server
python main.py
Access API Documentation
Once the Node.js server is running, visit:
- Swagger UI:
http://localhost:3000/api-docs
- OpenAPI JSON:
http://localhost:3000/api-docs/swagger.json
๐ API Endpoints
Method | Endpoint | Description |
---|---|---|
GET | /api/products | Get all products (with pagination) |
GET | /api/products/:id | Get a specific product by ID |
POST | /api/products | Create a new product |
PUT | /api/products/:id | Update a product |
DELETE | /api/products/:id | Delete a product |
Sample Product Object
{
"name": "iPhone 15 Pro",
"description": "Latest iPhone with advanced camera and A17 Pro chip",
"price": 1199.99,
"category": "Electronics",
"stock": 50,
"imageUrl": "https://example.com/iphone15pro.jpg",
"isActive": true
}
๐งช Testing
Validate OpenAPI Specification
cd test-node-app
npm run validate-api
Manual Testing
You can test the API using:
- Swagger UI:
http://localhost:3000/api-docs
- Postman: Import the OpenAPI specification
- curl commands:
# Get all products
curl -X GET http://localhost:3000/api/products
# Create a new product
curl -X POST http://localhost:3000/api/products \
-H "Content-Type: application/json" \
-d '{
"name": "Test Product",
"description": "A test product",
"price": 29.99,
"category": "Test",
"stock": 10
}'
๐ง Available Scripts
Node.js API Scripts
npm start
- Start the production servernpm run dev
- Start the development server with auto-reloadnpm run docs
- Start documentation server on port 8080npm run validate-api
- Validate OpenAPI specification files
๐ Environment Variables
Create a .env
file in the test-node-app
directory:
# Server Configuration
PORT=3000
NODE_ENV=development
# Database Configuration
MONGODB_URI=mongodb://localhost:27017/productdb
# Optional: Authentication (if implemented)
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=7d
๐ Documentation
- API Documentation: Available at
/api-docs
when server is running - OpenAPI Spec: See
test-node-app/openapi.yaml
- MCP Server: See
mcp-server/README.md
๐ค Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
๐ License
This project is licensed under the ISC License - see the LICENSE file for details.
๐ Troubleshooting
Common Issues
-
MongoDB Connection Error
- Ensure MongoDB is running locally or check your MongoDB Atlas connection string
- Verify the
MONGODB_URI
in your.env
file
-
Port Already in Use
- Change the
PORT
in your.env
file - Kill the process using the port:
npx kill-port 3000
- Change the
-
MCP Server Issues
- Ensure Python 3.12+ is installed
- Check that all Python dependencies are installed correctly
๐ Support
If you encounter any issues or have questions, please:
- Check the troubleshooting section above
- Review the API documentation at
/api-docs
- Open an issue in the repository
Made with โค๏ธ using Node.js, Express.js, MongoDB, and FastMCP