gogcli-mcp-contacts 2.8.0 → 2.18.0

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-contacts",
   "display_name": "gogcli (Contacts)",
-  "version": "2.8.0",
+  "version": "2.18.0",
   "description": "Extended Google Contacts for Claude via gogcli — auth + Contacts + Workspace directory (People API)",
   "author": {
     "name": "Chris Hall",
@@ -58,6 +58,18 @@
       "name": "gog_auth_add",
       "description": "Authorize a Google account via browser-based OAuth"
     },
+    {
+      "name": "gog_auth_health",
+      "description": "Live per-account token health: validity, age, and pre-expiry warnings (detects invalid_grant)"
+    },
+    {
+      "name": "gog_auth_add_url",
+      "description": "Begin remote/headless OAuth (step 1): return a sign-in URL to open in any browser"
+    },
+    {
+      "name": "gog_auth_add_complete",
+      "description": "Complete remote/headless OAuth (step 2): exchange the pasted redirect URL and store the token"
+    },
     {
       "name": "gog_auth_list",
       "description": "List all Google accounts stored in gogcli"
@@ -128,7 +140,7 @@
     },
     {
       "name": "gog_contacts_dedupe",
-      "description": "Find likely duplicate contacts (preview only)"
+      "description": "Find duplicate contacts; optionally merge and delete redundants"
     },
     {
       "name": "gog_contacts_directory_list",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-contacts",
-  "version": "2.8.0",
+  "version": "2.18.0",
   "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>",
@@ -19,11 +19,12 @@
     "build": "tsc --noEmit && npm run bundle",
     "bundle": "node ../../scripts/bundle.js src/index.ts dist/index.js",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
+    "test": "vitest run --coverage",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
+    "@chrischall/mcp-utils": "^0.13.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3"
   },

package/src/index.ts

@@ -1,12 +1,10 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createServer, registerAuthTools, registerContactsTools } from '../../gogcli-mcp/src/lib.js';
+import { runMcp } from '@chrischall/mcp-utils';
+import { VERSION, authToolsFor, registerContactsTools } from '../../gogcli-mcp/src/lib.js';
 import { registerExtraContactsTools } from './tools/contacts-extra.js';
 
-const server = createServer({ name: 'gogcli-contacts' });
-registerAuthTools(server);
-registerContactsTools(server);
-registerExtraContactsTools(server);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
+await runMcp({
+  name: 'gogcli-contacts',
+  version: VERSION,
+  tools: [authToolsFor('contacts'), registerContactsTools, registerExtraContactsTools],
+});

package/src/tools/contacts-extra.ts

@@ -100,7 +100,7 @@ export function registerExtraContactsTools(server: McpServer): void {
       account: accountParam,
     },
   }, async ({ resourceName, account }) => {
-    return runOrDiagnose(['contacts', 'delete', resourceName], { account });
+    return runOrDiagnose(['contacts', 'delete', resourceName, '--force'], { account }); // gog gates this op; without --force the runner's --no-input makes it refuse
   });
 
   server.registerTool('gog_contacts_export', {
@@ -127,17 +127,24 @@ export function registerExtraContactsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_contacts_dedupe', {
-    description: 'Find likely duplicate personal contacts (preview only — does not modify anything).',
-    annotations: { readOnlyHint: true },
+    description: 'Find likely duplicate personal contacts. Defaults to a read-only preview of the merge plan; set apply to actually merge each duplicate group and delete the redundant contacts (etag-checked, with ambiguous or unmergeable groups refused). Scope a risky apply with resource. Always preview first.',
+    annotations: { destructiveHint: true },
     inputSchema: {
       match: z.string().optional().describe('Match fields, comma-separated from email,phone,name (default: email,phone)'),
-      max: z.number().optional().describe('Max contacts to scan (0 = all)'),
+      max: z.number().optional().describe('Max contacts to scan (0 = all). Mutually exclusive with resource — gog rejects passing both.'),
+      resource: z.array(z.string()).optional().describe('Limit dedupe to these exact contact resource names (e.g. people/c123), repeatable — useful to scope an apply to known duplicates. Mutually exclusive with max.'),
+      apply: z.boolean().optional().describe('Merge each duplicate group and DELETE the redundant contacts. Without this the tool only previews the plan. Destructive — preview first.'),
+      failEmpty: z.boolean().optional().describe('Exit with an error (code 3) when no duplicates are found, instead of succeeding empty.'),
       account: accountParam,
     },
-  }, async ({ match, max, account }) => {
+  }, async ({ match, max, resource, apply, failEmpty, account }) => {
     const args = ['contacts', 'dedupe'];
     if (match) args.push(`--match=${match}`);
     if (max !== undefined) args.push(`--max=${max}`);
+    if (resource) for (const r of resource) args.push(`--resource=${r}`);
+    if (apply) args.push('--apply');
+    if (failEmpty) args.push('--fail-empty');
+    if (apply) args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse
     return runOrDiagnose(args, { account });
   });
 

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

@@ -1,7 +1,8 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { registerExtraContactsTools } from '../../src/tools/contacts-extra.js';
 import * as lib from '../../../gogcli-mcp/src/lib.js';
-import { setupHandlers, toText, type ToolHandler } from '../../../gogcli-mcp/tests/helpers/test-harness.js';
+import { createTestHarness, type TestHarness } from '@chrischall/mcp-utils/test';
+import { rawTextResult } from '@chrischall/mcp-utils';
 
 vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   const actual = await importOriginal<typeof lib>();
@@ -11,41 +12,41 @@ vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   };
 });
 
-let handlers: Map<string, ToolHandler>;
+let harness: TestHarness;
 
-beforeEach(() => {
+beforeEach(async () => {
   vi.clearAllMocks();
-  vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
-  handlers = setupHandlers(registerExtraContactsTools);
+  vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+  harness = await createTestHarness(registerExtraContactsTools);
 });
 
 describe('gog_people_me', () => {
   it('calls runOrDiagnose with people me', async () => {
-    await handlers.get('gog_people_me')!({});
+    await harness.callTool('gog_people_me', {});
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'me'], { account: undefined });
   });
 
   it('forwards account', async () => {
-    await handlers.get('gog_people_me')!({ account: 'a@b.com' });
+    await harness.callTool('gog_people_me', { account: 'a@b.com' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'me'], { account: 'a@b.com' });
   });
 });
 
 describe('gog_people_get', () => {
   it('calls runOrDiagnose with userId', async () => {
-    await handlers.get('gog_people_get')!({ userId: 'people/c123' });
+    await harness.callTool('gog_people_get', { userId: 'people/c123' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'get', 'people/c123'], { account: undefined });
   });
 });
 
 describe('gog_people_search', () => {
   it('calls runOrDiagnose with query', async () => {
-    await handlers.get('gog_people_search')!({ query: 'alice' });
+    await harness.callTool('gog_people_search', { query: 'alice' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'search', 'alice'], { account: undefined });
   });
 
   it('passes pagination flags', async () => {
-    await handlers.get('gog_people_search')!({ query: 'alice', max: 100, page: 'tok', all: true });
+    await harness.callTool('gog_people_search', { query: 'alice', max: 100, page: 'tok', all: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
       ['people', 'search', 'alice', '--max=100', '--page=tok', '--all'],
       { account: undefined },
@@ -53,19 +54,19 @@ describe('gog_people_search', () => {
   });
 
   it('omits --all when false', async () => {
-    await handlers.get('gog_people_search')!({ query: 'x', all: false });
+    await harness.callTool('gog_people_search', { query: 'x', all: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'search', 'x'], { account: undefined });
   });
 });
 
 describe('gog_people_relations', () => {
   it('calls runOrDiagnose with no userId', async () => {
-    await handlers.get('gog_people_relations')!({});
+    await harness.callTool('gog_people_relations', {});
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'relations'], { account: undefined });
   });
 
   it('passes userId and --type when provided', async () => {
-    await handlers.get('gog_people_relations')!({ userId: 'people/c123', type: 'manager' });
+    await harness.callTool('gog_people_relations', { userId: 'people/c123', type: 'manager' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
       ['people', 'relations', 'people/c123', '--type=manager'],
       { account: undefined },
@@ -75,12 +76,12 @@ describe('gog_people_relations', () => {
 
 describe('gog_contacts_update', () => {
   it('calls runOrDiagnose with just resourceName', async () => {
-    await handlers.get('gog_contacts_update')!({ resourceName: 'people/c1' });
+    await harness.callTool('gog_contacts_update', { resourceName: 'people/c1' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'update', 'people/c1'], { account: undefined });
   });
 
   it('passes all fields including empty-string clears', async () => {
-    await handlers.get('gog_contacts_update')!({
+    await harness.callTool('gog_contacts_update', {
       resourceName: 'people/c1',
       given: 'Ada',
       family: 'Lovelace',
@@ -106,26 +107,26 @@ describe('gog_contacts_update', () => {
   });
 
   it('omits --ignore-etag when false', async () => {
-    await handlers.get('gog_contacts_update')!({ resourceName: 'people/c1', ignoreEtag: false });
+    await harness.callTool('gog_contacts_update', { resourceName: 'people/c1', ignoreEtag: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'update', 'people/c1'], { account: undefined });
   });
 });
 
 describe('gog_contacts_delete', () => {
   it('calls runOrDiagnose with resourceName', async () => {
-    await handlers.get('gog_contacts_delete')!({ resourceName: 'people/c1' });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'delete', 'people/c1'], { account: undefined });
+    await harness.callTool('gog_contacts_delete', { resourceName: 'people/c1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'delete', 'people/c1', '--force'], { account: undefined });
   });
 });
 
 describe('gog_contacts_export', () => {
   it('calls runOrDiagnose with no options', async () => {
-    await handlers.get('gog_contacts_export')!({});
+    await harness.callTool('gog_contacts_export', {});
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'export'], { account: undefined });
   });
 
   it('passes selector and all flags', async () => {
-    await handlers.get('gog_contacts_export')!({
+    await harness.callTool('gog_contacts_export', {
       selector: 'people/c1',
       query: 'ada',
       all: true,
@@ -140,34 +141,51 @@ describe('gog_contacts_export', () => {
   });
 
   it('omits --all when false', async () => {
-    await handlers.get('gog_contacts_export')!({ all: false });
+    await harness.callTool('gog_contacts_export', { all: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'export'], { account: undefined });
   });
 });
 
 describe('gog_contacts_dedupe', () => {
   it('calls runOrDiagnose with no options', async () => {
-    await handlers.get('gog_contacts_dedupe')!({});
+    await harness.callTool('gog_contacts_dedupe', {});
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'dedupe'], { account: undefined });
   });
 
   it('passes --match and --max', async () => {
-    await handlers.get('gog_contacts_dedupe')!({ match: 'name', max: 100 });
+    await harness.callTool('gog_contacts_dedupe', { match: 'name', max: 100 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
       ['contacts', 'dedupe', '--match=name', '--max=100'],
       { account: undefined },
     );
   });
+
+  it('passes --apply, repeatable --resource, and --fail-empty', async () => {
+    await harness.callTool('gog_contacts_dedupe', {
+      apply: true,
+      resource: ['people/c1', 'people/c2'],
+      failEmpty: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['contacts', 'dedupe', '--resource=people/c1', '--resource=people/c2', '--apply', '--fail-empty', '--force'],
+      { account: undefined },
+    );
+  });
+
+  it('omits --apply and --fail-empty when false', async () => {
+    await harness.callTool('gog_contacts_dedupe', { apply: false, failEmpty: false });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'dedupe'], { account: undefined });
+  });
 });
 
 describe('gog_contacts_directory_list', () => {
   it('calls runOrDiagnose with no options', async () => {
-    await handlers.get('gog_contacts_directory_list')!({});
+    await harness.callTool('gog_contacts_directory_list', {});
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'directory', 'list'], { account: undefined });
   });
 
   it('passes pagination flags', async () => {
-    await handlers.get('gog_contacts_directory_list')!({ max: 50, page: 'tok', all: true });
+    await harness.callTool('gog_contacts_directory_list', { max: 50, page: 'tok', all: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
       ['contacts', 'directory', 'list', '--max=50', '--page=tok', '--all'],
       { account: undefined },
@@ -175,19 +193,19 @@ describe('gog_contacts_directory_list', () => {
   });
 
   it('omits --all when false', async () => {
-    await handlers.get('gog_contacts_directory_list')!({ all: false });
+    await harness.callTool('gog_contacts_directory_list', { all: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'directory', 'list'], { account: undefined });
   });
 });
 
 describe('gog_contacts_other_list', () => {
   it('calls runOrDiagnose with no options', async () => {
-    await handlers.get('gog_contacts_other_list')!({});
+    await harness.callTool('gog_contacts_other_list', {});
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'other', 'list'], { account: undefined });
   });
 
   it('passes pagination flags', async () => {
-    await handlers.get('gog_contacts_other_list')!({ max: 100, page: 'tok', all: true });
+    await harness.callTool('gog_contacts_other_list', { max: 100, page: 'tok', all: true });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
       ['contacts', 'other', 'list', '--max=100', '--page=tok', '--all'],
       { account: undefined },
@@ -195,19 +213,19 @@ describe('gog_contacts_other_list', () => {
   });
 
   it('omits --all when false', async () => {
-    await handlers.get('gog_contacts_other_list')!({ all: false });
+    await harness.callTool('gog_contacts_other_list', { all: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'other', 'list'], { account: undefined });
   });
 });
 
 describe('gog_contacts_other_search', () => {
   it('calls runOrDiagnose with query', async () => {
-    await handlers.get('gog_contacts_other_search')!({ query: 'ada' });
+    await harness.callTool('gog_contacts_other_search', { query: 'ada' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['contacts', 'other', 'search', 'ada'], { account: undefined });
   });
 
   it('passes --max when provided', async () => {
-    await handlers.get('gog_contacts_other_search')!({ query: 'ada', max: 25 });
+    await harness.callTool('gog_contacts_other_search', { query: 'ada', max: 25 });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(
       ['contacts', 'other', 'search', 'ada', '--max=25'],
       { account: undefined },
@@ -217,12 +235,12 @@ describe('gog_contacts_other_search', () => {
 
 describe('gog_people_raw', () => {
   it('calls runOrDiagnose with userId', async () => {
-    await handlers.get('gog_people_raw')!({ userId: 'people/c123' });
+    await harness.callTool('gog_people_raw', { userId: 'people/c123' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'raw', 'people/c123'], { account: undefined });
   });
 
   it('passes --person-fields and --pretty when provided', async () => {
-    await handlers.get('gog_people_raw')!({
+    await harness.callTool('gog_people_raw', {
       userId: 'people/c123',
       personFields: 'names,emailAddresses',
       pretty: true,
@@ -234,7 +252,7 @@ describe('gog_people_raw', () => {
   });
 
   it('omits --pretty when false', async () => {
-    await handlers.get('gog_people_raw')!({ userId: 'people/c123', pretty: false });
+    await harness.callTool('gog_people_raw', { userId: 'people/c123', pretty: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['people', 'raw', 'people/c123'], { account: undefined });
   });
 });

package/tsconfig.json

@@ -5,5 +5,5 @@
     "rootDir": "../"
   },
   "include": ["src/**/*", "../gogcli-mcp/src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "../gogcli-mcp/src/worker.ts"]
 }