MCP Node.js TypeScript API

A Node.js REST API built with TypeScript, TypeORM, MongoDB, and OpenAPI following a layered architecture with feature-based organization.

🏗️ Architecture

This project follows a layered architecture organized by features:

src/
├── config/              # Configuration files
│   ├── database.ts      # Database configuration
│   └── swagger.ts       # OpenAPI/Swagger configuration
├── features/            # Feature modules
│   ├── user/
│   │   ├── entities/    # TypeORM entities
│   │   ├── dtos/        # Data Transfer Objects
│   │   ├── repositories/# Data access layer
│   │   ├── services/    # Business logic layer
│   │   ├── controllers/ # HTTP request handlers
│   │   └── routes/      # Route definitions
│   └── product/
│       ├── entities/
│       ├── dtos/
│       ├── repositories/
│       ├── services/
│       ├── controllers/
│       └── routes/
├── middleware/          # Express middlewares
├── app.ts              # Express app setup
└── index.ts            # Application entry point

✨ Features

User Feature

• Attributes: email, password (hashed), pictureUrl, name
• Endpoints:
  • POST /api/users - Create a new user
  • GET /api/users - Get all users
  • GET /api/users/:id - Get user by ID
  • PUT /api/users/:id - Update user
  • DELETE /api/users/:id - Delete user

Product Feature

• Attributes: name, description, pictureUrl, unitPrice, quantity, measureType, attributes (map)
• Endpoints:
  • POST /api/products - Create a new product
  • GET /api/products - Get all products
  • GET /api/products/:id - Get product by ID
  • PUT /api/products/:id - Update product
  • DELETE /api/products/:id - Delete product

🤖 MCP (Model Context Protocol) Integration

This project includes an MCP server that exposes all API endpoints as MCP tools, allowing AI assistants like Claude to interact with your API directly.

MCP Tools Available

User Management Tools:

• create_user - Create a new user
• get_all_users - Retrieve all users
• get_user_by_id - Get a specific user by ID
• update_user - Update an existing user
• delete_user - Delete a user

Product Management Tools:

• create_product - Create a new product
• get_all_products - Retrieve all products
• get_product_by_id - Get a specific product by ID
• update_product - Update an existing product
• delete_product - Delete a product

Running the MCP Server

1. Build the project:

   npm run build
   

2. Run the MCP server:

   npm run mcp
   

   Or for development:

   npm run mcp
   

Configuring Claude Desktop

To use this MCP server with Claude Desktop, add the configuration to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this configuration (adjust the path to match your installation):

{
  "mcpServers": {
    "mcpnodefil": {
      "command": "node",
      "args": [
        "c:/Users/USER/Desktop/aimcpproj/mcpnodefil/dist/mcp/index.js"
      ],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/mcpnodefil",
        "PORT": "3000"
      }
    }
  }
}

Important: Make sure MongoDB is running before starting the MCP server, as it connects to the database on startup.

MCP Server Features

• Direct Database Access: The MCP server connects directly to MongoDB, bypassing the REST API
• Type Safety: All tools use TypeScript for type safety
• Validation: Input validation using class-validator DTOs
• Error Handling: Comprehensive error handling with detailed error messages
• Automatic Shutdown: Graceful shutdown on SIGINT/SIGTERM signals

🚀 Getting Started

Prerequisites

• Node.js (v16 or higher)
• MongoDB (running locally or remote instance)
• npm or yarn

Installation

1. Clone the repository

   git clone <repository-url>
   cd mcpnodefil
   

2. Install dependencies

   npm install
   

3. Configure environment variables

   cp .env.example .env
   

   Edit .env file with your configuration:

   PORT=3000
   NODE_ENV=development
   MONGODB_URI=mongodb://localhost:27017/mcpnodefil
   

4. Start MongoDB Make sure MongoDB is running on your system:

   # If using local MongoDB
   mongod
   
   # Or using Docker
   docker run -d -p 27017:27017 --name mongodb mongo:latest
   

5. Run the application

   Development mode (with auto-reload):

   npm run dev
   

   Build for production:

   npm run build
   

   Run production build:

   npm start
   

📚 API Documentation

Once the server is running, you can access:

• Swagger UI: http://localhost:3000/api-docs
• Health Check: http://localhost:3000/health

🧪 Testing the API

Using cURL

Create a user:

curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123",
    "name": "John Doe",
    "pictureUrl": "https://example.com/photo.jpg"
  }'

Create a product:

curl -X POST http://localhost:3000/api/products \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Name",
    "description": "Product Description",
    "pictureUrl": "https://example.com/product.jpg",
    "unitPrice": 29.99,
    "quantity": 100,
    "measureType": "unit",
    "attributes": {
      "color": "blue",
      "size": "medium"
    }
  }'

Get all users:

curl http://localhost:3000/api/users

Get all products:

curl http://localhost:3000/api/products

🛠️ Technology Stack

• Runtime: Node.js
• Language: TypeScript
• Framework: Express.js
• Database: MongoDB
• ORM: TypeORM
• Validation: class-validator
• Documentation: Swagger/OpenAPI
• Security: bcrypt (password hashing)

📁 Project Structure Details

Layers

1. Entities Layer: TypeORM entities that map to MongoDB collections
2. DTOs Layer: Data Transfer Objects for request/response validation
3. Repository Layer: Data access and database operations
4. Service Layer: Business logic and orchestration
5. Controller Layer: HTTP request handling and response formatting
6. Routes Layer: API endpoint definitions

Key Design Patterns

• Dependency Injection: Manual DI through constructors
• Repository Pattern: Abstraction of data access logic
• Service Pattern: Business logic separation
• DTO Pattern: Request/response validation and transformation

🔒 Security Features

• Password hashing with bcrypt (10 salt rounds)
• Input validation using class-validator
• CORS enabled for cross-origin requests
• Environment variable configuration

📝 Scripts

• npm run dev - Start development server with hot reload
• npm run build - Compile TypeScript to JavaScript
• npm start - Run compiled JavaScript in production mode
• npm run mcp - Run MCP server (development mode)
• npm run mcp:build - Build and run MCP server (production mode)
• npm run typeorm - Run TypeORM CLI commands

🤝 Contributing

1. Fork the repository
2. Create your 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 MIT License - see the LICENSE file for details.