cli-mcp

[![Go Reference][goreference_badge]][goreference_link] [![Go Report Card][goreportcard_badge]][goreportcard_link] [![Tests status][test_badge]][test_link]

cli-mcp turns a [urfave/cli][urfave/cli] v3 command tree into a CLI by default, with a batteries-included [Model Context Protocol][mcp] server attached. One binary, three usage forms, same code path.

app := &cli.Command{Name: "demo", Commands: []*cli.Command{ /* your tree */ }}
climcp.AttachMCP(app, climcp.Options{Name: "demo", Version: "v0.0.0"})
app.Run(ctx, os.Args)

That's it. app is now a regular CLI you can run directly, AND an MCP server when invoked as app mcp serve (stdio) or app mcp serve-http (Streamable HTTP).

The three forms

Given a hello subcommand, the same code is reachable as:

1. Plain CLI — humans run subcommands directly:

./demo hello kai --loud
# HELLO, KAI!

2. MCP server, raw JSON-RPC over the [Streamable HTTP][streamable] transport: start ./demo mcp serve-http --addr 127.0.0.1:8080, POST a tools/call payload to /mcp with the standard MCP headers. Returns "HELLO, KAI!" for the same args.

3. MCP server, called via [mcporter][mcporter] — the client wraps MCP tools as subcommands, so the caller sees a CLI shape again:

# mcporter.json
# {"mcpServers":{"demo":{"command":"./demo","args":["mcp","serve"]}}}
mcporter call demo hello kai --loud
# HELLO, KAI!

Form 1 runs the Action directly. Forms 2 and 3 round-trip through MCP and end up running the same Action with the same flags and args. The mcp subcommand group is auto-excluded from the MCP tool surface so calling MCP doesn't expose "how to start MCP".

See examples/dual-mode for the runnable version.

Features

• Every leaf command becomes an MCP tool; tool name is the dot-joined path from the root's children.
• Input schema derived from urfave flags (typed) and positional args.
• stdio transport for editor/agent integrations, [Streamable HTTP][streamable] (current spec) for remote.
• Built on the official [modelcontextprotocol/go-sdk][go-sdk].
• Relays webops.* metadata onto MCP tool.Meta for [cli-web-ops] consumption.
• Composes with [cli-guard]: Guard-wrapped actions audit and validate every tool call.

Documentation

docs/FEATURES.md inventory, examples/ demos, CLI reference, deploy/Caddyfile.example production posture. Dev verbs in .agent-guard/agent-guard.yaml; agent-guard lint validates against the Makefile.

Support

Bug or feature request: [create a new issue]. Conduct: Code of Conduct. Security: SECURITY.md. Siblings: [cli-guard], [cli-web-docs], [cli-web-ops].

See also

• AGENTS.md - agent-facing operating rules.
• docs/FEATURES.md - inventory of what ships today.
• .agent-guard/agent-guard.yaml - allowlisted commands.

Cross-reference convention from coilysiren/agentic-os#59.