Skip to content

feat: return contact relations and omit binary vCard payloads - #4

Open
janbaer wants to merge 3 commits into
dominik1001:mainfrom
janbaer:feat/get-contact-relations
Open

janbaer wants to merge 3 commits into
dominik1001:mainfrom
janbaer:feat/get-contact-relations

Conversation

@janbaer

@janbaer janbaer commented Aug 16, 2026

Copy link
Copy Markdown

Two changes to what get-contact returns.

Binary payloads. The stored vCard was echoed verbatim. A card with 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, and the tool result exceeded my client's response limit. PHOTO, LOGO, SOUND and KEY are now reported as <57312 bytes omitted>. A photo referenced by URI is left alone.

Relations. Added a relations object keyed by role, e.g. {"Spouse": "Ada Lovelace"}. Clients store these as a pair sharing a property group (itemN.X-ABLABEL holds the role, itemN.X-ABRELATEDNAMES the 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.

claude and others added 2 commits July 7, 2026 15:28
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.
@janbaer
janbaer marked this pull request as draft August 16, 2026 15:39
`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.
@janbaer

janbaer commented Aug 16, 2026

Copy link
Copy Markdown
Author

Pushed one follow-up: 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 that 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 spelled out in the tool description that the returned vcard is normalised rather than byte-for-byte: continuation lines are unfolded and line endings rewritten, so it should not be mistaken for the stored copy.

@janbaer
janbaer marked this pull request as ready for review August 16, 2026 15:50
@dominik1001
dominik1001 changed the base branch from claude/beautiful-carson-4lqy46 to main November 17, 2026 13:13

@dominik1001 dominik1001 left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this. Returning relations and dropping inline photos are both good improvements. Requesting changes for these before merge:

  1. parseRelations crashes on some custom labels. A label such as constructor throws people.includes is not a function, and then get-contact can't read that contact at all. I reproduced this.
  2. stripBinaryValues misses common base64 forms. It doesn't catch Outlook's X-MS-CARDPICTURE;ENCODING=BASE64 or vCard 2.1's PHOTO;JPEG;BASE64:. Those cards still produce the oversized response this PR is meant to fix. I reproduced this too.
  3. 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.
  4. The release.yml change 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.

Comment thread src/tools/vcard.ts
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[]> = {};

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/tools/vcard.ts
const name = propertyName(line);
if (!split || !name || !BINARY_PROPERTIES.has(name)) return line;
const isBinary =
/;ENCODING=(B|BASE64)(;|$)/i.test(split.head) ||

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:... (bare BASE64 parameter)

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.

Comment thread src/tools/vcard.ts
const name = propertyName(line);
if (!split || !name) continue;
const value = unescapeText(split.value).trim();
if (name === "X-SPOUSE" && value) add("Spouse", value);

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/tools/vcard.ts
const value = unescapeText(split.value).trim();
if (name === "X-SPOUSE" && value) add("Spouse", value);
const group = propertyGroup(line);
if (!group || !value) continue;

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/tools/vcard.ts
/;ENCODING=(B|BASE64)(;|$)/i.test(split.head) ||
split.value.startsWith("data:");
return isBinary
? `${split.head}:<${split.value.length} bytes omitted>`

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/tools/vcard.ts
const split = splitLine(line);
const name = propertyName(line);
if (!split || !name) continue;
const value = unescapeText(split.value).trim();

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/tools/vcard.ts
}

/** Property group of a logical line, e.g. `item3` in `item3.X-ABLABEL:...`. */
function propertyGroup(line: string): string | null {

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/tools/vcard.ts
}

/**
* Relations recorded on a card, keyed by role: `{ Spouse: "Susann Baer" }`.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread src/tools/vcard.test.ts
test("pairs a label with the related name by property group", () => {
const card = [
"BEGIN:VCARD",
"FN:Jan Baer",

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants