Skip to content

index.md

Latest commit

 

History

History
124 lines (99 loc) · 5.62 KB

index.md

File metadata and controls

124 lines (99 loc) · 5.62 KB
Raw

mcp2cli Documentation

mcp2cli turns any MCP server into a native command-line application. Server tools become verbs, resources become nouns, prompts become workflows — no MCP protocol knowledge required at the command line.

# One binary. Any server. Real CLI commands.
local echo --message hello
email send --to user@example.com --body "Meeting at 3"
email get mail://inbox
staging deploy --version 2.1.0 --background

Why mcp2cli?

Problem mcp2cli Solution
MCP requires JSON-RPC plumbing to interact with servers Auto-discovers capabilities → typed CLI commands
Testing MCP servers needs custom client code mcp2cli ls, mcp2cli echo --message test — instant validation
AI agents can't easily call MCP tools JSON output mode + structured envelopes for programmatic parsing
Each server needs its own CLI wrapper One binary + config files = unlimited server bindings
CI/CD pipelines can't orchestrate MCP --json output, --non-interactive mode, exit codes, pipes

Architecture at a Glance

graph TB
    subgraph "User Interface"
        CLI["CLI Input<br/>local echo --message hello"]
        JSON["--json output"]
    end

    subgraph "mcp2cli Runtime"
        DISPATCH["Dispatch Router"]
        MANIFEST["Command Manifest<br/>auto-generated from discovery"]
        BRIDGE["Bridge Engine"]
        PROFILE["Profile Overlay<br/>aliases, groups, flags"]
        CACHE["Discovery Cache<br/>offline fallback"]
        DAEMON["Daemon (optional)<br/>warm connections"]
    end

    subgraph "MCP Transport"
        HTTP["Streamable HTTP"]
        STDIO["Stdio subprocess"]
        DEMO["Demo backend"]
    end

    subgraph "MCP Server"
        SERVER["Any MCP Server<br/>tools · resources · prompts"]
    end

    CLI --> DISPATCH
    DISPATCH --> MANIFEST
    MANIFEST --> BRIDGE
    PROFILE -.-> MANIFEST
    CACHE -.-> MANIFEST
    BRIDGE --> HTTP
    BRIDGE --> STDIO
    BRIDGE --> DEMO
    BRIDGE -.-> DAEMON
    HTTP --> SERVER
    STDIO --> SERVER
    BRIDGE --> JSON
Loading

Documentation Map

Getting Started

Document Description
Getting Started Install, configure, and run your first command in under a minute
Configuration Reference Complete YAML config schema with every field explained
CLI Reference Every command, flag, and option in one place
Telemetry What's collected, how to opt out, and how to set up a backend

Feature Guides

Each major feature has its own deep-dive page with examples, diagrams, and best practices.

Feature Page Summary
Discovery-Driven CLI features/discovery-driven-cli.md How server capabilities become typed CLI commands
Profile Overlays features/profile-overlays.md Rename, hide, group, and customize commands
Transports features/transports.md HTTP, Stdio, and Demo transport configuration
Ad-Hoc Connections features/ad-hoc-connections.md --url and --stdio for config-free usage
Request Timeouts features/request-timeouts.md Per-config and per-command timeout control
Fuzzy Matching features/fuzzy-matching.md "Did you mean?" suggestions for mistyped commands
Daemon Mode features/daemon-mode.md Keep MCP connections warm between invocations
Background Jobs features/background-jobs.md --background flag and the jobs/tasks system
Event System features/event-system.md Webhooks, Unix sockets, SSE, and command sinks
Authentication features/authentication.md Token management and auth flows
Output Formats features/output-formats.md Human, JSON, and NDJSON output modes
Elicitation & Sampling features/elicitation-and-sampling.md Interactive server-initiated prompts
Named Configs & Aliases features/named-configs-and-aliases.md Multi-server setup with symlink aliases

Articles & Guides

In-depth walkthroughs for specific use cases and audiences.

Article Audience
AI Agents + MCP via CLI Agent developers who want tool-use through shell
Testing MCP Servers Server authors validating protocol compliance
E2E & Conformance Testing Server authors building structured conformance test suites
Shell Scripting with MCP DevOps teams building CI/CD pipelines
Multi-Server Workflows Platform engineers orchestrating multiple servers
Local Development & Prototyping Server developers iterating on MCP implementations
Platform Engineering Infrastructure teams automating ops through MCP
From Zero to Production End-to-end production deployment guide

Quick Links