netadx1ai/mcp_aicore_boilerplate

NetADX AI-CORE - MCP API Boilerplate

A minimal, production-ready MCP (Model Context Protocol) API server boilerplate for building scalable AI-powered backend services.

Purpose: Simple, extensible foundation for building MCP-compliant API servers with TypeScript, MongoDB, and JWT authentication.

Architecture: Clean, minimal structure - easy to understand and extend for your specific use case.

Table of Contents

• Overview
• Features
• Quick Start
• Interactive API Documentation
• Project Structure
• Configuration
• Development
• Deployment
• Creating Your First Tool
• API Documentation
• Claude Desktop Integration

Overview

NetADX AI-CORE is a simple, clean boilerplate for building MCP API servers. It provides:

• MCP Protocol Compliance - Official SDK v1.0.0
• TypeScript - Type-safe development
• MongoDB Integration - Database ready with connection pooling
• JWT Authentication - Secure API access
• Interactive API Documentation - Comprehensive Swagger/OpenAPI 3.0 docs
• Direct TypeScript Execution - No build step with tsx
• Production Ready - Logging, error handling, graceful shutdown
• Minimal and Clean - Easy to understand and extend

What's Included

Core Infrastructure:

• MCP Server setup with stdio and HTTP transports
• MongoDB connection manager
• JWT authentication manager
• Winston logging
• Environment configuration
• Example CRUD tool
• Interactive Swagger documentation at /docs

Deployment:

• Quick deployment script (deploy-quick.sh)
• PM2 ecosystem configuration
• Docker support
• Nginx reverse proxy with CORS
• Comprehensive deployment documentation

Claude Desktop Integration:

• Built-in stdio wrapper support
• Local development with development/mcp-stdio-wrapper
• Production-ready npm package @netadx1ai/mcp-stdio-wrapper
• Complete integration documentation

Features

Direct TypeScript Execution

No build step required! Uses tsx to run TypeScript directly:

# Traditional approach (NOT used here)
npm run build        # Compile TS → JS
node dist/index.js   # Run compiled code

# NetADX AI-CORE approach
npx tsx src/index.ts  # Run TypeScript directly

Benefits:

• Faster deployments - no compilation step required
• Easier debugging - errors point to actual .ts source files
• Live updates - change code, restart, ready
• Simpler CI/CD - just sync TypeScript files directly

Technology Stack

• Runtime: Node.js 18+
• Language: TypeScript 5.2+ (strict mode)
• Framework: MCP Protocol (official SDK v1.0.0)
• Database: MongoDB with connection pooling
• Transport: HTTP/HTTPS + stdio
• Authentication: JWT (HS256)
• Logging: Winston
• Execution: tsx (direct TypeScript execution)

Quick Start

Prerequisites

# Node.js 18+ required
node -v

# MongoDB (local or remote)
mongod --version

Installation

# Clone or use this boilerplate
cd development/mcp_aicore_boilerplate

# Install dependencies
npm install

# Configure environment
cp .env.example .env
nano .env  # Edit with your settings

Configuration

Edit .env file:

# Server
NODE_ENV=development
PORT=8005
USE_HTTP=true

# MongoDB
MONGODB_URI=mongodb://localhost:27017/netadx_aicore

# JWT
JWT_SECRET=your-secure-random-secret-here
JWT_EXPIRES_IN=24h

# Logging
LOG_LEVEL=info

Run

# Development mode
npm run dev

# Production mode (with tsx)
npm start

# Or directly
npx tsx src/index.ts

Test

# Health check
curl http://localhost:8005/health

# List tools (requires JWT token)
curl -H "x-access-token: YOUR_JWT_TOKEN" \
     http://localhost:8005/tools

# Call example tool
curl -X POST \
  -H "x-access-token: YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_items"}' \
  http://localhost:8005/tools/example_tool

Interactive API Documentation

Swagger/OpenAPI 3.0 Documentation

The boilerplate includes comprehensive interactive API documentation powered by Swagger UI and OpenAPI 3.0 specification.

Access Documentation:

# Start the server
npm run dev

# Open documentation in browser
open http://localhost:8005/docs

Features:

• 🚀 Interactive Testing - Test all endpoints directly from the browser
• 🔐 Built-in Authentication - JWT and API key authentication flows
• 📝 Comprehensive Examples - Real request/response examples for every endpoint
• ✅ Schema Validation - Request/response validation against OpenAPI schemas
• 📊 Error Documentation - Complete error codes and recovery suggestions
• ⚡ Performance Metrics - Response time tracking and optimization tips

Key Endpoints Documented:

• GET /health - System health check with performance metrics
• GET /info - Server information and capabilities
• GET /tools - List all available MCP tools
• POST /tools/{name} - Execute specific MCP tools with validation
• POST /rpc - JSON-RPC 2.0 endpoint for MCP communication

Authentication Methods:

• JWT Bearer Token: Authorization: Bearer <token>
• API Key: X-API-Key: <key>

Quick Test Example:

# Test health endpoint (no auth required)
curl http://localhost:8005/health

# List tools (requires auth)
curl -H "Authorization: Bearer your-jwt-token" \
     http://localhost:8005/tools

# Execute example tool
curl -X POST \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"action": "list_items"}}' \
  http://localhost:8005/tools/example-tool

For detailed documentation about the Swagger implementation, see:

Project Structure

mcp_aicore_boilerplate/
├── src/
│   ├── index.ts                 # Main entry point
│   ├── core/                    # MCP core infrastructure
│   │   ├── server.ts           # Base MCP server
│   │   └── index.ts
│   ├── tools/                   # MCP tools (your business logic)
│   │   └── example-tool.ts     # Example CRUD tool
│   ├── swagger/                 # API documentation
│   │   ├── index.ts            # Main Swagger/OpenAPI configuration
│   │   ├── tools.ts            # Tool-specific documentation
│   │   └── endpoints.ts        # Endpoint documentation
│   ├── transport/               # Transport layers
│   │   ├── http.ts             # HTTP transport with Swagger integration
│   │   ├── http-server.ts      # HTTP server wrapper
│   │   └── index.ts
│   ├── utils/                   # Utilities
│   │   ├── auth.ts             # JWT authentication
│   │   ├── config.ts           # Configuration management
│   │   ├── logger.ts           # Winston logging
│   │   ├── mongodb.ts          # MongoDB manager
│   │   └── index.ts
│   └── types/                   # TypeScript type definitions
│       └── index.ts
├── deployment/                  # Deployment configurations
│   ├── deploy.sh               # Full deployment script
│   ├── pm2/                    # PM2 configs
│   ├── docker/                 # Docker configs
│   ├── nginx/                  # Nginx reverse proxy with CORS
│   └── README.md
├── docs/                        # Documentation (cleaned)
├── .env.example                 # Environment template (simplified)
├── .env.deploy.example          # Deployment config template
├── deploy-quick.sh              # Quick TypeScript deployment
├── ecosystem.config.js          # PM2 config (uses tsx)
├── package.json                 # Dependencies
├── tsconfig.json                # TypeScript config
└── README.md                    # This file

Configuration

Environment Variables

All configuration in .env file:

# Server Configuration
NODE_ENV=development          # development | staging | production
PORT=8005                     # API server port
HOST=0.0.0.0                  # Listen address
USE_HTTP=true                 # true = HTTP, false = stdio

# MongoDB
MONGODB_URI=mongodb://localhost:27017/netadx_aicore
MONGODB_MAX_POOL_SIZE=50

# JWT Authentication
JWT_SECRET=change-this-secret
JWT_EXPIRES_IN=24h
JWT_ALGORITHM=HS256

# CORS
CORS_ORIGIN=http://localhost:3000
CORS_CREDENTIALS=true

# Logging
LOG_LEVEL=info               # error | warn | info | debug
LOG_FORMAT=json
LOG_FILE=/var/log/netadx-aicore/app.log

MongoDB Collections

The example tool uses example_items collection. Add your own collections as needed.

Development

Adding a New Tool

1. Create tool file in src/tools/:

// src/tools/my-tool.ts
import { z } from 'zod';
import type { MongoDBManager } from '../utils/mongodb';
import type { Logger } from '../utils/logger';

const MyToolInputSchema = z.object({
  action: z.enum(['do_something']),
  data: z.string(),
});

export function createMyTool(mongodb: MongoDBManager, logger: Logger) {
  return {
    name: 'my_tool',
    description: 'My custom tool',
    inputSchema: {
      type: 'object',
      properties: {
        action: { type: 'string', enum: ['do_something'] },
        data: { type: 'string' },
      },
      required: ['action'],
    },
    async execute(input: unknown) {
      const { action, data } = MyToolInputSchema.parse(input);
      
      // Your logic here
      const result = { success: true, message: 'Done!' };
      
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
      };
    },
  };
}

2. Register tool in src/index.ts:

import { createMyTool } from './tools/my-tool';

// In registerTools() method:
const myTool = createMyTool(this.mongodb, this.logger);

// Add to tools list
this.server.setRequestHandler('tools/list', async () => {
  return {
    tools: [
      { name: exampleTool.name, description: exampleTool.description, inputSchema: exampleTool.inputSchema },
      { name: myTool.name, description: myTool.description, inputSchema: myTool.inputSchema },
    ],
  };
});

// Add to tools/call handler
if (name === myTool.name) {
  return await myTool.execute(args);
}

3. Test your tool:

npx tsx src/index.ts

curl -X POST \
  -H "x-access-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"do_something","data":"test"}' \
  http://localhost:8005/tools/my_tool

Running Tests

# Add tests in tests/ directory
npm test

Code Quality

# Linting
npm run lint

# Format code
npm run format

# Type checking
npm run type-check

Deployment

Quick Deployment (Recommended)

Uses deploy-quick.sh to sync TypeScript files directly:

# Configure deployment
cp .env.deploy.example .env.deploy
nano .env.deploy  # Set your server details

# Deploy all files
./deploy-quick.sh

# Deploy specific file
./deploy-quick.sh src/tools/my-tool.ts

# Deploy without restart
./deploy-quick.sh src/ true

PM2 Deployment

# Start with PM2
pm2 start ecosystem.config.js --env production

# Monitor
pm2 status
pm2 logs netadx-aicore
pm2 monit

Docker Deployment

cd deployment/docker
docker build -t netadx-aicore .
docker run -d -p 8005:8005 --env-file .env netadx-aicore

Nginx Reverse Proxy

# Copy nginx config
sudo cp deployment/nginx/netadx-aicore-simple.conf /etc/nginx/sites-available/netadx-aicore

# Enable and reload
sudo ln -s /etc/nginx/sites-available/netadx-aicore /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

See deployment/README.md and deployment/nginx/README.md for complete guides.

Claude Desktop Integration

Using Published Package (Production)

Configure Claude Desktop to connect to your deployed API:

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "netadx-aicore": {
      "command": "npx",
      "args": ["-y", "@netadx1ai/mcp-stdio-wrapper@latest"],
      "env": {
        "API_URL": "https://your-api-domain.com",
        "JWT_TOKEN": "your-jwt-token-here",
        "LOG_FILE": "/tmp/netadx-aicore-mcp.log",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Using Local Development Wrapper

For local development and testing:

{
  "mcpServers": {
    "netadx-aicore-dev": {
      "command": "npx",
      "args": [
        "tsx",
        "/Volumes/T72/Work2025AI/mongodb/netadx-workspace/development/mcp-stdio-wrapper/src/index.ts"
      ],
      "env": {
        "API_URL": "http://localhost:8005",
        "JWT_TOKEN": "your-jwt-token-here",
        "LOG_FILE": "/tmp/netadx-aicore-dev-mcp.log",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

See for complete documentation.

API Documentation

Authentication

All API endpoints (except /health) require JWT authentication:

# Include JWT token in header
curl -H "x-access-token: YOUR_JWT_TOKEN" http://localhost:8005/tools

Endpoints

Example Tool Actions

List items:

curl -X POST \
  -H "x-access-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"list_items"}' \
  http://localhost:8005/tools/example_tool

Create item:

curl -X POST \
  -H "x-access-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"create_item","data":{"name":"Test","value":123}}' \
  http://localhost:8005/tools/example_tool

Get item:

curl -X POST \
  -H "x-access-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"get_data","id":"item_id"}' \
  http://localhost:8005/tools/example_tool

Contributing

This is a boilerplate template. Fork it and customize for your needs!

License

MIT License - NetADX AI-CORE Team

Learning Resources

• MCP Protocol Documentation
• TypeScript Handbook
• MongoDB Node.js Driver
• JWT Introduction

Support

For questions or issues:

• Check the deployment/README.md for deployment help
• Check the deployment/nginx/README.md for nginx/CORS help
• Review the example tool in src/tools/example-tool.ts
• See for MCP client setup

Document Control

• Created: 2025-10-31
• Version: 1.0.0
• Status: Boilerplate/Template
• Developed by: NetADX AI-CORE Team
• License: MIT

What is NetADX AI-CORE?

NetADX AI-CORE is a production-ready boilerplate for building MCP (Model Context Protocol) compliant API servers. It provides:

• Complete MCP implementation with official SDK v1.0.0
• Production-tested authentication and authorization
• Scalable MongoDB integration
• Comprehensive logging and error handling
• Direct TypeScript execution (no build step)
• Deployment scripts and configurations
• Clean, minimal, easy to extend
• Claude Desktop integration support

Use Cases:

• Building AI-powered backend APIs
• Creating MCP-compliant services
• Rapid API prototyping
• Learning MCP protocol implementation

Get Started:

1. Copy .env.example to .env
2. Configure MongoDB and JWT settings
3. Run npm install && npm start
4. Start building your tools in src/tools/
5. Integrate with Claude Desktop using the stdio wrapper