27.0.0-beta.12 • Published 16h agoCLI

axiom-mcp

Licence

MIT

Version

27.0.0-beta.12

Deps

Size

39.2 MB

Vulns

Weekly

1.1K

Summary Dependency Versions

Axiom MCP Server

Model Context Protocol (MCP) server for Axiom's Apple-platform development skills, agents, commands, and bundled CLI tools. Enables cross-platform access to Axiom's battle-tested guidance in any MCP-compatible AI coding tool.

Features

Skills — Apple-platform (iOS, iPadOS, macOS, watchOS, tvOS) development expertise as MCP Resources (on-demand loading)
Commands — Structured prompts as MCP Prompts
Agents — Autonomous auditors, retrievable as MCP Tools
Profiling tools — the bundled xcprof CLI exposed as MCP Tools (macOS + Xcode)
Dual Distribution — Works standalone or bundled with Claude Code plugin
Hybrid Runtime — Development mode (live files) or production mode (bundled)

Installation

Quick Start (npm)

No clone or build step needed. Add to your tool's MCP configuration:

{
  "mcpServers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "axiom-mcp"]
    }
  }
}

This downloads and runs the server in production mode with all skills bundled.

For Claude Code Users (Bundled)

The MCP server starts automatically when you install the Axiom plugin:

claude-code plugin add axiom@axiom-marketplace

No additional configuration needed — the plugin's .mcp.json launches the server in development mode.

Usage

VS Code + GitHub Copilot

Add to your VS Code settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "axiom-mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "axiom-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your workspace:

{
  "mcpServers": {
    "axiom": {
      "command": "npx",
      "args": ["-y", "axiom-mcp"]
    }
  }
}

Gemini CLI

Configure MCP server in ~/.gemini/config.toml:

[[mcp_servers]]
name = "axiom"
command = "npx"
args = ["-y", "axiom-mcp"]

Configuration

Environment Variables

Variable	Values	Default	Description
`AXIOM_MCP_MODE`	`development`, `production`	`production`	Runtime mode
`AXIOM_DEV_PATH`	File path	—	Plugin directory for dev mode
`AXIOM_LOG_LEVEL`	`debug`, `info`, `warn`, `error`	`info`	Logging verbosity
`AXIOM_XCPROF_PATH`	File path	bundled binary	Override the `xcprof` binary the profiling tools invoke
`AXIOM_XCPROF_TIMEOUT`	Seconds	`300`	Per-invocation ceiling for `xcprof` calls (raise for long recordings)

Modes

Development Mode (Live Skills)

AXIOM_MCP_MODE=development AXIOM_DEV_PATH=/path/to/plugin node dist/index.js

Reads skills directly from Claude Code plugin directory
Changes to skills reflected immediately (no rebuild needed)
Ideal for skill development and testing
Used by Claude Code plugin's .mcp.json

Production Mode (Bundled Skills)

# Default mode — no environment variables needed
npx axiom-mcp

Reads pre-bundled snapshot from dist/bundle.json
Bundle contains the full Axiom skill, command, and agent set
No file system access after initialization
Self-contained, distributed via npm

MCP Resources

Skills are exposed as MCP Resources with URI scheme:

axiom://skill/{skill-name}

Examples:

axiom://skill/xcode-debugging
axiom://skill/swiftui-nav
axiom://skill/memory-debugging
axiom://skill/liquid-glass-ref

Resource Discovery

// resources/list response
{
  "resources": [
    {
      "uri": "axiom://skill/xcode-debugging",
      "name": "Xcode Debugging",
      "description": "Environment-first diagnostics for BUILD FAILED, test crashes, simulator hangs",
      "mimeType": "text/markdown"
    }
  ]
}

Resource Reading

// resources/read request
{
  "method": "resources/read",
  "params": {
    "uri": "axiom://skill/xcode-debugging"
  }
}

// Response includes full skill content as markdown
{
  "contents": [{
    "uri": "axiom://skill/xcode-debugging",
    "mimeType": "text/markdown",
    "text": "# Xcode Debugging\n\n..."
  }]
}

MCP Tools

Beyond the read-only skill-lookup tools (axiom_get_catalog, axiom_search_skills, axiom_read_skill, axiom_get_agent), the server wraps the bundled xcprof profiler so non-Claude-Code clients get the same Instruments workflow. These tools shell out to a macOS universal binary shipped inside the package (dist/bin/xcprof).

Requires macOS with Xcode installed. xcprof drives xctrace, which is macOS-only — on other platforms the tools return an explanatory message instead of running.

Tool	What it does	Read-only
`axiom_xcprof_doctor`	Verify `xctrace`; count Instruments templates + devices	yes
`axiom_xcprof_analyze`	Analyze an existing `.trace` → structured CPU/hang/network JSON	yes
`axiom_xcprof_compare`	Diff two traces (baseline vs current) for regression detection	yes
`axiom_xcprof_record`	Capture a new `.trace` by attaching to, launching, or system-wide profiling	no

record is the only side-effecting tool. It defaults to attaching to a process and always runs non-interactively (--no-prompt). Its higher-risk modes stay gated, mirroring the CLI's ADR-002 security gates:

Launching a process (launch) requires allowLaunch: true.
System-wide capture (allProcesses) requires allowAllProcesses: true.

Without those explicit flags the binary refuses the operation. Recordings are always duration-bounded.

Development

Project Structure

axiom-mcp/
├── package.json              # npm package config
├── tsconfig.json             # TypeScript config
├── skill-annotations.json    # MCP search/catalog metadata
├── src/
│   ├── index.ts              # Entry point + stdio transport
│   ├── config.ts             # Configuration + logging
│   ├── loader/
│   │   ├── types.ts          # Loader interface
│   │   ├── parser.ts         # Frontmatter parsing
│   │   ├── dev-loader.ts     # Live file reading
│   │   └── prod-loader.ts    # Bundle reading
│   ├── resources/
│   │   └── handler.ts        # Resources protocol
│   ├── prompts/
│   │   └── handler.ts        # Prompts protocol
│   ├── tools/
│   │   └── handler.ts        # Tools protocol
│   ├── catalog/
│   │   └── index.ts          # Skill catalog + search
│   ├── search/
│   │   └── index.ts          # BM25 search engine
│   └── scripts/
│       └── bundle.ts         # Bundle generator
└── dist/                     # Compiled output
    ├── index.js              # Server entry point
    ├── bundle.json           # Production bundle
    └── ...

Build Commands

# Install dependencies
npm install

# Build once
npm run build

# Build with production bundle
npm run build:bundle

# Watch mode (rebuild on changes)
npm run dev

# Run server
npm start

The build:bundle command:

Compiles TypeScript (tsc)
Generates dist/bundle.json from plugin files
Bundle includes all skills, commands, and agents
Required for production mode

Adding Skills

Skills are automatically discovered from {AXIOM_DEV_PATH}/skills/<name>/SKILL.md.

Skill frontmatter follows the Agent Skills spec:

---
name: my-skill
description: Use when...
license: MIT
---

MCP search/catalog annotations (category, tags, related) are stored separately in skill-annotations.json:

{
  "my-skill": {
    "category": "debugging",
    "tags": ["xcode", "swift", "performance"],
    "related": ["other-skill", "another-skill"]
  }
}

Changes are picked up automatically in development mode.

Testing

Manual Testing (Development Mode)

# Terminal 1: Start server
AXIOM_MCP_MODE=development \
AXIOM_DEV_PATH=../.claude-plugin/plugins/axiom \
AXIOM_LOG_LEVEL=debug \
node dist/index.js

# Terminal 2: Send MCP requests via stdin
echo '{"jsonrpc":"2.0","id":1,"method":"resources/list"}' | node dist/index.js

Testing with MCP Inspector

Install the official MCP Inspector:

npx @modelcontextprotocol/inspector npx axiom-mcp

Opens a web UI for testing MCP protocol interactions.

Testing Claude Code Integration

# Reload plugin (triggers .mcp.json)
claude-code plugin reload axiom

# Check MCP server logs
# (Logs go to stderr, visible in plugin console)

Troubleshooting

Server Won't Start

Check Node version:

node --version
# Should be 18.0.0 or higher

Check environment variables:

echo $AXIOM_MCP_MODE
echo $AXIOM_DEV_PATH

Verify plugin path exists (dev mode):

ls $AXIOM_DEV_PATH/skills
# Should show skill directories

Skills Not Appearing

Check log output (stderr):

AXIOM_LOG_LEVEL=debug npx axiom-mcp 2>&1 | grep -i skill

MCP Client Can't Connect

MCP uses stdin/stdout for communication. Common issues:

Wrong command in your tool's config — use npx with args ["-y", "axiom-mcp"]
Other stdout writers — make sure nothing else writes to stdout; logs go to stderr only

Test the command from your config manually:

npx axiom-mcp
# Should start without errors, waiting for stdin

Roadmap

Phase 1: Foundation

MCP server with stdio transport
Resources protocol (skills)
Development mode loader
Claude Code .mcp.json integration

Phase 2: MCP Annotations

Add MCP metadata to test skills
Enhanced skill categorization
Cross-references between skills

Phase 3: Full Primitives

Prompts protocol (commands)
Tools protocol (agents)
Complete MCP feature coverage

Phase 4: Production Bundle

Pre-compiled skill snapshot
Production mode loader
Bundle generator script
Dual-mode Loader interface

Phase 5: npm Distribution

Published as axiom-mcp on npm
Zero-config install via npx axiom-mcp
Multi-client configuration guides

Architecture

Dual Distribution Model

Bundled (Claude Code Plugin)

User installs plugin → .mcp.json → MCP server (dev mode) → Live skills

Standalone (Other Tools)

npx axiom-mcp → Server (prod mode) → Bundled skills

Key Insight: Same codebase, different entry points. Development mode for rapid iteration, production mode for distribution.