Core AI

Monorepo containing Helius developer tools distributed as independent packages:

• helius-mcp/ — MCP server (npm: helius-mcp) — AI-assistant agnostic
• helius-skills/ — Standalone Claude Code skill (installed via install.sh)
• helius-plugin/ — Claude Code plugin (all-in-one: bundles skill + auto-starts MCP)
• helius-cursor/ — Cursor plugin (all-in-one: bundles skill + auto-starts MCP)
• helius-cli/ — CLI for account setup (npm: helius-cli)

Compiler-managed sync

The compiler (npx tsx scripts/compile-skills.ts) is the source of truth for everything generated from helius-skills/. It writes:

1. helius-skills/<skill>/SKILL.md frontmatter version (re-injected from versions.json) and every helius-mcp@<version> mention in the body
2. .agents/skills/<skill>/ — Codex-native SKILL.md + 3 prompt variants (openai.developer.md, claude.system.md, full.md)
3. helius-mcp/system-prompts/<skill>/ — same prompt variants, npm-shipped
4. helius-plugin/skills/<dir>/references/ and helius-plugin/skills/<dir>/SKILL.md (refs bytewise from canonical; SKILL.md gets version re-injected)
5. helius-cursor/skills/<dir>/references/ and helius-cursor/skills/<dir>/SKILL.md (same)
6. helius-plugin/.mcp.json and helius-cursor/.mcp.json — generated from the helius-mcp pin in versions.json
7. helius-skills/<skill>/references/*.md and helius-skills/<skill>/install.sh — the helius-mcp@<version> token only
8. helius-skills/<skill>/references/ copies of shared references — rendered from helius-skills/shared/references/ for every skill that lists them in sharedRefs (see SKILLS in the compiler)
9. .gitattributes — the block between the compile-skills markers, marking every generated path linguist-generated so GitHub collapses it in PR diffs

Run npx tsx scripts/compile-skills.ts after any change in helius-skills/. CI runs --check mode and fails on drift.

Shared references (Sender, DAS, WebSockets, priority fees, Wallet API, onboarding, LaserStream, Enhanced Transactions) have one source in helius-skills/shared/references/. Edit them there, never in a skill's references/ copy — those copies carry a "Generated from" header and --check fails if one is hand-edited. The compiler rewrites links between references to each skill's filenames, and turns a link to a reference the skill does not include into a link to the matching docs page (SHARED_REF_DOCS). A skill that needs its own version of a reference leaves it out of sharedRefs and owns the file, as helius-phantom does for its @solana/kit Sender and priority-fee references.

Reference files are byte-identical across all destinations — never hand-edit helius-plugin/ or helius-cursor/ references; edit the shared source, or for skill-specific references the canonical copy in helius-skills/<skill>/references/.

SKILL.md bodies in helius-plugin/ and helius-cursor/ are intentionally not identical to canonical (different MCP prerequisite messaging, condensed router surface section). They are hand-managed in those packages. Only the frontmatter version and the helius-mcp@<version> token are auto-synced from versions.json.

.mcp.json in helius-plugin/ and helius-cursor/ is fully compiler-generated and byte-identical across both — never hand-edit either file. Change the pin in versions.json and re-run the compiler.

MCP Server Pin

helius-plugin/.mcp.json pins an exact helius-mcp version, never @latest. The Claude plugin marketplace pins this repo to a reviewed commit, so a floating tag would mean the server code actually executed on install sits outside that review — this is what got the plugin pulled from the official marketplace.

The pin is not only .mcp.json. The compiler re-stamps every helius-mcp@<version> mention in skill content — canonical SKILL.md bodies and references/, install.sh, the hand-managed plugin/cursor SKILL.md bodies, and all generated prompt variants — so the "add it manually" instructions a skill prints can never recommend a version the plugin does not ship. Write @latest anywhere in that surface and --check fails.

Deliberately outside the pin: repo-level docs (README.md, AGENTS.md, helius-skills/README.md, helius-skills/SYSTEM-PROMPTS.md, helius-mcp/README.md) and the server's own runtime recovery strings in helius-mcp/src/. Those describe adding helius-mcp standalone, outside any pinned plugin, where tracking latest is the intended behavior. Only helius-cli keeps a floating tag inside skill content.

To advance the pin, in this order:

1. Publish helius-mcp@X.Y.Z to npm (bump helius-mcp/package.json → merge → tag helius-mcp@X.Y.Z → merge the changelog PR → publish the draft release).
2. Then update the helius-mcp key in versions.json, re-run the compiler, and merge.

Never pin a version that is not yet on npm — main would ship a config that breaks every install. sync-check blocks on an unpublished pin and warns (without failing) while the pin lags helius-mcp/package.json, which is the expected state during the publish→pin window.

The DFlow connector is deliberately not in the default config: an official marketplace listing requires third-party connectors to be in the Anthropic MCP connector directory. Do not re-add it to .mcp.json unless that listing lands.

Skill Versioning

Skill versions are managed via versions.json at the repo root (single source of truth). To bump a version, edit versions.json and re-run the compiler. Versions follow semver.

pnpm Version Pin

helius-mcp and helius-cli pin pnpm with "packageManager": "pnpm@9.15.9", matching CI's pnpm/action-setup version: 9. Without a pin, Dependabot runs the newest pnpm it has (12 as of October 2026), which ignores the pnpm.overrides field in package.json and regenerates the lockfile without them, failing CI's frozen install. With the pin, Corepack and newer pnpm versions both switch to 9.15.9. Bump the pin and CI's version together.

Router Surface Maintenance

The Helius MCP public surface is a coordinated contract: 11 public tools total, shared action routing, and summary-first responses with expandResult.

If you change the router surface, routed tool descriptions, action-routing guidance, or summary-first response behavior, update all of these in the same pass:

• AGENTS.md
• README.md
• helius-mcp/README.md
• helius-plugin/README.md
• helius-cursor/README.md
• canonical helius-skills/*/SKILL.md
• manual plugin/cursor SKILL.md copies
• generated .agents/skills/ output
• generated helius-mcp/system-prompts/ output

Do not leave router/runtime changes documented in only one layer.

Tool titles and annotations

Every public tool carries a title and explicit readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The Anthropic and OpenAI directories both require them. Titles live in helius-mcp/src/router/annotations.ts; the hints are derived from the action catalog, so they follow each action's labels:

• mutability: 'write' on any action makes its tool non-read-only. Label every action that changes state, including local config.
• Writes are destructive unless marked nonDestructiveWrite (purely additive, like recommendStack saving preferences).
• A write that is handle-eligible must be non-destructive and list the params that carry its side effect in replayOmitParams, so expandResult never replays it. pnpm validate enforces this, which is what keeps expandResult read-only.

tests/tool-annotations.test.ts snapshots every tool's hints; update it deliberately.

Read-only surface

createServer({ surface }) in helius-mcp/src/server.ts builds either the full surface or a readOnly one; stdio picks it with --read-only or HELIUS_MCP_READ_ONLY=1. The read-only surface is what goes to the Anthropic, OpenAI, and xAI directories, whose policies rule out executing crypto transfers. Everything about it is derived from the catalog in helius-mcp/src/router/surface.ts, so labelling an action correctly is all it takes to keep it off:

• Reads are on it. Writes are not, except a non-destructive write whose side effect sits entirely in replayOmitParams (recommendStack): those params are removed from its schema and stripped at dispatch, so it runs as a read.
• A routed tool left with no actions (heliusWrite) is not registered. Each action enum lists only the surface's actions, and a schema field is removed when only off-surface actions read it.
• Dispatch and expandResult refuse anything off the surface as a second line of defense.
• A routed tool whose description names removed capabilities has a readOnly description in router/register.ts, and router/instructions.ts has read-only instructions. Keep both in step with the full versions.
• Handler output must not send the model to an action the surface removed. Dispatch runs every handler inside runOnSurface, so a message that would say "call setHeliusApiKey", "signup", or "upgradePlan" checks isReadOnlySurface() and uses READ_ONLY_GUIDANCE (both in utils/runtime.ts) instead. Output that lists actions by name filters them with isAvailableOnCurrentSurface.

tests/read-only-surface.test.ts pins the surface, and tests/read-only-guidance.test.ts fails if any account or setup message on it names a removed action. Add a case there when you add a message that names one.