tasqr-mcp-node: Instructions file for Claude Code

CLAUDE.md

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

What this is

tasqr-mcp is a thin local MCP proxy (Node/ESM port of the Python tasqr-mcp-python sibling repo — keep behavior in sync between the two when changing protocol/crypto logic). It runs as a stdio process, authenticates with a Tasqr API key, and forwards every listTools/callTool request to the remote Tasqr Lambda MCP server over streamable HTTP (https://mcp.tasqr.ai/mcp by default). The actual task-management logic (task storage, claiming, tags, etc.) lives server-side — this repo does not implement it. The only substantial local logic is credential/auth bootstrapping and optional client-side (BYOK) encryption of task fields before they leave the process.

Commands

# Install for local dev
npm install

# Run the full test suite (node's built-in test runner, no framework dep)
npm test                       # node --test  (default discovery finds tests/*.test.js)

# Run a single test file
node --test tests/test_crypto.test.js

# Lint / format
npm run lint
npm run format

# Run against a local dev server instead of production
TASQR_MCP_URL=http://localhost:8000/mcp npx tasqr-mcp

# Check version / run the CLI directly
node bin/tasqr-mcp.js --version

Lint and format with npm run lint (ESLint, flat config in eslint.config.js) and npm run format (Prettier). CI fails on either. This is an ESM package ("type": "module"); use import/export, not require.

The Node floor is 22 — the oldest release line still supported upstream (20 reached EOL on 2026-04-30). @aws-sdk/client-kms independently requires 20+. Keep engines and the CI matrix in step with the supported LTS lines.

The AWS SDK is an optional dependency, so "not installed" is a supported state. fetchOrGenerateDek loads the KMS SDK lazily, after the org-state probe, so that refusing to encrypt for a server-managed org never depends on AWS being present or configured. Don't hoist that import to the top of the function: it would make the refusal unreachable whenever the SDK is missing. The no-optional-deps CI job pins this by deleting node_modules/@aws-sdk after npm ci and re-running the suite — deliberately not via npm ci --omit=optional, which npm 10 ignores for optional deps (the job would quietly test nothing). Tests that mock the SDK via mock.module skip in that job (canMockKms in tests/helpers.js): mock.module must resolve the specifier, so it can't stub a package that isn't on disk.