IAC MCP Server

A Model Context Protocol (MCP) server providing comprehensive Firebase Firestore access for the IAC (I Am Coming) event management platform. This server enables programmatic access to all IAC Firebase collections with proper authentication, rate limiting, and comprehensive tooling.

🚀 Features

• Complete Firebase Access: Read/write access to all IAC collections
• 78+ MCP Tools: Comprehensive toolset for all IAC operations
• API Key Authentication: Secure access with multiple API key support
• Rate Limiting: Configurable request limits per API key
• Docker Ready: Containerized deployment with multi-stage builds
• Comprehensive Documentation: Detailed tool reference and examples
• Production Ready: Logging, monitoring, and error handling

📚 Documentation

• Tools Reference - Complete documentation of all 78+ MCP tools
• Setup Guide - Installation and configuration instructions
• API Examples - Common usage patterns and examples
• Docker Deployment - Container deployment guide
• Docker Compose Integration - Integration with existing IAC infrastructure

🛠 Installation

Prerequisites

• Node.js 22.0.0 or higher
• Firebase Admin SDK credentials
• Valid API keys for authentication

Local Development

1. Clone the repository

   git clone https://github.com/iamcoming-io/mcp-server.git
   cd mcp-server

2. Install dependencies

   npm install

3. Configure environment

   cp .env.example .env
   # Edit .env with your configuration

4. Required Environment Variables

   # Server Configuration
   PORT=3001
   NODE_ENV=development
   
   # Authentication
   API_KEYS=your-api-key-1,your-api-key-2,your-api-key-3
   
   # Firebase Configuration
   FIREBASE_PROJECT_ID=your-firebase-project-id
   FIREBASE_CLIENT_EMAIL=your-service-account@project.iam.gserviceaccount.com
   FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY\n-----END PRIVATE KEY-----"
   
   # Optional Configuration
   LOG_LEVEL=info
   RATE_LIMIT_WINDOW_MS=900000
   RATE_LIMIT_MAX_REQUESTS=100

5. Start development server

   npm run dev

6. Build for production

   npm run build
   npm start

🐳 Docker Deployment

Build and Run Locally

# Build the Docker image
npm run docker:build

# Run with environment file
npm run docker:run

Using Docker Compose

# docker-compose.yml
version: '3.8'
services:
  mcp-server:
    build: .
    ports:
      - "3001:3001"
    environment:
      - PORT=3001
      - NODE_ENV=production
      - API_KEYS=${API_KEYS}
      - FIREBASE_PROJECT_ID=${FIREBASE_PROJECT_ID}
      - FIREBASE_CLIENT_EMAIL=${FIREBASE_CLIENT_EMAIL}
      - FIREBASE_PRIVATE_KEY=${FIREBASE_PRIVATE_KEY}
    restart: unless-stopped

Production Deployment

# Deploy using the deployment script
./scripts/deploy.sh

🔧 Usage

Basic MCP Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "firebase_get_document",
    "arguments": {
      "collection": "users",
      "documentId": "user123"
    }
  }
}

Authentication

Include your API key in the request headers:

# Using x-api-key header
curl -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:3001/mcp

# Using Authorization header
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:3001/mcp

Common Operations

List All Available Tools

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Query Events for an Organization

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "firebase_query_collection",
    "arguments": {
      "collection": "events",
      "options": {
        "filters": [
          {
            "field": "organizationId",
            "operator": "==",
            "value": "org123"
          }
        ],
        "orderBy": "eventDate",
        "orderDirection": "desc",
        "limit": 10
      }
    }
  }
}

Create a New Event

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "event_create",
    "arguments": {
      "eventName": "Team Meeting",
      "eventDate": "2024-12-25T00:00:00.000Z",
      "start": "14:00",
      "end": "16:00",
      "location": "Conference Room A",
      "timezone": "America/New_York",
      "rsvpDueDate": "2024-12-20T00:00:00.000Z",
      "message": "Monthly team sync and planning session",
      "host": "John Manager",
      "ownerAccountId": "user123",
      "organizationId": "org123",
      "plan": "host_plus"
    }
  }
}

Generate Event Analytics

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "analytics_event_report",
    "arguments": {
      "eventId": "event123"
    }
  }
}

🔐 Security

API Key Management

• API keys are validated on every request
• Support for multiple API keys (comma-separated)
• Minimum 8 characters per key
• Keys should be rotated regularly

Rate Limiting

• Read Operations: 1000 requests per 15 minutes
• Write Operations: 100 requests per 15 minutes
• Bulk Operations: 10 requests per 15 minutes
• Admin Operations: 50 requests per 15 minutes

Collection Permissions

Collection	Read	Write	Delete	Notes
users	✅	❌	❌	Read-only access
organizations	✅	✅	❌	Full management
events	✅	✅	❌	Event lifecycle
invites	✅	✅	✅	Full invitation management
contactGroups	✅	✅	✅	Contact management

📊 Monitoring

Health Check

curl http://localhost:3001/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T12:00:00.000Z",
  "firebase": true,
  "version": "1.0.0"
}

Logging

The server provides structured logging with configurable levels:

• Error: Application errors and failures
• Warn: Warning conditions and invalid requests
• Info: General application flow and requests
• Debug: Detailed debugging information

Configure logging level with LOG_LEVEL environment variable.

Rate Limit Headers

All responses include rate limiting information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

🧪 Development

Available Scripts

# Development
npm run dev          # Start with hot reload
npm run build        # Build TypeScript
npm run start        # Start production server

# Code Quality
npm run lint         # Run ESLint
npm run typecheck    # TypeScript type checking
npm run test         # Run tests

# Docker
npm run docker:build # Build Docker image
npm run docker:run   # Run Docker container

Project Structure

src/
├── handlers/           # MCP protocol handlers
│   ├── index.ts       # Main MCP handler
│   ├── tools.ts       # Tool implementations
│   └── resources.ts   # Resource handlers
├── middleware/        # Express middleware
│   ├── auth.ts        # API key authentication
│   └── cors.ts        # CORS configuration
├── services/          # Core services
│   ├── firebase.ts    # Firebase Admin SDK
│   └── database.ts    # Database operations
├── types/             # TypeScript definitions
│   ├── user.ts        # User types
│   ├── event.ts       # Event types
│   ├── invite.ts      # Invitation types
│   └── common.ts      # Shared types
├── utils/             # Utilities
│   ├── logger.ts      # Logging configuration
│   └── validation.ts  # Input validation
├── server.ts          # Express server setup
└── index.ts           # Application entry point

Adding New Tools

1. Define the tool interface in handlers/tools.ts
2. Implement the tool method with proper error handling
3. Add tool definition to handlers/index.ts
4. Update documentation in TOOLS.md
5. Add validation schema if needed in utils/validation.ts

🔄 Deployment

Deployment Script

The deployment script follows the IAC MVP pattern with Docker Compose integration:

# Standard deployment (build image and restart via docker-compose)
./scripts/deploy.sh

# Deploy with registry push
./scripts/deploy.sh --publish

This script:

1. Builds the Docker image locally
2. Optionally pushes to container registry (with --publish flag)
3. Navigates to /home/balwant/code-mini/iamcoming/
4. Restarts the service via docker-compose up -d --force-recreate
5. Performs comprehensive health checks

For integration with existing infrastructure, see DOCKER-COMPOSE.md.

Environment-Specific Deployment

# Development
NODE_ENV=development ./scripts/deploy.sh

# Staging  
NODE_ENV=staging ./scripts/deploy.sh

# Production
NODE_ENV=production ./scripts/deploy.sh

🐛 Troubleshooting

Common Issues

1. Firebase Connection Failed

   • Verify FIREBASE_PROJECT_ID is correct
   • Check Firebase private key formatting
   • Ensure service account has proper permissions

2. Authentication Errors

   • Verify API keys are correctly formatted
   • Check API key length (minimum 8 characters)
   • Ensure API_KEYS environment variable is set

3. Rate Limiting

   • Check rate limit headers in response
   • Implement exponential backoff for retries
   • Consider upgrading rate limits if needed

4. Collection Access Denied

   • Review collection permissions in documentation
   • Verify you're using correct collection names
   • Check if write/delete operations are allowed

Debug Mode

Enable debug logging for detailed troubleshooting:

LOG_LEVEL=debug npm run dev

Health Checks

Monitor server health with automated checks:

# Basic health check
curl -f http://localhost:3001/health || exit 1

# Detailed status with authentication
curl -H "x-api-key: YOUR_API_KEY" \
     http://localhost:3001/mcp \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (npm test)
6. Run linting (npm run lint)
7. Commit changes (git commit -m 'Add amazing feature')
8. Push to branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Code Style

• Use TypeScript strict mode
• Follow existing code patterns
• Add JSDoc comments for public methods
• Include error handling for all operations
• Validate all inputs with Zod schemas

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Documentation: TOOLS.md for complete tool reference
• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺 Roadmap

• WebSocket support for real-time updates
• GraphQL interface for complex queries
• Additional analytics and reporting tools
• Integration with external services (SendGrid, Twilio)
• Automated backup and restore functionality
• Enhanced monitoring and alerting

---

IAC MCP Server - Empowering programmatic access to the IAC event management ecosystem.