[EPIC] Make xp-clifford CLIs AI agent-native via MCP

[Kukkerem]

Goal

Make the xp-clifford framework a first-class citizen for AI agent workflows by adding
Model Context Protocol (MCP) support, machine-readable
output, input hardening, runtime schema introspection, dry-run validation, and agent context
file generation - all at the framework level so every CLI built on xp-clifford inherits these
capabilities automatically.

Motivation

AI agents are becoming primary consumers of CLI tools. The failure modes, ergonomics, and
interface requirements of an agent are fundamentally different from those of a human operator:

• Agents don't parse --help; they need typed, schema-backed tool definitions they can query at runtime.
• Agents don't scroll through colored output; they need clean, structured JSON they can process reliably.
• Agents don't typo; they hallucinate - generating path traversals, embedded query params, and
  control characters that humans would almost never produce.
• Agents don't click through browser OAuth; they need headless credential injection via environment variables.

xp-clifford already has the right primitives: named subcommands, typed config parameters,
structured event handlers. The framework is one translation layer away from serving agents.

Building that layer once in the framework - rather than in each individual CLI - means every
Crossplane exporter built on xp-clifford gains agent-native capabilities without any per-tool
implementation work.

Scope

This epic covers six areas of work, all delivered as framework-level additions to xp-clifford:

1. MCP Server Support

Expose all registered subcommands as MCP tools over stdio by importing a single package.
Running <binary> mcp starts a JSON-RPC 2.0 server.
Agents discover tools via tools/list and invoke them via tools/call with typed JSON arguments.
Resource output and warnings are returned as structured MCP content blocks.

2. Machine-Readable Output Mode

Add --output-format json (and OUTPUT_FORMAT env var) so exported resources are emitted as
NDJSON on stdout and logs go to stderr. Non-TTY stdout triggers machine-readable mode
automatically. Existing human-facing output is preserved when running interactively.

3. Input Hardening Against Hallucinations

Add a WithValidator(fn) API to string-based configparam types and ship built-in validators
for the inputs agents are known to hallucinate: path traversals (../../.ssh), embedded query
params (id?fields=name), control characters, and percent-encoded bypasses. Apply safe
defaults to built-in params like --output.

4. Schema Introspection Command

Add a describe subcommand that outputs the full JSON Schema of all registered subcommands
and their parameters. Agents query it at runtime instead of relying on potentially
stale documentation in their system prompt.

5. Dry-Run Support

Add a --dry-run global flag. In dry-run mode all parameters are resolved and validated, but
GetRun is not called. The resolved parameter set is printed as JSON (with sensitive values
redacted) and the process exits cleanly - giving agents a safe way to validate a call before committing it.

6. Agent Context File Generation

Add a generate-context subcommand that produces an CONTEXT.md or skill file from the CLI's
registered subcommands, parameter definitions, and optional author-defined annotations. The
file encodes usage invariants agents cannot intuit from --help.

Out of scope

• Agent CLI extensions - agent-specific
• Context window discipline and guidance - based on the usage, it could mean different approaches for filtering and masking
• Streamable HTTP transport - stdio covers all major agent clients
• MCP outputSchema / structuredContent - unstructured text content blocks are sufficient for YAML export results in v1
• MCP task support (execution.taskSupport) - relevant for long-running exports

Reference

• Blog post: https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/
• MCP Abstraction Tax (follow-up): https://justin.poehnelt.com/posts/mcp-abstraction-tax/
• MCP specification: https://modelcontextprotocol.io/specification/2025-11-25

[mpechkurov]

Postponed,
Will move it back to "Tech description"