planhat-mcp: Instructions file for Codex

AGENTS.md: handbook for AI coding agents (and curious humans)

This file is the single source of agent guidance for this repo. CLAUDE.md is a symlink to it; edit this file only.

What this repo is

A small TypeScript MCP server exposing the Planhat CRM REST API (https://api.planhat.com) as 60 tools: 12 resource families x 5 verbs (list/get/create/update/delete). Built on the official @modelcontextprotocol/sdk, using Node's built-in fetch, with a bearer token read from the environment (or a local .env for manual installs).

esbuild compiles src/ into one dependency-free dist/server.js. The bundle manifest is server.type: "node", so Claude Desktop runs it with its own built-in Node runtime: users install nothing (no Python, no uv, no runtime). Node.js 18+ is required only for manual installs from a checkout.

Commands

npm install          # install dependencies
npm test             # offline test suite (node:test); all tools, fetch mocked
npm run typecheck    # tsc --noEmit, strict
npm run build        # esbuild -> dist/server.js
npm start            # run the built server over stdio

A read-only live smoke check (needs a real token in .env; GETs only, mutates nothing):

node -e '
const t = process.env.PLANHAT_TOKEN;
const paths = ["/companies","/endusers","/opportunities","/conversations","/users","/assets","/issues","/tickets","/tasks","/licenses","/invoices"];
for (const p of paths) {
  const r = await fetch("https://api.planhat.com"+p+"?limit=1", { headers: { Authorization: "Bearer "+t } });
  console.log(r.status, p);
}'

Hard rules

• Never commit .env or planhat-mcp-notes.md. Both are gitignored; they contain live credentials. If you ever see a secret in a tracked file, stop and flag it.
• Never fire create/update/delete calls against the live API in tests, smoke checks, or "just to verify". This is a production Planhat tenant. Read-only GETs with limit=1 are the ceiling for live verification.
• Tests must stay fully offline: tool tests drive handlers with a recorder Http, and the HTTP tests mock the global fetch.
• No emojis and no em dashes in public-facing copy (README, docs, manifest strings, release notes, commit messages). Rewrite with colons, semicolons, periods or parentheses instead.