🚀 Enterprise-Grade MCP Server for Google Sheets & Apps Script 🚀

A production-ready Model Context Protocol server that provides intelligent integration between autonomous AI agents and Google Sheets/Apps Script with 100+ tools, enterprise security, self-healing capabilities, and complete observability.

flowchart LR
    subgraph "🤖 AI Agents"
        A[MCP Client]
    end
    
    subgraph "🔷 MCP Server"
        B[Tool Registry]
        C[Rate Limiter]
        D[Context Engine]
        E[Security Layer]
    end
    
    subgraph "📊 Google APIs"
        F[Sheets API]
        G[Apps Script]
        H[Drive API]
    end
    
    A -->|JSON-RPC| B
    B --> C --> D --> E --> F
    E --> G
    E --> H
    
    style A fill:#1a1a2e,stroke:#00d9ff,color:#fff
    style B fill:#16213e,stroke:#a855f7,color:#fff
    style C fill:#0f3460,stroke:#22c55e,color:#fff
    style D fill:#1a1a2e,stroke:#f59e0b,color:#fff
    style E fill:#0f0f23,stroke:#ef4444,color:#fff
    style F fill:#1e3a5f,stroke:#3b82f6,color:#fff
    style G fill:#1e3a5f,stroke:#3b82f6,color:#fff
    style H fill:#1e3a5f,stroke:#3b82f6,color:#fff

⭐ Star us on GitHub	📖 Read the Docs	💬 Join Discord	🐛 Report Issues

📋 Table of Contents (Click to expand)

✨ Features
🏗️ Architecture
🚀 Quick Start
🔧 Configuration
🛠️ Tools Reference
🔐 Security
📈 Observability
💚 Self-Healing
� Exemplos
🤝 Contribution
📄 License

✨ Features

Powerful capabilities that set us apart

🧠

Context Intelligence

Token estimation • Compression • Semantic search • Dataset management

100K+ tokens supported

🛠️

100+ MCP Tools

Spreadsheet ops • AI analysis • Automation workflows • Data pipelines

Comprehensive coverage

💚

Self-Healing

Circuit breaker • Auto-retry • Error recovery • Health checks

99.9% uptime

⚡

Adaptive Rate Limiting

Per-agent limits • Per-API quotas • Sliding windows • Backoff strategy

Smart throttling

🔐

Enterprise Security

RBAC • AES-256 encryption • OAuth2 • Audit logging • SOC2 ready

Bank-grade protection

📊

Complete Observability

Metrics • Tracing • Health checks • Alerting • Audit logs

Full visibility

🏗️ Architecture

Enterprise-grade system architecture

╔═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                          GOOGLE APPS SCRIPT MCP SERVER                                              ║
║                                                  HIGH-LEVEL ARCHITECTURE                                             ║
╠═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║                                                                                                                                 ║
║      ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐   ║
║      │                                                    🤖 MCP CLIENT (AI AGENT)                                   │   ║
║      │                                                         ┌──────────────┐                                       │   ║
║      │                                                         │ JSON-RPC 2.0 │                                       │   ║
║      │                                                         │  SSE Stream  │                                       │   ║
║      │                                                         └──────┬───────┘                                       │   ║
║      └───────────────────────────────────────────────────────────────┼───────────────────────────────────────────────┘   ║
║                                                                  │                                                    ║
║                                                                  ▼                                                    ║
║      ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────┐   ║
║      │                                                   🔷 MCP SERVER                                                │   ║
║      │  ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐  │   ║
║      │  │                                     📦 SERVER MANAGEMENT LAYER                                          │  │   ║
║      │  │  ┌────────────────┐     ┌───────────────────┐     ┌────────────────────────┐     ┌─────────────────┐   │  │   ║
║      │  │  │   ⚙️ Config   │     │   🖥️ Server        │     │     🗂️ Tool            │     │   🔒 Auth       │   │  │   ║
║      │  │  │   Manager     │     │   Manager          │     │     Registry          │     │   Manager       │   │  │   ║
║      │  │  └────────────────┘     └───────────────────┘     └────────────────────────┘     └─────────────────┘   │  │   ║
║      │  └──────────────────────────────────────────────────────────────────────────────────────────────────────────┘  │   ║
║      │                                                                                                                 │   ║
║      │  ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐  │   ║
║      │  │                                🧠 CONTEXT INTELLIGENCE LAYER                                              │  │   ║
║      │  │  ┌────────────────┐     ┌───────────────────┐     ┌────────────────────────┐     ┌─────────────────┐   │  │   ║
║      │  │  │   📊 Context  │     │   🎯 Token        │     │     💾 Dataset         │     │   🗄️ Embedding │   │  │   ║
║      │  │  │   Manager     │     │   Estimator       │     │     Store              │     │   Store         │   │  │   ║
║      │  │  └────────────────┘     └───────────────────┘     └────────────────────────┘     └─────────────────┘   │  │   ║
║      │  │  ┌────────────────┐     ┌───────────────────┐     ┌────────────────────────┐     ┌─────────────────┐   │  │   ║
║      │  │  │   🗜️ Compress │     │   💨 Memory      │     │     🔍 Semantic        │     │   📐 Truncator │   │  │   ║
║      │  │  │   or          │     │   Cache          │     │     Search             │     │                 │   │  │   ║
║      │  │  └────────────────┘     └───────────────────┘     └────────────────────────┘     └─────────────────┘   │  │   ║
║      │  └──────────────────────────────────────────────────────────────────────────────────────────────────────────┘  │   ║
║      │                                                                                                                 │   ║
║      │  ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐  │   ║
║      │  │                                     🔌 MIDDLEWARE LAYER                                                     │  │   ║
║      │  │  ┌────────────────┐     ┌───────────────────┐     ┌────────────────────────┐     ┌─────────────────┐   │  │   ║
║      │  │  │   ⏱️ Rate     │     │   🔄 Interceptor  │     │     ⚠️ Error           │     │   📝 Prompt    │   │  │   ║
║      │  │  │   Limiter     │     │   Chain           │     │     Handler           │     │   Manager       │   │  │   ║
║      │  │  └────────────────┘     └───────────────────┘     └────────────────────────┘     └─────────────────┘   │  │   ║
║      │  └──────────────────────────────────────────────────────────────────────────────────────────────────────────┘  │   ║
║      │                                                                                                                 │   ║
║      │  ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐  │   ║
║      │  │                                     🔐 SECURITY LAYER                                                       │  │   ║
║      │  │  ┌────────────────┐     ┌───────────────────┐     ┌────────────────────────┐     ┌─────────────────┐   │  │   ║
║      │  │  │   🛡️ Access  │     │   🔏 Encryption  │     │     🔎 Threat          │     │   ✅ Compliance │   │  │   ║
║      │  │  │   Control     │     │                   │     │     Detection          │     │                 │   │  │   ║
║      │  │  └────────────────┘     └───────────────────┘     └────────────────────────┘     └─────────────────┘   │  │   ║
║      │  └──────────────────────────────────────────────────────────────────────────────────────────────────────────┘  │   ║
║      │                                                                                                                 │   ║
║      │  ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐  │   ║
║      │  │                                    📈 OBSERVABILITY LAYER                                                  │  │   ║
║      │  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────┐  ┌───────────┐  ┌────────────────┐           │  │   ║
║      │  │  │  📊      │  │  ❤️       │  │  🔍      │  │   📋      │  │   🔔       │  │    📜         │           │  │   ║
║      │  │  │ Metrics  │  │ Health   │  │ Tracing  │  │  Audit    │  │ Alerting   │  │    Logging    │           │  │   ║
║      │  │  └──────────┘  └──────────┘  └──────────┘  └───────────┘  └───────────┘  └────────────────┘           │  │   ║
║      │  └──────────────────────────────────────────────────────────────────────────────────────────────────────────┘  │   ║
║      │                                                                                                                 │   ║
║      │  ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────┐  │   ║
║      │  │                                    💚 SELF-HEALING LAYER                                                   │  │   ║
║      │  │  ┌────────────────┐     ┌───────────────────┐     ┌────────────────────────┐                          │  │   ║
║      │  │  │   🔄 Circuit │     │   🔁 Auto        │     │     🩺 Health          │                          │  │   ║
║      │  │  │   Breaker    │     │   Retry         │     │     Monitor            │                          │  │   ║
║      │  │  └────────────────┘     └───────────────────┘     └────────────────────────┘                          │  │   ║
║      │  └──────────────────────────────────────────────────────────────────────────────────────────────────────────┘  │   ║
║      └───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘   ║
║                                                                  │                                                    ║
║                                                                  ▼                                                    ║
║      ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────┐   ║
║      │                                                📱 GOOGLE APIS                                                │   ║
║      │   ┌──────────────────────┐     ┌────────────────────────┐     ┌─────────────────────────────────────────┐    │   ║
║      │   │       📊            │     │        📜              │     │              📁                       │    │   ║
║      │   │    Sheets API       │     │    Apps Script API     │     │            Drive API                   │    │   ║
║      │   └──────────────────────┘     └────────────────────────┘     └─────────────────────────────────────────┘    │   ║
║      └───────────────────────────────────────────────────────────────────────────────────────────────────────────────┘   ║
╚═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝

Request Flow

┌──────────┐     ┌───────────────┐     ┌────────────────┐     ┌──────────────┐     ┌────────────────┐
│  Client  │────►│     Tool      │────►│      Rate     │────►│    Context   │────►│     Auth       │
│ Request  │     │    Registry   │     │    Limiter    │     │    Engine    │     │    Layer       │
└──────────┘     └───────────────┘     └────────────────┘     └──────────────┘     └───────┬────────┘
                                                                                                │
      ┌───────────────────────────────────────────────────────────────────────────────────────┘
      │
      ▼
┌──────────────┐     ┌────────────────┐     ┌─────────────┐
│   Google     │────►│   Response     │────►│    Client   │
│     APIs     │     │    Builder     │     │   Response  │
└──────────────┘     └────────────────┘     └─────────────┘

Circuit Breaker State Machine

                            ┌───────────────────┐
                            │   🔴 CLOSED       │
                            │    (Normal Ops)   │
                            └─────────┬─────────┘
                                      │
                     failures > threshold
                                      │
                                      ▼
                            ┌───────────────────┐
                            │   🟠 OPEN STATE   │
                            │ (Rejecting Reqs)  │
                            └─────────┬─────────┘
                                      │
                           timer expires
                                      │
                                      ▼
                            ┌───────────────────┐
                            │  🟡 HALF-OPEN     │
                            │   (Test Mode)     │
                            └─────────┬─────────┘
                                      │
           ┌──────────────────────────┼──────────────────────────┐
           │                          │                          │
      success ✓                   success ✓                failure ✗
           │                          │                          │
           ▼                          ▼                          ▼
    ┌─────────────┐           ┌─────────────┐           ┌─────────────┐
    │   CLOSED    │           │   CLOSED    │           │    OPEN     │
    │   ✅        │           │   ✅        │           │     🔴      │
    └─────────────┘           └─────────────┘           └─────────────┘

🚀 Quick Start

Prerequisites

Installation

# Clone the repository
git clone https://github.com/devfinprojects/GAS-MCPSERVER.git
cd GAS-MCPSERVER

# Install dependencies
npm install

# Build the project
npm run build

Environment Setup

# Copy example environment file
cp env.example .env

# Edit configuration
#nano .env  # Linux/Mac
#notepad .env  # Windows

🔧 Configuration

Configure your MCP server

Variable	Description	Default	Required
`GOOGLE_CREDENTIALS_PATH`	Path to OAuth JSON	`./credentials.json`	✅ Yes
`PORT`	HTTP server port	`3000`	❌ No
`LOG_LEVEL`	Logging verbosity	`info`	❌ No
`RATE_LIMIT_REQUESTS_PER_MINUTE`	Rate limit per minute	`60`	❌ No
`CONTEXT_MAX_TOKENS`	Max context tokens	`100000`	❌ No
`ENABLE_SELF_HEALING`	Enable circuit breaker	`true`	❌ No
`ENABLE_METRICS`	Enable Prometheus metrics	`false`	❌ No
`ENABLE_TRACING`	Enable distributed tracing	`false`	❌ No
`ENABLE_AUDIT_LOGGING`	Enable audit logs	`true`	❌ No
`CIRCUIT_BREAKER_THRESHOLD`	Failure threshold	`5`	❌ No
`CIRCUIT_BREAKER_TIMEOUT`	Reset timeout (ms)	`30000`	❌ No

🛠️ Tools Reference

100+ MCP tools across 5 categories

╔══════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║                                    100+ MCP TOOLS BREAKDOWN                                             ║
╠══════════════════════════════════════════════════════════════════════════════════════════════════════════╣
║                                                                                                          ║
║   ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐             ║
║   │      🤖      │  │      ⚡      │  │      📊     │  │      🧠     │  │      📝      │             ║
║   │      AI      │  │  AUTOMATION  │  │ DATA ENGR   │  │   CONTEXT   │  │ CODE QUALITY │             ║
║   │    TOOLS     │  │    TOOLS     │  │    TOOLS    │  │    TOOLS    │  │    TOOLS     │             ║
║   │              │  │              │  │             │  │             │  │              │             ║
║   │ • Analysis   │  │ • Jobs       │  │ • ETL       │  │ • Datasets  │  │ • Analysis   │             ║
║   │ • Anomaly    │  │ • Workflows  │  │ • Import    │  │ • Query     │  │ • Review     │             ║
║   │ • Patterns   │  │ • Webhooks   │  │ • Export    │  │ • Control   │  │ • Doc Gen    │             ║
║   │ • Transform  │  │ • Triggers   │  │ • Mapping   │  │             │  │ • Test Gen   │             ║
║   │ • NLQ       │  │ • Notifs     │  │ • Pipeline  │  │             │  │ • Types      │             ║
║   │ • Recommen-  │  │ • Scheduled  │  │ • Validation│  │             │  │              │             ║
║   │   dations   │  │              │  │             │  │             │  │              │             ║
║   │              │  │              │  │             │  │             │  │              │             ║
║   │    35+       │  │     25+      │  │     25+     │  │     15+     │  │     25+      │             ║
║   └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘             ║
║                                                                                                          ║
╚══════════════════════════════════════════════════════════════════════════════════════════════════════════╝

🤖 AI Analysis Tools (35+ tools)

Powerful AI-driven analysis capabilities

Tool Category	Tools	Description
📈 Analysis	8 tools	Data analysis, column analysis, summaries
🔍 Anomaly Detection	4 tools	Outlier detection, unusual values
🔁 Pattern Recognition	5 tools	Patterns, sequences, cycles, distributions
🔮 Recommendations	4 tools	Improvements, chart suggestions
🧹 Transformation	5 tools	Data cleaning, reshaping, aggregation
💬 Natural Language	5 tools	NL to spreadsheet, formula generation

📋 View AI Tool Reference

Analysis Tools

Tool Name	Parameters	Return Type	Example
`analyze_sheet_data`	`spreadsheetId, range`	`{ analysis }`	`{ "name": "analyze_sheet_data", "args": { "spreadsheetId": "abc" } }`
`analyze_column`	`spreadsheetId, range, column`	`{ stats }`	`{ "name": "analyze_column", "args": { "spreadsheetId": "abc", "column": "A" } }`
`get_data_summary`	`spreadsheetId`	`{ summary }`	`{ "name": "get_data_summary", "args": { "spreadsheetId": "abc" } }`

Anomaly Detection

Tool Name	Parameters	Return Type	Example
`detect_outliers`	`spreadsheetId, range, method`	`{ outliers }`	`{ "name": "detect_outliers", "args": { "spreadsheetId": "abc" } }`
`analyze_anomalies`	`spreadsheetId, timeRange`	`{ anomalies }`	`{ "name": "analyze_anomalies", "args": { "spreadsheetId": "abc" } }`
`find_unusual_values`	`spreadsheetId, column`	`{ values }`	`{ "name": "find_unusual_values", "args": { "spreadsheetId": "abc" } }`

Pattern Recognition

Tool Name	Parameters	Return Type	Example
`detect_patterns`	`spreadsheetId, range`	`{ patterns }`	`{ "name": "detect_patterns", "args": { "spreadsheetId": "abc" } }`
`find_sequences`	`spreadsheetId, column`	`{ sequences }`	`{ "name": "find_sequences", "args": { "spreadsheetId": "abc" } }`
`detect_cycles`	`spreadsheetId, range`	`{ cycles }`	`{ "name": "detect_cycles", "args": { "spreadsheetId": "abc" } }`

Transformation

Tool Name	Parameters	Return Type	Example
`clean_sheet_data`	`spreadsheetId, rules`	`{ cleaned }`	`{ "name": "clean_sheet_data", "args": { "spreadsheetId": "abc" } }`
`transform_data`	`spreadsheetId, transforms`	`{ result }`	`{ "name": "transform_data", "args": { "spreadsheetId": "abc" } }`
`reshape_data`	`spreadsheetId, pivotConfig`	`{ reshaped }`	`{ "name": "reshape_data", "args": { "spreadsheetId": "abc" } }`

Natural Language Query

Tool Name	Parameters	Return Type	Example
`nl_to_spreadsheet_action`	`query, spreadsheetId`	`{ action }`	`{ "name": "nl_to_spreadsheet_action", "args": { "query": "add column" } }`
`generate_formula`	`description, context`	`{ formula }`	`{ "name": "generate_formula", "args": { "description": "sum of column" } }`
`query_data_nl`	`query, spreadsheetId`	`{ results }`	`{ "name": "query_data_nl", "args": { "query": "sales > 1000" } }`

⚡ Automation Tools (25+ tools)

Workflow automation and scheduling

Tool Category	Tools	Description
📅 Job Scheduler	8 tools	Create, manage, trigger scheduled jobs
🔀 Workflows	7 tools	Multi-step automation workflows
🪝 Webhooks	9 tools	Event-driven triggers
⏰ Triggers	6 tools	Spreadsheet trigger management
🔔 Notifications	12 tools	Alerts and notifications

📋 View Automation Tool Reference

Job Scheduler

Tool Name	Parameters	Return Type
`create_scheduled_job`	`name, schedule, action`	`{ jobId }`
`list_scheduled_jobs`	`filters`	`{ jobs }`
`get_scheduled_job`	`jobId`	`{ job }`
`update_scheduled_job`	`jobId, updates`	`{ updated }`
`delete_scheduled_job`	`jobId`	`{ deleted }`
`trigger_job_now`	`jobId`	`{ triggered }`
`pause_scheduled_job`	`jobId`	`{ paused }`
`resume_scheduled_job`	`jobId`	`{ resumed }`

Workflows

Tool Name	Parameters	Return Type
`create_workflow`	`name, steps`	`{ workflowId }`
`list_workflows`	`filters`	`{ workflows }`
`get_workflow`	`workflowId`	`{ workflow }`
`run_workflow`	`workflowId, inputs`	`{ result }`
`stop_workflow`	`workflowId`	`{ stopped }`
`validate_workflow`	`workflow`	`{ valid }`

Webhooks

Tool Name	Parameters	Return Type
`register_webhook`	`url, events, secret`	`{ webhookId }`
`list_webhooks`	`filters`	`{ webhooks }`
`delete_webhook`	`webhookId`	`{ deleted }`
`test_webhook`	`webhookId`	`{ result }`
`enable_webhook`	`webhookId`	`{ enabled }`
`disable_webhook`	`webhookId`	`{ disabled }`

📊 Data Engineering Tools (25+ tools)

ETL pipelines and data operations

Tool Category	Tools	Description
🔄 ETL	5 tools	Extract, transform, load pipelines
📥 Import/Export	6 tools	CSV, JSON, batch operations
🗺️ Mapping	5 tools	Schema detection and mapping
📦 Pipeline	5 tools	Data pipeline management
✅ Validation	5 tools	Data quality and schema validation

📋 View Data Engineering Tool Reference

ETL Tools

Tool Name	Parameters	Return Type
`extract_spreadsheet_data`	`spreadsheetId, range, options`	`{ data }`
`transform_data_batch`	`data, transforms`	`{ transformed }`
`load_to_spreadsheet`	`spreadsheetId, data, options`	`{ loaded }`
`run_etl_pipeline`	`config`	`{ result }`

Import/Export

Tool Name	Parameters	Return Type
`import_csv`	`url, spreadsheetId, options`	`{ imported }`
`export_csv`	`spreadsheetId, range, options`	`{ url }`
`import_json`	`data, spreadsheetId`	`{ imported }`
`export_json`	`spreadsheetId, range`	`{ data }`
`convert_format`	`source, targetFormat`	`{ converted }`
`batch_export`	`spreadsheetIds, format`	`{ results }`

Pipeline

Tool Name	Parameters	Return Type
`create_pipeline`	`config`	`{ pipelineId }`
`run_pipeline`	`pipelineId, inputs`	`{ result }`
`get_pipeline_status`	`pipelineId`	`{ status }`
`list_pipelines`	`filters`	`{ pipelines }`
`delete_pipeline`	`pipelineId`	`{ deleted }`

🧠 Context Tools (15+ tools)

LLM context optimization and management

Tool Category	Tools	Description
💾 Dataset	5 tools	Store, query, manage datasets
🔍 Query	4 tools	Search and retrieve context
🎛️ Control	6 tools	Context mode and optimization

📋 View Context Tool Reference

Dataset Tools

Tool Name	Parameters	Return Type
`store_dataset`	`name, data, schema`	`{ datasetId }`
`query_dataset`	`datasetId, filters`	`{ rows }`
`list_datasets`	`filters`	`{ datasets }`
`delete_dataset`	`datasetId`	`{ deleted }`
`update_dataset`	`datasetId, data`	`{ updated }`

Query Tools

Tool Name	Parameters	Return Type
`semantic_search`	`query, datasetId`	`{ results }`
`get_dataset_stats`	`datasetId`	`{ stats }`
`get_token_usage`	`sessionId`	`{ usage }`
`dataset_exists`	`datasetId`	`{ exists }`

Context Control

Tool Name	Parameters	Return Type
`estimate_context_cost`	`spreadsheetId, range`	`{ tokens, cost }`
`set_context_mode`	`mode`	`{ mode }`
`get_context_config`	—	`{ config }`
`reset_session_tokens`	`sessionId`	`{ reset }`
`process_through_context`	`data, options`	`{ processed }`

📝 Code Quality Tools (25+ tools)

Apps Script code analysis and improvement

Tool Category	Tools	Description
📊 Analysis	5 tools	Code quality and complexity
👀 Review	3 tools	Automated code reviews
📚 Documentation	4 tools	JSDoc generation
🧪 Test Generation	3 tools	Unit test creation
✅ Type Checking	3 tools	Type validation

📋 View Code Quality Tool Reference

Analysis Tools

Tool Name	Parameters	Return Type
`analyze_code_quality`	`code, includeComplexity`	`{ metrics }`
`analyze_complexity`	`code`	`{ complexity }`
`analyze_dependencies`	`code`	`{ deps }`

Code Review

Tool Name	Parameters	Return Type
`perform_code_review`	`code`	`{ issues }`
`check_best_practices`	`code`	`{ violations }`
`suggest_improvements`	`code`	`{ suggestions }`

Documentation

Tool Name	Parameters	Return Type
`generate_jsdoc`	`code`	`{ docs }`
`generate_readme`	`project`	`{ readme }`
`update_comments`	`code`	`{ updated }`

Test Generation

Tool Name	Parameters	Return Type
`generate_unit_tests`	`code, framework`	`{ tests }`
`generate_integration_tests`	`code`	`{ tests }`
`generate_mocks`	`code`	`{ mocks }`

🔐 Security

Enterprise-grade security features

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              🔐 SECURITY ARCHITECTURE                                │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     │
│   │   🔒 OAuth2 │────►│   🛡️ RBAC   │────►│  🔏 AES-256 │────►│   📋 Audit  │     │
│   │  + Token    │     │  + Roles    │     │  Encryption │     │   Logging   │     │
│   │   Refresh   │     │  + Perms    │     │  + at Rest   │     │   + SOC2    │     │
│   └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     │
│                                                                                     │
└─────────────────────────────────────────────────────────────────────────────────────┘

✅ OAuth2 with automatic token refresh
✅ Role-Based Access Control (RBAC)
✅ AES-256 encryption at rest
✅ Comprehensive audit logging
✅ SOC2 and GDPR ready
✅ Threat detection and prevention

📈 Observability

Complete visibility into your system

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                           📈 OBSERVABILITY DASHBOARD                               │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│   ┌────────────────┐  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐│
│   │     📊        │  │      ❤️        │  │      🔍       │  │      🔔       ││
│   │   METRICS     │  │    HEALTH      │  │   TRACING     │  │   ALERTING    ││
│   │                │  │                │  │                │  │                ││
│   │ Prometheus    │  │  Liveness     │  │  Distributed  │  │  Rule-based   ││
│   │  Compatible   │  │  + Readiness  │  │    Spans      │  │  Notifications││
│   │                │  │                │  │                │  │                ││
│   │ • Request     │  │  • /health    │  │ • Jaeger      │  │ • Email       ││
│   │   Rate        │  │  • /ready      │  │   Compatible  │  │ • Slack       ││
│   │ • Latency     │  │  • Custom      │  │ • Custom      │  │ • Webhook     ││
│   │ • Errors      │  │    Checks      │  │   Tags        │  │ • PagerDuty   ││
│   └────────────────┘  └────────────────┘  └────────────────┘  └────────────────┘│
│                                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────────────┐│
│   │                              📜 AUDIT LOGGING                                  ││
│   │                                                                                 ││
│   │  • Every API call logged    • User/agent tracking    • Immutable records    ││
│   │  • Queryable logs           • Export to SIEM          • Retention policies    ││
│   └─────────────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────────────┘

💚 Self-Healing

Automatic error recovery for 99.9% uptime

┌─────────────────────────────────────────────────────────────────────────────────────┐
│                          💚 SELF-HEALING MECHANISMS                                 │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                     │
│   ┌────────────────┐  ┌────────────────┐  ┌────────────────┐                      │
│   │  🔄 CIRCUIT    │  │  🔁 AUTO       │  │  🩺 HEALTH    │                      │
│   │   BREAKER     │  │    RETRY       │  │   MONITOR     │                      │
│   │                │  │                │  │                │                      │
│   │  • Open       │  │  • Exponential │  │  • Periodic   │                      │
│   │  • Half-Open │  │    Backoff     │  │    Checks     │                      │
│   │  • Closed    │  │  • Max Attempts│  │  • Recovery   │                      │
│   │                │  │  • Jitter     │  │    Actions    │                      │
│   └────────────────┘  └────────────────┘  └────────────────┘                      │
│                                                                                     │
│   ═══════════════════════════════════════════════════════════════════════════════   │
│                                                                                     │
│   Configuration:                                                                     │
│   ┌─────────────────────────────────────────────────────────────────────────────┐   │
│   │  circuitBreaker: { failureThreshold: 5, resetTimeoutMs: 30000 }           │   │
│   │  maxRetries: 3, backoffMultiplier: 2, maxBackoffMs: 30000                  │   │
│   │  healthCheckInterval: 10000, recoveryThreshold: 3                          │   │
│   └─────────────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────────────┘

📦 Examples

▶ Basic Usage: Create and Manage Spreadsheets

import { createClient } from '@modelcontextprotocol/sdk';

const client = await createClient({
  serverUrl: 'http://localhost:3000',
  auth: { token: process.env.MCP_TOKEN }
});

// Create a new spreadsheet
const spreadsheet = await client.tools.create_spreadsheet({
  title: 'Sales Dashboard 2024',
  sheets: [
    { title: 'Q1 Data', rowCount: 1000, columnCount: 26 },
    { title: 'Q2 Data', rowCount: 1000, columnCount: 26 },
    { title: 'Summary', rowCount: 100, columnCount: 10 }
  ]
});

console.log(`Created: ${spreadsheet.spreadsheetId}`);

// Add data to the spreadsheet
await client.tools.update_values({
  spreadsheetId: spreadsheet.spreadsheetId,
  range: 'Q1 Data!A1',
  values: [
    ['Product', 'Revenue', 'Quantity'],
    ['Widget A', 15000, 150],
    ['Widget B', 23000, 230],
    ['Widget C', 18000, 180]
  ]
});

▶ Advanced: AI-Powered Data Analysis

// Analyze spreadsheet data with AI
const analysis = await client.tools.analyze_sheet_data({
  spreadsheetId: 'abc123',
  range: 'Sales!A1:Z1000',
  includeCharts: true,
  generateInsights: true
});

console.log('Analysis Results:');
console.log(`- Total Rows: ${analysis.summary.rowCount}`);
console.log(`- Columns: ${analysis.summary.columns.join(', ')}`);
console.log(`- Insights: ${analysis.insights.length}`);

// Detect anomalies in the data
const anomalies = await client.tools.detect_outliers({
  spreadsheetId: 'abc123',
  range: 'Sales!B1:B1000',
  method: 'iqr',
  threshold: 1.5
});

console.log(`Found ${anomalies.outliers.length} outliers`);

▶ Automation: Create ETL Pipeline

// Create and run an ETL pipeline
const pipeline = await client.tools.create_pipeline({
  name: 'Daily Sales ETL',
  schedule: '0 2 * * *',  // 2 AM daily
  steps: [
    {
      id: 'extract',
      type: 'extract',
      source: {
        type: 'spreadsheet',
        spreadsheetId: 'source-id',
        range: 'Raw Data!A1:Z'
      }
    },
    {
      id: 'transform',
      type: 'transform',
      operations: [
        { type: 'filter', condition: { column: 'status', equals: 'active' } },
        { type: 'map', mappings: { old_col: 'new_col' } },
        { type: 'aggregate', groupBy: 'region', operations: ['sum', 'avg', 'count'] }
      ]
    },
    {
      id: 'load',
      type: 'load',
      destination: {
        type: 'spreadsheet',
        spreadsheetId: 'dest-id',
        sheet: 'Processed'
      }
    }
  ]
});

// Run the pipeline
const result = await client.tools.run_pipeline({
  pipelineId: pipeline.pipelineId,
  inputs: {}
});

console.log(`Processed ${result.rowsProcessed} rows in ${result.duration}ms`);

🤝 Contribution

We welcome contributions!

# 1. Fork the repository
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/GAS-MCPSERVER.git

# 3. Create a feature branch
git checkout -b feature/amazing-feature

# 4. Install dependencies
npm install

# 5. Make your changes
# 6. Run tests
npm test

# 7. Build the project
npm run build

# 8. Commit and push
git commit -m 'Add amazing feature'
git push origin feature/amazing-feature

# 9. Open a Pull Request

Development Scripts

Script	Description
`npm run build`	Compile TypeScript
`npm run start`	Start production server
`npm run dev`	Start development server
`npm test`	Run tests
`npm run test:watch`	Run tests in watch mode

📄 License

MIT License - See LICENSE file for details

Made with ❤️ by the MCP Server Team

_{📄 Last updated: March 2026 | Version 3.0.0 |
API Documentation |
GitHub}

GAS MCP Server Advanced

✨ Features

🏗️ Architecture

Request Flow

Circuit Breaker State Machine

🚀 Quick Start

Prerequisites

Installation

Environment Setup

🔧 Configuration

🛠️ Tools Reference

🤖 AI Analysis Tools (35+ tools)

Analysis Tools

Anomaly Detection

Pattern Recognition

Transformation

Natural Language Query

⚡ Automation Tools (25+ tools)

Job Scheduler

Workflows

Webhooks

📊 Data Engineering Tools (25+ tools)

ETL Tools

Import/Export

Pipeline

🧠 Context Tools (15+ tools)

Dataset Tools

Query Tools

Context Control

📝 Code Quality Tools (25+ tools)

Analysis Tools

Code Review

Documentation

Test Generation

🔐 Security

📈 Observability

💚 Self-Healing

📦 Examples

🤝 Contribution

Development Scripts

📄 License

Reviews