gogcli-mcp-contacts 4.5.2 → 4.6.1

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-contacts",
   "display_name": "gogcli (Contacts)",
-  "version": "4.5.2",
+  "version": "4.6.1",
   "description": "Extended Google Contacts for Claude via gogcli — auth + Contacts + Workspace directory (People API)",
   "author": {
     "name": "Chris Hall",
@@ -160,6 +160,22 @@
     {
       "name": "gog_contacts_other_search",
       "description": "Search auto-collected other contacts"
+    },
+    {
+      "name": "gog_contacts_batch_get",
+      "description": "Fetch exact Contacts in native People API batches."
+    },
+    {
+      "name": "gog_contacts_batch_create",
+      "description": "Create Contacts in native People API batches."
+    },
+    {
+      "name": "gog_contacts_batch_update",
+      "description": "Update Contacts in native People API batches with etag guards."
+    },
+    {
+      "name": "gog_contacts_batch_delete",
+      "description": "Permanently delete Contacts in native People API batches after confirmation."
     }
   ],
   "compatibility": {

package/mint.yaml

@@ -92,7 +92,7 @@ dependencies:
   # bumping these nine pins, and the pin stored on each mcp-host registration.
   - kind: github-release
     repo: openclaw/gogcli
-    tag: v0.41.0
+    tag: v0.43.0
     asset: "gogcli_*_linux_amd64.tar.gz"
     bin: [gog]
 state:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-contacts",
-  "version": "4.5.2",
+  "version": "4.6.1",
   "mcpName": "io.github.chrischall/gogcli-mcp-contacts",
   "description": "Extended Google Contacts + People MCP server via gogcli — auth + Contacts + Workspace directory (People API)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -24,7 +24,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^2.6.0",
+    "@chrischall/mcp-utils": "^2.13.0",
     "@modelcontextprotocol/server": "^2.1.0",
     "zod": "^4.6.1"
   },

package/src/tools/contacts-extra.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, pageTokenParam, pageAliasParam, resolvePageToken, pos, confinePath } from '../../../gogcli-mcp/src/lib.js';
+import { accountParam, runOrDiagnose, pageTokenParam, pageAliasParam, resolvePageToken, pos, confinePath, confirmTokenParam, requireDispatchConfirmation } from '../../../gogcli-mcp/src/lib.js';
 import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 
 // People is the richer API behind Google Contacts: Workspace directory
@@ -107,6 +107,52 @@ export function registerExtraContactsTools(server: McpServer): void {
     return runOrDiagnose(['contacts', 'delete', pos(resourceName), '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
+  server.registerTool('gog_contacts_batch_get', {
+    description: 'Fetch exact Google Contacts by People resource name in native API batches (up to 200).',
+    annotations: { readOnlyHint: true },
+    inputSchema: z.object({ resourceNames: z.array(z.string().min(1)).min(1).max(200).describe('Exact resource names such as people/c123; maximum 200'), account: accountParam }),
+  }, async ({ resourceNames, account }) => runOrDiagnose(['contacts', 'batch', 'get', ...resourceNames.map(pos)], { account }));
+
+  server.registerTool('gog_contacts_batch_create', {
+    description: 'Create Google Contacts in native People API batches (up to 200). peopleJson is a JSON array of People API Person resources. The payload is materialized in a temporary file on the gog host.',
+    // Same kind of write as gog_contacts_create, so the same annotation.
+    annotations: { readOnlyHint: false, destructiveHint: true },
+    inputSchema: z.object({ peopleJson: z.string().describe('JSON array of People API Person resources, up to 200 contacts'), account: accountParam }),
+  }, async ({ peopleJson, account }) => {
+    let people: unknown;
+    try { people = JSON.parse(peopleJson); } catch { throw new Error('peopleJson must be valid JSON'); }
+    if (!Array.isArray(people) || people.length === 0 || people.length > 200) throw new Error('peopleJson must be a non-empty array with at most 200 contacts');
+    return runOrDiagnose(['contacts', 'batch', 'create', { kind: 'file', flag: 'from-file', contents: peopleJson, ext: 'json' }], { account });
+  });
+
+  server.registerTool('gog_contacts_batch_update', {
+    description: 'Update Google Contacts in native People API batches. peopleByResourceName is a JSON object keyed by People resource name; each value must include the CONTACT source metadata and etag returned by a prior read. gog preserves those etag guards and reports partial progress.',
+    // Overwrites fields like gog_contacts_update, so the same annotation.
+    annotations: { readOnlyHint: false, destructiveHint: true },
+    inputSchema: z.object({ peopleByResourceName: z.string().describe('JSON object keyed by people/... resource name, with Person resources including CONTACT source metadata and etag'), account: accountParam }),
+  }, async ({ peopleByResourceName, account }) => {
+    let people: unknown;
+    try { people = JSON.parse(peopleByResourceName); } catch { throw new Error('peopleByResourceName must be valid JSON'); }
+    if (!people || typeof people !== 'object' || Array.isArray(people) || Object.keys(people).length === 0 || Object.keys(people).length > 200) throw new Error('peopleByResourceName must be a JSON object with between 1 and 200 contacts');
+    return runOrDiagnose(['contacts', 'batch', 'update', { kind: 'file', flag: 'from-file', contents: peopleByResourceName, ext: 'json' }], { account });
+  });
+
+  server.registerTool('gog_contacts_batch_delete', {
+    description: 'Permanently delete exact Google Contacts in native People API batches (up to 500). Requires explicit user confirmation; deleted contacts cannot be restored from Trash.',
+    annotations: { destructiveHint: true },
+    inputSchema: z.object({ resourceNames: z.array(z.string().min(1)).min(1).max(500).describe('Exact People resource names; maximum 500'), account: accountParam, confirmToken: confirmTokenParam }),
+  }, async ({ resourceNames, account, confirmToken }, ctx) => {
+    const confirmation = await requireDispatchConfirmation(ctx, {
+      action: 'contacts.batch-delete',
+      message: 'Review and confirm permanent deletion of these Google Contacts:',
+      confirmationLabel: 'Confirm permanent deletion of the listed contacts.',
+      details: { resourceNames },
+      fallback: { tool: 'gog_contacts_batch_delete', account, confirmToken, subject: () => ({ target: 'contacts', payload: { resourceNames }, preview: { resourceNames } }) },
+    });
+    if (confirmation) return confirmation;
+    return runOrDiagnose(['contacts', 'batch', 'delete', ...resourceNames.map(pos), '--force'], { account });
+  });
+
   server.registerTool('gog_contacts_export', {
     description: 'Export contacts as vCard (.vcf). Provide a selector (resource name, email, or name), or use query / all to export multiple.',
     // Writes a file on the gog host and can overwrite one: not read-only (audit SEC-4).

package/tests/tools/contacts-extra.test.ts

@@ -120,6 +120,73 @@ describe('gog_contacts_delete', () => {
   });
 });
 
+describe('native batched Contacts tools', () => {
+  it('fetches exact resource names in one command', async () => {
+    await harness.callTool('gog_contacts_batch_get', { resourceNames: ['people/a', 'people/b'] });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'batch', 'get', pos('people/a'), pos('people/b')], { account: undefined });
+  });
+
+  it('materializes a validated create array as a JSON file argument', async () => {
+    const peopleJson = '[{"names":[{"givenName":"Ada"}]}]';
+    await harness.callTool('gog_contacts_batch_create', { peopleJson });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith([
+      'contacts', 'batch', 'create', { kind: 'file', flag: 'from-file', contents: peopleJson, ext: 'json' },
+    ], { account: undefined });
+  });
+
+  it('rejects invalid create JSON before invoking gog', async () => {
+    const result = await harness.callTool('gog_contacts_batch_create', { peopleJson: '{' });
+    expect(result.isError).toBe(true);
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  it('rejects an empty or non-array create payload', async () => {
+    expect((await harness.callTool('gog_contacts_batch_create', { peopleJson: '{}' })).isError).toBe(true);
+    expect((await harness.callTool('gog_contacts_batch_create', { peopleJson: '[]' })).isError).toBe(true);
+    expect((await harness.callTool('gog_contacts_batch_create', { peopleJson: JSON.stringify(Array(201).fill({})) })).isError).toBe(true);
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  it('materializes an update map and preserves the account', async () => {
+    const peopleByResourceName = '{"people/a":{"etag":"x"}}';
+    await harness.callTool('gog_contacts_batch_update', { peopleByResourceName, account: 'a@b.com' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith([
+      'contacts', 'batch', 'update', { kind: 'file', flag: 'from-file', contents: peopleByResourceName, ext: 'json' },
+    ], { account: 'a@b.com' });
+  });
+
+  it('rejects invalid or empty update maps', async () => {
+    expect((await harness.callTool('gog_contacts_batch_update', { peopleByResourceName: '{' })).isError).toBe(true);
+    expect((await harness.callTool('gog_contacts_batch_update', { peopleByResourceName: '[]' })).isError).toBe(true);
+    expect((await harness.callTool('gog_contacts_batch_update', { peopleByResourceName: '{}' })).isError).toBe(true);
+    const tooMany = Object.fromEntries(Array.from({ length: 201 }, (_, i) => [`people/${i}`, {}]));
+    expect((await harness.callTool('gog_contacts_batch_update', { peopleByResourceName: JSON.stringify(tooMany) })).isError).toBe(true);
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  it('requires confirmation and then forces the guarded permanent delete', async () => {
+    const confirmed = await createTestHarness(registerExtraContactsTools, {
+      elicitation: async () => ({ action: 'accept', content: { confirmed: true } }),
+    });
+    await confirmed.callTool('gog_contacts_batch_delete', { resourceNames: ['people/a', 'people/b'] });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith([
+      'contacts', 'batch', 'delete', pos('people/a'), pos('people/b'), '--force',
+    ], { account: undefined });
+  });
+
+  it('allows an unprompted client to confirm the exact batch with a one-time token', async () => {
+    process.env.MCP_CONFIRM_MODE = 'ask-user';
+    const unprompted = await createTestHarness(registerExtraContactsTools);
+    const args = { resourceNames: ['people/a'] };
+    const prompt = await unprompted.callTool('gog_contacts_batch_delete', args);
+    const payload = JSON.parse(prompt.content[0].text);
+    await unprompted.callTool('gog_contacts_batch_delete', { ...args, confirmToken: payload.confirmToken });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['contacts', 'batch', 'delete', pos('people/a'), '--force'], { account: undefined });
+    delete process.env.MCP_CONFIRM_MODE;
+  });
+});
+
 describe('gog_contacts_export', () => {
   it('calls runOrDiagnose with no options', async () => {
     await harness.callTool('gog_contacts_export', {});