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

Build the project:
```
npm run build
```
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

Clone the repository

git clone <repository-url>
cd mcpnodefil

Install dependencies
```
npm install
```

Configure environment variables

cp .env.example .env

Edit .env file with your configuration:

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

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

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

Entities Layer: TypeORM entities that map to MongoDB collections
DTOs Layer: Data Transfer Objects for request/response validation
Repository Layer: Data access and database operations
Service Layer: Business logic and orchestration
Controller Layer: HTTP request handling and response formatting
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

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