harmonica-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 Overview

MCP (Model Context Protocol) server for Harmonica, enabling AI agents to create and query Harmonica sessions programmatically. Published to npm as harmonica-mcp.

Commands

npm run build   # Compile TypeScript → dist/
npm run dev     # Watch mode compilation
npm start       # Run the MCP server (requires HARMONICA_API_KEY env var)

Vitest test suite — npm test (src/client.test.ts, src/methodSpec.test.ts, src/index.test.ts). No linter configured.

npm test runs npm run build first, because index.test.ts drives the built dist/index.js over stdio rather than importing a factory — what we publish is the binary, so the tests send the same tools/list a real client sends. That also catches bootstrap failures (bad import specifier, transport wiring) a unit test would miss.

Publishing

Published to npm (harmonica-mcp). Users install via npx -y harmonica-mcp.

npm version patch|minor|major   # Bump version in package.json
npm publish                     # Runs prepublishOnly → build → publish

Publishing is an actor-split workflow. Before any release command, work from this repository root and verify the release target with Get-Location, git branch --show-current, git status --short --branch, npm pkg get name version, and npm view harmonica-mcp version. The agent prepares the release completely: select master, fast-forward it, run the required tests, run npm version, and push the release commit and tag. Only then hand the final npm publish command to Artem to run in an interactive terminal from this folder. An unauthenticated agent shell (npm whoami → E401) is expected and does not block preparation; do not troubleshoot npm credentials or ask Artem to run the versioning, Git, or verification steps. After Artem reports success, verify the new version directly in the npm registry before declaring the release published.