mcp-google-contacts 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +306 -0
- package/README.ru.md +306 -0
- package/dist/client.js +561 -0
- package/dist/config.js +83 -0
- package/dist/index.js +126 -0
- package/dist/telemetry.js +120 -0
- package/dist/tools/batch.js +71 -0
- package/dist/tools/contacts.js +150 -0
- package/dist/tools/groups.js +123 -0
- package/dist/tools/other.js +62 -0
- package/dist/tools/raw.js +30 -0
- package/dist/tools/util.js +221 -0
- package/dist/types.js +48 -0
- package/package.json +60 -0
- package/test/dist-smoke.test.js +176 -0
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { DESTRUCTIVE, fail, ok } from "./util.js";
|
|
3
|
+
export function registerRawTool(server, client) {
|
|
4
|
+
server.registerTool("raw_request", {
|
|
5
|
+
title: "Raw Google People API call",
|
|
6
|
+
// Full API surface incl. updateContactPhoto and batch deletes — annotate
|
|
7
|
+
// for the worst case a call can do, not the average.
|
|
8
|
+
annotations: DESTRUCTIVE,
|
|
9
|
+
description: 'Escape hatch to call any Google People API v1 path directly, for requests the typed tools don\'t cover — e.g. contact photos (PATCH "v1/people/<id>:updateContactPhoto" with {"photoBytes":"<base64>"} or DELETE "v1/people/<id>:deleteContactPhoto"), "Other contacts" (GET "v1/otherContacts?readMask=..." — needs the contacts.other.readonly scope on the token), or extra query parameters like sources. The path may carry a query string; repeated parameters are written inline ("v1/people:batchGet?resourceNames=people/a&resourceNames=people/b&personFields=names"). The Bearer token is added automatically; the method defaults to GET. Writes are never retried after ambiguous failures.',
|
|
10
|
+
inputSchema: {
|
|
11
|
+
path: z
|
|
12
|
+
.string()
|
|
13
|
+
.min(1)
|
|
14
|
+
.describe('API path relative to https://people.googleapis.com, e.g. "v1/people/c123?personFields=names".'),
|
|
15
|
+
method: z
|
|
16
|
+
.enum(["GET", "POST", "PUT", "PATCH", "DELETE"])
|
|
17
|
+
.optional()
|
|
18
|
+
.describe("HTTP method. Defaults to GET."),
|
|
19
|
+
body: z.record(z.any()).optional().describe("JSON request body (POST/PUT/PATCH only)."),
|
|
20
|
+
},
|
|
21
|
+
}, async ({ path, method, body }) => {
|
|
22
|
+
try {
|
|
23
|
+
const m = (method ?? "GET");
|
|
24
|
+
return ok(await client.request(m, path, body));
|
|
25
|
+
}
|
|
26
|
+
catch (e) {
|
|
27
|
+
return fail(e);
|
|
28
|
+
}
|
|
29
|
+
});
|
|
30
|
+
}
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* Every field name the People API accepts in personFields/readMask. Person
|
|
4
|
+
* masks are validated against this closed set so a typo fails at the schema,
|
|
5
|
+
* not as an opaque 400 from Google.
|
|
6
|
+
*/
|
|
7
|
+
const PERSON_FIELD_NAMES = [
|
|
8
|
+
"addresses",
|
|
9
|
+
"ageRanges",
|
|
10
|
+
"biographies",
|
|
11
|
+
"birthdays",
|
|
12
|
+
"calendarUrls",
|
|
13
|
+
"clientData",
|
|
14
|
+
"coverPhotos",
|
|
15
|
+
"emailAddresses",
|
|
16
|
+
"events",
|
|
17
|
+
"externalIds",
|
|
18
|
+
"genders",
|
|
19
|
+
"imClients",
|
|
20
|
+
"interests",
|
|
21
|
+
"locales",
|
|
22
|
+
"locations",
|
|
23
|
+
"memberships",
|
|
24
|
+
"metadata",
|
|
25
|
+
"miscKeywords",
|
|
26
|
+
"names",
|
|
27
|
+
"nicknames",
|
|
28
|
+
"occupations",
|
|
29
|
+
"organizations",
|
|
30
|
+
"phoneNumbers",
|
|
31
|
+
"photos",
|
|
32
|
+
"relations",
|
|
33
|
+
"sipAddresses",
|
|
34
|
+
"skills",
|
|
35
|
+
"urls",
|
|
36
|
+
"userDefined",
|
|
37
|
+
];
|
|
38
|
+
/** The only fields that exist on "Other contacts". */
|
|
39
|
+
const OTHER_CONTACT_FIELD_NAMES = ["names", "emailAddresses", "phoneNumbers", "photos", "metadata"];
|
|
40
|
+
/** The fields copyOtherContactToMyContactsGroup can carry over. */
|
|
41
|
+
const COPY_MASK_NAMES = ["names", "emailAddresses", "phoneNumbers"];
|
|
42
|
+
/** The fields a ContactGroup exposes via groupFields. */
|
|
43
|
+
const GROUP_FIELD_NAMES = ["name", "groupType", "memberCount", "metadata", "clientData"];
|
|
44
|
+
/**
|
|
45
|
+
* Schema factories, not shared consts: reusing one zod object across two fields
|
|
46
|
+
* makes zod-to-json-schema dedupe them into a `$ref`, which some tool-schema
|
|
47
|
+
* consumers (OpenAI Apps review) don't dereference and flag as `any`. A fresh
|
|
48
|
+
* object per field keeps each one inlined with its type + pattern.
|
|
49
|
+
*/
|
|
50
|
+
export const personResourceNameSchema = () => z
|
|
51
|
+
.string()
|
|
52
|
+
.regex(/^people\/[a-zA-Z0-9_-]+$/, 'Must look like "people/<id>"')
|
|
53
|
+
.describe('The contact\'s full resource name, e.g. "people/c1234567890" — exactly as returned by list_contacts, search_contacts or create_contact.');
|
|
54
|
+
export const groupResourceNameSchema = () => z
|
|
55
|
+
.string()
|
|
56
|
+
.regex(/^contactGroups\/[a-zA-Z0-9_-]+$/, 'Must look like "contactGroups/<id>"')
|
|
57
|
+
.describe('The group\'s full resource name, e.g. "contactGroups/12abc34d567" — from list_contact_groups.');
|
|
58
|
+
export const otherContactResourceNameSchema = () => z
|
|
59
|
+
.string()
|
|
60
|
+
.regex(/^otherContacts\/[a-zA-Z0-9_-]+$/, 'Must look like "otherContacts/<id>"')
|
|
61
|
+
.describe('The Other-contact\'s full resource name, e.g. "otherContacts/c123" — from list_other_contacts.');
|
|
62
|
+
/** A person-fields mask: which Person fields the API should return. */
|
|
63
|
+
export const personFieldsSchema = () => z
|
|
64
|
+
.array(z.enum(PERSON_FIELD_NAMES))
|
|
65
|
+
.min(1)
|
|
66
|
+
.describe("Person fields to return (default names, emailAddresses, phoneNumbers, organizations, memberships). Only masked fields come back — an absent field may be unmasked, not empty.");
|
|
67
|
+
/** The restricted mask for Other-contacts reads. */
|
|
68
|
+
export const otherContactFieldsSchema = () => z
|
|
69
|
+
.array(z.enum(OTHER_CONTACT_FIELD_NAMES))
|
|
70
|
+
.min(1)
|
|
71
|
+
.describe("Fields to return (default names, emailAddresses, phoneNumbers) — Other contacts have no more.");
|
|
72
|
+
/** Which fields copy_other_contact carries into the new saved contact. */
|
|
73
|
+
export const copyMaskSchema = () => z
|
|
74
|
+
.array(z.enum(COPY_MASK_NAMES))
|
|
75
|
+
.min(1)
|
|
76
|
+
.describe("Fields to copy into the new saved contact (default all three).");
|
|
77
|
+
/** A group-fields mask for contact-group reads. */
|
|
78
|
+
export const groupFieldsSchema = () => z
|
|
79
|
+
.array(z.enum(GROUP_FIELD_NAMES))
|
|
80
|
+
.min(1)
|
|
81
|
+
.describe("Group fields to return (default metadata, groupType, memberCount, name).");
|
|
82
|
+
/**
|
|
83
|
+
* The shape of one normalized contact — shared by create_contact,
|
|
84
|
+
* update_contact and the batch tools. A factory that builds fresh schemas per
|
|
85
|
+
* call for the same `$ref`-dedup reason as above.
|
|
86
|
+
*/
|
|
87
|
+
export const contactFieldsShape = () => ({
|
|
88
|
+
given_name: z.string().optional().describe("First name."),
|
|
89
|
+
middle_name: z.string().optional().describe("Middle name."),
|
|
90
|
+
family_name: z.string().optional().describe("Last name."),
|
|
91
|
+
prefix: z.string().optional().describe('Honorific prefix, e.g. "Dr.".'),
|
|
92
|
+
suffix: z.string().optional().describe('Honorific suffix, e.g. "Jr.".'),
|
|
93
|
+
nickname: z.string().optional().describe('Nickname. On update "" clears it.'),
|
|
94
|
+
emails: z
|
|
95
|
+
.array(z.object({
|
|
96
|
+
value: z.string().min(1).describe("The email address."),
|
|
97
|
+
type: z.string().optional().describe('Label, e.g. "home", "work", "other".'),
|
|
98
|
+
}))
|
|
99
|
+
.optional()
|
|
100
|
+
.describe("Email addresses. On update this list replaces ALL existing emails; [] clears them."),
|
|
101
|
+
phones: z
|
|
102
|
+
.array(z.object({
|
|
103
|
+
value: z.string().min(1).describe("The phone number (any human-readable format)."),
|
|
104
|
+
type: z.string().optional().describe('Label, e.g. "mobile", "home", "work".'),
|
|
105
|
+
}))
|
|
106
|
+
.optional()
|
|
107
|
+
.describe("Phone numbers. On update this list replaces ALL existing phones; [] clears them."),
|
|
108
|
+
addresses: z
|
|
109
|
+
.array(z.object({
|
|
110
|
+
street: z.string().optional().describe("Street address line."),
|
|
111
|
+
city: z.string().optional(),
|
|
112
|
+
region: z.string().optional().describe("State / province / region."),
|
|
113
|
+
postal_code: z.string().optional(),
|
|
114
|
+
country: z.string().optional(),
|
|
115
|
+
type: z.string().optional().describe('Label, e.g. "home", "work".'),
|
|
116
|
+
}))
|
|
117
|
+
.optional()
|
|
118
|
+
.describe("Postal addresses. On update this list replaces ALL existing addresses; [] clears them."),
|
|
119
|
+
organization: z
|
|
120
|
+
.object({
|
|
121
|
+
name: z.string().optional().describe("Company / organization name."),
|
|
122
|
+
title: z.string().optional().describe("Job title."),
|
|
123
|
+
department: z.string().optional(),
|
|
124
|
+
})
|
|
125
|
+
.optional()
|
|
126
|
+
.describe("Employer info. On update it replaces the existing organizations; {} clears them."),
|
|
127
|
+
birthday: z
|
|
128
|
+
.string()
|
|
129
|
+
.regex(/^((\d{4}-)?\d{1,2}-\d{1,2})?$/, 'Must be "YYYY-MM-DD", "MM-DD", or "" to clear')
|
|
130
|
+
.optional()
|
|
131
|
+
.describe('Birthday: "YYYY-MM-DD", or "MM-DD" for a year-less birthday. On update "" clears it.'),
|
|
132
|
+
notes: z
|
|
133
|
+
.string()
|
|
134
|
+
.optional()
|
|
135
|
+
.describe('Free-text notes (the "Notes" field in Google Contacts). On update "" clears it.'),
|
|
136
|
+
urls: z
|
|
137
|
+
.array(z.object({
|
|
138
|
+
value: z.string().min(1).describe("The URL."),
|
|
139
|
+
type: z.string().optional().describe('Label, e.g. "homePage", "work", "blog".'),
|
|
140
|
+
}))
|
|
141
|
+
.optional()
|
|
142
|
+
.describe("Websites. On update this list replaces ALL existing urls; [] clears them."),
|
|
143
|
+
});
|
|
144
|
+
/**
|
|
145
|
+
* Maps the snake_case tool arguments to the client's normalized ContactFields.
|
|
146
|
+
* Pure key renaming — no wire knowledge (that lives in client.buildPerson) and
|
|
147
|
+
* no defaults: absent keys stay absent, and an explicit empty list survives as
|
|
148
|
+
* the "clear this group" signal.
|
|
149
|
+
*/
|
|
150
|
+
export function toContactFields(args) {
|
|
151
|
+
const a = args;
|
|
152
|
+
return {
|
|
153
|
+
givenName: a.given_name,
|
|
154
|
+
middleName: a.middle_name,
|
|
155
|
+
familyName: a.family_name,
|
|
156
|
+
prefix: a.prefix,
|
|
157
|
+
suffix: a.suffix,
|
|
158
|
+
nickname: a.nickname,
|
|
159
|
+
emails: a.emails,
|
|
160
|
+
phones: a.phones,
|
|
161
|
+
addresses: a.addresses?.map((addr) => ({
|
|
162
|
+
street: addr.street,
|
|
163
|
+
city: addr.city,
|
|
164
|
+
region: addr.region,
|
|
165
|
+
postalCode: addr.postal_code,
|
|
166
|
+
country: addr.country,
|
|
167
|
+
type: addr.type,
|
|
168
|
+
})),
|
|
169
|
+
organization: a.organization,
|
|
170
|
+
birthday: a.birthday,
|
|
171
|
+
notes: a.notes,
|
|
172
|
+
urls: a.urls,
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
/** Wraps a value as a compact-JSON tool result (compact: the consumer is an LLM). */
|
|
176
|
+
export function ok(data) {
|
|
177
|
+
const text = typeof data === "string" ? data : JSON.stringify(data);
|
|
178
|
+
return { content: [{ type: "text", text: text ?? "null" }] };
|
|
179
|
+
}
|
|
180
|
+
export function fail(err) {
|
|
181
|
+
let message = err instanceof Error ? err.message : String(err);
|
|
182
|
+
// Surface the underlying cause (e.g. the network error behind a timeout) — no
|
|
183
|
+
// secrets live in cause, and it makes failures far easier to diagnose.
|
|
184
|
+
if (err instanceof Error && err.cause instanceof Error)
|
|
185
|
+
message += ` (${err.cause.message})`;
|
|
186
|
+
return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* MCP tool annotations — hints the consuming client can use to gate or label a
|
|
190
|
+
* tool. All four hints are set explicitly on every tool: some clients (OpenAI
|
|
191
|
+
* Apps review) require readOnlyHint, destructiveHint and openWorldHint on each.
|
|
192
|
+
*
|
|
193
|
+
* The People API mixes reads and writes, so each tool picks one of four presets:
|
|
194
|
+
* READ_ONLY (pure reads), WRITE (creates new state; replaying duplicates it),
|
|
195
|
+
* UPDATE (overwrites existing fields; replaying the same update converges) and
|
|
196
|
+
* DESTRUCTIVE (removes existing state; replaying hits different targets).
|
|
197
|
+
*/
|
|
198
|
+
export const READ_ONLY = {
|
|
199
|
+
readOnlyHint: true,
|
|
200
|
+
destructiveHint: false,
|
|
201
|
+
idempotentHint: true,
|
|
202
|
+
openWorldHint: true,
|
|
203
|
+
};
|
|
204
|
+
export const WRITE = {
|
|
205
|
+
readOnlyHint: false,
|
|
206
|
+
destructiveHint: false,
|
|
207
|
+
idempotentHint: false,
|
|
208
|
+
openWorldHint: true,
|
|
209
|
+
};
|
|
210
|
+
export const UPDATE = {
|
|
211
|
+
readOnlyHint: false,
|
|
212
|
+
destructiveHint: true,
|
|
213
|
+
idempotentHint: true,
|
|
214
|
+
openWorldHint: true,
|
|
215
|
+
};
|
|
216
|
+
export const DESTRUCTIVE = {
|
|
217
|
+
readOnlyHint: false,
|
|
218
|
+
destructiveHint: true,
|
|
219
|
+
idempotentHint: false,
|
|
220
|
+
openWorldHint: true,
|
|
221
|
+
};
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The server talks to the Google People API v1 (https://people.googleapis.com,
|
|
3
|
+
* REST over JSON) — the API behind Google Contacts. Auth is Google OAuth 2.0:
|
|
4
|
+
* a Bearer access token, minted on demand from a refresh token via
|
|
5
|
+
* https://oauth2.googleapis.com/token (or a static short-lived access token,
|
|
6
|
+
* mostly for testing). Scopes are minimal: `contacts` for read/write,
|
|
7
|
+
* `contacts.readonly` for reads only, `contacts.other.readonly` additionally
|
|
8
|
+
* for the Other-contacts tools (see docs/DEVELOPMENT.md).
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Google APIs report failures as a non-2xx HTTP status with a JSON envelope
|
|
12
|
+
* ({ error: { code, message, status, details } }); the OAuth token endpoint
|
|
13
|
+
* uses { error, error_description }. The parsed body is kept alongside the
|
|
14
|
+
* status and a short readable message is derived. The message never carries
|
|
15
|
+
* credentials — only what Google itself wrote about the failure.
|
|
16
|
+
*/
|
|
17
|
+
export class GoogleContactsError extends Error {
|
|
18
|
+
status;
|
|
19
|
+
body;
|
|
20
|
+
constructor(status, body) {
|
|
21
|
+
super(`HTTP ${status}: ${formatErrorBody(body)}`);
|
|
22
|
+
this.name = "GoogleContactsError";
|
|
23
|
+
this.status = status;
|
|
24
|
+
this.body = body;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
/** Turns a parsed Google API error body into a short, readable message. */
|
|
28
|
+
function formatErrorBody(body) {
|
|
29
|
+
if (body == null)
|
|
30
|
+
return "(no body)";
|
|
31
|
+
if (typeof body === "string")
|
|
32
|
+
return body.slice(0, 500);
|
|
33
|
+
if (typeof body !== "object")
|
|
34
|
+
return String(body);
|
|
35
|
+
const obj = body;
|
|
36
|
+
// OAuth token endpoint style: { error: "invalid_grant", error_description: "..." }
|
|
37
|
+
if (typeof obj.error === "string") {
|
|
38
|
+
const description = typeof obj.error_description === "string" ? `: ${obj.error_description}` : "";
|
|
39
|
+
return `${obj.error}${description}`.slice(0, 500);
|
|
40
|
+
}
|
|
41
|
+
// Google API envelope: { error: { code, message, status, details } }
|
|
42
|
+
const err = (typeof obj.error === "object" && obj.error !== null ? obj.error : obj);
|
|
43
|
+
if (typeof err.message === "string") {
|
|
44
|
+
const status = typeof err.status === "string" ? `[${err.status}] ` : "";
|
|
45
|
+
return `${status}${err.message}`.slice(0, 500);
|
|
46
|
+
}
|
|
47
|
+
return JSON.stringify(obj).slice(0, 500);
|
|
48
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "mcp-google-contacts",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "MCP server for Google Contacts (People API) — search, read, create, update and delete contacts, manage contact groups and run batch operations. For Claude, Cursor, Codex and other AI clients.",
|
|
5
|
+
"mcpName": "io.github.A1-x-Tech/mcp-google-contacts",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"mcp-google-contacts": "dist/index.js"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist",
|
|
12
|
+
"test"
|
|
13
|
+
],
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=20"
|
|
16
|
+
},
|
|
17
|
+
"scripts": {
|
|
18
|
+
"build": "rm -rf dist && tsc",
|
|
19
|
+
"start": "node dist/index.js",
|
|
20
|
+
"dev": "tsx watch src/index.ts",
|
|
21
|
+
"typecheck": "tsc -p tsconfig.check.json",
|
|
22
|
+
"smoke": "node --import tsx src/smoke.ts",
|
|
23
|
+
"test": "npm run test:src && npm run test:dist",
|
|
24
|
+
"test:src": "node --import tsx --test $(find src -name '*.test.ts')",
|
|
25
|
+
"test:dist": "npm run build && node --test test/dist-smoke.test.js",
|
|
26
|
+
"prepare": "npm run build",
|
|
27
|
+
"prepublishOnly": "npm run typecheck && npm test"
|
|
28
|
+
},
|
|
29
|
+
"keywords": [
|
|
30
|
+
"mcp",
|
|
31
|
+
"model-context-protocol",
|
|
32
|
+
"google",
|
|
33
|
+
"google-contacts",
|
|
34
|
+
"people-api",
|
|
35
|
+
"contacts",
|
|
36
|
+
"contact-groups",
|
|
37
|
+
"claude",
|
|
38
|
+
"cursor",
|
|
39
|
+
"codex"
|
|
40
|
+
],
|
|
41
|
+
"license": "MIT",
|
|
42
|
+
"author": "gistrec <gistrec@gmail.com>",
|
|
43
|
+
"repository": {
|
|
44
|
+
"type": "git",
|
|
45
|
+
"url": "git+https://github.com/A1-x-Tech/mcp-google-contacts.git"
|
|
46
|
+
},
|
|
47
|
+
"homepage": "https://github.com/A1-x-Tech/mcp-google-contacts#readme",
|
|
48
|
+
"bugs": {
|
|
49
|
+
"url": "https://github.com/A1-x-Tech/mcp-google-contacts/issues"
|
|
50
|
+
},
|
|
51
|
+
"dependencies": {
|
|
52
|
+
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
53
|
+
"zod": "^3.25.0"
|
|
54
|
+
},
|
|
55
|
+
"devDependencies": {
|
|
56
|
+
"@types/node": "^25.9.3",
|
|
57
|
+
"tsx": "^4.22.4",
|
|
58
|
+
"typescript": "^5.7.0"
|
|
59
|
+
}
|
|
60
|
+
}
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import { fileURLToPath } from "node:url";
|
|
4
|
+
|
|
5
|
+
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
6
|
+
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
|
|
7
|
+
|
|
8
|
+
import { GoogleContactsClient } from "../dist/client.js";
|
|
9
|
+
import { registerContactTools } from "../dist/tools/contacts.js";
|
|
10
|
+
import { registerGroupTools } from "../dist/tools/groups.js";
|
|
11
|
+
import { registerBatchTools } from "../dist/tools/batch.js";
|
|
12
|
+
import { registerOtherContactTools } from "../dist/tools/other.js";
|
|
13
|
+
import { registerRawTool } from "../dist/tools/raw.js";
|
|
14
|
+
|
|
15
|
+
const ALL_TOOLS = [
|
|
16
|
+
"batch_create_contacts",
|
|
17
|
+
"batch_delete_contacts",
|
|
18
|
+
"batch_get_contacts",
|
|
19
|
+
"batch_update_contacts",
|
|
20
|
+
"copy_other_contact",
|
|
21
|
+
"create_contact",
|
|
22
|
+
"create_contact_group",
|
|
23
|
+
"delete_contact",
|
|
24
|
+
"delete_contact_group",
|
|
25
|
+
"get_contact",
|
|
26
|
+
"get_contact_group",
|
|
27
|
+
"list_contact_groups",
|
|
28
|
+
"list_contacts",
|
|
29
|
+
"list_other_contacts",
|
|
30
|
+
"modify_group_members",
|
|
31
|
+
"raw_request",
|
|
32
|
+
"search_contacts",
|
|
33
|
+
"update_contact",
|
|
34
|
+
"update_contact_group",
|
|
35
|
+
];
|
|
36
|
+
|
|
37
|
+
test("dist client rejects foreign-origin paths before sending the Bearer token", async () => {
|
|
38
|
+
const original = globalThis.fetch;
|
|
39
|
+
let called = false;
|
|
40
|
+
globalThis.fetch = async () => {
|
|
41
|
+
called = true;
|
|
42
|
+
return new Response("{}", { status: 200 });
|
|
43
|
+
};
|
|
44
|
+
try {
|
|
45
|
+
const client = new GoogleContactsClient({
|
|
46
|
+
accessToken: "SECRET",
|
|
47
|
+
apiBase: "https://people.googleapis.com",
|
|
48
|
+
timeoutMs: 1000,
|
|
49
|
+
maxRetries: 0,
|
|
50
|
+
});
|
|
51
|
+
await assert.rejects(() => client.request("GET", "https://example.invalid/steal"), /foreign origin/);
|
|
52
|
+
assert.equal(called, false);
|
|
53
|
+
} finally {
|
|
54
|
+
globalThis.fetch = original;
|
|
55
|
+
}
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
test("dist client sends the Bearer token and JSON bodies", async () => {
|
|
59
|
+
const original = globalThis.fetch;
|
|
60
|
+
let seen;
|
|
61
|
+
globalThis.fetch = async (url, init) => {
|
|
62
|
+
seen = { url: String(url), auth: init.headers.Authorization, body: JSON.parse(init.body) };
|
|
63
|
+
return new Response('{"resourceName":"people/c1"}', { status: 200 });
|
|
64
|
+
};
|
|
65
|
+
try {
|
|
66
|
+
const client = new GoogleContactsClient({
|
|
67
|
+
accessToken: "SECRET",
|
|
68
|
+
apiBase: "https://people.googleapis.com",
|
|
69
|
+
timeoutMs: 1000,
|
|
70
|
+
maxRetries: 0,
|
|
71
|
+
});
|
|
72
|
+
await client.createContact({ givenName: "Smoke" });
|
|
73
|
+
const url = new URL(seen.url);
|
|
74
|
+
assert.equal(url.origin + url.pathname, "https://people.googleapis.com/v1/people:createContact");
|
|
75
|
+
assert.equal(seen.auth, "Bearer SECRET");
|
|
76
|
+
assert.deepEqual(seen.body, { names: [{ givenName: "Smoke" }] });
|
|
77
|
+
} finally {
|
|
78
|
+
globalThis.fetch = original;
|
|
79
|
+
}
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
test("dist registers the expected tools", () => {
|
|
83
|
+
const names = [];
|
|
84
|
+
const server = {
|
|
85
|
+
registerTool(name) {
|
|
86
|
+
names.push(name);
|
|
87
|
+
},
|
|
88
|
+
};
|
|
89
|
+
const client = {};
|
|
90
|
+
|
|
91
|
+
registerContactTools(server, client);
|
|
92
|
+
registerGroupTools(server, client);
|
|
93
|
+
registerBatchTools(server, client);
|
|
94
|
+
registerOtherContactTools(server, client);
|
|
95
|
+
registerRawTool(server, client);
|
|
96
|
+
|
|
97
|
+
assert.deepEqual(names.sort(), ALL_TOOLS);
|
|
98
|
+
});
|
|
99
|
+
|
|
100
|
+
test("dist binary completes a real MCP handshake over stdio and lists every tool", async () => {
|
|
101
|
+
const transport = new StdioClientTransport({
|
|
102
|
+
command: process.execPath,
|
|
103
|
+
args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
|
|
104
|
+
env: {
|
|
105
|
+
...process.env,
|
|
106
|
+
GOOGLE_CONTACTS_ACCESS_TOKEN: "test-token",
|
|
107
|
+
ASKADS_TELEMETRY: "0", // keep the suite offline
|
|
108
|
+
},
|
|
109
|
+
stderr: "pipe",
|
|
110
|
+
});
|
|
111
|
+
const client = new Client({ name: "dist-smoke", version: "0.0.0" });
|
|
112
|
+
await client.connect(transport);
|
|
113
|
+
try {
|
|
114
|
+
const server = client.getServerVersion();
|
|
115
|
+
assert.equal(server?.name, "mcp-google-contacts");
|
|
116
|
+
assert.match(String(server?.version), /^\d+\.\d+\.\d+$/);
|
|
117
|
+
|
|
118
|
+
// The instructions the calling model reads before it picks any tool.
|
|
119
|
+
const instructions = client.getInstructions();
|
|
120
|
+
assert.equal(typeof instructions, "string");
|
|
121
|
+
assert.ok(instructions.trim().length > 0, "initialize result carries no instructions");
|
|
122
|
+
assert.match(instructions, /Google People API v1/);
|
|
123
|
+
|
|
124
|
+
const { tools } = await client.listTools();
|
|
125
|
+
assert.deepEqual(tools.map((t) => t.name).sort(), ALL_TOOLS);
|
|
126
|
+
|
|
127
|
+
const getContact = tools.find((t) => t.name === "get_contact");
|
|
128
|
+
assert.equal(getContact.annotations?.readOnlyHint, true);
|
|
129
|
+
assert.ok(getContact.inputSchema?.properties?.resource_name, "input schema must reach the client");
|
|
130
|
+
} finally {
|
|
131
|
+
await client.close();
|
|
132
|
+
}
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* The degraded-start contract: without any credentials the binary must not
|
|
137
|
+
* exit(1) before the handshake, leaving the client a dead server and no reason.
|
|
138
|
+
* It must start, list every tool, open the instructions with the fix, and
|
|
139
|
+
* answer a tool call with the actionable error — offline: the CredentialsError
|
|
140
|
+
* fires before any fetch, so this test never touches the network.
|
|
141
|
+
*/
|
|
142
|
+
test("dist binary starts without credentials: handshake, tool list, actionable call error", async () => {
|
|
143
|
+
const env = Object.fromEntries(
|
|
144
|
+
Object.entries(process.env).filter(
|
|
145
|
+
([key, value]) => value !== undefined && !key.startsWith("GOOGLE_CONTACTS_"),
|
|
146
|
+
),
|
|
147
|
+
);
|
|
148
|
+
env.ASKADS_TELEMETRY = "0"; // keep the suite offline
|
|
149
|
+
const transport = new StdioClientTransport({
|
|
150
|
+
command: process.execPath,
|
|
151
|
+
args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
|
|
152
|
+
env,
|
|
153
|
+
stderr: "pipe",
|
|
154
|
+
});
|
|
155
|
+
const client = new Client({ name: "dist-smoke-unconfigured", version: "0.0.0" });
|
|
156
|
+
await client.connect(transport);
|
|
157
|
+
try {
|
|
158
|
+
// The model must read the fix before it picks a tool.
|
|
159
|
+
const instructions = client.getInstructions() ?? "";
|
|
160
|
+
assert.match(instructions, /not connected/);
|
|
161
|
+
assert.match(instructions, /GOOGLE_CONTACTS_CLIENT_ID/);
|
|
162
|
+
assert.match(instructions, /restart/);
|
|
163
|
+
|
|
164
|
+
const { tools } = await client.listTools();
|
|
165
|
+
assert.deepEqual(tools.map((t) => t.name).sort(), ALL_TOOLS);
|
|
166
|
+
|
|
167
|
+
// A tool call fails with the exact message instead of killing the server.
|
|
168
|
+
const result = await client.callTool({ name: "get_contact", arguments: { resource_name: "people/me" } });
|
|
169
|
+
assert.equal(result.isError, true);
|
|
170
|
+
const text = result.content.map((c) => c.text ?? "").join(" ");
|
|
171
|
+
assert.match(text, /Google OAuth credentials are required: set GOOGLE_CONTACTS_CLIENT_ID/);
|
|
172
|
+
assert.match(text, /restart the server/);
|
|
173
|
+
} finally {
|
|
174
|
+
await client.close();
|
|
175
|
+
}
|
|
176
|
+
});
|