@goatech/mcp

MCP (Model Context Protocol) server for GoaTech. Lets Claude / Cursor / any MCP-compatible client drive your GoaTech project — campaigns, destinations, flags, dashboards, insights queries — directly from a chat.

The same ~/.goatech/credentials.json file goatech login writes authenticates this server. One OAuth round-trip, both surfaces unlocked.

0.3.0 — what changed

Security and DX hardening from the MCP audit arc (2026-05-25 → 2026-05-26). Additive only — no removed tools, no tightened input schemas, no removed exported names. Drop-in upgrade from 0.2.0.

• structuredContent sanitize sweep. Every tool that returns structuredContent: { ... } (campaigns, destinations, dashboards, groups, event catalog) now runs untrusted string leaves through the same C0 + DEL + angle-bracket strip the content[].text channel already used. MCP-spec hosts MAY surface structuredContent direct-to-model, so both channels needed the defense.
• Unicode hardening (Trojan-Source class). STRIP_PATTERN extended to cover bidi/RTL overrides, the Tag block, lookalike brackets (＜＞⟨⟩《》‹›), default-ignorable characters (Hangul fillers, Khmer Vowel Inherent, Mongolian VS, BMP variation selectors), and U+FFFD. Combining diacriticals (U+0300–U+036F) intentionally preserved so names like "Peña" round-trip unchanged.
• recoveryHint per HTTP status. Tool error envelopes now include a one-line hint on how to recover (401 → re-run goatech login, 404 → list parents first, 409 → version-pin mismatch, etc.). Surfaced to the model so it can self-correct without bouncing the user.
• Post-install credentials banner. npx @goatech/mcp install detects a missing ~/.goatech/credentials.json and prints a single follow-up line pointing at goatech login. Unparseable files get a distinct "found but unparseable" message.
• Help-content schema drift gate. The insights_query JSON example embedded in goatech_help is now CI-asserted against the live request schema. Schema drift fails the build before it ships.
• source: "automation" discriminator on the api-key mint path when authenticated by a secret key (vs. JWT). Lets the audit trail distinguish human-initiated dashboard mints from automation-initiated mints without a separate event stream.

Quick start (3 commands)

# 1. One-time OAuth login (PKCE — opens your browser)
npx @goatech/cli login

# 2. Auto-write the MCP entry into your IDE config.
#    Dry-run first; pass --yes to apply. Backs up the existing file.
npx @goatech/mcp install
npx @goatech/mcp install --yes

# 3. Restart your IDE. In Claude / Cursor, ask:
#    "what can I do with GoaTech?"

The first thing the LLM should call is goatech_help — it returns a curated overview of every surface and how to chain tools together. For a concrete recipe, ask for goatech_quickstart with one of: send_email_campaign, create_dashboard, analyze_signups, ship_feedback, wire_webhook_destination.

The CLI / MCP key the OAuth flow mints is stamped source = "cli" | "mcp" on the GoaTech side, so you can audit which tool produced any given event.

What the LLM can do

37 tools as of 0.3.0 (live build-time count is in src/generated/build-meta.ts; this README counter is bumped per release):

• 2 Discovery tools — goatech_help (top-level "what is this?" or a per-topic deep-dive) and goatech_quickstart (concrete N-step recipe for a goal). Call goatech_help first when the user is new.
• 11 Campaign tools — campaign_list / get / create / update / preview / launch / pause / resume / complete / archive / results. Preview/launch is enforced via single-use snapshot tokens — the LLM physically cannot launch a campaign without first running campaign_preview.
• 7 Destination tools — destination_catalog / list / get / create / update / delete / test. Connectors live behind a typed catalog so the LLM can't request a destination that isn't actually wired (webhook, resend, …).
• 11 Dashboard tools — dashboard_list / get / create / update / delete / template_list / template_get / widget_create / widget_update / widget_delete / insights_query. insights_query lets the LLM run arbitrary timeseries against events_raw so it can answer "did signups dip yesterday?" without opening a UI.
• 1 Feedback tool — feedback_submit. The LLM should call this proactively when the user expresses frustration ("this is confusing") or hits an obvious gap. Auto-stamps source=mcp + version metadata so the GoaTech team's admin queue can filter MCP-origin reports.

CLI

goatech-mcp serve              # default — runs the stdio MCP server
goatech-mcp install            # dry-run: show what would change
goatech-mcp install --yes      # apply: writes the IDE config + .bak.<ts>
goatech-mcp install --force    # overwrite an existing goatech entry
goatech-mcp install --client=claude-desktop|cursor|codex
goatech-mcp version
goatech-mcp help

serve reads ~/.goatech/credentials.json; falls back to GOATECH_API_KEY / GOATECH_PROFILE env vars if the file isn't present.

install is idempotent (re-running with the same MCP entry already present is a no-op) and conservative (it backs up existing configs to <path>.bak.<unix-ts> before writing). It supports Claude Desktop, Cursor, and Codex out of the box.

Versioning

This package follows the GoaTech monorepo. Major-version bumps signal either the MCP protocol moving, or a breaking change to the API surface the tools wrap. Schemas are validated with Zod at request time so an out-of-date client gets a structured error rather than silent drift.

License

MIT. See LICENSE.