savannah-i-g/nanotracker-api-sdk

nanoTracker API SDK

Drive a live nanoTracker session from any AI coding agent, CLI, or script — no DevTools, no browser flags, no PWA-breaking workarounds.

---

What this is

A small, MIT-licensed harness that lets external programs read and write a live nanoTracker project running in a browser tab at .

The tracker exposes a JavaScript API (window.nanoTracker) with batched CRUD over patterns, samples, sequence layers, and song state. This SDK ships:

• a tiny local relay that bridges HTTP and the browser tab,
• an MCP server so any modern coding agent gets six tools for free,
• a CLI for shell scripts and humans,
• per-agent skill bundles mirroring the nanoTracker plugin-sdk layout,
• adapter snippets for nine MCP-aware coding tools,
• runnable end-to-end examples.

   you ──MCP / HTTP / CLI──>   relay (127.0.0.1:9311)   ──WS──>   nanoTracker tab
                                                              │
                                                              ↓
                                                window.nanoTracker

The page-side bridge that closes the loop ships with nanoTracker itself; this repo is the everything-else.

---

5-minute quickstart

You need Node 20+, a recent Chromium / Firefox / Safari, and a nanoTracker tab open at .

# 1. Clone + install
git clone https://github.com/savannah-i-g/nanotracker-api-sdk
cd nanotracker-api-sdk/tools
npm install

# 2. Start the relay
node relay.mjs
# → token written to ~/.nanotracker/relay-token, also printed to stderr

# 3. In the nanoTracker tab:
#    FILE > API…  →  Enable Local API
#                 →  Connect to local relay
#                 →  paste the token

# 4. Drive it
node ../tools/cli.mjs read getProjectSummary
node ../tools/cli.mjs execute '[{"op":"setBpm","value":140}]' '{"undoDescription":"first batch"}'

That’s the whole loop. Everything else in this repo is detail.

---

Pick your agent

Every agent below speaks MCP. Drop one snippet, get six tools.

The MCP server exposes:

nanotracker_health         nanotracker_assets_list
nanotracker_read           nanotracker_assets_load
nanotracker_execute        nanotracker_assets_unload

---

Three surfaces

The API has three orthogonal verbs. Each one is a single MCP tool / a single relay endpoint / a single CLI subcommand.

Full reference in docs/PROTOCOL.md. The machine-readable schema is always available at runtime:

node tools/cli.mjs read getSchema

---

Where to read next

New here

• docs/AGENTS-OVERVIEW.md — one page that fits in any LLM’s context window
• AGENTS.md — terse must-know rules for any agent
• CLAUDE.md — full Claude orientation

Building against the API

Operating it

Running examples

---

Working with an AI assistant

Six agent folders (mirroring plugin-sdk) ship four skills with the do-it-right-the-first-time knowledge:

• api-inspect-state — pick the cheapest read for the question
• api-author-pattern — compose batches, dry-run first, undo discipline
• api-load-sample — project-only flow, graceful fallback on noProject
• api-subscribe-stream — polling pattern with backoff

Bodies are intentionally identical across all three folders — only frontmatter differs.

---

Folder map

nanotracker-api-sdk/
├── README.md                 ← you are here
├── CLAUDE.md  AGENTS.md      LLM coding-agent orientation
├── CHANGELOG.md              API version history
├── LICENSE                   MIT
│
├── tools/                    Node ESM scripts, install once with npm
│   ├── relay.mjs             ★ the local relay
│   ├── cli.mjs               shell wrapper around the relay
│   ├── mcp-server.mjs        ★ stdio MCP server (six tools)
│   └── lib/schema.mjs        machine-readable schema mirror
│
├── docs/                     narrative documentation
│   ├── PROTOCOL.md           ★ every command + query
│   ├── ASSETS.md             ★ project-only sample I/O
│   ├── SECURITY.md           ★ token, bind, audit, rate limits
│   ├── BROWSER-COMPAT.md     ★ WS / long-poll matrix
│   ├── AGENTS-OVERVIEW.md    ★ compact one-pager
│   └── reference/
│       └── note-numbers.md   tracker / MIDI / Hz cheatsheet
│
├── adapters/                 one markdown per MCP-aware tool
│   ├── claude-code.md  cursor.md  cline.md  continue.md
│   ├── aider.md        codex.md   gemini-cli.md
│   ├── opencode.md     openclaude.md
│   └── mcp-config-snippet.json   the canonical config
│
├── examples/                 runnable end-to-end .mjs scripts
│   ├── 01-inspect-state.mjs
│   ├── 02-drum-pattern.mjs
│   ├── 03-chord-progression.mjs
│   ├── 04-load-and-conform-loop.mjs
│   ├── 05-subscribe-stream.mjs
│   └── _client.mjs           tiny shared HTTP client
│
├── .claude/   .hermes/   .agents/    AI assistant skill bundles
└── .github/
    └── copilot-instructions.md

---

Security in one paragraph

The relay binds 127.0.0.1 only — never the network interface. Every authenticated endpoint requires a 256-bit bearer token stored at ~/.nanotracker/relay-token (mode 0600). Every batch goes through the same page-side validator as UI edits — no commands bypass it. The browser tab keeps an audit log of every relay-sourced batch. The API, postMessage bridge, and relay are all off by default. Full notes in docs/SECURITY.md.

---

Prerequisites

• Node.js 20 or later (we use ESM, top-level await, crypto.randomUUID)
• npm install once inside tools/ to pull ws and the MCP SDK
• A modern browser with the nanoTracker tab open

You do not need to clone the nanoTracker app — production hosting at is the canonical endpoint for any user.

---

License

MIT — see LICENSE. Anything you build on top is yours.

---

Part of the nanoTracker family alongside plugin-sdk.