NOTE: The use of this project requires that you have a basic knowledge of using Express in building a REST API.

What is MCP?

MCP (Model Context Protocol) is an open protocol that lets AI assistants (e.g. Claude, ChatGPT, Cursor) interact with your application through a standard interface. Instead of the LLM calling your REST API with raw HTTP, it uses MCP to discover and use tools (actions like create, update, delete) and resources (read-only data like list and get-by-id). - Wikipedia

This framework ships with a built-in MCP server. When you generate a service with npm run generate -- --name users, the same data is exposed as:

• REST API — GET/POST/PUT/DELETE /users for apps and integrations
• MCP tools — e.g. create_users, update_users, list_users for LLMs
• MCP resources — e.g. users://list, users://{id} for LLM context

You get one codebase, dual access: traditional REST for clients and MCP for AI. See MCP Guide for setup (including Cursor) and details.

Why use Express REST API and MCP Server Framework?

1. Fast development — Generate full CRUD + MCP with one command (npm run generate -- --name <Name>)
2. Dual interface — Every generated service exposes both REST API and MCP (tools + resources) for LLMs
3. LLM-ready — Connect Cursor, Claude, or other MCP clients via HTTP; no extra glue code
4. TypeScript — Full type safety, strict mode, and a clear structure for controllers and models
5. API versioning — Route files like users.v1.ts map to /v1/users; latest stays at /users
6. Testing — Auto-generated tests for routes, controllers, and models; run with npm test
7. Quality — Linting, consistent error handling, and uniform JSON response shapes
8. Security — Optional encryption, rate limiting, and security headers; x-tag for POST
9. Data safety — Deleted records go to trash and can be restored
10. Audit — Request/response logging for debugging and compliance
11. Background jobs — Bull queue + clock + workers for scheduled and async tasks
12. Database choice — MongoDB (Mongoose) or SQL (Sequelize), or an external API as the data source
13. Organized layout — Clear separation of routes, controllers, models, services, and MCP

Installation

Prerequisites

• Node.js 22.x or higher (LTS recommended)
• MongoDB (for default database)
• Redis (for queue system and caching)

Setup

Clone the repository and install dependencies:

$ git clone https://github.com/iolufemi/Express-REST-API-and-MCP-Server-Framework.git ./yourProjectName 
$ cd yourProjectName
$ npm install

Key scripts

| Command | Description | |---------|-------------| | npm run generate -- --name <Name> | Generate a MongoDB CRUD endpoint (route, controller, model, MCP registration, tests). Use -n for short. | | npm run generate -- --name <Name> --sql | Generate a SQL CRUD endpoint (Sequelize model, SQL controller/routes/tests). | | npm run generate -- --name <Name> --baseurl <URL> --endpoint <path> | Generate an API-as-DB endpoint (proxy to external API). Short: -n, -b, -e. | | npm run dev | Start development server with hot reload | | npm run build | Compile TypeScript to dist/ | | npm start | Run production server | | npm test | Run unit tests (Mocha, spec reporter) | | npm run type-check | Run TypeScript type-check only | | npm run release -- --release-type patch | Bump version, changelog, tag, and GitHub release (use minor or major for --release-type as needed) |

For release to create the GitHub release, set GITHUB_TOKEN, GIT_OAUTH_TOKEN, or CONVENTIONAL_GITHUB_RELEASER_TOKEN to a Personal Access Token: classic token needs repo scope; fine-grained token needs Releases: Read and write for this repository. Example: GITHUB_TOKEN=ghp_xxx npm run release -- --release-type patch. You can also use RELEASE_TYPE=minor npm run release (no extra args).

The generate script runs npx gulp --gulpfile gulpfile.cjs service so the correct gulpfile is always used (avoids "No gulpfile found" when running gulp directly).

Generate Your First Service

Generate a complete CRUD service with both REST API and MCP server support using the generate script (runs the gulp service task with the correct config via npx):

$ npm run generate -- --name yourFirstEndpoint

Or using the short form:

$ npm run generate -- -n yourFirstEndpoint

This single command generates:

• ✅ REST API endpoints (routes, controllers, models)
• ✅ MCP server tools and resources (for LLM integration)
• ✅ Complete test suites
• ✅ TypeScript type definitions (when TypeScript migration is complete)

Why npm run generate? The project uses gulpfile.cjs. Running gulp service directly can fail with "No gulpfile found". The generate script runs npx gulp --gulpfile gulpfile.cjs service, so you don't need to install gulp globally or remember the gulpfile path.

With the generate command, you have the option of using either Mongo DB, an SQL compatible DB or using an API generated by this framework as a database model. To use an API as a database you can pass the baseurl and the endpoint option; for an SQL compatible db, pass the sql option. See examples below.

Using an API as a DB

$ npm run generate -- --name yourEndpointWithAPIAsDB --baseurl http://localhost:8080 --endpoint users

See API as DB specification for the contract your API must implement and how to test for compliance.

Important for MCP: After generating an API-based model, you need to:

1. Inspect the actual API response structure
2. Update the schemaObject in the generated model file to match the real data structure
3. Add description and mcpDescription fields for each schema field
4. This ensures the MCP server has proper context about the data structure

The generated template includes a schema definition section with examples - replace them with your actual API response fields. The schema endpoint (GET /{service}/schema) can optionally discover schema from the external API at GET {baseurl}/{endpoint}/schema; if that fails or is not available, it falls back to the _schema defined in the model file.

Using an SQL compatible database

$ npm run generate -- --name yourEndpointWITHSQL --sql

Note: You can use -n instead of --name, -b instead of --baseurl, -e instead of --endpoint.

Try out your new endpoint.

Start the app

$ npm start

by default, the app will start on POST 8080

You can change the PORT by adding a PORT environment variable. eg.

$ PORT=6000 npm start

now the app will start on PORT 6000

To start the app for development, run

$ npm run dev

This will automatically restart your app whenever a change is detected using tsx watch.

Generated Service Features

When you generate a service, you get access to:

REST API Endpoints

• [POST] http://localhost:8080/yourFirstEndpoint - Create resources (single or bulk)
• [GET] http://localhost:8080/yourFirstEndpoint - List/search resources (supports filters, pagination, sorting, projection, date range)
• [GET] http://localhost:8080/yourFirstEndpoint/:id - Get a specific resource
• [PUT] http://localhost:8080/yourFirstEndpoint - Update multiple resources (with query)
• [PATCH] http://localhost:8080/yourFirstEndpoint/:id - Update a single resource
• [DELETE] http://localhost:8080/yourFirstEndpoint?key=value - Delete multiple resources (with query)
• [DELETE] http://localhost:8080/yourFirstEndpoint/:id - Delete a single resource
• `[POST] http://localhost:8080/yourFirs