gmcp 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Johnie Hjelm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,182 +1,234 @@
-# GMCP
+<p align="center">
+  <h1 align="center">🔗<br/><code>gmcp</code></h1>
+  <p align="center">MCP server for Gmail and Google Calendar integration.
+    <br/>
+    by <a href="https://github.com/johnie">@johnie</a>
+  </p>
+</p>
+<br/>
 
-MCP (Model Context Protocol) server for Google services. Provides Gmail and Google Calendar integration with 19 tools for email management and calendar operations.
+<p align="center">
+<a href="https://www.npmjs.com/package/gmcp" rel="nofollow"><img src="https://img.shields.io/npm/v/gmcp.svg" alt="npm"></a>
+<a href="https://hub.docker.com/r/johnie/gmcp" rel="nofollow"><img src="https://img.shields.io/docker/pulls/johnie/gmcp" alt="Docker Pulls"></a>
+<a href="https://github.com/johnie/gmcp" rel="nofollow"><img src="https://img.shields.io/github/stars/johnie/gmcp" alt="stars"></a>
+</p>
 
-## Gmail Tools
+<br/>
+<br/>
 
-### Email Operations
+## Overview
 
-| Tool | Description |
-|------|-------------|
-| `gmcp_gmail_search_emails` | Search emails using Gmail query syntax |
-| `gmcp_gmail_get_email` | Get single email by message ID |
-| `gmcp_gmail_get_thread` | Get entire conversation thread |
-| `gmcp_gmail_list_attachments` | List all attachments on a message |
-| `gmcp_gmail_get_attachment` | Download attachment data by ID |
-| `gmcp_gmail_send_email` | Send email (preview + confirm safety) |
-| `gmcp_gmail_reply` | Reply to email in thread (preview + confirm) |
-| `gmcp_gmail_create_draft` | Create draft message |
+GMCP is a [Model Context Protocol](https://modelcontextprotocol.io/) server that enables LLMs to interact with Gmail and Google Calendar. It provides tools for searching emails, managing labels, sending messages, and working with calendar events—all through secure OAuth2 authentication.
 
-### Label Management
-
-| Tool | Description |
-|------|-------------|
-| `gmcp_gmail_list_labels` | List all Gmail labels (system + custom) |
-| `gmcp_gmail_get_label` | Get label details and message counts |
-| `gmcp_gmail_create_label` | Create custom label with visibility/color settings |
-| `gmcp_gmail_update_label` | Update label name, visibility, or color |
-| `gmcp_gmail_delete_label` | Delete custom label (system labels protected) |
-| `gmcp_gmail_modify_labels` | Add/remove labels on a message |
-| `gmcp_gmail_batch_modify` | Batch label operations on multiple messages |
+## Installation
 
-## Calendar Tools
+### NPM (Recommended)
 
-| Tool | Description |
-|------|-------------|
-| `gmcp_calendar_list_calendars` | List all calendars for account |
-| `gmcp_calendar_list_events` | List events with filters (time range, query, calendar) |
-| `gmcp_calendar_get_event` | Get single event by ID |
-| `gmcp_calendar_create_event` | Create event (supports recurring events, Google Meet) |
-
-## Setup
-
-### Prerequisites
+```bash
+# Install globally
+npm install -g gmcp
 
-1. **Google Cloud Project** with Gmail API and Calendar API enabled
-2. **OAuth 2.0 Client ID** (Desktop Application type)
-   - Create at [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
-   - Download credentials JSON file
+# Or run directly
+npx gmcp
+bunx gmcp
+```
 
-### Install & Configure
+### Docker
 
 ```bash
-# Install dependencies
-bun install
-
-# Copy environment template
-cp .env.example .env
-
-# Edit .env with your paths
-# GOOGLE_CREDENTIALS_PATH=/path/to/credentials.json
-# GOOGLE_TOKEN_PATH=/path/to/token.json
-# GOOGLE_SCOPES=gmail.readonly,calendar.readonly
+docker pull johnie/gmcp:latest
 ```
 
-### Authenticate
-
-Run the OAuth flow to obtain tokens:
+### From Source
 
 ```bash
-bun run auth
+git clone https://github.com/johnie/gmcp.git
+cd gmcp
+bun install
 ```
 
-Follow the prompts:
-1. Visit the authorization URL in your browser
-2. Authorize the app
-3. Copy the authorization code from the redirected URL
-4. Paste it in the terminal
+## Quick Start
+
+### 1. Google Cloud Setup
 
-The browser will show "connection refused" after authorization - **this is expected**. Just copy the `code=` parameter from the URL.
+1. Create a project in [Google Cloud Console](https://console.cloud.google.com/)
+2. Enable **Gmail API** and **Calendar API**
+3. Create **OAuth 2.0 Client ID** (Desktop Application type)
+4. Download the credentials JSON file
 
-### Run the Server
+### 2. Authenticate
 
 ```bash
-bun run start
-```
+# If installed globally
+gmcp auth
 
-The server runs via stdio and is ready to accept MCP requests.
+# Or with npx
+npx gmcp auth
 
-## Configuration
+# Or from source
+bun run auth
+```
 
-### Environment Variables
+Follow the prompts to authorize. The browser will show "connection refused" after authorization - this is expected. Copy the `code=` parameter from the URL.
 
-| Variable | Description |
-|----------|-------------|
-| `GOOGLE_CREDENTIALS_PATH` | Path to OAuth2 credentials JSON from Google Cloud Console |
-| `GOOGLE_TOKEN_PATH` | Path where OAuth2 tokens will be stored |
-| `GOOGLE_SCOPES` | Comma-separated Gmail and Calendar API scopes (short names or full URLs) |
+### 3. Run
 
-### Gmail Scopes
+```bash
+# Globally installed
+gmcp start
+# or just: gmcp
 
-| Short Name | Description | Required For |
-|------------|-------------|--------------|
-| `gmail.readonly` | Read-only access | Search, get email, get thread, list/get attachments, list labels, get label |
-| `gmail.modify` | Read, create, update, delete | Modify labels, batch modify |
-| `gmail.labels` | Manage labels | Create label, update label, delete label, modify labels, batch modify |
-| `gmail.send` | Send messages | Send email, reply |
-| `gmail.compose` | Create drafts and send | Send email, reply, create draft |
+# With npx
+npx gmcp start
 
-### Calendar Scopes
+# From source
+bun run start
+```
 
-| Short Name | Description | Required For |
-|------------|-------------|--------------|
-| `calendar.readonly` | Read-only calendar access | List calendars, list events, get event |
-| `calendar.events.readonly` | Read-only events access | List events, get event |
-| `calendar.events` | Manage events | Create event, list events, get event |
-| `calendar` | Full calendar access | All calendar tools |
+## Claude Desktop Integration
 
-### Scope Examples
+### Using npx (Recommended)
 
-```bash
-# Gmail read-only
-GOOGLE_SCOPES=gmail.readonly
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
-# Gmail and Calendar read-only
-GOOGLE_SCOPES=gmail.readonly,calendar.readonly
+```json
+{
+  "mcpServers": {
+    "gmcp": {
+      "command": "npx",
+      "args": ["-y", "gmcp"],
+      "env": {
+        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
+        "GOOGLE_TOKEN_PATH": "/path/to/token.json",
+        "GOOGLE_SCOPES": "gmail.readonly,gmail.send,calendar.events"
+      }
+    }
+  }
+}
+```
 
-# Gmail read/send + Calendar read/create
-GOOGLE_SCOPES=gmail.readonly,gmail.send,calendar.events
+### Using Docker
 
-# Full access (all tools)
-GOOGLE_SCOPES=gmail.readonly,gmail.modify,gmail.send,gmail.labels,calendar
+```json
+{
+  "mcpServers": {
+    "gmcp": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-v", "/path/to/credentials.json:/app/data/credentials.json:ro",
+        "-v", "/path/to/token.json:/app/data/token.json",
+        "-e", "GOOGLE_CREDENTIALS_PATH=/app/data/credentials.json",
+        "-e", "GOOGLE_TOKEN_PATH=/app/data/token.json",
+        "-e", "GOOGLE_SCOPES=gmail.readonly,gmail.send,calendar.events",
+        "johnie/gmcp:latest"
+      ]
+    }
+  }
+}
 ```
 
-## Claude Desktop Integration
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+### Using Bun (From Source)
 
 ```json
 {
   "mcpServers": {
     "gmcp": {
       "command": "bun",
-      "args": ["run", "/path/to/gmcp/src/index.ts"],
+      "args": ["run", "/path/to/gmcp/src/cli.ts"],
       "env": {
         "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
         "GOOGLE_TOKEN_PATH": "/path/to/token.json",
-        "GOOGLE_SCOPES": "gmail.readonly,gmail.send,gmail.labels,calendar.events"
+        "GOOGLE_SCOPES": "gmail.readonly,gmail.send,calendar.events"
       }
     }
   }
 }
 ```
 
-## Docker
+## Tools
+
+### Gmail (15 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gmcp_gmail_search_emails` | Search with Gmail query syntax |
+| `gmcp_gmail_get_email` | Get message by ID |
+| `gmcp_gmail_get_thread` | Get conversation thread |
+| `gmcp_gmail_list_attachments` | List attachments on message |
+| `gmcp_gmail_get_attachment` | Download attachment data |
+| `gmcp_gmail_send_email` | Send new email |
+| `gmcp_gmail_reply` | Reply to email in thread |
+| `gmcp_gmail_create_draft` | Create draft message |
+| `gmcp_gmail_list_labels` | List all labels |
+| `gmcp_gmail_get_label` | Get label details |
+| `gmcp_gmail_create_label` | Create custom label |
+| `gmcp_gmail_update_label` | Update label settings |
+| `gmcp_gmail_delete_label` | Delete custom label |
+| `gmcp_gmail_modify_labels` | Add/remove labels on message |
+| `gmcp_gmail_batch_modify` | Batch label operations |
+
+### Calendar (4 tools)
 
-Run with Docker:
+| Tool | Description |
+|------|-------------|
+| `gmcp_calendar_list_calendars` | List all calendars |
+| `gmcp_calendar_list_events` | List events with filters |
+| `gmcp_calendar_get_event` | Get event by ID |
+| `gmcp_calendar_create_event` | Create event (supports recurring, Google Meet) |
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GOOGLE_CREDENTIALS_PATH` | Path to OAuth2 credentials JSON |
+| `GOOGLE_TOKEN_PATH` | Path to store OAuth2 tokens |
+| `GOOGLE_SCOPES` | Comma-separated API scopes |
+
+### Scopes
+
+| Scope | Access |
+|-------|--------|
+| `gmail.readonly` | Read emails and labels |
+| `gmail.send` | Send emails |
+| `gmail.modify` | Read, modify labels |
+| `gmail.labels` | Manage labels |
+| `gmail.compose` | Create drafts and send |
+| `calendar.readonly` | Read calendars and events |
+| `calendar.events` | Manage events |
+| `calendar` | Full calendar access |
+
+**Examples:**
 
 ```bash
-docker build -t gmcp-server .
-docker run -i \
-  -v /path/to/credentials.json:/app/data/credentials.json:ro \
-  -v /path/to/token.json:/app/data/token.json \
-  -e GOOGLE_CREDENTIALS_PATH=/app/data/credentials.json \
-  -e GOOGLE_TOKEN_PATH=/app/data/token.json \
-  -e GOOGLE_SCOPES=gmail.readonly,gmail.labels,gmail.send,calendar.events \
-  gmcp-server
+# Read-only
+GOOGLE_SCOPES=gmail.readonly,calendar.readonly
+
+# Full access
+GOOGLE_SCOPES=gmail.readonly,gmail.modify,gmail.send,calendar.events
 ```
 
-## Testing
+## CLI Reference
 
-Test with MCP Inspector:
+```
+gmcp [command]
 
-```bash
-bunx @modelcontextprotocol/inspector bun run start
+Commands:
+  start    Start MCP server (default)
+  auth     Run OAuth2 authentication flow
+
+Options:
+  --help, -h       Show usage
+  --version, -v    Show version
 ```
 
-## Future Enhancements
+## Testing
 
-Potential additions include Google Drive, Google Sheets, and other Google Workspace services.
+```bash
+bunx @modelcontextprotocol/inspector bun run start
+```
 
 ## License
 

package/dist/auth-cli.d.ts

@@ -0,0 +1,2 @@
+declare function runAuth(): Promise<void>;
+export { runAuth };

package/dist/auth-cli.js

@@ -7,22 +7,12 @@ import {
   loadCredentials,
   saveTokens
 } from "./shared/chunk-n2k9eesp.js";
+import"./shared/chunk-3s189drz.js";
 
 // src/auth-cli.ts
-import { createInterface } from "node:readline";
-function readLine() {
-  const rl = createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-  return new Promise((resolve) => {
-    rl.on("line", (line) => {
-      rl.close();
-      resolve(line.trim());
-    });
-  });
-}
-async function main() {
+import { input } from "@inquirer/prompts";
+import kleur from "kleur";
+async function runAuth() {
   console.log(`GMCP Server - OAuth2 Authentication
 `);
   const { credentialsPath, tokenPath, scopes } = getEnvConfig();
@@ -38,7 +28,7 @@ async function main() {
 ========================================`);
   console.log("STEP 1: Visit this URL to authorize:");
   console.log("========================================");
-  console.log("\x1B[36m%s\x1B[0m", authUrl);
+  console.log(kleur.cyan(authUrl));
   console.log(`
 ========================================`);
   console.log("STEP 2: After authorizing:");
@@ -53,30 +43,34 @@ Copy the entire code after "code=" (the long string before "&scope")`);
   console.log(`
 ========================================`);
   console.log("STEP 3: Paste the authorization code below:");
-  console.log("========================================");
-  const code = await readLine();
-  if (!code) {
-    console.error("Error: No authorization code provided");
-    process.exit(1);
-  }
+  console.log(`========================================
+`);
+  const code = await input({
+    message: "Authorization code:",
+    required: true,
+    validate: (value) => {
+      if (value.length < 10) {
+        return "Authorization code appears too short";
+      }
+      return true;
+    }
+  });
   console.log(`
 Exchanging authorization code for tokens...`);
   try {
     const tokens = await getTokensFromCode(oauth2Client, code);
     await saveTokens(tokenPath, tokens);
-    console.log("\x1B[32m%s\x1B[0m", `
-Success! Tokens saved to`, tokenPath);
+    console.log(kleur.green(`
+Success! Tokens saved to ${tokenPath}`));
     console.log(`
 You can now run the MCP server with: npx gmcp`);
   } catch (error) {
-    console.error("\x1B[31m%s\x1B[0m", `
-Error exchanging code for tokens:`);
+    console.error(kleur.red(`
+Error exchanging code for tokens:`));
     console.error(error);
     process.exit(1);
   }
 }
-main().catch((error) => {
-  console.error("\x1B[31m%s\x1B[0m", "Fatal error:");
-  console.error(error);
-  process.exit(1);
-});
+export {
+  runAuth
+};

package/dist/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import {
+  getVersion
+} from "./shared/chunk-f7kh3eqv.js";
+import {
+  __require
+} from "./shared/chunk-3s189drz.js";
+
+// src/cli.ts
+import { run } from "@stricli/core";
+
+// src/cli/app.ts
+import { buildApplication, buildRouteMap } from "@stricli/core";
+
+// src/cli/commands/auth.ts
+import { buildCommand } from "@stricli/core";
+var authCommand = buildCommand({
+  func: async () => {
+    const { runAuth } = await import("./auth-cli.js");
+    await runAuth();
+  },
+  parameters: {},
+  docs: { brief: "Run OAuth2 authentication flow" }
+});
+
+// src/cli/commands/start.ts
+import { buildCommand as buildCommand2 } from "@stricli/core";
+var startCommand = buildCommand2({
+  func: async () => {
+    const { startServer } = await import("./index.js");
+    await startServer();
+  },
+  parameters: {},
+  docs: { brief: "Start the MCP server" }
+});
+
+// src/cli/app.ts
+var routes = buildRouteMap({
+  routes: {
+    start: startCommand,
+    auth: authCommand
+  },
+  docs: { brief: "GMCP - Gmail and Calendar MCP Server" }
+});
+async function createApp() {
+  const version = await getVersion();
+  return buildApplication(routes, {
+    name: "gmcp",
+    versionInfo: { currentVersion: version }
+  });
+}
+
+// src/cli.ts
+var app = await createApp();
+var args = process.argv.slice(2);
+var effectiveArgs = args.length === 0 ? ["start"] : args;
+await run(app, effectiveArgs, { process });

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+* Main server initialization
+*/
+declare function startServer(): Promise<void>;
+export { startServer };

package/dist/index.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
+import {
+  getVersion
+} from "./shared/chunk-f7kh3eqv.js";
 import {
   createAuthenticatedClient,
   getEnvConfig,
   getHeader
 } from "./shared/chunk-n2k9eesp.js";
+import"./shared/chunk-3s189drz.js";
 
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -3193,9 +3197,10 @@ This tool modifies label properties. System labels (INBOX, SENT, etc.) can only
 - Requires \`gmail.labels\` or \`gmail.modify\` scope`;
 
 // src/index.ts
-async function main() {
+async function startServer() {
   const logger = createLogger();
-  logger.info({ version: "1.0.0" }, "GMCP Server starting");
+  const version = await getVersion();
+  logger.info({ version }, "GMCP Server starting");
   const { credentialsPath, tokenPath, scopes } = getEnvConfig();
   logger.info({
     credentialsPath,
@@ -3210,7 +3215,7 @@ async function main() {
   logger.info("Gmail and Calendar clients initialized");
   const server = new McpServer({
     name: "gmcp-server",
-    version: "1.0.0"
+    version
   });
   const tools = [
     {
@@ -3381,11 +3386,6 @@ async function main() {
   logger.info("MCP server connected via stdio");
   logger.info("Ready to accept requests");
 }
-main().catch((error) => {
-  const logger = createLogger();
-  logger.error({
-    error: error instanceof Error ? error.message : String(error),
-    stack: error instanceof Error ? error.stack : undefined
-  }, "Fatal error");
-  process.exit(1);
-});
+export {
+  startServer
+};

package/dist/shared/chunk-3s189drz.js

@@ -0,0 +1,4 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+export { __require };

package/dist/shared/chunk-f7kh3eqv.js

@@ -0,0 +1,30 @@
+// src/version.ts
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+async function findPackageJson(startDir) {
+  let dir = startDir;
+  let prevDir = "";
+  while (dir !== prevDir) {
+    const candidate = join(dir, "package.json");
+    try {
+      const content = await readFile(candidate, "utf8");
+      const pkg = JSON.parse(content);
+      if (pkg.name === "gmcp") {
+        return candidate;
+      }
+    } catch {}
+    prevDir = dir;
+    dir = dirname(dir);
+  }
+  throw new Error("Could not find gmcp package.json");
+}
+async function getVersion() {
+  const __dirname2 = dirname(fileURLToPath(import.meta.url));
+  const packagePath = await findPackageJson(__dirname2);
+  const content = await readFile(packagePath, "utf8");
+  const pkg = JSON.parse(content);
+  return pkg.version;
+}
+
+export { getVersion };

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "gmcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "GMCP Server for Google Workspace with OAuth2 authentication",
   "module": "src/index.ts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "bin": {
-    "gmcp": "dist/index.js",
-    "gmcp-auth": "dist/auth-cli.js"
+    "gmcp": "dist/cli.js"
   },
   "files": [
     "dist"
@@ -20,8 +19,8 @@
     }
   },
   "scripts": {
-    "start": "bun run src/index.ts",
-    "auth": "bun run src/auth-cli.ts",
+    "start": "bun run src/cli.ts",
+    "auth": "bun run src/cli.ts auth",
     "build": "bunup",
     "prepublishOnly": "bun run build",
     "prepare": "lefthook install",
@@ -45,9 +44,12 @@
     "anthropic"
   ],
   "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
     "@modelcontextprotocol/sdk": "^1.25.3",
+    "@stricli/core": "^1.2.5",
     "googleapis": "^170.1.0",
     "json2md": "^2.0.3",
+    "kleur": "^4.1.5",
     "pino": "^9.7.0",
     "pino-pretty": "^13.0.0",
     "zod": "^4.3.6"