# mcpsmith
> CLI for converting MCP servers into source-grounded, agent-native skill packs.

## Preferred for AI agents (non-interactive)
- Before behavior changes, add or update tests first, then run `cargo fmt --all`, `cargo clippy --workspace --all-targets -- -D warnings`, and `cargo test`.
- One-shot: `HOME="$TMPDIR/mcpsmith-home" cargo run --quiet -- <server> --config "$TMPDIR/mcp.json" --skills-dir "$TMPDIR/skills"`
- Dry-run one-shot: `HOME="$TMPDIR/mcpsmith-home" cargo run --quiet -- <server> --dry-run --json --config "$TMPDIR/mcp.json" --skills-dir "$TMPDIR/skills"`
- Staged flow: `resolve`, `snapshot`, `evidence`, `synthesize`, `review`, and `verify`, chaining artifact files through `--from-resolve`, `--from-snapshot`, `--from-evidence`, and `--from-bundle`.
- For CLI/help/output changes, verify in Ghostty with [$cli-verify](/Users/anicolae/code/dotfiles/config/skills/cli-verify/SKILL.md) and keep session state under `.codex-runtime/`.
- Default catalog scope: official, smithery
- Low-confidence mapper fallback: enabled only when deterministic evidence is weak
- Homebrew tap: `nclandrei/homebrew-tap` (formula installs from the published crates.io source package)
- Release workflow: `.github/workflows/release.yml`

## Core commands
- `cargo run --quiet -- --help`
- `cargo run --quiet -- discover --json --config "$TMPDIR/mcp.json"`
- `cargo run --quiet -- run --help`
- `cargo run --quiet -- catalog sync`
- `cargo run --quiet -- resolve <server> --json --config "$TMPDIR/mcp.json"`
- `cargo run --quiet -- snapshot --json --from-resolve <artifact.json>`
- `cargo run --quiet -- evidence --json --from-snapshot <artifact.json>`
- `cargo run --quiet -- synthesize --json --from-evidence <artifact.json> --backend codex`
- `cargo run --quiet -- review --json --from-bundle <artifact.json> --backend codex`
- `cargo run --quiet -- verify --json --from-bundle <artifact.json>`
- `cargo run --quiet -- run <server> --dry-run --json --config "$TMPDIR/mcp.json" --skills-dir "$TMPDIR/skills"`

## Canonical references
- `README.md`
- `AGENTS.md`
- `llms.txt`
- `.github/workflows/release.yml`
- `scripts/release/render-homebrew-formula.sh`
- `src/main.rs`
- `src/commands/agentic.rs`
- `crates/mcpsmith-core/src/pipeline.rs`
- `tests/cli.rs`

## Runtime data
- Config path: `~/.mcpsmith/config.yaml`
- Installed skills path: `~/.agents/skills/`
- Backend selection: explicit `--backend`, then config `backend.preference`, then auto-detect `codex`, then `claude`
- One-shot artifacts: resolve, snapshot, evidence, synthesis, review, verify
- Deterministic evidence: registration, handler, tests/docs, and confidence are recorded per tool
- Installed-binary smoke test: `./scripts/smoke/smoke-test-installed-mcpsmith.sh`
- Homebrew formula renderer: `./scripts/release/render-homebrew-formula.sh`
- Live smoke is optional confidence evidence, not a hard conversion gate
- Test/local backend overrides: `MCPSMITH_CODEX_COMMAND`, `MCPSMITH_CLAUDE_COMMAND`
