Repository navigation
Conversation
Trusted publishing can only be configured on a package that already exists on the registry, so the initial release authenticates with an NPM_TOKEN secret. Once carddav-mcp exists on npm and a trusted publisher is configured for this workflow, the secret and this env line can go. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WJjmg9LMuvaNqbTAXQahgU
get-contact echoed the stored vCard verbatim. A card holding an inline
portrait carries PHOTO;ENCODING=b with tens of thousands of base64
characters; on one real card that was 57 KB of a 60 KB result. For an MCP
client this is context spent on bytes no model can use, and it can push a
single tool result past the response limit. Embedded binary values (PHOTO,
LOGO, SOUND, KEY) are now reported as a size marker instead. A photo
referenced by URI is untouched.
Relations are surfaced as a `relations` object keyed by role, e.g.
{"Spouse": "Ada Lovelace"}. Clients record them as a pair sharing a property
group - itemN.X-ABLABEL carries the role, itemN.X-ABRELATEDNAMES the person,
with the role wrapped in Apple's _$!<...>!$_ form - which every caller would
otherwise have to reassemble from raw vCard text.
`relations` mapped a role to a single name, so a card recording two children under the same label kept only the last one and dropped the other without any signal. Children, siblings and friends are exactly the roles that repeat, so this is the ordinary case rather than a contrived one. Each role now carries a list, and a person reached twice — as X-SPOUSE and an item pair usually do — is recorded once. Also spells out in the tool description that the returned vCard is normalised rather than byte-for-byte, so nobody mistakes it for the stored copy.
|
Pushed one follow-up: Also spelled out in the tool description that the returned |
dominik1001
left a comment
There was a problem hiding this comment.
Thanks for this. Returning relations and dropping inline photos are both good improvements. Requesting changes for these before merge:
parseRelationscrashes on some custom labels. A label such asconstructorthrowspeople.includes is not a function, and thenget-contactcan't read that contact at all. I reproduced this.stripBinaryValuesmisses common base64 forms. It doesn't catch Outlook'sX-MS-CARDPICTURE;ENCODING=BASE64or vCard 2.1'sPHOTO;JPEG;BASE64:. Those cards still produce the oversized response this PR is meant to fix. I reproduced this too.- The test fixtures and JSDoc look like real names and family relationships. This repo is public and published to npm, so please swap them for fictional ones.
- The
release.ymlchange is unrelated to this feature. Please move it to its own PR. Its comment also refers to an npm upgrade step that doesn't exist.
The inline comments cover these and a few smaller points: relation formats that aren't parsed, the size shown in the omitted-data marker, and some repeated parsing work.
| export function parseRelations(data: string): Record<string, string[]> { | ||
| const labels = new Map<string, string>(); | ||
| const names = new Map<string, string>(); | ||
| const relations: Record<string, string[]> = {}; |
There was a problem hiding this comment.
Bug: relations is a plain object, so a role named constructor, toString or __proto__ returns the inherited Object.prototype member. add then calls .includes on it.
Repro: item1.X-ABLABEL:constructor + item1.X-ABRELATEDNAMES:Bob throws people.includes is not a function, and get-contact fails for that contact. Custom labels are free text, so any user can hit this.
Suggested fix: const relations: Record<string, string[]> = Object.create(null);, or a Map converted with Object.fromEntries at the end, or Object.hasOwn(relations, role) in add.
| const name = propertyName(line); | ||
| if (!split || !name || !BINARY_PROPERTIES.has(name)) return line; | ||
| const isBinary = | ||
| /;ENCODING=(B|BASE64)(;|$)/i.test(split.head) || |
There was a problem hiding this comment.
Size problem remains for some clients: this only strips properties on the PHOTO/LOGO/SOUND/KEY allowlist, and only when they carry ENCODING=B|BASE64. These pass through unchanged (I checked):
- Outlook:
X-MS-CARDPICTURE;TYPE=JPEG;ENCODING=BASE64:<tens of KB> - vCard 2.1:
PHOTO;JPEG;BASE64:...(bareBASE64parameter)
A more robust check would look at the encoding on any property, not at a list of names: ENCODING=b|BASE64, a bare BASE64 parameter, or a data: value.
| const name = propertyName(line); | ||
| if (!split || !name) continue; | ||
| const value = unescapeText(split.value).trim(); | ||
| if (name === "X-SPOUSE" && value) add("Spouse", value); |
There was a problem hiding this comment.
Only Apple's X-ABLABEL/X-ABRELATEDNAMES pairs and X-SPOUSE are recognised. Contacts from other clients return no relations at all:
- RFC 6350
RELATED;TYPE=spouse:...(Nextcloud Contacts and others) X-EVOLUTION-SPOUSE(Evolution)X-KADDRESSBOOK-X-SpousesName(KAddressBook)
That's risky because the agent will conclude the contact has no spouse on record. At minimum RELATED;TYPE=... should be handled, since it's the standard property.
| const value = unescapeText(split.value).trim(); | ||
| if (name === "X-SPOUSE" && value) add("Spouse", value); | ||
| const group = propertyGroup(line); | ||
| if (!group || !value) continue; |
There was a problem hiding this comment.
An X-ABRELATEDNAMES line with no group (X-ABRELATEDNAMES;TYPE=pref:Bob), or with a group that has no matching X-ABLABEL, is silently dropped, because the pairing loop below only iterates labels. A fallback role such as Related would keep the name.
| /;ENCODING=(B|BASE64)(;|$)/i.test(split.head) || | ||
| split.value.startsWith("data:"); | ||
| return isBinary | ||
| ? `${split.head}:<${split.value.length} bytes omitted>` |
There was a problem hiding this comment.
Nit: split.value.length counts base64 characters (or the full data: URI), not bytes, so the marker overstates the payload by about 33%. Either compute the decoded size (Math.floor(len * 3 / 4) minus padding) or label it base64 chars. The unit test currently locks in the wrong figure.
| const split = splitLine(line); | ||
| const name = propertyName(line); | ||
| if (!split || !name) continue; | ||
| const value = unescapeText(split.value).trim(); |
There was a problem hiding this comment.
Perf: unescapeText runs on every line before the property name is checked, including the large PHOTO line, which gets rebuilt one character at a time and then thrown away. Checking name first and unescaping only X-SPOUSE, X-ABLABEL and X-ABRELATEDNAMES avoids that.
Related: each card is now unfolded three times (parseVCard, parseRelations, stripBinaryValues) and each line split several times. Parsing once and sharing the result would be cleaner.
| } | ||
|
|
||
| /** Property group of a logical line, e.g. `item3` in `item3.X-ABLABEL:...`. */ | ||
| function propertyGroup(line: string): string | null { |
There was a problem hiding this comment.
propertyGroup repeats propertyName's parsing (splitLine, split on ;, split on .). A single parseProperty(line) → { group, name, head, value } helper would replace both and keep future fixes (quoted parameters, dotted parameter values) in one place.
| } | ||
|
|
||
| /** | ||
| * Relations recorded on a card, keyed by role: `{ Spouse: "Susann Baer" }`. |
There was a problem hiding this comment.
The JSDoc shows the return shape as a string ({ Spouse: "..." }), but the function returns Record<string, string[]>. The PR description has the same mismatch. Also, as with the test fixture, please use a fictional name in this example.
Separately, get-contact.test.ts wasn't updated, so the tool-level relations output and the binary stripping have no integration test.
| test("pairs a label with the related name by property group", () => { | ||
| const card = [ | ||
| "BEGIN:VCARD", | ||
| "FN:Jan Baer", |
There was a problem hiding this comment.
These fixtures look like real names and family relationships, while the rest of the suite uses fictional people (Ada Lovelace). This repo is public and the package is published to npm, so could you replace them with fictional names?
| # NPM_TOKEN authenticates the first publish, before the package exists | ||
| # on the registry. Once it does, configure npm trusted publishing for | ||
| # this workflow, remove the secret, and drop the NPM_TOKEN line (OIDC | ||
| # needs npm >= 11.5.1, hence the npm upgrade step above semantic-release |
There was a problem hiding this comment.
This release-workflow change (adding NPM_TOKEN) isn't related to the vCard feature. Could you move it to its own PR so it gets its own review?
Also, this comment refers to "the npm upgrade step above semantic-release", but this job has no such step. Anyone who later follows the comment to switch to OIDC trusted publishing will find it fails on the bundled npm, which is older than 11.5.1.
Two changes to what
get-contactreturns.Binary payloads. The stored vCard was echoed verbatim. A card with an inline portrait carries
PHOTO;ENCODING=bwith tens of thousands of base64 characters; on one real card that was 57 KB of a 60 KB result, and the tool result exceeded my client's response limit.PHOTO,LOGO,SOUNDandKEYare now reported as<57312 bytes omitted>. A photo referenced by URI is left alone.Relations. Added a
relationsobject keyed by role, e.g.{"Spouse": "Ada Lovelace"}. Clients store these as a pair sharing a property group (itemN.X-ABLABELholds the role,itemN.X-ABRELATEDNAMESthe person, the role wrapped in Apple's_$!<...>!$_form), which every caller would otherwise reassemble from raw vCard text.Four unit tests added, README tool docs regenerated.