@wazobiatech/mcp-server

A comprehensive Model Context Protocol (MCP) server library for Node.js microservices with authentication, health checks, and Express/NestJS integration.

🚀 Features

• 🔧 MCP Server Implementation: Full Model Context Protocol server with tool registration and execution
• 🔐 Project Authentication: Built-in middleware for Wazobia platform project token validation
• 🏗️ Multiple Framework Support: Works seamlessly with Express.js and NestJS
• ❤️ Health Monitoring: Built-in health check tools and service monitoring
• 📝 TypeScript: Full TypeScript support with comprehensive type definitions
• 🚀 Easy Integration: Simple API for registering custom MCP tools
• 🛡️ Security First: Secure project token validation and authentication middleware
• 📊 Performance Optimized: Efficient tool execution and health monitoring

📦 Installation

npm install @wazobiatech/mcp-server

📋 Requirements

• Node.js >= 16.0.0
• TypeScript >= 4.5.0 (for TypeScript projects)
• Express.js >= 4.18.0 (optional, for Express integration)
• NestJS >= 10.0.0 (optional, for NestJS integration)

🚀 Quick Start

Basic MCP Server

import { MCPServer, BaseTool } from '@wazobiatech/mcp-server';
import { z } from 'zod';

// Create a custom tool
class HelloWorldTool extends BaseTool {
  name(): string {
    return 'hello_world';
  }

  description(): string {
    return 'Returns a hello world message';
  }

  schema() {
    return z.object({
      name: z.string().optional().default('World')
    });
  }

  async execute(args: { name?: string }) {
    return {
      content: [{
        type: 'text',
        text: `Hello, ${args.name || 'World'}!`
      }]
    };
  }
}

// Initialize and start server
const server = new MCPServer({
  serviceName: 'my-mcp-service',
  version: '1.0.0'
});

server.registerTool(new HelloWorldTool());
server.finalize();
server.start();

Express.js Integration

import express from 'express';
import { MCPServer, McpProjectAuthMiddleware } from '@wazobiatech/mcp-server';

const app = express();
const server = new MCPServer({
  serviceName: 'my-express-service',
  serviceId: 'my-service',
  mercuryBaseUrl: process.env.MERCURY_BASE_URL,
  signatureSharedSecret: process.env.SIGNATURE_SHARED_SECRET
});

// Add authentication middleware
app.use('/mcp', McpProjectAuthMiddleware());

// Register your custom tools
server.registerTool(new HelloWorldTool());
server.finalize();

// Create MCP HTTP handler
app.post('/mcp', server.createHttpHandler());

app.listen(3000, () => {
  console.log('MCP Server running on port 3000');
});

NestJS Integration

// app.module.ts
import { Module } from '@nestjs/common';
import { MCPModule } from '@wazobiatech/mcp-server';

@Module({
  imports: [
    MCPModule.forRoot({
      serviceName: 'my-nest-service',
      version: '1.0.0',
      serviceId: 'nest-service'
    })
  ],
})
export class AppModule {}

// mcp.controller.ts
import { Controller, Post, UseGuards, Req, Res } from '@nestjs/common';
import { McpProjectAuthGuard, MCPServer } from '@wazobiatech/mcp-server';

@Controller('mcp')
export class MCPController {
  constructor(private readonly mcpServer: MCPServer) {
    this.mcpServer.registerTool(new HelloWorldTool());
    this.mcpServer.finalize();
  }

  @Post()
  @UseGuards(McpProjectAuthGuard)
  async handleMCP(@Req() req: any, @Res() res: any) {
    return this.mcpServer.createHttpHandler()(req, res);
  }
}

⚙️ Configuration

Environment Variables

| Variable | Description | Required | Example | |----------|-------------|----------|---------| | MERCURY_BASE_URL | Mercury service base URL for authentication | Yes* | http://localhost:4000 | | SIGNATURE_SHARED_SECRET | HMAC shared secret for request authentication | Yes* | your-secret-key | | SERVICE_ID | Unique service identifier | Yes* | my-service | | REDIS_URL | Redis connection URL for caching | No | redis://localhost:6379 |

*Required only when using authentication features

MCPServerConfig

interface MCPServerConfig {
  serviceName: string;      // Required: Service name for MCP identification
  version?: string;         // Optional: Service version (default: "1.0.0")
  serviceId?: string;       // Optional: Service ID for authentication
  mercuryBaseUrl?: string;  // Optional: Mercury service URL
  signatureSharedSecret?: string; // Optional: Shared secret for auth
}

🛠️ Creating Custom Tools

Basic Tool Structure

import { BaseTool } from '@wazobiatech/mcp-server';
import { z } from 'zod';

class CustomTool extends BaseTool {
  name(): string {
    return 'my_custom_tool';
  }

  description(): string {
    return 'Description of what this tool does';
  }

  schema() {
    return z.object({
      param1: z.string().describe('Parameter description'),
      param2: z.number().optional().default(42)
    });
  }

  async execute(args: { param1: string; param2?: number }) {
    // Tool implementation
    try {
      const result = await someAsyncOperation(args);
      
      return {
        content: [{
          type: 'text',
          text: `Operation completed: ${result}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `Error: ${error.message}`
        }],
        isError: true
      };
    }
  }
}

Tool Response Types

interface MCPToolResponse {
  content: Array<{
    type: 'text' | 'image' | 'resource';
    text?: string;
    data?: string;
    mimeType?: string;
  }>;
  isError?: boolean;
}

💊 Health Monitoring

The library includes built-in health check tools:

Built-in Health Tools

• System Health Tool: Overall system health status
• Component Health Tool: Individual component health monitoring

Custom Health Checks

const server = new MCPServer({ serviceName: 'my-service' });

// Register custom health check
server.registerHealthCheck('database', async () => {
  const isHealthy = await checkDatabaseConnection();
  return {
    status: isHealthy ? 'healthy' : 'unhealthy',
    timestamp: new Date().toISOString(),
    details: { connection: isHealthy }
  };
});

// Access health service directly
const healthService = server.getHealthService();
healthService.addHealthCheck('redis', async () => {
  // Custom Redis health check
  return { status: 'healthy' };
});

🔐 Authentication

Project Authentication Middleware

import { McpProjectAuthMiddleware } from '@wazobiatech/mcp-server/auth';

// Express middleware
app.use('/api/mcp', McpProjectAuthMiddleware());

// NestJS Guard
@UseGuards(McpProjectAuthGuard)
@Controller('mcp')
export class MCPController {
  // Your controller methods
}

Authentication Headers

x-project-token: your-project-token-here

Project Context

After successful authentication, the project information is available:

// In Express
app.use('/mcp', McpProjectAuthMiddleware(), (req, res, next) => {
  console.log('Project:', req.project);
  // { project_uuid, enabled_services, secret_version, token_id }
  next();
});

// In NestJS
@UseGuards(McpProjectAuthGuard)
@Post('/mcp')
handleMCP(@Req() req: any) {
  console.log('Project:', req.project);
}

📊 Performance & Caching

Redis Integration

When REDIS_URL is configured, the library automatically caches:

• Project authentication tokens
• Health check results
• Tool execution metrics

Memory Management

• Efficient tool registry with Map-based storage
• Automatic cleanup of expired cache entries
• Minimal memory footprint for tool execution

🔧 Advanced Usage

Multiple Tool Registration

const tools = [
  new DataProcessingTool(),
  new NotificationTool(),
  new ReportingTool()
];

server.registerTools(tools);

Custom Server Configuration

const server = new MCPServer({
  serviceName: 'advanced-service',
  version: '2.1.0',
  serviceId: 'adv-svc',
  mercuryBaseUrl: process.env.MERCURY_BASE_URL,
  signatureSharedSecret: process.env.SIGNATURE_SECRET
});

// Access underlying MCP SDK server if needed
const mcpSdkServer = server.getServer();

HTTP Transport Configuration

// Create HTTP handler with custom options
const httpHandler = server.createHttpHandler();

app.post('/mcp', (req, res, next) => {
  // Custom middleware before MCP handling
  console.log('MCP request received');
  next();
}, httpHandler);

🐛 Error Handling

Tool Execution Errors

class ErrorProneWool extends BaseTool {
  async execute(args: any) {
    try {
      // Risky operation
      const result = await riskyOperation();
      return {
        content: [{ type: 'text', text: result }]
      };
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `Operation failed: ${error.message}`
        }],
        isError: true
      };
    }
  }
}

Server Error Handling

// Express error handling
app.use((error, req, res, next) => {
  console.error('MCP Server error:', error);
  res.status(500).json({
    error: 'Internal server error',
    message: error.message
  });
});

🧪 Testing

Unit Testing Tools

import { MCPServer, BaseTool } from '@wazobiatech/mcp-server';

describe('Custom Tool', () => {
  let server: MCPServer;
  let tool: CustomTool;

  beforeEach(() => {
    server = new MCPServer({ serviceName: 'test-service' });
    tool = new CustomTool();
    server.registerTool(tool);
    server.finalize();
  });

  it('should execute tool correctly', async () => {
    const result = await tool.execute({ param1: 'test' });
    expect(result.content[0].text).toContain('test');
    expect(result.isError).toBeFalsy();
  });
});

Integration Testing

import request from 'supertest';
import express from 'express';

describe('MCP HTTP Handler', () => {
  let app: express.Application;

  beforeEach(() => {
    app = express();
    const server = new MCPServer({ serviceName: 'test' });
    server.registerTool(new TestTool());
    server.finalize();
    
    app.post('/mcp', server.createHttpHandler());
  });

  it('should handle MCP requests', async () => {
    const response = await request(app)
      .post('/mcp')
      .send({
        jsonrpc: '2.0',
        method: 'tools/list',
        id: 1
      });

    expect(response.status).toBe(200);
    expect(response.body.result.tools).toBeDefined();
  });
});

📚 API Reference

Core Classes

MCPServer

Main server class for MCP protocol implementation.

Methods

• registerTool(tool: BaseTool): void
• registerTools(tools: BaseTool[]): void
• registerHealthCheck(name: string, checkFn: Function): void
• finalize(): void
• start(): Promise<void>
• createHttpHandler(): (req, res) => Promise<void>
• getHealthService(): HealthService
• getServer(): Server

BaseTool

Abstract base class for creating MCP tools.

Methods

• name(): string - Tool identifier
• description(): string - Tool description
• schema(): ZodTypeAny | null - Input validation schema
• execute(args: any): Promise<MCPToolResponse> - Tool implementation

Middleware & Guards

McpProjectAuthMiddleware()

Express middleware for project authentication.

McpProjectAuthGuard

NestJS guard for project authentication.

Types

interface MCPServerConfig {
  serviceName: string;
  version?: string;
  serviceId?: string;
  mercuryBaseUrl?: string;
  signatureSharedSecret?: string;
}

interface MCPToolResponse {
  content: Array<{
    type: string;
    text?: string;
    data?: string;
    mimeType?: string;
  }>;
  isError?: boolean;
}

interface Project {
  project_uuid: string;
  enabled_services: string[];
  secret_version: number;
  token_id: string;
  expires_at: number;
}

🔗 Related Packages

• @wazobiatech/auth-middleware - JWT authentication middleware
• @modelcontextprotocol/sdk - MCP SDK core

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make changes with tests
4. Run tests: npm test
5. Submit pull request

Development Setup

git clone https://github.com/wazobiatech/wazobia-platform.git
cd node_mcp_lib
npm install
npm run build
npm test

📄 License

MIT License - see LICENSE file for details.

📋 Changelog

Version 1.0.0

• ✅ Initial release
• ✅ MCP server implementation with tool registration
• ✅ Express.js and NestJS integration
• ✅ Project authentication middleware
• ✅ Built-in health monitoring tools
• ✅ TypeScript support with full type definitions
• ✅ Redis caching integration
• ✅ Comprehensive documentation and examples

🆘 Support

• Documentation: Wazobia Platform Docs
• Issues: GitHub Issues
• Email: [email protected]

Built with ❤️ by the Wazobia Technologies Team