convez.ai
MCP ServerAutomaçãoIntermediário
mcp2cli

mcp2cli — CLI adapter para servidores MCP

mcp2cli/source-code

Transforme servidores MCP em CLIs descobríveis e programáveis

Ver no GitHub
InicialPluginScore · de 0 a 100

Converte qualquer servidor MCP em ferramentas de linha de comando nativas, automatizando a descoberta de capacidades e gerando interfaces CLI tipadas a partir de schemas JSON. Elimina conhecimento de JSON-RPC e protocolo, permitindo uso imediato via comandos shell estruturados.

Instalação

$npx convez-ai mcp2cli/source-code

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
12
Forks
2
Acompanhando
0
Saúde
50%
Último commit
há 1 mês
Versão
v0.1.10
Issues abertas
0
Contribuidores
2

Casos de uso

  • Testar e debugar servidores MCP sem código cliente customizado
  • Orquestrar operações MCP em pipelines CI/CD com exit codes e JSON estruturado
  • Expor capabilities MCP como comandos nativos para automação de shell scripts

Veredito

Ferramenta pragmática que desburocratiza a integração MCP com CLI, adequada para equipes que precisam expor servidores MCP em ambientes já dominados por shell scripts e automação. Implementação em Rust garante portabilidade e performance.

README

A tradução para o português deste README ainda está na fila.

mcp2cli

Turn 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 terminal.

# One binary. Any server. Real CLI commands.
email ls
email send --to user@example.com --subject "Hi" --body "Meeting at 3"
email get mail://inbox
staging deploy --version 2.1.0 --background
prod --json doctor | jq '.data.server'

Why mcp2cli?

MCP (Model Context Protocol) defines a powerful standard for servers to expose tools, resources, and prompts. But interacting with an MCP server requires JSON-RPC plumbing, session negotiation, and protocol-level knowledge — none of which belongs in a CLI.

mcp2cli bridges that gap:

Problemmcp2cli
MCP requires JSON-RPC plumbingAuto-discovers capabilities → typed --flags from JSON Schema
Testing MCP servers needs custom client codePoint, shoot: mcp2cli --url http://localhost:3001/mcp ls
Each server needs its own CLI wrapperOne binary + config files = unlimited server bindings
AI agents can't easily call MCP tools from shell--json output → structured envelopes for programmatic parsing
CI/CD can't orchestrate MCP operationsExit codes, JSON output, pipes, --timeout, --background
Server tools have cryptic protocol namesProfile overlays rename, group, and hide commands

Quick Start

Install

cargo install --path .

Option A: Ad-hoc — zero config

# HTTP server — just point and go
mcp2cli --url http://127.0.0.1:3001/mcp ls
mcp2cli --url http://127.0.0.1:3001/mcp echo --message hello

# Stdio server — just run
mcp2cli --stdio "npx @modelcontextprotocol/server-everything" ls

Option B: Named config + alias

# Create a config
mcp2cli config init --name email --app bridge \
  --transport streamable_http --endpoint https://mcp.example.com/email

# Create a symlink alias
mcp2cli link create --name email

# Authenticate (the email server needs a bearer token)
email auth login

# Use it like a standalone app
email ls                                      # Discover capabilities
email send --to user@example.com \
  --subject "Hi" --body "Meeting at 3"        # Call a tool
email search --query "from:boss"              # Search the mailbox
email get mail://inbox                        # Read a resource
email doctor                                  # Health check

Option C: Demo mode — no server needed

mcp2cli config init --name demo --app bridge \
  --transport streamable_http --endpoint https://demo.invalid/mcp
mcp2cli use demo
mcp2cli ls

Full getting started guide →


How It Works

mcp2cli discovers → builds manifest → generates CLI → parses input → executes MCP call
  1. Discovers the server's tools, resources, resource templates, and prompts
  2. Builds a command manifest — each capability becomes a typed command with flags derived from JSON Schema
  3. Generates a clap CLI tree — dotted names become nested subcommands, required fields become required flags
  4. Parses your input against the generated tree with full type validation
  5. Executes the MCP operation and renders the result

Schema-to-flag mapping

JSON SchemaCLI flagExample
string--name <TEXT>--message hello
integer--count <INT>--steps 5
number--rate <NUM>--temperature 0.7
boolean--flag--include-image
enum--kind <A|B|C>--level error
array--tags <VAL,...>--labels bug,urgent
Complex--config <JSON>--config '{"a":1}'

Namespace grouping

Dotted tool names automatically become nested subcommands:

# Server tools: send, reply, draft.create
email send --to user@example.com --subject "Hi" --body "Hello"
email reply --thread-id 123 --body "Thanks"
email draft create --subject "New draft"

Features at a Glance

Core

Transports

  • Streamable HTTP — JSON-RPC over HTTP with SSE streaming and session negotiation
  • Stdio — spawn local subprocess servers, communicate via stdin/stdout
  • Demo mode — demo.invalid file-backed backend for offline learning and testing

Protocol Coverage

Full MCP 2025-11-25 implementation. See the Protocol Coverage reference for per-feature detail, source pointers, and CLI examples.

CategoryMethods / notificationsmcp2cli surface
Lifecycleinitialize, notifications/initialized, pingOne handshake per session; ping exposed as a CLI command
Discoverytools/list, resources/list, resources/templates/list, prompts/list + notifications/*/list_changedls populates a persistent cache; list-change notifications invalidate it automatically
Tool invocationtools/callTyped clap flags from JSON Schema (required/optional, enums, defaults, nested objects); progress token attached automatically
Resourcesresources/read, resources/subscribe, resources/unsubscribe, notifications/resources/updatedget <URI> for concrete reads; parameterised templates surface as commands; subscribe/unsubscribe stream change events
Promptsprompts/getEach prompt becomes a command with typed argument flags derived from the prompt definition
Completionscompletion/completecomplete command with ref context (resource or prompt) per MCP 2025-11-25
Logginglogging/setLevel, notifications/messagelog level <LEVEL>; server-emitted logs are surfaced as runtime events and written to the configured sinks
Progressnotifications/progress + _meta.progressTokenProgress tokens auto-attached to long-running ops; ticks rendered to stderr or event sinks
Cancellationnotifications/cancelled (bidirectional)Ctrl+C sends a cancel for the in-flight request; inbound cancels are acknowledged
Elicitation (server→client)elicitation/createInteractive terminal prompt — form mode (typed fields from JSON Schema) + URL mode (open-in-browser)
Sampling (server→client)sampling/createMessageHuman-in-the-loop review with tool display before forwarding to the LLM
Roots (server→client)roots/listClient advertises configurable root URIs; servers query on demand
Tasks (MCP 2025-11-25)tasks/get, tasks/result, tasks/cancel, _meta.task on tools/call--background creates a task; jobs show/wait/cancel/watch tracks it across invocations

Operations

  • Authentication — auth login/logout/status with file-backed token persistence
  • Event system — 5 sink types: stderr, HTTP webhook, Unix socket, SSE server, command exec
  • Output formats — --json, --output json|ndjson|human — every command supports structured output
  • Request timeouts — global default + per-command --timeout override
  • Daemon mode — keep MCP connections warm between invocations (Unix socket IPC)
  • Doctor & Inspect — runtime health diagnostics, full capability dump

Multi-Server Workflow

Each alias routes to a different MCP server. Each feels like its own standalone application.

# Set up multiple servers
mcp2cli config init --name dev --transport stdio --stdio-command ./dev-server
mcp2cli config init --name staging --transport streamable_http --endpoint https://staging.api/mcp
mcp2cli config init --name prod --transport streamable_http --endpoint https://prod.api/mcp

# Create aliases
mcp2cli link create --name dev
mcp2cli link create --name staging
mcp2cli link create --name prod

# Each alias is its own CLI
dev ls                          # Local dev server
staging deploy --version 1.2.3  # Staging HTTP server
prod doctor                     # Production health check

JSON Output for Scripts & Agents

Every command supports structured JSON output:

# JSON envelope
email --json ls | jq '.data.items[].id'

# Tool result
email --json send --to user@example.com --subject "Hi" --body "Hello" | jq '.data.content[0].text'

# Health check data
email --json doctor | jq '.data.server'

# Machine-readable discovery
email --json ls --tools | jq '[.data.items[] | {id, kind, summary}]'

Consistent envelope format:

{
  "app_id": "email",
  "command": "invoke",
  "summary": "called send",
  "lines": ["..."],
  "data": { "content": [...] }
}

Profile Overlays

Customize the CLI surface per-server — no server changes needed:

profile:
  display_name: "Email CLI"
  aliases:
    long-running-operation: lro     # Rename commands
    echo: ping
  hide:
    - debug-tool                    # Hide from help/ls
  groups:
    mail:                           # Custom grouping
      - send
      - reply
      - draft-create
  flags:
    echo:
      message: msg                  # Rename flags
  resource_verb: fetch              # "fetch" instead of "get"

Config Model

Each named config is a YAML file. Minimal example:

schema_version: 1
server:
  transport: streamable_http
  endpoint: http://localhost:3001/mcp

Full example with all options:

schema_version: 1

app:
  profile: bridge

server:
  display_name: My MCP Server
  transport: stdio                       # or streamable_http
  endpoint: null                         # required for streamable_http
  stdio:
    command: npx
    args: ['@modelcontextprotocol/server-everything']
  roots:
    - uri: "file:///home/user/project"
      name: "Project Root"

defaults:
  output: human                          # human | json | ndjson
  timeout_seconds: 120                   # 0 = no timeout

logging:
  level: warn
  format: pretty
  outputs:
    - kind: stderr

auth:
  browser_open_command: null

events:
  enable_stdio_events: true
  # http_endpoint: "http://127.0.0.1:9090/events"
  # local_socket_path: "/tmp/mcp2cli-events.sock"
  # sse_endpoint: "127.0.0.1:9091"
  # command: "logger -t mcp2cli '${MCP_EVENT_MESSAGE}'"

profile:
  display_name: "My Tool"
  aliases: {}
  hide: []
  groups: {}
  flags: {}
  resource_verb: get

Full config reference →


Runtime Commands

Always available alongside server-derived commands:

CommandDescription
ls [--tools|--resources|--prompts] [--filter]Discover capabilities
pingServer liveness with latency
doctorRuntime health diagnostics
inspectFull capability dump
auth login|logout|statusAuthentication management
jobs list|show|wait|cancel|watchBackground job management
log <LEVEL>Set server-side log level
subscribe <URI> / unsubscribe <URI>Resource change notifications
complete <REF> <NAME> <ARG>Tab-completion from server

Host Commands

Manage configs and aliases — no server connection needed:

CommandDescription
mcp2cli config init [options]Create a named config
mcp2cli config listList all configs
mcp2cli config show --name <NAME>Show a config
mcp2cli use <NAME>Set active config
mcp2cli link create --name <NAME>Create symlink alias
mcp2cli daemon start|stop|statusManage connection daemons

Full CLI reference →


Use Cases

mcp2cli is useful across the entire MCP lifecycle:

Use CaseHow
Test an MCP servermcp2cli --url http://localhost:3001/mcp doctor — instant health check
E2E conformance testingBash test suites that validate every MCP spec section with assertions
Local server developmentmcp2cli --stdio "./my-server" ls — test as you build, zero client code
AI agent tool-use--json output → parse in Python/Node → agents call any MCP tool
CI/CD pipelinesJSON output, exit codes, --timeout, --background — pipeline-native
Infrastructure automationPer-service aliases → k8s deploy, db backup, mon status
Shell scriptingPipe to jq, loop over tools, retry with backoff
Multi-server orchestrationNamed configs + symlinks = cross-service workflows in bash
Production monitoringEvent sinks → webhooks, SSE, Unix sockets, custom commands

Detailed articles for each use case →


Testing

cargo test --lib                # Unit tests
cargo test --test integration   # Integration tests
cargo test                      # All tests

Local Validation Servers

# Streamable HTTP server
npx @modelcontextprotocol/server-everything streamableHttp
# → http://127.0.0.1:3001/mcp

# Stdio server
npx @modelcontextprotocol/server-everything

E2E Testing Your Own Server

Use mcp2cli as a conformance test harness:

# Quick smoke test
mcp2cli --url http://localhost:3001/mcp doctor

# Structured conformance suite
./run-conformance.sh --url http://localhost:3001/mcp

E2E conformance testing guide →


Documentation

Getting Started

DocumentDescription
Getting StartedInstall, configure, run your first command
CLI ReferenceEvery command, flag, and option
Config ReferenceComplete YAML schema
config.example.yamlAnnotated config template

Feature Guides

FeatureGuide
Discovery-driven CLIdocs/features/discovery-driven-cli.md
Profile overlaysdocs/features/profile-overlays.md
Transportsdocs/features/transports.md
Ad-hoc connectionsdocs/features/ad-hoc-connections.md
Request timeoutsdocs/features/request-timeouts.md
Fuzzy matchingdocs/features/fuzzy-matching.md
Daemon modedocs/features/daemon-mode.md
Background jobsdocs/features/background-jobs.md
Event systemdocs/features/event-system.md
Authenticationdocs/features/authentication.md
Output formatsdocs/features/output-formats.md
Elicitation & samplingdocs/features/elicitation-and-sampling.md
Named configs & aliasesdocs/features/named-configs-and-aliases.md

Articles

ArticleAudience
AI Agents + MCP via CLIAgent developers
E2E & Conformance TestingMCP server authors
Testing MCP ServersServer validation
Local Development & PrototypingServer developers
Shell Scripting with MCPDevOps
Multi-Server WorkflowsPlatform engineers
Platform EngineeringInfrastructure teams
From Zero to ProductionProduction deployment

Architecture

DocumentDescription
Design ProposalArchitecture of the discovery-driven dynamic CLI
MCP Spec ComplianceSpec compliance audit and gap tracking
Implementation PlanMCP 2025-11-25 compliance roadmap

Telemetry

mcp2cli collects anonymous, non-sensitive usage telemetry to help us understand which features are used and where to focus improvements. We follow the same opt-out model used by Homebrew, Rust, and VS Code.

What is collected

  • Command category (e.g. "tool_invoke", "discover", "auth" — never the actual tool/prompt name)
  • Transport type used (stdio, HTTP)
  • Whether features like --json, --background, --timeout, daemon, profile overlay, or ad-hoc mode were used
  • Outcome (success/error) and duration in milliseconds
  • OS, architecture, and CLI version
  • A random installation UUID (not tied to your identity)

What is NOT collected

  • No server endpoints, URIs, tool names, argument values, file paths, or configuration content
  • No IP addresses or user identifiers
  • No environment variables or credentials

How to opt out

Any one of these disables telemetry completely:

# Config file
telemetry:
  enabled: false

# Environment variable
export MCP2CLI_TELEMETRY=off

# CLI flag (per-invocation)
mcp2cli --no-telemetry ls

# Respect DO_NOT_TRACK standard (https://consoledonottrack.com/)
export DO_NOT_TRACK=1

Where data is stored

Events are written to ~/.local/share/mcp2cli/telemetry.ndjson as newline-delimited JSON. You can inspect, delete, or rotate this file at any time.

Telemetry collection & backend setup guide →


Stewardship

mcp2cli is operated and developed by TSOK — The Source of Knowledge AI Laboratory (tsok.org), with engineering and agent operations supported by TSOK-Bot (tsok.bot), TSOK's in-house AI agent platform. The project is released under the Apache License 2.0; see LICENSE.

License

Apache License 2.0 — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados