Python Bridge for Calendar Service Orchestration (MCP)

This repository furnishes a Python-based Model Context Protocol (MCP) intermediary component, designed to translate abstract natural language commands into concrete interactions with the official Google Calendar Application Programming Interface. It enables AI agents to manipulate scheduling objects securely.

Capabilities Overview

• Authorization Mechanism: Utilizes OAuth 2.0 flow (Desktop App variant) for credential acquisition, ensuring persistent, automatically refreshing access tokens.
• Fundamental Calendar Operations:
  • Inventory existing calendars (mcp_google_calendar_list_calendars).
  • Provision new calendar containers (mcp_google_calendar_create_calendar).
  • Retrieve scheduled entries using precise criteria (mcp_google_calendar_find_events).
  • Generate detailed appointments (mcp_google_calendar_create_event).
  • Instant event creation from concise text (mcp_google_calendar_quick_add_event).
  • Modify existing event parameters (mcp_google_calendar_update_event).
  • Retire scheduled items (mcp_google_calendar_delete_event).
  • Append participants to functions (mcp_google_calendar_add_attendee).
• Advanced Temporal Management & Insight:
  • Determine RSVPs for invitees (mcp_google_calendar_check_attendee_status).
  • Assess concurrent availability across multiple schedules (mcp_google_calendar_query_free_busy).
  • Algorithmically determine and book optimal slots for group meetings (mcp_google_calendar_schedule_mutual).
  • Perform quantitative analysis on daily load distribution and duration (mcp_google_calendar_analyze_busyness).
  • (Future expansion targets recurring event projection logic, pending Task 3.5 completion.)
• Service Layer: Built upon a FastAPI backend, presenting capabilities through a standardized RESTful interface.
• MCP Compliance: Exposes functionality through standard input/output pipes adhering to the MCP specification, leveraging the mcp_sdk library.

Deployment Prerequisites

1. System Requirements:

   • Python interpreter (Version 3.8 or newer).
   • Git version control system.
   • Active Google Cloud Platform project access.

2. Source Acquisition: bash git clone <repository-url> cd <repository-directory>

3. **Google Cloud Authorization Configuration (OAuth Credentials):

   • Access the Google Cloud Console.
   • Establish or choose a GCP project.
   • Activate the Google Calendar API service for the project.
   • Navigate to 'APIs & Services' -> 'Credentials'.
   • Initiate credential creation: Click "+ CREATE CREDENTIALS" -> "OAuth client ID".
   • Select Application Type: Desktop app. Assign a recognizable label (e.g., "Calendar MCP Local Client").
   • Upon creation, securely record the resulting Client ID and Client Secret; these are vital for the configuration file.
   • Configure the OAuth consent screen:
     • User Type: "External".
     • Populate required application metadata (Name, Support Email, Developer Contact).
     • Define Scopes: Select "Add or Remove Scopes," locate calendar, and mandate the .../auth/calendar scope (full read/write access). Save changes.
     • Designate Test Users: Input the Google Account email addresses authorized for initial testing.
     • Finalize the consent screen setup.
   • Return to 'Credentials', select the Desktop App credential previously made.
   • Under 'Authorized redirect URIs', append http://localhost:8080/oauth2callback and save. (This port can be adjusted via the .env setting OAUTH_CALLBACK_PORT).

4. Environment Variable Setup (.env File):

   • Duplicate the env.example file in the root directory and rename it to .env.

   • Insert the retrieved Client ID and Client Secret into the .env file: ```dotenv # OAuth 2.0 Client Credentials (GCP Console - Desktop App) GOOGLE_CLIENT_ID='YOUR_CLIENT_ID' GOOGLE_CLIENT_SECRET='YOUR_CLIENT_SECRET'

     Token persistence location (auto-created by default: .gcp-saved-tokens.json)

     TOKEN_FILE_PATH='.gcp-saved-tokens.json'

     Local host port for credential exchange (must align with Google Cloud URI)

     OAUTH_CALLBACK_PORT=8080

     API Access Privileges (Read/Write default)

     CALENDAR_SCOPES='https://www.googleapis.com/auth/calendar' `` * Verify thatTOKEN_FILE_PATH` permits file write operations (the default location is typically sufficient and automatically excluded from version control).

5. Dependency Installation:

   • From the project root in the terminal: bash pip install -r requirements.txt
   • (Virtual environment usage is strongly suggested but not mandatory).

Initial Server Execution (Mandatory for Token Generation)

The server must be executed manually one time to initiate the OAuth handshake. Subsequent runs are managed by the calling MCP client.

1. First Authorization Run:

   • Execute the main launch script: bash python run_server.py
   • The script will check for existing authentication tokens. Upon failure to find them, it performs the following:
     • Outputs an authorization URL to the console.
     • Automatically launches the default web browser to this URL.
     • The user logs into their Google account and grants the application calendar permissions.
     • Google redirects the browser to the specified local endpoint (http://localhost:8080/oauth2callback).
     • The script captures the authorization response code and persists the resulting access tokens into the file designated in .env (.gcp-saved-tokens.json).
   • Following successful token saving, the script usually initializes the HTTP serving process (e.g., on http://localhost:8000). Execution can be halted (Ctrl+C) once token saving is confirmed or the HTTP service is reported as running.

2. Optional: Direct API Testing:

   • For validation via direct HTTP clients (e.g., curl, Postman), executing python run_server.py again will load the stored tokens and start the standard FastAPI listener.

Crucial Note: Post-initialization, manual execution of python run_server.py is unnecessary for routine MCP tool invocation; the client handles the process launch.

MCP Client Integration Configuration (Example for Agent Frameworks)

To utilize this component as an integrated capability within an MCP client, the client's configuration file must specify how to invoke the run_server.py script.

Illustrative mcp_config.json Structure:

{
  "tools": {
    "calendar_management": {
      "command": "python",
      "args": [
        "C:/absolute/path/to/calendar-mcp/run_server.py"
      ]
    }
  }
}

Configuration Directives:

• calendar_management: The arbitrary, unique identifier assigned to this tool instance by the orchestrator.
• command: Set to python if the interpreter is globally accessible in the system PATH. Otherwise, specify the full path to the Python executable (e.g., /usr/local/bin/python or C:\venv\Scripts\python.exe).
• args: Must contain the absolute filesystem path to the run_server.py file. Substitute the placeholder path with the actual location on your machine.
• (Optional) api: Some frameworks might require an explicit reference to the local HTTP endpoint (e.g., "api": "http://localhost:8000") for capability discovery, even when communication primarily occurs over stdio.
• (Optional) timeout: Define a maximum execution duration in milliseconds (e.g., "timeout": 60000).

Operational Flow: When the MCP client invokes this tool definition, it executes the defined command with the provided args. The run_server.py script intelligently detects invocation via piped I/O streams and switches execution mode to the MCP communication kernel, bypassing the standard HTTP server startup.

Security Consideration: The sensitive Google Client ID and Secret remain exclusively within the project's local .env file and are never exposed in the MCP client configuration.

Internal Architecture

• run_server.py: Main bootstrapping module; manages server launch and MCP channel detection.
• src/server.py: Defines the FastAPI application routing and structure.
• src/calendar_actions.py: Contains the encapsulated logic interfacing directly with the Google Calendar API.
• src/analysis.py: Houses advanced computational functions for schedule interpretation.
• src/auth.py: Manages the OAuth 2.0 lifecycle, including token validation and renewal.
• src/models.py: Utilizes Pydantic for strict definition of incoming and outgoing data schemas.
• src/mcp_bridge.py: Implements the MCP tool definitions using mcp_sdk, serving as the delegation layer to the FastAPI routines.
• Logging: Diagnostic output is written to calendar_mcp.log located in the repository root.

Future Development Roadmap

• Integrate MCP Resource and Prompt handling mechanisms (Tracking items 6.1, 6.2).
• Refine validation fidelity for MCP tool arguments and standardize output formatting (Tracking items 6.3, 6.4).
• Implement robust exception handling protocols for tool execution failures (Tracking item 6.5).
• Streamline and finalize the development environment setup (Tracking item 7).

Licensing Policy

This codebase is offered under a dual-licensing framework, accommodating both open-source collaboration and proprietary commercial deployment requirements:

1. GNU Affero General Public License v3.0 (AGPL-3.0):

   • This software is freely available for utilization, modification, and dissemination under the AGPLv3 terms.
   • A critical stipulation is that any derivative works, including those accessed or used over a network interface, must inherit the AGPLv3 license, and their complete source code must be publicly accessible.
   • This license suits projects prioritizing maximal source code transparency and adherence to copyleft principles.
   • Refer to the comprehensive terms in the dedicated [LICENSE] file.

2. Proprietary Commercial License:

   • For use cases where the constraints of the AGPLv3—specifically the requirement to release source code for network-accessed derivative works—are incompatible with proprietary business models (e.g., integrating this utility into closed-source commercial platforms), a distinct commercial agreement must be secured.
   • Inquiries regarding commercial licensing terms should be directed to deciduusleaf@gmail.com.

Deployment, modification, or distribution of this software constitutes acceptance of the terms mandated by either the AGPLv3 license or a separately negotiated commercial contract.