使用说明

IAC MCP服务器

一个模型上下文协议（MCP）服务器，为IAC（I Am Coming）事件管理平台提供全面的Firebase Firestore访问。此服务器允许通过适当的身份验证、速率限制和全面的工具对所有IAC Firebase集合进行编程访问。

🚀 特性

完成Firebase访问：对所有IAC收藏的读/写访问权限
78+MCP工具：适用于所有IAC操作的综合工具集
API密钥验证：使用多个API密钥支持进行安全访问
速率限制：每个API键的可配置请求限制
Docker就绪：具有多阶段构建的容器化部署
综合文档：详细的工具参考和示例
生产就绪：日志记录、监控和错误处理

📚 文档

工具参考 -所有78+MCP工具的完整文档
安装指南 -安装和配置说明
API示例 -常见使用模式和示例
Docker部署 -容器部署指南
Docker编写集成 -与现有IAC基础设施集成

🛠 安装

先决条件

Node.js 22.0.0或更高版本
Firebase管理员SDK凭据
用于身份验证的有效API密钥

地方发展

克隆存储库

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

安装依赖项
```
npm install
```

配置环境

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

所需的环境变量

# 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

启动开发服务器
```
npm run dev
```
为生产而建
```
npm run build
npm start
```

🐳 Docker部署

在本地构建和运行

# Build the Docker image
npm run docker:build

# Run with environment file
npm run docker:run

使用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

生产部署

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

🔧 用法

基本MCP请求

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

认证

在请求头中包含您的API密钥：

# 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

常见操作

列出所有可用工具

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

查询组织的事件

{
  "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
      }
    }
  }
}

创建新事件

{
  "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"
    }
  }
}

生成事件分析

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

🔐 安全

API密钥管理

API密钥在每个请求上都经过验证
支持多个API密钥（comm-aseparated）
每个键至少8个字符
钥匙应定期旋转

速率限制

读取操作：每15分钟1000个请求
写入操作：每15分钟100个请求
批量操作：每15分钟10个请求
管理操作：每15分钟50个请求

收集权限

收集	读取	写入	删除	注释
用户	✅	❌	❌	只读访问
组织	✅	✅	❌	全面管理
事件	✅	✅	❌	事件生命周期
邀请	✅	✅	✅	全面的邀请管理
联系人组	✅	✅	✅	联系人管理

📊 监控

健康检查

curl http://localhost:3001/health

答复：

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

日志记录

服务器提供具有可配置级别的结构化日志记录：

错误：应用程序错误和失败
警告：警告条件和无效请求
信息：一般应用程序流程和请求
调试：详细的调试信息

使用配置日志记录级别 LOG_LEVEL 环境变量。

速率限制标头

所有回复均包含限速信息：

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

🧪 发展

可用脚本

# 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

项目结构

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

添加新工具

定义工具界面 在……里面 handlers/tools.ts
实施工具法 通过适当的错误处理
添加工具定义 向 handlers/index.ts
更新文档 在……里面 TOOLS.md
添加验证架构 如果需要 utils/validation.ts

🔄 部署

部署脚本

部署脚本遵循IAC MVP模式，与Docker Compose集成：

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

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

此脚本：

在本地构建Docker镜像
可选地推送到容器注册表（使用 --publish 旗帜）
导航到 /home/balwant/code-mini/iamcoming/
通过以下方式重新启动服务 docker-compose up -d --force-recreate
进行全面的健康检查

有关与现有基础架构的集成，请参阅 DOCKER-COMPOSE.md.

特定于环境的部署

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

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

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

🐛 故障排除

常见问题

Firebase连接失败
- 验证 FIREBASE_PROJECT_ID 是正确的
- 检查Firebase私钥格式
- 确保服务帐户具有适当的权限
身份验证错误
- 验证API密钥的格式是否正确
- 检查API密钥长度（至少8个字符）
- 确保设置了API_KEYS环境变量
速率限制
- 检查响应中的速率限制标头
- 实现重试的指数回退
- 如果需要，考虑升级速率限制
收藏访问被拒绝
- 审查文档中的收集权限
- 验证您使用的集合名称是否正确
- 检查是否允许写入/删除操作

调试模式

启用调试日志记录以进行详细的故障排除：

LOG_LEVEL=debug npm run dev

健康检查

通过自动检查监控服务器运行状况：

# 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"}'

🤝 贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
进行更改
添加新功能的测试
确保所有测试通过(npm test)
跑linting(npm run lint)
提交更改(git commit -m 'Add amazing feature')
推送到分支(git push origin feature/amazing-feature)
打开拉取请求

代码的风格

使用TypeScript严格模式
遵循现有的代码模式
为公共方法添加JSDoc注释
包括所有操作的错误处理
使用Zod模式验证所有输入

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 支持

文档: TOOLS.md 完整的工具参考
问题: GitHub问题
讨论: GitHub讨论

🗺 路线图

[]WebSocket支持实时更新
[]用于复杂查询的GraphQL接口
[]其他分析和报告工具
[]与外部服务（SendGrid、Twilio）的集成
[]自动备份和恢复功能
[]加强监测和警报

IAC MCP服务器 -增强对IAC活动管理生态系统的程序化访问。

使用说明

IAC MCP服务器

🚀 特性

📚 文档

🛠 安装

先决条件

地方发展

🐳 Docker部署

在本地构建和运行

使用Docker Compose

生产部署

🔧 用法

基本MCP请求

认证

常见操作

列出所有可用工具

查询组织的事件

创建新事件

生成事件分析

🔐 安全

API密钥管理

速率限制

收集权限

📊 监控

健康检查

日志记录

速率限制标头

🧪 发展

可用脚本

项目结构

添加新工具

🔄 部署

部署脚本

特定于环境的部署

🐛 故障排除

常见问题

调试模式

健康检查

🤝 贡献

代码的风格

📄 许可证

🆘 支持

🗺 路线图

相关 MCP

区块链数据查询服务

日程管理服务器

Markdown文档协议服务器

事件管理 MCP 服务器

CMS API服务器

CMS API服务器