change-detection-store-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Status

Deployed and working (stack ChangeDetectionStore in eu-central-1; end-to-end verified through the Claude connector). All design decisions below are settled — do not re-litigate them without the user.

The repository is not yet a git repository (deliberately, for now).

What This Project Is

An open-source change-detection store exposed as an MCP server on AWS: it stores small JSON objects only when their content hash has changed. A client writes a value under a key in a named store; the service hashes the value and creates a new record only when the hash differs from the last stored one, producing a per-key timeline of real changes.

Approved Design Decisions

• Interface: MCP only (stateless streamable HTTP + OAuth endpoints on one Lambda Function URL). No parallel REST API. Tools: create_store, list_stores, delete_store, patch_item, patch_items, get_item, list_items, get_item_history, delete_item. Agent-friendly semantics (settled): create_store is an idempotent upsert returning { name, createdAt, created: bool }; get_item on a missing key returns { found: false } (a missing key is a normal state — only a missing STORE is an error); patch_item returns { changed, hash, date }; patch_items batches 1-50 writes with per-key results { key, changed, hash, date } | { key, error } (a bad item never fails the batch; a missing store does).
• Sidecar meta (settled): optional JSON field on patch_item/patch_items, persisted on EVERY call — including changed: false (via updateLatestMeta port method: condition on hash + liveness, no date bump, no history entry) — but NEVER hashed; replaced whole, ≤ 64 KB. Returned by get_item and snapshotted into each history entry. Purpose: often-changing info outside change detection (e.g. lastSeenAt).
• Auth: OAuth 2.0 with Cognito as the authorization server: hosted UI, app client secret in Secrets Manager, authorization via cognito:groups claim (group cds-allowed), no self-signup, manual Client ID entry in the Claude connector settings (no DCR). Implemented in app/src/interface/oauth/: RFC 9728 + RFC 8414 discovery metadata (base URL derived from the invocation host, never from env), /auth/authorize (PKCE S256 required; relay state carries the client's state + redirect_uri; redirect_uri allowlist enforced on BOTH authorize and callback — that closes the open redirect), /auth/token proxy (injects the client secret as Basic auth, pins redirect_uri), JWT gate via aws-jwt-verify (401 with WWW-Authenticate: ... resource_metadata=... vs 403 for missing group). Env: CDS_USER_POOL_ID, CDS_COGNITO_DOMAIN, CDS_CLIENT_SECRET_ID (the secret NAME — a partial ARN as SecretId FAILS IAM evaluation on GetSecretValue, verified in production; clientId+clientSecret live inside this secret), optional CDS_REQUIRED_GROUP, CDS_ALLOWED_REDIRECT_URIS; CDS_AUTH_DISABLED=true only for local dev. Known Function URL quirk: the 401 WWW-Authenticate header arrives remapped as x-amzn-Remapped-www-authenticate (fixed AWS behavior) — MCP clients rely on the /.well-known/oauth-protected-resource fallback, which we serve.
• Hashing: SHA-256 over RFC 8785 (JCS) canonical JSON via the canonicalize npm package. Object key order and number format never affect the hash; array order does — that is the client's responsibility (server never normalizes arrays).
• Data model (DynamoDB, PK + SK only, no GSI/LSI): single table.
  • Store registry: PK STORE, SK <name>
  • Latest state: PK S#<store>#LATEST, SK <key>
  • History entry: PK S#<store>#HIST#<key>, SK <ULID>, TTL always set to date + 30 days
• Deletes are soft: delete_store/delete_item set deletedAt and ttl = min(existing, now + 7 days) on all affected records; DynamoDB TTL does physical deletion (lag up to ~48 h), so every read filters out soft-deleted and expired-but-not-purged records. create_store on a soft-deleted name reactivates it; patch_item on a soft-deleted key starts a fresh life (changed: true).
• Validation (settled, security-relevant): store name ^[a-z0-9_-]{3,12}$ (lowercase only); item key ^[a-zA-Z0-9_|-]{3,32}$ (CASE-SENSITIVE — external IDs like source|ID6HfGma must not be lowercased); value ≤ 64 KB serialized. The # composite-key separator is excluded from both alphabets by design — do not widen these regexes further.
• Region: eu-central-1. Resource prefix: cds. License: MIT.
• Concurrency: patch_item uses TransactWriteItems with a condition on the previous hash PLUS a ConditionCheck that the owning store is still live (closes the patch × delete_store race; port result store-missing maps to STORE_NOT_FOUND).
• MCP layer: stateless — one McpServer + WebStandardStreamableHTTPServerTransport (enableJsonResponse: true) per request; the Lambda handler converts Function URL events to fetch Request/Response. Domain errors map to tool errors as CODE: message; unexpected errors are masked as INTERNAL_ERROR and logged without item values.
• Telemetry: domain metrics via CloudWatch EMF (EmfTelemetry, namespace ChangeDetectionStore — keep in sync with APP_METRICS_NAMESPACE in the api construct): ToolCalls/ToolErrors/InternalErrors (Tool dimension + dimensionless rollup), ChangesDetected/UnchangedCalls, AuthUnauthorized/AuthForbidden. No extra Lambdas — the app Lambda emits EMF log lines. The cds-health dashboard (monitoring construct) consumes ONLY constructs' metrics() and carries English how-to-read text per section + a holistic header; 6 alarms (incl. InternalErrors ≥ 1). Per-store granularity would be one added Store dimension; per-item analysis belongs in Logs Insights over EMF lines, NOT metric dimensions (cardinality cost).