Nvidia NIM Nemotron Google Sheets Orchestrator: MCP & Serverless Lambda

This repository contains a production-ready, AI-driven chatbot orchestrator that can read and write data to a Google Sheet using the Nvidia NIM Nemotron-3 (120B) model. It supports two distinct architectural implementations:

1. Local Multi-Container MCP Stack: Client-server separation using FastMCP and Server-Sent Events (SSE) private networks.
2. Serverless AWS Lambda Container: Consolidated, event-driven Lambda function behind API Gateway, using AWS Secrets Manager for OAuth token storage.

---

🚀 Key Features

• Brain (LLM): Integrates the state-of-the-art nvidia/nemotron-3-super-120b-a12b model via Nvidia NIM.
• Decoupled MCP Architecture: FastMCP Google Sheets server communicating with a FastAPI agent client over Server-Sent Events (SSE).
• Serverless Refactoring: Collapse the SSE network architecture into a single-process containerized AWS Lambda handler with in-process tool calling.
• Security (Zero Secret Hardcoding): Google OAuth Client ID, Secret, and Refresh Token are fetched dynamically in-memory from AWS Secrets Manager at runtime (no token files baked into the image).
• Telegram Webhook Reply: Optimized Lambda response payload supporting the Telegram Webhook Reply protocol (method: "sendMessage") for instant response routing.
• Resilient OAuth Consent Helper: Native local helper script (refresh_oauth.py) to trigger browser consent flows on the host machine and instantly sync refreshed tokens to AWS Secrets Manager.

---

📐 Architectures

1. Local Multi-Container (MCP)

  [User] ──(Webhook)──> [FastAPI Client] ──(SSE Network Bridge)──> [FastMCP Server] ──> [Google Sheets API]
                             │
                      (Nvidia NIM API)
                             ▼
                    [Nemotron-3 LLM]

2. Serverless AWS Lambda (Production)

  [User] ──(Telegram POST)──> [API Gateway /webhook]
                                      │
                                      ▼
                             [AWS Lambda Function] (Container Image)
                                 │          │
                     (In-Process Call)    (boto3) ──> [Secrets Manager]
                                 ▼
                          [app/tools.py]
                                 │
                                 ▼
                        [Google Sheets API]

---

🛠️ Folder Structure

├── app/                  # Consolidated serverless Lambda source code
│   ├── __init__.py
│   ├── secrets.py        # Credentials resolver (LOCAL_DEV env vs Production Secrets Manager)
│   ├── tools.py          # Google Sheets API read/write tools (LangChain decorated)
│   ├── agent.py          # LangGraph ReAct agent binding tools to ChatNVIDIA
│   └── main.py           # Lambda entrypoint handler & local CLI REPL
├── client/               # Original local FastAPI Agent Client (MCP mode)
├── server/               # Original local FastMCP Google Sheets Server (MCP mode)
├── Dockerfile            # Packages the app/ module for AWS Lambda
├── template.yaml         # AWS SAM Template declaration
├── requirements.txt      # Consolidated dependencies for AWS Lambda
├── refresh_oauth.py      # Local OAuth browser consent helper & Secrets Manager syncer
└── .env                  # Local environment file (ignored by Git)

---

📦 Running Locally

Step 1: Initialize OAuth Credentials

1. Go to the Google Cloud Console.
2. Enable the Google Sheets API.
3. Setup the OAuth Consent Screen (User Type: External, Status: Testing, add your email as a Test User).
4. Create an OAuth Client ID of type Desktop app.
5. Download the secret JSON, rename it to credentials.json, and place it in ./server/credentials.json.

Step 2: Perform Initial Consent & Run Local Stack

1. Run the local consent flow:

   cd server
   pip install -r requirements.txt
   python sheets_mcp.py
   

   A browser window will open. Click 'Allow' to grant access. This generates the initial token.json file.
2. Copy .env.example to .env in the root and fill in your keys:
   • NVIDIA_API_KEY: Your Nvidia API key.
   • SPREADSHEET_ID: Your default target spreadsheet ID.
   • TELEGRAM_BOT_TOKEN: Your Telegram Bot API token.
3. Start the local multi-container stack:

   docker-compose up --build -d
   

---

☁️ Deploying to AWS Lambda (Serverless)

AWS Lambda container images require the Docker V2 Schema 2 format. Standard OCI manifests (with buildx attestations/SBOMs) will be rejected by AWS with an InvalidParameterValueException.

To compile, build ECR registries, build the container image securely, push, create IAM roles, upload credentials, and deploy your API Gateway triggers, a complete deployment helper is provided in the project history. You can perform these steps manually or use standard SAM CLI:

Manual SAM Build & Deploy

1. Save Google Credentials to Secrets Manager: Create a secret in AWS Secrets Manager named sheets-orchestrator-google-oauth containing:

   {
     "client_id": "YOUR_CLIENT_ID",
     "client_secret": "YOUR_CLIENT_SECRET",
     "refresh_token": "YOUR_REFRESH_TOKEN"
   }
   

2. Build and Deploy:

   sam build
   sam deploy --guided
   

   Provide your stack name, AWS Region, NvidiaApiKey, and the secret ARN. Once deployment is complete, SAM will output the public regional Webhook URL: https://<api-id>.execute-api.<region>.amazonaws.com/Prod/webhook

---

🔄 Refreshing OAuth Credentials (The 7-Day Limit)

If your Google Cloud Console project is in Testing publishing status, your Google refresh token will expire after 7 days.

To resolve token expiry errors without having to redeploy your code:

1. Run the local OAuth syncer from your project root:

   python refresh_oauth.py
   

2. Sign in via your web browser.
3. The script will automatically fetch the new refresh token, write it to your local .env, connect to AWS, and update the secret in AWS Secrets Manager.
4. The Lambda function will pick up the new credentials on its next execution.