delx-mcp-kit

Shared primitives for Delx local-first MCP servers.

Not another wearable connector — the contract layer the fleet already dogfoods (whoop-mcp, google-health-mcp). Node >=20, ESM only.

npm i delx-mcp-kit

import {
  resolvePrivacyMode,
  stripGpsDeep,
  TokenStore,
  userActionRequired,
  buildAgentSafeSeries,
  clampMaxPoints,
} from "delx-mcp-kit";

const mode = resolvePrivacyMode(
  { privacyMode: "structured" },
  params.privacy_mode,
  { explicit_user_intent: params.explicit_user_intent, include_gps: params.include_gps },
);

Public API

| Export | Role | |---|---| | resolvePrivacyMode | Agent raw / include_gps requires explicit_user_intent | | stripGpsDeep / deepRedact / isGpsKey | Recursive GPS/PII key stripping | | TokenStore | Local tokens: dir 0700, file 0600, exclusive lock | | readOnlyAnnotation / readOnlyOpenWorldAnnotation / mutationAnnotation | Scorecard-ready MCP annotations | | ERROR_CODES / userActionRequired / authRequired / isUserActionRequired | Stable agent error strings | | AgentSafeSeries / buildAgentSafeSeries / clampMaxPoints | Frozen agent-safe-series/v1 envelope + hard cap 500 |

Re-exports live on the package root (import { … } from "delx-mcp-kit"). There is no subpath export.

Privacy annotations

• Default tools: readOnlyAnnotation() (openWorldHint: false).
• Tools that hit a live upstream: readOnlyOpenWorldAnnotation().
• Writes: mutationAnnotation({ destructive }).
• privacy_mode=raw and include_gps=true throw USER_ACTION_REQUIRED unless explicit_user_intent=true. A config-default raw (env) is allowed without per-call intent.

Series caps (agent-safe-series/v1)

Connectors still downsample. This kit only freezes the envelope:

1. Stats stay on full-resolution samples (connector-owned).
2. Server hard cap is 500 points (SERIES_HARD_MAX_POINTS); default budget 400.
3. Honest loss metadata: downsampled, method, source_points, returned_points.
4. GPS/latlng never enters a series tool — buildAgentSafeSeries rejects those metric names.
5. buildAgentSafeSeries stamps contract_version and t_unit: "seconds_from_start". Do not invent a second contract string.

Canonical field rules: delx-wellness agent-safe-series.md. Local note: docs/0.2-story.md.

const series = buildAgentSafeSeries({
  activity_id,
  metric: "heart_rate",
  unit: "bpm",
  resolution_seconds: 60,
  requested_resolution_seconds: 60,
  points, // already shaped + capped by the connector
  stats,
  downsampled: points.length < source_points,
  source_points,
  method: points.length < source_points ? "time_bucket_mean" : "none",
  data_quality,
  notes: [],
});

Use clampMaxPoints(params.max_points) on the input budget before shaping. If points.length is still over 500, the builder throws INVALID_INPUT instead of silently truncating.

Versioning

Two version lines:

| Line | What | Bump when | |---|---|---| | Package semver (0.2.0) | JS API of this kit | new export, behavior change, bugfix | | agent-safe-series/v1 | Frozen envelope string | never for optional fields; new required field / rename / meaning change → v2 and package major |

Package bumps (0.x, keep it boring):

• Additive export or optional envelope field agents may ignore → minor (0.1.1 → 0.2.0)
• Breaking JS API, tighter hard cap, or required-field change → major
• Bugfix that keeps the envelope identical → patch

Keep the previous contract major readable for ≥1 minor after a bump. Do not silently reinterpret v1 fields.

How to bump

1. Edit version in package.json (and the lockfile if npm rewrites it).
2. Add a CHANGELOG.md section. Mention agent-safe-series/v1 when the envelope changes.
3. Prove with npm test on this machine. GitHub Actions in .github/workflows is a leftover template, not a merge gate (no paid Actions minutes).
4. Maintainer publishes from a trusted machine: npm publish (prepublishOnly re-runs tests). This repo does not publish from CI.

Do not bump the contract string from a connector. Propose additive fields via the hub ADR / garmin-mcp#19 first.

Develop

npm ci
npm test          # typecheck + build + kit + series fixtures
npm run typecheck

See AGENTS.md, CONTRIBUTING.md, SECURITY.md.

MIT · part of the Delx wellness MCP surface. Yardstick: mcp-scorecard.