Adopt ix mcp server in plugin manifest and skills (tracking)

[josephismikhail]

Summary

Track the plugin-side adoption of the ix mcp MCP server once it lands in ix-infrastructure/Ix. See ix-infrastructure/Ix#219 for the upstream design and rationale.

This is the MCP counterpart to plugin#21 (which tracks adoption of the --format llm flag from Ix#206). MCP and --format llm are orthogonal:

• --format llm shrinks the bytes a tool/CLI result puts in the model's context.
• MCP changes how the model invokes ix in the first place, and how it discovers what's available.

Both stack: the MCP server's tool responses internally render with --format llm, so byte savings from plugin#21 carry over into MCP-invoked paths.

Why this is a separate issue

The Ix repo ships the server (ix mcp subcommand). This repo is responsible for:

• Registering the server in the plugin manifest so Claude Code auto-spawns it
• Updating skills (model-invoked reasoning paths) to prefer MCP tool calls over CLI invocations
• Leaving hooks on CLI (shell-event paths, no model in the loop)
• Updating test fixtures and docs

The MCP server is opt-in upstream; nothing breaks while this work is pending. Adoption captures the discovery + shell-escape robustness benefits described in Ix#219.

Scope

1. Register the server in the plugin manifest

Add an mcpServers block to .claude-plugin/plugin.json:

{
  "mcpServers": {
    "ix": {
      "command": "ix",
      "args": ["mcp"]
    }
  }
}

Claude Code reads this on session start and spawns ix mcp as a child process. Tools are auto-discovered; the model sees them as ix:search, ix:overview, etc.

2. Migrate skills from CLI to MCP tool calls

Skills under skills/ currently instruct the model to invoke ix <cmd> --format json (executed by the model via the Bash tool). Where the call is purely model-invoked reasoning, switch the recommendation to the corresponding ix:<tool> MCP tool. Concrete targets:

• skills/shared.md — the routing table at the heart of every Ix-aware skill. Replace ix <cmd> examples with ix:<tool> references in the "Decomposition Examples" and "Best Practices" sections.
• skills/ix-understand/SKILL.md, skills/ix-investigate/SKILL.md, skills/ix-impact/SKILL.md, skills/ix-debug/SKILL.md, skills/ix-architecture/SKILL.md, skills/ix-docs/SKILL.md, skills/ix-plan/SKILL.md — each prescribes a specific Ix command sequence; rewrite to use MCP tool calls.
• skills/ix-help/SKILL.md — router skill; should advertise MCP tools as the primary path.

Calls that remain CLI:

• Anything inside hooks/ — hooks fire on shell events synchronously and inject context; MCP doesn't apply.
• Anything skills use to invoke admin/ops commands (ix docker, ix status, etc.) — those aren't exposed via MCP in v1 and are mostly not model-invoked anyway.

3. Test fixtures

tests/fixtures/ix_outputs/*.json and tests/mock-ix.sh describe expected CLI outputs. Once skills move to MCP, add parallel fixtures covering the MCP tool call/response shape so hook+skill integration tests cover both paths.

4. Documentation

• README.md: a short section on MCP setup (mostly automatic once the manifest is updated).
• CLAUDE.md: update the "Cognitive Model" and "Practical Workflow" sections to mention that Ix tools are discoverable via MCP, not just CLI.
• IX_CLAUDE_PLUGIN_OVERVIEW.md: refresh if it lists invocation patterns.

Sequencing

Hard prerequisite: Ix#219 (upstream MCP server) and Ix#206 PR 1 (--format llm Tier 1) must both ship first.

Within this issue, suggested order:

1. Manifest registration (one-line change; verify the server starts under Claude Code)
2. skills/shared.md migration (highest-impact doc change; every skill inherits from it)
3. Per-skill migrations (one PR per skill is fine; they're independent)
4. Test fixture additions (can be deferred until skills are migrated)
5. Doc refresh

Each PR should reference both this tracking issue and Ix#219.

Coordination with plugin#21 (--format llm)

• Same plugin files are touched (skill docs, manifest, fixtures).
• Order doesn't matter strictly, but doing --format llm first means MCP-migrated skills inherit compact output for free without a second pass.
• Recommended: ship plugin#21 first, then start this one.

Decisions locked in (inherited from Ix#219)

• Transport: stdio. No client-side config beyond the manifest.
• Tool naming: ix:<flat name> in the model's view; ix:search, ix:overview, etc.
• Tool response format: --format llm-style by default; tools accept format: "json" if a skill needs structured data.
• Hooks stay on CLI. No migration there.

Done when

• .claude-plugin/plugin.json registers the ix MCP server.
• Every skill under skills/ whose call patterns target the model has been migrated from CLI to MCP tool references.
• skills/shared.md recommends MCP tools as the default for model-invoked reasoning paths.
• Hooks under hooks/ are unchanged.
• Test fixtures cover both CLI (for hook paths) and MCP (for skill paths) for each tool exercised in tests.
• README + CLAUDE.md mention MCP setup.

Out of scope

• Migrating hooks. They fire from shell events; MCP doesn't help them.
• New tools or workflow-aggregated tools (deferred to v2 in Ix#219).
• Per-tool confirmation policy beyond what Claude Code applies by default.