Building a MCP Client in Google Apps Script

/**
 * A simple MCP Client for Google Apps Script.
 * Uses UrlFetchApp to communicate via JSON-RPC 2.0.
 */
class McpClient {
  constructor(url) {
    this.url = url;
    this.sessionId = null;
    this.requestId = 1;
  }

  /**
   * Initializes the session and captures the session ID.
   */
  initialize() {
    const response = this.sendRequest("initialize", {
      protocolVersion: "2024-11-05",
      capabilities: {
        roots: { listChanged: false },
        sampling: {},
      },
      clientInfo: {
        name: "AppsScriptClient",
        version: "1.0.0",
      },
    });

    this.sendNotification("notifications/initialized");
    return response;
  }

  /**
   * Lists available tools.
   */
  listTools() {
    return this.sendRequest("tools/list", {});
  }

  /**
   * Calls a specific tool.
   * @param {string} name
   * @param {Object} args
   */
  callTool(name, args) {
    return this.sendRequest("tools/call", {
      name: name,
      arguments: args || {},
    });
  }

  /**
   * Closes the session.
   */
  close() {
    if (!this.sessionId) return;

    const options = {
      method: "delete",
      headers: {
        "MCP-Session-Id": this.sessionId,
      },
      muteHttpExceptions: true,
    };

    UrlFetchApp.fetch(this.url, options);
    this.sessionId = null;
  }

  /**
   * Sends a JSON-RPC request.
   */
  sendRequest(method, params) {
    const payload = {
      jsonrpc: "2.0",
      id: String(this.requestId++),
      method: method,
    };
    if (params !== undefined) {
      payload.params = params;
    }

    const options = {
      method: "post",
      contentType: "application/json",
      headers: this._getHeaders(),
      payload: JSON.stringify(payload),
      muteHttpExceptions: true,
    };

    const response = UrlFetchApp.fetch(this.url, options);

    // Capture session ID from initialization response if not already set
    if (!this.sessionId && method === "initialize") {
      const respHeaders = response.getHeaders();
      // Headers might be case-insensitive or not, check both standard casing
      this.sessionId =
        respHeaders["MCP-Session-Id"] || respHeaders["mcp-session-id"];
    }

    const contentType = response.getHeaders()["Content-Type"] || "";

    let json;

    if (contentType.includes("text/event-stream")) {
      const content = response.getContentText();
      const lines = content.split("\n");
      for (const line of lines) {
        if (line.startsWith("data: ")) {
          try {
            const data = JSON.parse(line.substring(6));
            if (
              data.id === payload.id ||
              data.result !== undefined ||
              data.error !== undefined
            ) {
              json = data;
              break;
            }
          } catch (e) {
            // ignore parse errors for keep-alive or malformed lines
          }
        }
      }
      if (!json) {
        throw new Error("No valid JSON-RPC response in event stream");
      }
    } else {
      json = JSON.parse(response.getContentText());
    }

    if (json.error) {
      throw new Error(`MCP Error ${json.error.code}: ${json.error.message}`);
    }

    return json.result;
  }

  /**
   * Sends a JSON-RPC notification (no id, no response expected).
   */
  sendNotification(method, params) {
    const payload = {
      jsonrpc: "2.0",
      method: method,
      params: params,
    };

    const options = {
      method: "post",
      contentType: "application/json",
      headers: this._getHeaders(),
      payload: JSON.stringify(payload),
      muteHttpExceptions: true,
    };

    UrlFetchApp.fetch(this.url, options);
  }

  /**
   * Helper to construct headers.
   */
  _getHeaders() {
    const headers = {
      Accept: "application/json, text/event-stream",
      "MCP-Protocol-Version": "2024-11-05",
    };

    if (this.sessionId) {
      headers["MCP-Session-Id"] = this.sessionId;
    }
    return headers;
  }
}

/**
 * A simple MCP Client for Google Apps Script.
 * Uses UrlFetchApp to communicate via JSON-RPC 2.0.
 */
function runMcpClientDemo() {
  // Replace with your MCP server URL
  const SERVER_URL = "https://workspace-developer.goog/mcp";
  const client = new McpClient(SERVER_URL);

  // 1. Initialize
  console.log("Initializing...");
  const initResult = client.initialize();
  console.log("Capabilities:", JSON.stringify(initResult, null, 2));

  // 2. List Tools
  console.log("Listing Tools...");
  const tools = client.listTools();
  console.log("Available Tools:", JSON.stringify(tools, null, 2));

  // 3. Call Tool
  if (tools.tools && tools.tools.length > 0) {
    const toolName = tools.tools[0].name;
    const result = client.callTool(toolName, { query: "Apps Script" });
    console.log("Result:", JSON.stringify(result, null, 2));
  }

  // 4. Close Session
  console.log("Closing session...");
  client.close();
}

/**
 * Demonstrates using MCP tools with Vertex AI.
 */
function runVertexAiAgent() {
  const SERVER_URL = "https://workspace-developer.goog/mcp";
  const PROJECT_ID = "YOUR_PROJECT_ID";
  const LOCATION = "global";
  const MODEL_ID = "gemini-3-flash-preview";

  const client = new McpClient(SERVER_URL);
  client.initialize();

  // 1. Adapt MCP tools for Vertex AI
  const tools = client.listTools();
  const functionDeclarations = tools.tools.slice(0, 1).map((tool) => ({
    name: tool.name,
    description: tool.description,
    parameters: tool.inputSchema,
  }));

  // 2. Call the Model using Vertex AI Advanced Service
  const model =
    `projects/${PROJECT_ID}/locations/${LOCATION}` +
    `/publishers/google/models/${MODEL_ID}`;

  const payload = {
    contents: [
      {
        role: "user",
        parts: [
          {
            text: "How do I call Gemini from Apps Script in two sentences.",
          },
        ],
      },
    ],
    tools: [{ functionDeclarations }],
    // Model is constrained to always predicting function calls only.
    toolConfig: { functionCallingConfig: { mode: "ANY" } },
  };

  const url = `https://aiplatform.googleapis.com/v1/${model}:generateContent`;
  const options = {
    method: "post",
    contentType: "application/json",
    headers: { Authorization: `Bearer ${ScriptApp.getOAuthToken()}` },
    payload: JSON.stringify(payload),
    muteHttpExceptions: true,
  };

  const response = UrlFetchApp.fetch(url, options);
  const json = JSON.parse(response.getContentText());
  const content = json.candidates[0].content;
  const part = content.parts[0];

  // 3. Execute Tool Call
  if (part.functionCall) {
    const fn = part.functionCall;
    console.log(fn);
    const result = client.callTool(fn.name, fn.args);

    // 4. Call the Model again with the tool result
    payload.contents.push(content);
    payload.contents.push({
      role: "function",
      parts: [
        {
          functionResponse: {
            name: fn.name,
            response: { name: fn.name, content: result },
          },
        },
      ],
    });

    console.log("Payload now contains tool result");
    console.log(payload.contents);

    // Remove tools
    delete payload.tools;

    options.payload = JSON.stringify(payload);
    const response2 = UrlFetchApp.fetch(url, options);
    const answer = JSON.parse(response2.getContentText()).candidates[0].content
      .parts[0].text;
    console.log(answer);
  }

  // 5. Use it in a loop for agentic behavior
  // TODO(developer): Implement agent loop
}

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "VertexAI",
        "version": "v1",
        "serviceId": "aiplatform"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/script.external_request"
  ]
}