Sumac (sxmc)

Sumac makes AI assistants stop guessing how your tools work.

It inspects the real tools already on your machine, turns them into structured profiles, and uses that knowledge to generate AI-host startup docs, client config, MCP wrappers, and reusable discovery artifacts from one Rust binary.

Crates.io | docs.rs

Stable 1.x line: Sumac now treats setup -> add -> status -> sync as the maintained onboarding and reconciliation loop for day-to-day use.

Stable Product Path

If you only learn four commands, learn these:

sxmc setup --root .
sxmc add gh --root .
sxmc status --human
sxmc sync --root . --apply

When you want user-level host files instead of repo-local files, switch the same workflow to --global:

sxmc setup --global
sxmc add gh --global
sxmc status --global --human
sxmc sync --global --apply

What they mean:

• sxmc setup: onboard the common tools a repo uses
• sxmc add <tool>: teach Sumac and your AI hosts one more CLI
• sxmc status: see what your AI knows, what is stale, and what to do next
• sxmc sync: reconcile saved profiles and generated host artifacts as tools change

Why It Exists

Without Sumac, the same capability usually gets rebuilt several times:

• a skill adapter for one agent
• a JSON-RPC script for one MCP server
• a thin shell wrapper for one API
• per-host startup docs and config files for AI tools

Sumac collapses that into one installable binary (sxmc) with four core flows:

Skills -> MCP server
MCP server -> CLI
API -> CLI
CLI -> AI startup surfaces

That means less glue code, narrower MCP discovery, fewer retry turns, and much less repeated setup across Claude Code, Cursor, Gemini CLI, Copilot, Codex-style tools, and generic MCP clients. The CLI command is sxmc — short to type, same letters as the brand.

Install

cargo install sxmc

Other channels:

• GitHub Releases: prebuilt archives with checksums
• npm wrapper: packaging/npm
• Homebrew formula: packaging/homebrew/sxmc.rb

Quick Start

Serve local skills over MCP:

sxmc serve
sxmc serve --transport http --host 127.0.0.1 --port 8000

Install a reusable skill into project-local or user-global skill storage:

sxmc skills install tests/fixtures/simple-skill --root .
sxmc skills install https://github.com/openai/skills/tree/main/skills/.curated/example-skill --global
sxmc skills update simple-skill --global

Inspect and call any MCP server from the terminal:

sxmc stdio "npx @modelcontextprotocol/server-memory" --list
sxmc stdio "npx @modelcontextprotocol/server-memory" create_entities 'entities=[{"name":"sxmc","entityType":"project","observations":["Rust MCP bridge"]}]'

Use a baked, token-efficient MCP workflow:

sxmc bake create memory --type stdio --source "npx @modelcontextprotocol/server-memory"
sxmc mcp servers
sxmc mcp info memory/create_entities --format toon
sxmc mcp call memory/create_entities '{"entities":[{"name":"sxmc","entityType":"project","observations":["Rust MCP bridge"]}]}'

Run an API as a CLI:

sxmc api https://petstore3.swagger.io/api/v3/openapi.json --list
sxmc api https://petstore3.swagger.io/api/v3/openapi.json findPetsByStatus status=available

Turn a CLI into startup-facing AI artifacts:

sxmc doctor
sxmc doctor --human
sxmc doctor --check --only claude-code,cursor
sxmc doctor --check --fix --only claude-code,cursor --from-cli gh
sxmc inspect cli gh --format toon
sxmc inspect cli curl --compact --format json-pretty
sxmc inspect cli cargo --depth 1 --format json-pretty
sxmc inspect cli gh --depth 2 --compact --format json-pretty
sxmc inspect batch git cargo brew --parallel 4 --compact --format json-pretty
sxmc inspect batch --from-file tools.txt --compact --format json-pretty
sxmc inspect batch --from-file tools.yaml --since 2026-03-22T00:00:00Z
sxmc inspect batch --from-file tools.yaml --compact  # nested depth shows up as nested_profile_count
sxmc inspect diff git --before before.json --format json-pretty
sxmc inspect diff git --before before.json --format toon
sxmc inspect cache-stats --format json-pretty
sxmc inspect cache-invalidate cargo --format json-pretty
sxmc inspect cache-invalidate 'g*' --dry-run --format json-pretty
sxmc inspect cache-clear --format json-pretty
sxmc inspect cache-warm --from-file tools.toml --parallel 4 --format json-pretty
sxmc init ai --from-cli gh --coverage full --mode preview
sxmc init ai --from-cli gh --coverage full --host claude-code,cursor,github-copilot --mode apply
sxmc init ai --from-cli gh --coverage full --host claude-code --mode apply --remove

Use sxmc first when the surface is unknown:

sxmc inspect cli <tool> --depth 1 --format json-pretty
sxmc stdio "<cmd>" --list
sxmc mcp grep <pattern>
sxmc api <url-or-spec> --list
sxmc serve --paths <dir>
sxmc scan --paths <dir>

inspect cli executes a real command via subprocess spawn. It can inspect installed binaries or explicit executable paths, but it does not see shell-only aliases or functions from your interactive shell.

inspect batch --from-file reads one command spec per line. Blank lines and lines beginning with # are ignored, trailing whitespace is trimmed, and inline arguments are preserved, so lines like git status or "cargo" build work as full command specs.

For structured batch input, .yaml / .yml and .toml files can define tools with per-command depth overrides. Example YAML:

tools:
  - command: git
    depth: 1
  - command: cargo

When a structured batch file sets depth: 1, full JSON output exposes nested profiles under subcommand_profiles. Compact output keeps the summary smaller and reports only counts like nested_profile_count.

Recent inspection hardening:

• sxmc inspect cli gh now recovers top-level flags as well as grouped subcommands
• sxmc inspect cli rustup preserves global options like --verbose, --quiet, --help, and --version
• sxmc inspect cli python3 avoids treating environment variables as subcommands
• sxmc inspect cli node --depth 1 keeps the inspect subcommand while using a cleaner runtime summary

Generate shell completions:

sxmc completions zsh > "${fpath[1]}/_sxmc"
sxmc completions bash > ~/.local/share/bash-completion/completions/sxmc

Practical Wins

• sxmc stdio "<cmd>" --list replaces ad hoc JSON-RPC client scripts for MCP discovery.
• sxmc mcp grep "file" searches across baked MCP servers, which is hard to reproduce cleanly with one-off tooling.
• sxmc scan catches hidden Unicode, dangerous permissions, and prompt-injection patterns that plain grep misses.
• sxmc inspect cli ... plus sxmc init ai ... turns per-host AI setup into generated, reviewable artifacts.
• sxmc doctor makes the next move explicit for agents and humans: unknown CLI, unknown MCP server, unknown API, local skills you want to serve, or startup setup.
• sxmc inspect batch ... amortizes inspection startup when you need several CLI profiles in one pass.
• sxmc inspect cache-stats exposes profile-cache size and entry counts so repeated agent lookups are observable instead of opaque.
• sxmc inspect cache-invalidate ... and sxmc inspect cache-clear let you recover from stale inspection state without manual cache surgery.

The current validation docs capture the real-world comparison set, token/turn estimates, and hidden retry-cost analysis.

Stable 1.x

The product name is Sumac. The command stays sxmc.

The maintained support boundary for the stable 1.x line is:

• stable onboarding and maintenance commands:
  • sxmc setup
  • sxmc add
  • sxmc doctor
  • sxmc status
  • sxmc sync
• stable machine-readable output contracts for those onboarding and maintenance commands
• stable host-selection aliases such as --client and --host
• additive evolution for richer JSON output instead of silent shape rewrites

See:

• Product Contract
• Stability Guide
• Validation Guide

Command Overview

• sxmc setup / sxmc add: first-run onboarding and one-tool onboarding
• sxmc status / sxmc sync: maintained-state view and reconciliation loop
• sxmc doctor: startup-discovery health and repair guidance
• sxmc serve: expose skills as stdio or HTTP MCP
• sxmc skills: list, inspect, run, and generate skills
• sxmc stdio / sxmc http: raw MCP bridge and debugging layer
• sxmc mcp: baked daily-use MCP workflow
• sxmc api / sxmc spec / sxmc graphql: API-to-CLI bridge
• sxmc scan: security scanning for skills and MCP surfaces
• sxmc inspect / sxmc init / sxmc scaffold: CLI-to-AI inspection and scaffolding
• sxmc doctor: startup-discovery status plus recommended first commands
• sxmc inspect batch: inspect several CLIs in one invocation
• sxmc inspect cache-stats: inspect cached profile inventory and size
• sxmc inspect cache-invalidate / sxmc inspect cache-clear: selectively invalidate or fully reset cached CLI profiles
• sxmc bake: saved connections
• sxmc completions: shell completion generation

Safety and Reliability

• preview-first AI artifact generation
• low-confidence CLI profiles are blocked from startup-doc generation unless explicitly overridden
• managed markdown/TOML blocks instead of wholesale overwrites
• recursive CLI inspection with sxmc inspect cli --depth 1
• deeper recursive CLI exploration is available with larger values like --depth 2 for multi-layer CLIs such as gh
• compact CLI inspection with sxmc inspect cli --compact for lower-context summaries
• batch CLI inspection with sxmc inspect batch --parallel ... when you need several profiles in one shot
• interactive inspections now emit lightweight stderr progress notes on cache misses and slower supplemental probes
• generated docs and skill scaffolds now surface larger CLI inventories with counts instead of hiding everything after the first few subcommands
• CLI inspection profiles are cached so repeated agent lookups do not keep reparsing unchanged binaries
• cache inventory is visible with sxmc inspect cache-stats
• cached CLI profiles can be invalidated selectively with sxmc inspect cache-invalidate <tool> or reset entirely with sxmc inspect cache-clear
• cleanup support with sxmc init ai --remove
• CLI inspection now supplements sparse help output with man pages without clobbering richer --help surfaces
• atomic bake persistence
• bake create/update now validate sources by default, with --skip-validate when you intentionally want to persist a broken or offline target
• bake validation errors now include source-type-specific guidance for stdio, HTTP MCP, OpenAPI, and GraphQL targets
• invalid --from-profile / inspect profile inputs now explain that sxmc expected a real CLI surface profile from sxmc inspect cli ...
• inspect cli targets must be real executables on PATH (or explicit paths), not shell-only aliases or functions
• baked stdio configs can pin a base directory for portable relative paths
• configurable timeouts for networked commands
• HTTP MCP guardrails for max concurrency and request body size
• stateful MCP workflows supported through sxmc mcp session
• this repo now ships generated AGENTS.md, CLAUDE.md, GEMINI.md, Cursor rules, and Copilot instructions from sxmc itself

Docs

• Usage: install, daily workflows, MCP usage, CLI-to-AI, completions
• Architecture: module map, data flow, and design boundaries
• Demo: short scripted demo path for terminal recordings
• Operations: hosting, release process, branch policy, distribution
• Validation: tests, smoke checks, compatibility, token/turn findings
• Product Contract: explicit support boundary
• Stability: what 1.0.0 will promise, what evolves additively, and what remains out of scope
• Compatibility Matrix: cross-platform lanes and CLI -> AI host coverage

Development

cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo test

Use the validation flow before release:

bash scripts/certify_release.sh target/debug/sxmc tests/fixtures
bash scripts/smoke_real_world_mcps.sh target/debug/sxmc

License

MIT