zhongwei/gh-raw-labs-claude-code-marketplace-claude-plugin-plugins-mxcp-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:49:50 +08:00
commit adc4b2be25
147 changed files with 24716 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
skills/mxcp-expert/assets/project-templates/google-calendar/README.md Normal file
View File

@@ -0,0 +1,213 @@
# Google Calendar OAuth Demo (Read-Only)
This example demonstrates how to create safe, read-only MCP tools that interact with Google Calendar using the MXCP OAuth authentication system with the Google Calendar API.
## Features Demonstrated
### 1. MXCP OAuth Authentication
- Project-wide Google OAuth configuration
- Automatic token management through MXCP authentication system
- User authentication via standard OAuth 2.0 flow
- Error handling for authentication failures
### 2. Google Calendar API Integration (Read-Only)
- `whoami` - Display information about the current authenticated Google user
- `list_calendars` - Retrieve all accessible calendars with filtering options
- `get_calendar` - Get detailed information for a specific calendar
- `list_events` - List events from a calendar with time filtering and pagination
- `get_event` - Retrieve detailed information for a specific event
- `search_events` - Search for events matching text queries
- `get_freebusy` - Check availability across multiple calendars
- Token-based API access using authenticated user context
- **Safe Design**: Only read operations - no calendar or event modifications
## Prerequisites
1. **Google Account**: You need a Google account with Calendar access
2. **Google Cloud Project**: Create a project in Google Cloud Console with Calendar API enabled
3. **OAuth Credentials**: Create OAuth 2.0 credentials for your application
4. **Python Dependencies**: The `google-api-python-client` and related libraries (automatically managed by MXCP)
## Setup
### 1. Create Google Cloud Project and Enable APIs
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the Google Calendar API:
- Go to **APIs & Services** → **Library**
- Search for "Google Calendar API"
- Click on it and press **Enable**
### 2. Configure OAuth Consent Screen (Required First)
1. In Google Cloud Console, go to **APIs & Services** → **OAuth consent screen**
2. Configure the consent screen:
- **User Type**: External (for testing) or Internal (for organization use)
- **App Name**: "MXCP Google Calendar Integration" (or your preferred name)
- **User Support Email**: Your email
- **Developer Contact**: Your email
3. **Add Scopes** (under "Data access" section):
- Click "Add or Remove Scopes"
- In the scope selection dialog, search for "calendar"
- Find and select `https://www.googleapis.com/auth/calendar.readonly` (Calendar read-only access)
- Click "Update" to save the scopes
4. Save the consent screen configuration
**Note**: The scopes are configured in the OAuth Consent Screen, not when creating the Client ID. This is why you don't see scope options when creating credentials.
### 3. Create OAuth 2.0 Client ID
1. Go to **APIs & Services** → **Credentials**
2. Click **Create Credentials** → **OAuth 2.0 Client IDs**
3. Configure the client:
- **Application Type**: Web application
- **Name**: "MXCP Calendar Client" (or your preferred name)
- **Authorized Redirect URIs**: Add based on your deployment:
- **Local Development**: `http://localhost:8000/google/callback`
- **Remote/Production**: `https://your-domain.com/google/callback` (replace with your actual server URL)
4. Save and note down the **Client ID** and **Client Secret**
### 4. Configure Environment Variables
Set your Google OAuth credentials:
```bash
export GOOGLE_CLIENT_ID="your-client-id-from-google-cloud"
export GOOGLE_CLIENT_SECRET="your-client-secret-from-google-cloud"
```
### 5. Configure Callback URL for Your Deployment
The callback URL configuration depends on where your MXCP server will run:
#### Local Development
For local development, the default configuration in `config.yml` uses `http://localhost:8000/google/callback`. This works when:
- You're running MXCP locally on your development machine
- Users authenticate from the same machine where MXCP is running
#### Remote/Production Deployment
For remote servers or production deployments, you need to:
1. **Update config.yml**: Modify the callback URL:
```yaml
redirect_uris:
- "https://your-domain.com/google/callback" # Your actual URL
```
2. **Update base_url**: Set the correct base URL in your config:
```yaml
transport:
http:
base_url: https://your-domain.com # Your actual server URL
```
3. **Configure OAuth Credentials**: Add the production callback URL to your Google Cloud OAuth credentials
**Important**:
- The callback URL must be accessible from the user's browser, not just from your server
- For production deployments, Google requires HTTPS for callback URLs
- You can configure multiple callback URLs in your OAuth credentials to support both local development and production
## Project Structure
```
google-calendar/
├── mxcp-site.yml # Project metadata
├── config.yml # Server and authentication configuration
├── python/ # Python modules
│ └── google_calendar_client.py # Google Calendar API implementations
├── tools/ # Tool definitions (read-only)
│ ├── whoami.yml # Current user information
│ ├── list_calendars.yml # List accessible calendars
│ ├── get_calendar.yml # Get calendar details
│ ├── list_events.yml # List calendar events
│ ├── get_event.yml # Get event details
│ ├── search_events.yml # Search for events
│ └── get_freebusy.yml # Check availability
└── README.md # This file
```
## Key Concepts
1. **MXCP OAuth Integration**: Uses MXCP's built-in Google OAuth provider for secure authentication
2. **User Context**: Access tokens are automatically managed and provided through `get_user_context()`
3. **Token-based Authentication**: Google API client is initialized with OAuth tokens instead of service account credentials
4. **Project-wide Configuration**: Authentication is configured at the project level in `config.yml`
5. **Error Handling**: Comprehensive error handling for authentication and API failures
6. **Type Safety**: Uses Python type hints and comprehensive error handling for data validation
## Running the Example
Once you've completed the setup above:
1. **Start MXCP**:
```bash
# From the examples/google-calendar directory:
MXCP_CONFIG=config.yml mxcp serve
```
2. **Connect your MCP client** (e.g., Claude Desktop) to the MXCP server
3. **Authenticate**: When the client first connects, you'll be redirected to Google to authorize the application
4. **Use the tools**: Once authenticated, you can use all the Google Calendar tools through your MCP client
## Example Usage
When you use the tools through an MCP client, you can:
### Get User Information
```
Use the whoami tool to see your Google profile information
```
### Manage Calendars
```
List all your calendars, get details for specific calendars, and check which ones you can modify
```
### View Calendar Events
```
- List events: "What's on my calendar this week?"
- Search events: "Find all meetings with John"
- Get event details: "Show me details for my 3 PM meeting"
- View event information: "What meetings do I have with the marketing team?"
```
### Check Availability
```
Use the freebusy tool to find available time slots across multiple calendars
```
## Troubleshooting
### Authentication Errors
- **"No user context available"**: User needs to authenticate first by running `mxcp serve` and completing OAuth flow
- **"No Google access token found"**: Authentication was incomplete or token expired - re-authenticate
- **OAuth Credentials Issues**: Verify your `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are correct
- **Callback URL Mismatch**: Ensure the callback URL in your Google Cloud OAuth credentials matches where your MXCP server is accessible
- **API Not Enabled**: Make sure the Google Calendar API is enabled in your Google Cloud project
### API Errors
- **403 Forbidden**: Check that the Calendar API is enabled and your OAuth scopes include calendar access
- **404 Not Found**: Verify calendar IDs and event IDs are correct and accessible to the authenticated user
- **Rate Limiting**: Google Calendar API has rate limits - implement appropriate retry logic if needed
### OAuth Setup Issues
- **Consent Screen**: Make sure your OAuth consent screen is properly configured with the correct scopes
- **Redirect URI**: The redirect URI must exactly match your MXCP server's accessible address
- **Scopes**: Ensure your OAuth configuration includes `https://www.googleapis.com/auth/calendar.readonly` scope
## Next Steps
This example demonstrates a comprehensive set of read-only Google Calendar integration tools. You could extend it with additional features like:
- Advanced calendar filtering and search capabilities
- Integration with other Google Workspace services (read-only)
- Calendar analytics and reporting
- Event pattern analysis and insights
- Multi-calendar comparison and availability analysis
**Note**: This example is intentionally read-only for safety. If you need write operations (create, update, delete), you would need to:
- Change the OAuth scope to `https://www.googleapis.com/auth/calendar` (full access)
- Add appropriate write functions with proper validation and error handling
- Implement additional safety measures and user confirmations