Destynova2/cli-code-skills / cli-audit-wizard
cli-audit-wizard
FlaggedAudit configuration wizard UX and lifecycle quality (setup, doctor, edit, migrate). Scores the 4 Laws (ask once, defaults, recap, config-as-code), credential discovery, multi-surface consistency (CLI/MCP/web), and scriptability. Detects wizard anti-patterns. Use on 'wizard', 'setup flow', 'config UX', 'init command', 'doctor mode', 'wizard audit', 'onboarding UX', 'first-run experience', 'config lifecycle', 'wizard broken', 'interactive setup', 'MCP config', 'config reload'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 25.4 KB |
| references/analogies.md | markdown | 35.1 KB |
| references/anti-patterns.md | markdown | 7.6 KB |
| references/doctor-checks.md | markdown | 5.8 KB |
| references/mcp-patterns.md | markdown | 5.3 KB |
| references/reference-flows.md | markdown | 9.2 KB |
| references/tooling-ladder.md | markdown | 5.6 KB |
references/mcp-patterns.md
View on GitHub# MCP Patterns -- Exposing Wizards as MCP Tools
> **When to read:** When auditing multi-surface consistency (Step 4) or when the project exposes config via MCP.
>
> **Staleness:** Verified 2026-04-05. MCP spec is evolving rapidly (Apps spec Jan 2026, Registry Q4 2026). Tool naming conventions (`wizard_*`) are skill-specific patterns, not MCP standards. Verify current MCP capabilities before recommending specific features.
---
## Contents
- Core principle
- Standard MCP tool set for config wizards
- Design rules for MCP wizard tools
- MCP Apps (2026 spec)
- Audit checklist for MCP surface
- Reference implementations
---
## Core principle
The MCP surface calls the same wizard engine as CLI and web. It writes the same TOML config file. JSON is transport only -- never on disk, never user-facing.
```
CLI (Huh/Gum) -+
MCP tool calls -+---> wizard engine ---> config.toml ---> app reload
Web UI (Caddy-served) -+
```
---
## Standard MCP tool set for config wizards
### Read tools
| Tool name | Input | Output | Idempotent |
|-----------|-------|--------|------------|
| `wizard_get_config` | (none) | Full config as JSON struct | Yes |
| `wizard_get_section` | `section: string` | One config section as JSON | Yes |
| `wizard_get_schema` | (none) | Config schema with types, defaults, descriptions | Yes |
### Write tools
| Tool name | Input | Output | Idempotent |
|-----------|-------|--------|------------|
| `wizard_set_{section}` | Section-specific fields | `{ ok: bool, diff: string }` | Yes |
| `wizard_remove_{key}` | `key: string` | `{ ok: bool, diff: string }` | Yes |
### Credential tools
| Tool name | Input | Output | Idempotent |
|-----------|-------|--------|------------|
| `wizard_check_credentials` | (none) | `{ providers: [{name, status, expires_at, source}] }` | Yes |
| `wizard_discover_credential` | `service: string` | `{ found: bool, source: string, valid: bool }` | Yes |
| `wizard_set_credential` | `service: string, ref: string` | `{ ok: bool, valid: bool, diff: string }` | Yes |
| `wizard_start_oauth` | `service: string` | `{ auth_url: string, device_code?: string }` | No |
### Lifecycle tools
| Tool name | Input | Output | Idempotent |
|-----------|-------|--------|------------|
| `wizard_run_doctor` | (none) | `{ checks: [{name, status, message, fix}] }` | Yes |
| `wizard_diff` | (none) | Pending changes as unified diff | Yes |
| `wizard_apply` | (none) | `{ ok: bool, reloaded: bool }` | Yes |
| `wizard_migrate` | `from_version: string` | `{ ok: bool, diff: string, breaking: [string] }` | No |
---
## Design rules for MCP wizard tools
### 1. Every tool is idempotent (except migrate)
Calling `wizard_set_backend(name="mistral", url="...")` twice produces the same config. The agent can retry safely.
### 2. Write tools return diffs
Every mutation tool returns a diff showing what changed. The agent (or human reviewing agent actions) can see exactly what happened.
```json
{
"ok": true,
"diff": "+[backends.mistral]\n+url = \"https://api.mistral.ai\"\n+model = \"mistral-large\""
}
```
### 3. Doctor before apply
The recommended agent flow is:
1. `wizard_get_config()` -- understand current state
2. `wizard_set_*()` -- make changes (returns diff each time)
3. `wizard_run_doctor()` -- verify health
4. `wizard_apply()` -- reload only if doctor passes
### 4. Schema tool enables autonomous config
`wizard_get_schema()` returns enough metadata for an agent to configure the tool without human guidance:
```json
{
"backends": {
"type": "map",
"value_schema": {
"url": { "type": "string", "required": true, "description": "Backend API endpoint" },
"model": { "type": "string", "required": true, "description": "Model name" },
"api_key_env": { "type": "string", "default": "API_KEY", "description": "Env var containing API key" }
}
}
}
```
### 5. No wizard_setup tool
There is no `wizard_setup` tool. Setup is just a sequence of `wizard_set_*` calls. The agent decides what to ask the user, not the MCP tool.
---
## MCP Apps (2026 spec)
MCP Apps allow tools to return interactive UI components rendered as sandboxed iframes in the conversation:
```json
{
"name": "wizard_configure",
"inputSchema": {},
"_meta": {
"ui": {
"resourceUri": "ui://wizard/config-form"
}
}
}
```
This means a config wizard can render an interactive form directly in the chat, collect input, validate, and write config -- all without leaving the conversation.
**Client support (as of 2026):** Claude (web + desktop), Goose, VS Code Insiders, ChatGPT (rolling out).
---
## Audit checklist for MCP surface
```
[ ] All MCP tools call the same engine as CLI
[ ] Write tools return diffs
[ ] Config written as TOML (not JSON on disk)
[ ] Doctor tool exists and returns structured checks
[ ] Schema tool exists for autonomous agent config
[ ] Tools are idempotent (safe to retry)
[ ] Apply tool validates before reloading
[ ] Tool names follow wizard_{action} convention
```
---
## Reference implementations
| Project | Pattern | Notes |
|---------|---------|-------|
| mcp-manager | Web GUI for MCP server management | Auto-scanning, interactive setup wizard |
| continuedev-hub-config-wizard | Reusable AI assistant configs | Models, rules, prompts published via Continue Dev Hub |
| mssql-mcp-config-builder | Step-by-step config UI | Visual builder for mcp_config.json |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 468k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |