gogcli-mcp-docs 4.8.1 → 4.10.0

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "4.8.1",
+  "version": "4.10.0",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",
@@ -414,6 +414,10 @@
     {
       "name": "gog_docs_insert_date_chip",
       "description": "Insert a native Google Docs date smart chip."
+    },
+    {
+      "name": "gog_upload_slots",
+      "description": "Get signed upload URLs so a hosted (remote) server can receive files you hold; pass the returned blobKeys to the tool that takes the file"
     }
   ],
   "compatibility": {

package/mint.yaml

@@ -4,6 +4,10 @@ slug: gogcli-mcp-docs
 summary: >-
   Extended Google Docs MCP server via gogcli — all base tools plus full Docs
   support
+examples:
+  - prompt: "Summarize this Google Doc for me: <doc link>"
+  - prompt: "Show me the outline of headings in my project proposal doc."
+  - prompt: "List the open comments on the design spec and who left each one."
 command:
   # This package publishes a single bin; naming it keeps the install
   # unambiguous alongside its eight sibling packages.
@@ -92,7 +96,7 @@ dependencies:
   # bumping these nine pins, and the pin stored on each mcp-host registration.
   - kind: github-release
     repo: openclaw/gogcli
-    tag: v0.44.0
+    tag: v0.46.0
     asset: "gogcli_*_linux_amd64.tar.gz"
     bin: [gog]
 state:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-docs",
-  "version": "4.8.1",
+  "version": "4.10.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-docs",
   "description": "Extended Google Docs MCP server via gogcli — all base tools plus full Docs support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -24,7 +24,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^3.0.3",
+    "@chrischall/mcp-utils": "^3.6.0",
     "@modelcontextprotocol/server": "^2.3.1",
     "zod": "^4.6.1"
   },

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp-docs"
   },
-  "version": "4.8.1",
+  "version": "4.10.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp-docs",
-      "version": "4.8.1",
+      "version": "4.10.0",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { runMcp } from '@chrischall/mcp-utils';
-import { VERSION, authToolsFor, registerDocsTools, bootstrapGogAuth } from '../../gogcli-mcp/src/lib.js';
+import { VERSION, authToolsFor, registerDocsTools, registerUploadTools, bootstrapGogAuth } from '../../gogcli-mcp/src/lib.js';
 import { registerExtraDocsTools } from './tools/docs-extra.js';
 
 
@@ -10,5 +10,5 @@ await bootstrapGogAuth();
 await runMcp({
   name: 'gogcli-docs',
   version: VERSION,
-  tools: [authToolsFor('docs'), registerDocsTools, registerExtraDocsTools],
+  tools: [authToolsFor('docs'), registerDocsTools, registerExtraDocsTools, registerUploadTools],
 });

package/src/tools/docs-extra.ts

@@ -8,6 +8,11 @@ import {
   payloadArg,
   pos,
   confinePath,
+  assertOneFileSource,
+  confineUploadPath,
+  readBlobFiles,
+  releaseBlobs,
+  singleBlobKeyParam,
   bodyPreview,
   commentMentions,
   commentSnapshot,
@@ -18,6 +23,9 @@ import {
 } from '../../../gogcli-mcp/src/lib.js';
 import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 
+const URL_ALTERNATIVE = 'or pass a public HTTPS image `url`';
+const IMAGE_BLOB_NOTE = ' On a hosted deployment, where no path on your machine exists, upload the image with gog_upload_slots and pass blobKeys instead of file.';
+
 /** A Doc's title from `gog docs info`, for a comment's prompt. Unreadable output names nothing. */
 export function docTitle(raw: string): string | undefined {
   try {
@@ -1135,12 +1143,13 @@ export function registerExtraDocsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_docs_insert_image', {
-    description: 'Insert an image into a Google Doc from a local file or a public HTTPS URL. file: uploaded to Drive, temporarily shared so Docs can fetch it, inserted, then the public permission is revoked. url: inserted directly with no Drive upload or temporary sharing. Replaces placeholder text (at) or appends at end-of-doc.',
+    description: 'Insert an image into a Google Doc from a local file or a public HTTPS URL. file: uploaded to Drive, temporarily shared so Docs can fetch it, inserted, then the public permission is revoked. url: inserted directly with no Drive upload or temporary sharing. Replaces placeholder text (at) or appends at end-of-doc.' + IMAGE_BLOB_NOTE,
     annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({
       docId: z.string().describe('Doc ID (from the URL)'),
-      file: z.string().optional().describe('Local PNG, JPEG, or GIF image to upload and insert (exactly one of file or url)'),
-      url: z.string().optional().describe('Public HTTPS image URL to insert directly — no Drive upload or temporary public sharing (exactly one of file or url)'),
+      file: z.string().optional().describe('PNG, JPEG, or GIF image on the gog server to upload and insert (exactly one of file, url or blobKeys)'),
+      url: z.string().optional().describe('Public HTTPS image URL to insert directly — no Drive upload or temporary public sharing (exactly one of file, url or blobKeys)'),
+      blobKeys: singleBlobKeyParam,
       at: z.string().optional().describe('Placeholder text to replace, or "end" to append (default: end)'),
       before: z.string().optional().describe('Insert the image immediately before the first literal text match (no text is deleted)'),
       after: z.string().optional().describe('Insert the image immediately after the first literal text match (no text is deleted)'),
@@ -1152,10 +1161,13 @@ export function registerExtraDocsTools(server: McpServer): void {
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
       account: accountParam,
     }),
-  }, async ({ docId, file, url, at, before, after, width, height, name, parent, onRestricted, tab, account }) => {
-    if (file) confinePath(file, 'file');
+  }, async ({ docId, file, url, blobKeys, at, before, after, width, height, name, parent, onRestricted, tab, account }) => {
+    if (file) confineUploadPath(file, 'file', URL_ALTERNATIVE);
+    assertOneFileSource({ file, url, blobKeys });
+    const blobs = await readBlobFiles(blobKeys, 'file');
     const args: GogArg[] = ['docs', 'insert-image', pos(docId)];
     if (file) args.push(`--file=${file}`);
+    for (const blob of blobs) args.push(blob.arg);
     if (url) args.push(`--url=${url}`);
     if (at) args.push(`--at=${at}`);
     if (before) args.push(`--before=${before}`);
@@ -1166,8 +1178,8 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (parent) args.push(`--parent=${parent}`);
     if (onRestricted) args.push(`--on-restricted=${onRestricted}`);
     if (tab) args.push(`--tab=${tab}`);
-    if (file) args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse (local files upload via a temporary public share)
-    return runOrDiagnose(args, { account });
+    if (file || blobs.length > 0) args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse (local files upload via a temporary public share)
+    return releaseBlobs(await runOrDiagnose(args, { account }), blobs);
   });
 
   server.registerTool('gog_docs_insert_person', {
@@ -1517,12 +1529,13 @@ export function registerExtraDocsTools(server: McpServer): void {
   // --- gog 0.30 image replacement & table-row pin/style ---
 
   server.registerTool('gog_docs_replace_image', {
-    description: 'Replace an existing image in a Google Doc in place — keeping its position and bounds — with a new image from a local file or public HTTPS URL. Target the image by exact object ID (from gog_docs_images_list), by alt-text substring, or leave both off to replace the only image in the doc/tab.',
+    description: 'Replace an existing image in a Google Doc in place — keeping its position and bounds — with a new image from a local file or public HTTPS URL. Target the image by exact object ID (from gog_docs_images_list), by alt-text substring, or leave both off to replace the only image in the doc/tab.' + IMAGE_BLOB_NOTE,
     annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({
       docId: z.string().describe('Doc ID (from the URL)'),
-      file: z.string().optional().describe('Local PNG, JPEG, or GIF image to upload and use (exactly one of file or url)'),
-      url: z.string().optional().describe('Public HTTPS image URL to use directly — no Drive upload (exactly one of file or url)'),
+      file: z.string().optional().describe('PNG, JPEG, or GIF image on the gog server to upload and use (exactly one of file, url or blobKeys)'),
+      url: z.string().optional().describe('Public HTTPS image URL to use directly — no Drive upload (exactly one of file, url or blobKeys)'),
+      blobKeys: singleBlobKeyParam,
       objectId: z.string().optional().describe('Exact image object ID to replace (from gog_docs_images_list)'),
       matchAlt: z.string().optional().describe('Select the image whose alt text contains this value (case-insensitive)'),
       name: z.string().optional().describe('Override the uploaded Drive filename (file mode)'),
@@ -1530,18 +1543,21 @@ export function registerExtraDocsTools(server: McpServer): void {
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
       account: accountParam,
     }),
-  }, async ({ docId, file, url, objectId, matchAlt, name, parent, tab, account }) => {
-    if (file) confinePath(file, 'file');
+  }, async ({ docId, file, url, blobKeys, objectId, matchAlt, name, parent, tab, account }) => {
+    if (file) confineUploadPath(file, 'file', URL_ALTERNATIVE);
+    assertOneFileSource({ file, url, blobKeys });
+    const blobs = await readBlobFiles(blobKeys, 'file');
     const args: GogArg[] = ['docs', 'replace-image', pos(docId)];
     if (file) args.push(`--file=${file}`);
+    for (const blob of blobs) args.push(blob.arg);
     if (url) args.push(`--url=${url}`);
     if (objectId) args.push(`--object-id=${objectId}`);
     if (matchAlt) args.push(`--match-alt=${matchAlt}`);
     if (name) args.push(`--name=${name}`);
     if (parent) args.push(`--parent=${parent}`);
     if (tab) args.push(`--tab=${tab}`);
-    if (file) args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse (local files upload via a temporary public share)
-    return runOrDiagnose(args, { account });
+    if (file || blobs.length > 0) args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse (local files upload via a temporary public share)
+    return releaseBlobs(await runOrDiagnose(args, { account }), blobs);
   });
 
   server.registerTool('gog_docs_table_row_pin_header', {

package/tests/tool-annotations.test.ts

@@ -1,10 +1,10 @@
-import { authToolsFor, registerDocsTools } from '../../gogcli-mcp/src/lib.js';
+import { authToolsFor, registerDocsTools, registerUploadTools } from '../../gogcli-mcp/src/lib.js';
 import { registerExtraDocsTools } from '../src/tools/docs-extra.js';
 import { describeToolAnnotations, LOCAL_AUTH_TOOLS } from '../../gogcli-mcp/tests/support/tool-annotations.js';
 
 // The same registrar list src/index.ts hands to runMcp.
-describeToolAnnotations([authToolsFor('docs'), registerDocsTools, registerExtraDocsTools] as never, {
-  tools: 83,
+describeToolAnnotations([authToolsFor('docs'), registerDocsTools, registerExtraDocsTools, registerUploadTools] as never, {
+  tools: 84,
   destructive: 52,
-  local: [...LOCAL_AUTH_TOOLS, 'gog_batch_abort', 'gog_batch_begin', 'gog_batch_list', 'gog_batch_prune', 'gog_batch_show'],
+  local: [...LOCAL_AUTH_TOOLS, 'gog_upload_slots', 'gog_batch_abort', 'gog_batch_begin', 'gog_batch_list', 'gog_batch_prune', 'gog_batch_show'],
 });

package/tests/tools/docs-blobkeys.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createTestHarness, type TestHarness } from '@chrischall/mcp-utils/test';
+import { rawTextResult, errorResult } from '@chrischall/mcp-utils';
+import { blobStoreFromEnv, mintUploadSlot } from '@chrischall/mcp-utils/export';
+import * as lib from '../../../gogcli-mcp/src/lib.js';
+import type { GogArg, GogFileArg } from '../../../gogcli-mcp/src/lib.js';
+import { registerExtraDocsTools } from '../../src/tools/docs-extra.js';
+import { installFakeBlobStore, type FakeBlobStore } from '../../../gogcli-mcp/tests/support/fake-blob-store.js';
+
+vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof lib>();
+  return { ...actual, runOrDiagnose: vi.fn() };
+});
+
+const ORIGINAL_ENV = { ...process.env };
+let fake: FakeBlobStore;
+let harness: TestHarness;
+let root: string;
+
+beforeEach(async () => {
+  vi.clearAllMocks();
+  process.env = { ...ORIGINAL_ENV };
+  delete process.env.MCP_DATA_DIR;
+  root = mkdtempSync(join(tmpdir(), 'docs-blobkeys-'));
+  process.env.GOG_FILE_ROOTS = root;
+  fake = installFakeBlobStore();
+  vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+  harness = await createTestHarness(registerExtraDocsTools, {
+    elicitation: async () => ({ action: 'accept', content: { confirmed: true } }),
+  });
+});
+
+afterEach(() => {
+  process.env = ORIGINAL_ENV;
+  vi.unstubAllGlobals();
+});
+
+function upload(filename: string, bytes: string): string {
+  const key = mintUploadSlot(blobStoreFromEnv()!, { filename }).blobKey;
+  fake.put(key, bytes);
+  return key;
+}
+
+const lastArgs = () => vi.mocked(lib.runOrDiagnose).mock.calls.at(-1)![0] as GogArg[];
+const fileArg = (args: GogArg[]) => args.find((a): a is GogFileArg => typeof a === 'object' && a.kind === 'file');
+
+describe('docs image tools + blobKeys', () => {
+  it.each(['gog_docs_insert_image', 'gog_docs_replace_image'])('%s passes the blob as --file, with --force, and deletes it after', async (tool) => {
+    const key = upload('logo.png', 'PNGBYTES');
+    const result = await harness.callTool(tool, { docId: 'd1', blobKeys: [key] });
+    expect(result.isError).toBeFalsy();
+    const args = lastArgs();
+    expect(fileArg(args)).toMatchObject({ flag: 'file', filename: 'logo.png', encoding: 'base64' });
+    expect(fileArg(args)!.positional).toBeUndefined();
+    expect(args.at(-1)).toBe('--force');
+    expect(fake.deleted).toEqual([key]);
+  });
+
+  it('keeps the blob when gog fails', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(errorResult('Error: restricted'));
+    const key = upload('logo.png', 'PNGBYTES');
+    await harness.callTool('gog_docs_insert_image', { docId: 'd1', blobKeys: [key] });
+    expect(fake.deleted).toEqual([]);
+  });
+
+  it('wants exactly one image source', async () => {
+    const result = await harness.callTool('gog_docs_replace_image', { docId: 'd1' });
+    expect(result.content[0]!.text).toMatch(/exactly one of file, url or blobKeys/);
+  });
+
+  it('url mode needs no --force', async () => {
+    await harness.callTool('gog_docs_insert_image', { docId: 'd1', url: 'https://x.test/i.png' });
+    expect(lastArgs()).not.toContain('--force');
+  });
+
+  it('on a hosted deployment, a file path that is not on the server points at the slot tool', async () => {
+    const result = await harness.callTool('gog_docs_insert_image', { docId: 'd1', file: '/Users/someone/a.png' });
+    expect(result.content[0]!.text).toMatch(/server is remote.*gog_upload_slots/s);
+  });
+});