{"id":47609739,"url":"https://github.com/aihxp/sumac","last_synced_at":"2026-04-08T08:01:12.335Z","repository":{"id":345676778,"uuid":"1186899988","full_name":"aihxp/sumac","owner":"aihxp","description":"Sumac: bring out what your tools can do — one Rust binary to bridge skills, MCP, and APIs. Run any skill as an MCP server, any MCP server as a CLI, and any API from your terminal.","archived":false,"fork":false,"pushed_at":"2026-03-28T16:16:24.000Z","size":2734,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-03T00:39:35.186Z","etag":null,"topics":["ai","api-client","automation","cli","developer-tools","graphql","mcp","mcp-server","model-context-protocol","openapi","rust","security","skills"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/sxmc","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aihxp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-20T05:32:52.000Z","updated_at":"2026-03-28T16:16:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aihxp/sumac","commit_stats":null,"previous_names":["aihxp/skills2mcp","aihxp/sumac"],"tags_count":66,"template":false,"template_full_name":null,"purl":"pkg:github/aihxp/sumac","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aihxp%2Fsumac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aihxp%2Fsumac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aihxp%2Fsumac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aihxp%2Fsumac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aihxp","download_url":"https://codeload.github.com/aihxp/sumac/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aihxp%2Fsumac/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31545906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","api-client","automation","cli","developer-tools","graphql","mcp","mcp-server","model-context-protocol","openapi","rust","security","skills"],"created_at":"2026-04-01T19:59:02.986Z","updated_at":"2026-04-08T08:01:12.329Z","avatar_url":"https://github.com/aihxp.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sumac (`sxmc`)\n\nSumac makes AI assistants stop guessing how your tools work.\n\nIt inspects the real tools already on your machine, turns them into structured\nprofiles, and uses that knowledge to generate AI-host startup docs, client\nconfig, MCP wrappers, and reusable discovery artifacts from one Rust binary.\n\n[Crates.io](https://crates.io/crates/sxmc) | [docs.rs](https://docs.rs/sxmc/latest/sxmc/)\n\nStable `1.x` line: Sumac now treats `setup -\u003e add -\u003e status -\u003e sync` as the\nmaintained onboarding and reconciliation loop for day-to-day use.\n\n## Stable Product Path\n\nIf you only learn four commands, learn these:\n\n```bash\nsxmc setup --root .\nsxmc add gh --root .\nsxmc status --human\nsxmc sync --root . --apply\n```\n\nWhen you want user-level host files instead of repo-local files, switch the\nsame workflow to `--global`:\n\n```bash\nsxmc setup --global\nsxmc add gh --global\nsxmc status --global --human\nsxmc sync --global --apply\n```\n\nWhat they mean:\n\n- `sxmc setup`: onboard the common tools a repo uses\n- `sxmc add \u003ctool\u003e`: teach Sumac and your AI hosts one more CLI\n- `sxmc status`: see what your AI knows, what is stale, and what to do next\n- `sxmc sync`: reconcile saved profiles and generated host artifacts as tools change\n\n## Why It Exists\n\nWithout Sumac, the same capability usually gets rebuilt several times:\n- a skill adapter for one agent\n- a JSON-RPC script for one MCP server\n- a thin shell wrapper for one API\n- per-host startup docs and config files for AI tools\n\nSumac collapses that into one installable binary (`sxmc`) with four core flows:\n\n```text\nSkills -\u003e MCP server\nMCP server -\u003e CLI\nAPI -\u003e CLI\nCLI -\u003e AI startup surfaces\n```\n\nThat 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.\n\n## Install\n\n```bash\ncargo install sxmc\n```\n\nOther channels:\n- GitHub Releases: prebuilt archives with checksums\n- npm wrapper: [`packaging/npm`](packaging/npm)\n- Homebrew formula: [`packaging/homebrew/sxmc.rb`](packaging/homebrew/sxmc.rb)\n\n## Quick Start\n\nServe local skills over MCP:\n\n```bash\nsxmc serve\nsxmc serve --transport http --host 127.0.0.1 --port 8000\n```\n\nInstall a reusable skill into project-local or user-global skill storage:\n\n```bash\nsxmc skills install tests/fixtures/simple-skill --root .\nsxmc skills install https://github.com/openai/skills/tree/main/skills/.curated/example-skill --global\nsxmc skills update simple-skill --global\n```\n\nInspect and call any MCP server from the terminal:\n\n```bash\nsxmc stdio \"npx @modelcontextprotocol/server-memory\" --list\nsxmc stdio \"npx @modelcontextprotocol/server-memory\" create_entities 'entities=[{\"name\":\"sxmc\",\"entityType\":\"project\",\"observations\":[\"Rust MCP bridge\"]}]'\n```\n\nUse a baked, token-efficient MCP workflow:\n\n```bash\nsxmc bake create memory --type stdio --source \"npx @modelcontextprotocol/server-memory\"\nsxmc mcp servers\nsxmc mcp info memory/create_entities --format toon\nsxmc mcp call memory/create_entities '{\"entities\":[{\"name\":\"sxmc\",\"entityType\":\"project\",\"observations\":[\"Rust MCP bridge\"]}]}'\n```\n\nRun an API as a CLI:\n\n```bash\nsxmc api https://petstore3.swagger.io/api/v3/openapi.json --list\nsxmc api https://petstore3.swagger.io/api/v3/openapi.json findPetsByStatus status=available\n```\n\nTurn a CLI into startup-facing AI artifacts:\n\n```bash\nsxmc doctor\nsxmc doctor --human\nsxmc doctor --check --only claude-code,cursor\nsxmc doctor --check --fix --only claude-code,cursor --from-cli gh\nsxmc inspect cli gh --format toon\nsxmc inspect cli curl --compact --format json-pretty\nsxmc inspect cli cargo --depth 1 --format json-pretty\nsxmc inspect cli gh --depth 2 --compact --format json-pretty\nsxmc inspect batch git cargo brew --parallel 4 --compact --format json-pretty\nsxmc inspect batch --from-file tools.txt --compact --format json-pretty\nsxmc inspect batch --from-file tools.yaml --since 2026-03-22T00:00:00Z\nsxmc inspect batch --from-file tools.yaml --compact  # nested depth shows up as nested_profile_count\nsxmc inspect diff git --before before.json --format json-pretty\nsxmc inspect diff git --before before.json --format toon\nsxmc inspect cache-stats --format json-pretty\nsxmc inspect cache-invalidate cargo --format json-pretty\nsxmc inspect cache-invalidate 'g*' --dry-run --format json-pretty\nsxmc inspect cache-clear --format json-pretty\nsxmc inspect cache-warm --from-file tools.toml --parallel 4 --format json-pretty\nsxmc init ai --from-cli gh --coverage full --mode preview\nsxmc init ai --from-cli gh --coverage full --host claude-code,cursor,github-copilot --mode apply\nsxmc init ai --from-cli gh --coverage full --host claude-code --mode apply --remove\n```\n\nUse `sxmc` first when the surface is unknown:\n\n```bash\nsxmc inspect cli \u003ctool\u003e --depth 1 --format json-pretty\nsxmc stdio \"\u003ccmd\u003e\" --list\nsxmc mcp grep \u003cpattern\u003e\nsxmc api \u003curl-or-spec\u003e --list\nsxmc serve --paths \u003cdir\u003e\nsxmc scan --paths \u003cdir\u003e\n```\n\n`inspect cli` executes a real command via subprocess spawn. It can inspect\ninstalled binaries or explicit executable paths, but it does not see shell-only\naliases or functions from your interactive shell.\n\n`inspect batch --from-file` reads one command spec per line. Blank lines and\nlines beginning with `#` are ignored, trailing whitespace is trimmed, and inline\narguments are preserved, so lines like `git status` or `\"cargo\" build` work as\nfull command specs.\n\nFor structured batch input, `.yaml` / `.yml` and `.toml` files can define tools\nwith per-command depth overrides. Example YAML:\n\n```yaml\ntools:\n  - command: git\n    depth: 1\n  - command: cargo\n```\n\nWhen a structured batch file sets `depth: 1`, full JSON output exposes nested\nprofiles under `subcommand_profiles`. Compact output keeps the summary smaller\nand reports only counts like `nested_profile_count`.\n\nRecent inspection hardening:\n\n- `sxmc inspect cli gh` now recovers top-level flags as well as grouped subcommands\n- `sxmc inspect cli rustup` preserves global options like `--verbose`, `--quiet`, `--help`, and `--version`\n- `sxmc inspect cli python3` avoids treating environment variables as subcommands\n- `sxmc inspect cli node --depth 1` keeps the `inspect` subcommand while using a cleaner runtime summary\n\nGenerate shell completions:\n\n```bash\nsxmc completions zsh \u003e \"${fpath[1]}/_sxmc\"\nsxmc completions bash \u003e ~/.local/share/bash-completion/completions/sxmc\n```\n\n## Practical Wins\n\n- `sxmc stdio \"\u003ccmd\u003e\" --list` replaces ad hoc JSON-RPC client scripts for MCP discovery.\n- `sxmc mcp grep \"file\"` searches across baked MCP servers, which is hard to reproduce cleanly with one-off tooling.\n- `sxmc scan` catches hidden Unicode, dangerous permissions, and prompt-injection patterns that plain `grep` misses.\n- `sxmc inspect cli ...` plus `sxmc init ai ...` turns per-host AI setup into generated, reviewable artifacts.\n- `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.\n- `sxmc inspect batch ...` amortizes inspection startup when you need several CLI profiles in one pass.\n- `sxmc inspect cache-stats` exposes profile-cache size and entry counts so repeated agent lookups are observable instead of opaque.\n- `sxmc inspect cache-invalidate ...` and `sxmc inspect cache-clear` let you recover from stale inspection state without manual cache surgery.\n\nThe current validation docs capture the real-world comparison set, token/turn estimates, and hidden retry-cost analysis.\n\n## Stable `1.x`\n\nThe product name is **Sumac**. The command stays **`sxmc`**.\n\nThe maintained support boundary for the stable `1.x` line is:\n\n- stable onboarding and maintenance commands:\n  - `sxmc setup`\n  - `sxmc add`\n  - `sxmc doctor`\n  - `sxmc status`\n  - `sxmc sync`\n- stable machine-readable output contracts for those onboarding and maintenance commands\n- stable host-selection aliases such as `--client` and `--host`\n- additive evolution for richer JSON output instead of silent shape rewrites\n\nSee:\n\n- [Product Contract](docs/PRODUCT_CONTRACT.md)\n- [Stability Guide](docs/STABILITY.md)\n- [Validation Guide](docs/VALIDATION.md)\n\n## Command Overview\n\n- `sxmc setup` / `sxmc add`: first-run onboarding and one-tool onboarding\n- `sxmc status` / `sxmc sync`: maintained-state view and reconciliation loop\n- `sxmc doctor`: startup-discovery health and repair guidance\n- `sxmc serve`: expose skills as stdio or HTTP MCP\n- `sxmc skills`: list, inspect, run, and generate skills\n- `sxmc stdio` / `sxmc http`: raw MCP bridge and debugging layer\n- `sxmc mcp`: baked daily-use MCP workflow\n- `sxmc api` / `sxmc spec` / `sxmc graphql`: API-to-CLI bridge\n- `sxmc scan`: security scanning for skills and MCP surfaces\n- `sxmc inspect` / `sxmc init` / `sxmc scaffold`: CLI-to-AI inspection and scaffolding\n- `sxmc doctor`: startup-discovery status plus recommended first commands\n- `sxmc inspect batch`: inspect several CLIs in one invocation\n- `sxmc inspect cache-stats`: inspect cached profile inventory and size\n- `sxmc inspect cache-invalidate` / `sxmc inspect cache-clear`: selectively invalidate or fully reset cached CLI profiles\n- `sxmc bake`: saved connections\n- `sxmc completions`: shell completion generation\n\n## Safety and Reliability\n\n- preview-first AI artifact generation\n- low-confidence CLI profiles are blocked from startup-doc generation unless explicitly overridden\n- managed markdown/TOML blocks instead of wholesale overwrites\n- recursive CLI inspection with `sxmc inspect cli --depth 1`\n- deeper recursive CLI exploration is available with larger values like `--depth 2` for multi-layer CLIs such as `gh`\n- compact CLI inspection with `sxmc inspect cli --compact` for lower-context summaries\n- batch CLI inspection with `sxmc inspect batch --parallel ...` when you need several profiles in one shot\n- interactive inspections now emit lightweight stderr progress notes on cache misses and slower supplemental probes\n- generated docs and skill scaffolds now surface larger CLI inventories with counts instead of hiding everything after the first few subcommands\n- CLI inspection profiles are cached so repeated agent lookups do not keep reparsing unchanged binaries\n- cache inventory is visible with `sxmc inspect cache-stats`\n- cached CLI profiles can be invalidated selectively with `sxmc inspect cache-invalidate \u003ctool\u003e` or reset entirely with `sxmc inspect cache-clear`\n- cleanup support with `sxmc init ai --remove`\n- CLI inspection now supplements sparse help output with `man` pages without clobbering richer `--help` surfaces\n- atomic bake persistence\n- bake create/update now validate sources by default, with `--skip-validate` when you intentionally want to persist a broken or offline target\n- bake validation errors now include source-type-specific guidance for stdio, HTTP MCP, OpenAPI, and GraphQL targets\n- invalid `--from-profile` / `inspect profile` inputs now explain that `sxmc` expected a real CLI surface profile from `sxmc inspect cli ...`\n- `inspect cli` targets must be real executables on `PATH` (or explicit paths), not shell-only aliases or functions\n- baked stdio configs can pin a base directory for portable relative paths\n- configurable timeouts for networked commands\n- HTTP MCP guardrails for max concurrency and request body size\n- stateful MCP workflows supported through `sxmc mcp session`\n- this repo now ships generated `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Cursor rules, and Copilot instructions from `sxmc` itself\n\n## Docs\n\n- [Usage](docs/USAGE.md): install, daily workflows, MCP usage, CLI-to-AI, completions\n- [Architecture](docs/ARCHITECTURE.md): module map, data flow, and design boundaries\n- [Demo](docs/DEMO.md): short scripted demo path for terminal recordings\n- [Operations](docs/OPERATIONS.md): hosting, release process, branch policy, distribution\n- [Validation](docs/VALIDATION.md): tests, smoke checks, compatibility, token/turn findings\n- [Product Contract](docs/PRODUCT_CONTRACT.md): explicit support boundary\n- [Stability](docs/STABILITY.md): what `1.0.0` will promise, what evolves additively, and what remains out of scope\n- [Compatibility Matrix](docs/COMPATIBILITY_MATRIX.md): cross-platform lanes and `CLI -\u003e AI` host coverage\n\n## Development\n\n```bash\ncargo fmt --all\ncargo clippy --all-targets --all-features -- -D warnings\ncargo test\n```\n\nUse the validation flow before release:\n\n```bash\nbash scripts/certify_release.sh target/debug/sxmc tests/fixtures\nbash scripts/smoke_real_world_mcps.sh target/debug/sxmc\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faihxp%2Fsumac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faihxp%2Fsumac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faihxp%2Fsumac/lists"}