@warmio/mcp

@warmio/mcp is Warm's local stdio MCP server. Run the interactive installer to validate and store one full-access WARM_API_KEY, then configure detected supported clients:

npx -y @warmio/[email protected] install

Each client starts the server with the exact pinned package spec from @warmio/contracts/mcp (currently @warmio/[email protected]):

npx -y @warmio/[email protected] mcp

The server exposes financial-context read tools plus the automation operation catalog. The installer stores the local credential with owner-only file permissions. Importing @warmio/mcp exposes the library API without starting the CLI.

Environment precedence

Credential and config resolution is fixed and never loaded from ancestor or project .env files by default:

1. WARM_API_KEY — direct process environment value wins over every file-backed credential.
2. WARM_API_KEY_FILE — overrides the default stored-key path ($WARM_CONFIG_DIR/api_key or the platform default Warm config directory).
3. WARM_CONFIG_DIR — overrides the default Warm config directory used for the stored API key file.

API traffic always uses the canonical API_ORIGIN (https://app.warm.io). The only supported endpoint override is an explicit programmatic apiUrl option passed by trusted callers such as tests; ambient WARM_API_URL and project .env values are ignored.

Optional local development: set WARM_LOAD_PROJECT_ENV=1 before starting the CLI to load only process.cwd()/.env. Even with that opt-in, WARM_API_KEY, WARM_API_KEY_FILE, WARM_CONFIG_DIR, and WARM_API_URL are blocked and must be supplied through the process environment or installer storage instead.

Launcher integrity contract

Generated launcher configs pin an exact package version (@warmio/mcp@<version>), never @latest. The release manifest records a packageIntegrity contract whose registryIntegrity value is populated only after the trusted publish workflow (.github/workflows/publish-mcp.yml) completes npm registry readback for the pinned version. Until that gate passes, treat registryIntegrity: null as an external deployment requirement rather than a local hash to copy by hand.

Set WARM_MCP_REQUIRE_REGISTRY_INTEGRITY=1 to require an exact registry readback. When the manifest still has registryIntegrity: null, set WARM_MCP_REGISTRY_INTEGRITY to the trusted workflow's dist.integrity value. The gate rejects missing or malformed values. Default installs and launcher generation remain allowed until this opt-in gate is enabled.

Claude Desktop Extension

For Claude Desktop users, a packaged .mcpb extension is available in mcpb/. To build it:

cd mcpb
pnpm install
pnpm pack

This produces warm.mcpb which can be installed via double-click or drag-and-drop into Claude Desktop. The extension uses the same API key authentication as the CLI but provides a settings UI for key entry.

Cursor Plugin

The official Cursor plugin packaging lives in a separate public repository:

https://github.com/jasonstockman/warm-cursor-plugin

This package (@warmio/mcp) is the MCP implementation. The public plugin repo contains only:

• .cursor-plugin/plugin.json — Plugin metadata and marketplace configuration
• skills/warm/SKILL.md — Agent-facing tool documentation
• User-facing installation and usage docs

When tool schemas or behavior change here, update skills/warm/SKILL.md in the plugin repo to keep agent docs in sync.