mcp-server-with-openapi-spec

sreenubodanapati/mcp-server-with-openapi-spec

3.1

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

MethodEndpointDescription
GET/api/productsGet all products (with pagination)
GET/api/products/:idGet a specific product by ID
POST/api/productsCreate a new product
PUT/api/products/:idUpdate a product
DELETE/api/products/:idDelete 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 server
  • npm run dev - Start the development server with auto-reload
  • npm run docs - Start documentation server on port 8080
  • npm 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

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

๐Ÿ“ License

This project is licensed under the ISC License - see the LICENSE file for details.

๐Ÿ› Troubleshooting

Common Issues

  1. MongoDB Connection Error

    • Ensure MongoDB is running locally or check your MongoDB Atlas connection string
    • Verify the MONGODB_URI in your .env file
  2. Port Already in Use

    • Change the PORT in your .env file
    • Kill the process using the port: npx kill-port 3000
  3. 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:

  1. Check the troubleshooting section above
  2. Review the API documentation at /api-docs
  3. Open an issue in the repository

Made with โค๏ธ using Node.js, Express.js, MongoDB, and FastMCP