GAS MCP Server Advanced
README.md
<!--
╔═══════════════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ████████╗██████╗ █████╗ ███╗ ██╗███████╗██╗ ██╗███████╗██████╗ ║
║ ╚══██╔══╝██╔══██╗██╔══██╗████╗ ██║██╔════╝██║ ██║██╔════╝██╔══██╗ ║
║ ██║ ██████╔╝███████║██╔██╗ ██║███████╗███████║█████╗ ██████╔╝ ║
║ ██║ ██╔══██╗██╔══██║██║╚██╗██║╚════██║██╔══██║██╔══╝ ██╔══██╗ ║
║ ██║ ██║ ██║██║ ██║██║ ╚████║███████║██║ ██║███████╗██║ ██║ ║
║ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═══╝╚══════╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ║
║ ║
║ ██████╗ ███████╗███████╗██╗ ██╗███╗ ██╗███████╗ ║
║ ██╔══██╗██╔════╝██╔════╝██║ ██║████╗ ██║██╔════╝ ║
║ ██║ ██║█████╗ █████╗ ██║ ██║██╔██╗ ██║█████╗ ║
║ ██║ ██║██╔══╝ ██╔══╝ ██║ ██║██║╚██╗██║██╔══╝ ║
║ ██████╔╝███████╗███████╗███████╗██║██║ ╚████║███████╗ ║
║ ╚═════╝ ╚══════╝╚══════╝╚══════╝╚═╝╚═╝ ╚═══╝╚══════╝ ║
║ ║
║ ██████╗ ██████╗ ███╗ ██╗████████╗██████╗ ██████╗ ║
║ ██╔══██╗██╔══██╗████╗ ██║╚══██╔══╝██╔══██╗██╔═══██╗ ║
║ ██████╔╝██████╔╝██╔██╗ ██║ ██║ ██████╔╝██║ ██║ ║
║ ██╔═══╝ ██╔══██╗██║╚██╗██║ ██║ ██╔══██╗██║ ██║ ║
║ ██║ ██║ ██║██║ ╚████║ ██║ ██║ ██║╚██████╔╝ ║
║ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ║
║ ║
║ MODEL CONTEXT PROTOCOL SERVER ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════════════╝
-->
<p align="center">
<img src="https://img.shields.io/badge/version-3.0.0-blueviolet?style=for-the-badge&logo=version" alt="Version">
<img src="https://img.shields.io/badge/Node.js-18%2B-green?style=for-the-badge&logo=node.js" alt="Node.js">
<img src="https://img.shields.io/badge/TypeScript-5.3-blue?style=for-the-badge&logo=typescript" alt="TypeScript">
<img src="https://img.shields.io/badge/License-MIT-orange?style=for-the-badge" alt="License">
<img src="https://img.shields.io/badge/MCP-Server-purple?style=for-the-badge&logo=server" alt="MCP Server">
</p>
<p align="center">
<img src="https://img.shields.io/badge/100%2B-Tools-61DAFB?style=flat-square&logo=wrench" alt="Tools">
<img src="https://img.shields.io/badge/Enterprise--Grade_Security-cyan?style=flat-square&logo=shield" alt="Security">
<img src="https://img.shields.io/badge/Self--Healing_Circuit_Breaker-lime?style=flat-square&logo=heartbeat" alt="Self-Healing">
<img src="https://img.shields.io/badge/Observability_Complete-pink?style=flat-square&logo=eye" alt="Observability">
</p>
---
<p align="center">
<strong>
<span style="background: linear-gradient(90deg, #ff6b6b, #feca57, #48dbfb, #ff9ff3, #54a0ff, #5f27cd); -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text; animation: rainbow 3s ease-in-out infinite; font-size: 1.5em;">
🚀 Enterprise-Grade MCP Server for Google Sheets & Apps Script 🚀
</span>
</strong>
</p>
<p align="center">
<em>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.</em>
</p>
<div align="center">
```mermaid
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
```
</div>
---
<div align="center">
| ⭐ Star us on GitHub | 📖 Read the Docs | 💬 Join Discord | 🐛 Report Issues |
|:---:|:---:|:---:|:---:|
| [](https://github.com/devfinprojects/GAS-MCPSERVER/stargazers) | [](docs/API.md) | [](https://discord.gg/mcp) | [](https://github.com/devfinprojects/GAS-MCPSERVER/issues) |
</div>
---
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
<!-- 📋 TABLE OF CONTENTS -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
<details>
<summary><strong>📋 Table of Contents</strong> <em>(Click to expand)</em></summary>
- [✨ Features](#-features)
- [🏗️ Architecture](#-architecture)
- [🚀 Quick Start](#-quick-start)
- [🔧 Configuration](#-configuration)
- [🛠️ Tools Reference](#-tools-reference)
- [🤖 AI Analysis Tools](#-ai-analysis-tools)
- [⚡ Automation Tools](#-automation-tools)
- [📊 Data Engineering Tools](#-data-engineering-tools)
- [🧠 Context Tools](#-context-tools)
- [📝 Code Quality Tools](#-code-quality-tools)
- [🔐 Security](#-security)
- [📈 Observability](#-observability)
- [💚 Self-Healing](#-self-healing)
- [� Exemplos](#-exemplos)
- [🤝 Contribution](#-contribution)
- [📄 License](#-license)
</details>
---
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
<!-- ✨ FEATURES -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## ✨ Features
<p align="center">
<em>Powerful capabilities that set us apart</em>
</p>
<table style="width:100%; border-collapse: separate; border-spacing: 0 10px;">
<tr>
<td style="background: linear-gradient(135deg, rgba(168,85,247,0.15) 0%, rgba(88,166,255,0.15) 100%); border: 2px solid; border-image: linear-gradient(135deg, #a855f7, #58a6ff) 1; border-radius: 12px; padding: 20px; text-align: center;">
<div style="font-size: 2.5em;">🧠</div>
**Context Intelligence**
Token estimation • Compression • Semantic search • Dataset management
<span style="background: linear-gradient(90deg, #a855f7, #58a6ff); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">100K+ tokens supported</span>
</td>
<td style="background: linear-gradient(135deg, rgba(245,158,11,0.15) 0%, rgba(239,68,68,0.15) 100%); border: 2px solid; border-image: linear-gradient(135deg, #f59e0b, #ef4444) 1; border-radius: 12px; padding: 20px; text-align: center;">
<div style="font-size: 2.5em;">🛠️</div>
**100+ MCP Tools**
Spreadsheet ops • AI analysis • Automation workflows • Data pipelines
<span style="background: linear-gradient(90deg, #f59e0b, #ef4444); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">Comprehensive coverage</span>
</td>
<td style="background: linear-gradient(135deg, rgba(34,197,94,0.15) 0%, rgba(132,204,22,0.15) 100%); border: 2px solid; border-image: linear-gradient(135deg, #22c55e, #84cc16) 1; border-radius: 12px; padding: 20px; text-align: center;">
<div style="font-size: 2.5em;">💚</div>
**Self-Healing**
Circuit breaker • Auto-retry • Error recovery • Health checks
<span style="background: linear-gradient(90deg, #22c55e, #84cc16); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">99.9% uptime</span>
</td>
</tr>
<tr>
<td style="background: linear-gradient(135deg, rgba(59,130,246,0.15) 0%, rgba(147,51,234,0.15) 100%); border: 2px solid; border-image: linear-gradient(135deg, #3b82f6, #9333ea) 1; border-radius: 12px; padding: 20px; text-align: center;">
<div style="font-size: 2.5em;">⚡</div>
**Adaptive Rate Limiting**
Per-agent limits • Per-API quotas • Sliding windows • Backoff strategy
<span style="background: linear-gradient(90deg, #3b82f6, #9333ea); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">Smart throttling</span>
</td>
<td style="background: linear-gradient(135deg, rgba(236,72,153,0.15) 0%, rgba(99,102,241,0.15) 100%); border: 2px solid; border-image: linear-gradient(135deg, #ec4899, #6366f1) 1; border-radius: 12px; padding: 20px; text-align: center;">
<div style="font-size: 2.5em;">🔐</div>
**Enterprise Security**
RBAC • AES-256 encryption • OAuth2 • Audit logging • SOC2 ready
<span style="background: linear-gradient(90deg, #ec4899, #6366f1); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">Bank-grade protection</span>
</td>
<td style="background: linear-gradient(135deg, rgba(20,184,166,0.15) 0%, rgba(6,182,212,0.15) 100%); border: 2px solid; border-image: linear-gradient(135deg, #14b8a6, #06b6d4) 1; border-radius: 12px; padding: 20px; text-align: center;">
<div style="font-size: 2.5em;">📊</div>
**Complete Observability**
Metrics • Tracing • Health checks • Alerting • Audit logs
<span style="background: linear-gradient(90deg, #14b8a6, #06b6d4); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">Full visibility</span>
</td>
</tr>
</table>
---
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
<!-- 🏗️ ARCHITECTURE -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 🏗️ Architecture
<p align="center">
<em>Enterprise-grade system architecture</em>
</p>
```
╔═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ 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 -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 🚀 Quick Start
### Prerequisites
<p>
<img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=flat&logo=node.js" alt="Node.js">
<img src="https://img.shields.io/badge/npm-9%2B-CB3837?style=flat&logo=npm" alt="npm">
<img src="img.shields.io/badge/Google_Cloud-4285F4?style=flat&logo=google" alt="Google Cloud">
</p>
### Installation
```bash
# 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
```bash
# Copy example environment file
cp env.example .env
# Edit configuration
#nano .env # Linux/Mac
#notepad .env # Windows
```
---
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
<!-- 🔧 CONFIGURATION -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 🔧 Configuration
<p align="center">
<em>Configure your MCP server</em>
</p>
| 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 -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 🛠️ Tools Reference
<p align="center">
<em>100+ MCP tools across 5 categories</em>
</p>
```
╔══════════════════════════════════════════════════════════════════════════════════════════════════════════╗
║ 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 -->
### 🤖 AI Analysis Tools <span style="background: linear-gradient(90deg, #f59e0b, #ef4444); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">(35+ tools)</span>
<p align="center">
<em>Powerful AI-driven analysis capabilities</em>
</p>
| 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 |
<details>
<summary><strong>📋 View AI Tool Reference</strong></summary>
#### 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" } }` |
</details>
---
<!-- ⚡ Automation Tools -->
### ⚡ Automation Tools <span style="background: linear-gradient(90deg, #a855f7, #6366f1); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">(25+ tools)</span>
<p align="center">
<em>Workflow automation and scheduling</em>
</p>
| 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 |
<details>
<summary><strong>📋 View Automation Tool Reference</strong></summary>
#### 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 }` |
</details>
---
<!-- 📊 Data Engineering Tools -->
### 📊 Data Engineering Tools <span style="background: linear-gradient(90deg, #3b82f6, #06b6d4); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">(25+ tools)</span>
<p align="center">
<em>ETL pipelines and data operations</em>
</p>
| 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 |
<details>
<summary><strong>📋 View Data Engineering Tool Reference</strong></summary>
#### 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 }` |
</details>
---
<!-- 🧠 Context Tools -->
### 🧠 Context Tools <span style="background: linear-gradient(90deg, #22c55e, #84cc16); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">(15+ tools)</span>
<p align="center">
<em>LLM context optimization and management</em>
</p>
| 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 |
<details>
<summary><strong>📋 View Context Tool Reference</strong></summary>
#### 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 }` |
</details>
---
<!-- 📝 Code Quality Tools -->
### 📝 Code Quality Tools <span style="background: linear-gradient(90deg, #ec4899, #f43f5e); -webkit-background-clip: text; -webkit-text-fill-color: transparent;">(25+ tools)</span>
<p align="center">
<em>Apps Script code analysis and improvement</em>
</p>
| 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 |
<details>
<summary><strong>📋 View Code Quality Tool Reference</strong></summary>
#### 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 }` |
</details>
---
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
<!-- 🔐 SECURITY -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 🔐 Security
<p align="center">
<em>Enterprise-grade security features</em>
</p>
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ 🔐 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 -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 📈 Observability
<p align="center">
<em>Complete visibility into your system</em>
</p>
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ 📈 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 -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 💚 Self-Healing
<p align="center">
<em>Automatic error recovery for 99.9% uptime</em>
</p>
```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ 💚 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 -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 📦 Examples
<details>
<summary><strong>▶ Basic Usage: Create and Manage Spreadsheets</strong></summary>
```typescript
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]
]
});
```
</details>
<details>
<summary><strong>▶ Advanced: AI-Powered Data Analysis</strong></summary>
```typescript
// 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`);
```
</details>
<details>
<summary><strong>▶ Automation: Create ETL Pipeline</strong></summary>
```typescript
// 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`);
```
</details>
---
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
<!-- 🤝 CONTRIBUTION -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 🤝 Contribution
<p align="center">
<em>We welcome contributions!</em>
</p>
```bash
# 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 -->
<!-- ════════════════════════════════════════════════════════════════════════════════════ -->
## 📄 License
<p align="center">
<img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License">
</p>
<p align="center">
<em>MIT License - See <a href="LICENSE">LICENSE</a> file for details</em>
</p>
---
<p align="center">
<strong>
Made with ❤️ by the MCP Server Team
</strong>
</p>
<p align="center">
<a href="https://github.com/devfinprojects/GAS-MCPSERVER">
<img src="https://img.shields.io/github/stars/devfinprojects/GAS-MCPSERVER?style=social" alt="Stars">
</a>
<a href="https://github.com/devfinprojects/GAS-MCPSERVER/fork">
<img src="https://img.shields.io/github/forks/devfinprojects/GAS-MCPSERVER?style=social" alt="Forks">
</a>
<a href="https://github.com/devfinprojects/GAS-MCPSERVER/issues">
<img src="https://img.shields.io/github/issues/devfinprojects/GAS-MCPSERVER" alt="Issues">
</a>
</p>
---
<p align="center">
<sub>
📄 Last updated: March 2026 | Version 3.0.0 |
<a href="docs/API.md">API Documentation</a> |
<a href="https://github.com/devfinprojects/GAS-MCPSERVER">GitHub</a>
</sub>
</p>TDQS
B3.3/5.0
Scored across 26 tools
Disambiguation4/5
Most tools have distinct purposes, but some overlap exists. For example, 'update_values' and 'batch_update_values' could be confused, as batch updates are a subset of updates. Similarly, 'get_values' and 'get_values_formatted' are closely related, though the formatted version adds formatting details. Overall, descriptions help clarify differences, but minor ambiguities remain.
Naming Consistency5/5
Tool names follow a highly consistent verb_noun pattern throughout, such as 'add_data_validation', 'append_values', and 'create_spreadsheet'. There are no deviations in style or convention, making the naming predictable and easy to understand across all 26 tools.
Tool Count3/5
With 26 tools, the count is borderline high for a single server, potentially making it heavy for agents to navigate. However, given the advanced scope covering Google Sheets and Apps Script operations, it's reasonable but may feel overwhelming compared to more focused servers.
Completeness5/5
The tool set provides comprehensive coverage for Google Sheets and Apps Script management, including CRUD operations for spreadsheets, sheets, and data, as well as advanced features like scripting, formatting, and authentication. No obvious gaps are present, supporting full lifecycle workflows in this domain.
Maintenance
ActivityInactive
ResponsivenessNo issues