changemaker-mcp-bridge

Changemaker MCP Bridge

Production-ready Express server with full Model Context Protocol (MCP) integration for the Changemaker platform.

Overview

This server provides a robust bridge between the Changemaker platform and various MCP servers, enabling:

• Multi-tenant Architecture: Organization-scoped access with user permissions
• MCP Integration: Support for Taskmaster-AI, Zen Suite, and Playwright MCP servers
• Enterprise Features: Rate limiting, caching, monitoring, and comprehensive error handling
• External Integrations: Supabase, Resend, Sentry, and RewardStack support

Key Features

Core Capabilities

• ✅ Production-ready Express server with TypeScript
• ✅ Full MCP client implementation with Claude Code CLI integration
• ✅ Multi-tenant context management with organization isolation
• ✅ Redis-based caching for performance optimization
• ✅ Comprehensive authentication and authorization
• ✅ Rate limiting per organization and user
• ✅ Structured logging and error tracking
• ✅ Health checks and monitoring endpoints

MCP Features

• Execute tools on multiple MCP servers
• Batch tool execution support
• Tool discovery and listing
• Server health monitoring
• Context-aware tool execution
• Result caching for improved performance

Security

• JWT-based authentication
• API key support
• Role-based access control (RBAC)
• Organization-level isolation
• Request validation and sanitization

Architecture

src/
├── api/
│   ├── server.ts           # Express server setup
│   ├── controllers/        # Request handlers
│   ├── middleware/         # Auth, validation, error handling
│   └── routes/            # API route definitions
├── integrations/
│   └── mcp/
│       ├── mcp-client.ts   # MCP client implementation
│       └── context/        # Context management
├── services/              # Business logic
├── types/                 # TypeScript definitions
├── utils/                 # Utilities (logger, errors)
└── config/               # Configuration

API Endpoints

MCP Operations

• POST /api/v1/mcp/execute - Execute a single MCP tool
• POST /api/v1/mcp/batch - Execute multiple MCP tools
• GET /api/v1/mcp/servers/:server/tools - List available tools
• GET /api/v1/mcp/servers/:server/status - Get server status
• GET /api/v1/mcp/servers/status - Get all servers status
• GET /api/v1/mcp/health - MCP integration health check

Challenge Management

• POST /api/v1/challenges - Create challenge
• GET /api/v1/challenges - List challenges
• GET /api/v1/challenges/:id - Get challenge details
• PATCH /api/v1/challenges/:id - Update challenge
• DELETE /api/v1/challenges/:id - Delete challenge
• POST /api/v1/challenges/:id/participate - Join challenge
• POST /api/v1/challenges/:id/metrics - Update metrics
• GET /api/v1/challenges/:id/stats - Get statistics

Health & Monitoring

• GET /health - Basic health check
• GET /api/v1/health/detailed - Detailed system health
• GET /api/v1/health/ready - Kubernetes readiness probe
• GET /api/v1/health/live - Kubernetes liveness probe

Getting Started

Prerequisites

• Node.js 18+
• Redis server
• PostgreSQL (for Supabase)

Installation

1. Clone the repository

2. Install dependencies:

   npm install
   

3. Copy environment variables:

   cp .env.example .env
   

4. Configure your environment variables in .env

5. Start Redis:

   redis-server
   

6. Run in development:

   npm run dev
   

Building for Production

npm run build
npm start

Configuration

The server uses environment variables for configuration. See .env.example for all available options.

Key configurations:

• Server: Port, host, environment
• Security: JWT secret, CORS origins
• Redis: Connection URL and TTL settings
• MCP Servers: API keys and configurations
• External Services: Supabase, Resend, Sentry credentials

Authentication

The server supports two authentication methods:

1. Bearer Token (JWT):

   Authorization: Bearer <jwt-token>
   

2. API Key:

   x-api-key: org_<orgId>_user_<userId>
   

Error Handling

The server implements comprehensive error handling with:

• Structured error responses
• Proper HTTP status codes
• Sentry integration for production monitoring
• Detailed logging for debugging

Error response format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "details": {}
  }
}

Development

Running Tests

npm test
npm run test:watch
npm run test:coverage

Linting

npm run lint

TypeScript Type Checking

npx tsc --noEmit

Deployment

The server is designed for containerized deployment:

1. Build the Docker image
2. Set environment variables
3. Ensure Redis is accessible
4. Deploy with health check monitoring

License

MIT