adriamarti/floogic-mcp-server

Floogic MCP Server

A modular and extensible MCP (Model Context Protocol) server that provides intelligent tools for automating business and productivity tasks. Currently includes complete Google Calendar integration, with expansion plans for multiple services and APIs.

🎯 What does this server do?

This MCP server acts as a bridge between AI applications (like Cursor) and multiple business services, enabling:

• Process automation: Connect AI with business tools
• Multi-service integration: Multiple tools in a single server
• Extensibility: Modular architecture to easily add new tools
• Centralized management: Single configuration point for multiple services

🚀 Available Tools

📅 Google Calendar (Current)

• createGoogleCalendarEvent: Creates events with automatic video call
• checkGoogleCalendarEventDisponibility: Checks schedule availability
• findGoogleCalendarEventByClientEmail: Searches events by client email
• cancelGoogleCalendarEvent: Cancels existing events

🔮 Upcoming Integrations (Roadmap)

• 📧 Email Management: Automatic email sending and management
• 📊 Analytics: Google Analytics and other services integration
• 🤖 CRM: Connection with popular CRM systems
• 📋 Task Management: Task and project management
• 💬 Communication: Slack, Teams, etc. integration
• 📈 Reporting: Automatic report generation

🚀 Main Features

📅 Google Calendar Tools

• createGoogleCalendarEvent: Creates events with automatic video call
• checkGoogleCalendarEventDisponibility: Checks schedule availability
• findGoogleCalendarEventByClientEmail: Searches events by client email
• cancelGoogleCalendarEvent: Cancels existing events

🔧 Technical Features

• ✅ Complete MCP protocol implementation
• ✅ Modular architecture for multiple tools
• ✅ Support for stdio (local) and HTTP/SSE (web) transport
• ✅ Google Calendar API integration (first tool)
• ✅ Robust error handling
• ✅ Flexible and extensible configuration
• ✅ Timezone configured for Spain (Europe/Madrid)

🛠️ Installation and Configuration

Prerequisites

• Node.js 20 or higher
• Google Cloud account with Calendar API enabled
• Google Service Account with Calendar permissions

1. Local Installation

# Clone the repository
git clone <your-repository>
cd floogic-mcp-server

# Install dependencies
yarn install

# Build the project
yarn build

2. Credentials Configuration

For local use (stdio):

Configure in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "floogic-calendar": {
      "command": "node",
      "args": ["/path/to/project/build/index.js"],
      "env": {
        "GOOGLE_CALENDAR_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...",
        "GOOGLE_CALENDAR_CLIENT_EMAIL": "your-service-account@project.iam.gserviceaccount.com"
      }
    }
  }
}

For web use (HTTP/SSE):

Configure environment variables in your server:

GOOGLE_CALENDAR_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."
GOOGLE_CALENDAR_CLIENT_EMAIL="your-service-account@project.iam.gserviceaccount.com"

📖 Using the Tools

1. Create Calendar Event

// Usage example
createGoogleCalendarEvent({
  start: "2024-01-15T10:00:00Z",
  end: "2024-01-15T11:00:00Z",
  cliente: "John Doe",
  email: "john.doe@email.com",
  contexto: "Initial consultation about services",
  calendarId: "primary",
});

2. Check Availability

checkGoogleCalendarEventDisponibility({
  start: "2024-01-15T10:00:00Z",
  end: "2024-01-15T11:00:00Z",
  calendarId: "primary",
});

3. Search Events by Email

findGoogleCalendarEventByClientEmail({
  email: "john.doe@email.com",
  calendarId: "primary",
});

4. Cancel Event

cancelGoogleCalendarEvent({
  eventId: "event_id_from_google",
  calendarId: "primary",
});

🌐 Deployment on Render

The project includes configuration for automatic deployment on Render:

1. Required Environment Variables:

   • GOOGLE_CALENDAR_CLIENT_EMAIL
   • GOOGLE_CALENDAR_PRIVATE_KEY

2. Available Endpoints:

   • GET / - Server information
   • GET /health - Health check
   • GET /sse - SSE connection endpoint
   • POST /messages - MCP messages endpoint

🏗️ Project Structure

floogic-mcp-server/
├── src/
│   ├── index.ts              # MCP server stdio (local)
│   ├── server.ts             # MCP server HTTP/SSE (web)
│   ├── mcp-config.ts         # MCP tools configuration
│   ├── constants.ts          # Environment variables configuration
│   └── tools/
│       └── google-calendar.ts # Tools implementation
├── Dockerfile                # Docker configuration
├── render.yaml               # Render configuration
└── package.json

🔒 Security

• Secure credentials: Google keys are handled through environment variables
• No hardcoding: No credentials in source code
• Easy rotation: Easy credential updates without touching code
• Configuration separation: Different configurations for development and production

🚀 Use Cases

For Businesses

• Process automation: Connect multiple business services with AI
• Centralized management: Single server for multiple tools
• Scalability: Easy addition of new integrations as needed
• Scheduling automation: Automatically create appointments from web forms
• Availability verification: Check schedules before confirming appointments

For Developers

• Extensible architecture: Easy addition of new tools
• AI integration: Connect AI tools with multiple services
• Custom APIs: Create specific endpoints for different services
• Process automation: Scripts for bulk task management
• Modular development: Each tool is an independent module

🏗️ Modular Architecture

The server is designed with a modular architecture that facilitates the addition of new tools:

Tools Structure

src/tools/
├── google-calendar.ts    # Google Calendar tools
├── email-management.ts   # Future email tools
├── crm-integration.ts    # Future CRM tools
└── analytics.ts         # Future analytics tools

How to Add New Tools

1. Create new tools file in src/tools/
2. Implement functions following the existing pattern
3. Register tools in src/mcp-config.ts
4. Add environment variables if needed in src/constants.ts

Implementation Pattern

// Example of new tool
const newTool = async (args: { parameter1: string; parameter2: string }) => {
  try {
    // Tool logic
    return {
      content: [{ type: "text" as const, text: "Successful result" }],
    };
  } catch (error: any) {
    return {
      content: [{ type: "text" as const, text: `Error: ${error.message}` }],
      isError: true,
    };
  }
};

📝 Technical Notes

• Timezone: Configured for Spain (Europe/Madrid)
• Video calls: Events are automatically created with video call option
• Search: Events are searched in the last 7 days by default
• Error handling: Detailed responses in case of error
• Modular architecture: Each tool is independent and reusable

🤝 Contributing

To contribute to the project:

🆕 Adding New Tools

1. Create new module in src/tools/
2. Follow the pattern of existing implementation
3. Register the tool in src/mcp-config.ts
4. Document the new functionality
5. Add tests if necessary

🐛 Reporting Bugs or Improvements

1. Fork the repository
2. Create a branch for your feature (git checkout -b feature/new-functionality)
3. Commit your changes (git commit -am 'Add new functionality')
4. Push to the branch (git push origin feature/new-functionality)
5. Create a Pull Request

📋 Tools Roadmap

• Email Management: Automatic email sending
• CRM Integration: Connection with CRM systems
• Analytics: Google Analytics integration
• Task Management: Task and project management
• Communication: Slack, Teams integration
• Reporting: Automatic report generation

Have an idea for a new tool? Open an issue and discuss it with us!