@mcp-layer/cli

@mcp-layer/cli

@mcp-layer/cli is a CLI framework that turns MCP server schemas into a usable command line. It discovers a server from configuration, connects over stdio, extracts the unified schema from @mcp-layer/schema, and renders commands for tools, prompts, resources, and templates. You can also extend it with custom commands.

Install

pnpm add @mcp-layer/cli

Quick start

Run the CLI against a configured MCP server:

mcp-layer servers list
mcp-layer tools list
mcp-layer tools echo --text "hello"

Command surface

The CLI exposes the same schema items for tools, prompts, resources, and templates.

mcp-layer servers list
mcp-layer tools list
mcp-layer tools <tool>
mcp-layer prompts list
mcp-layer prompts <prompt>
mcp-layer resources list
mcp-layer resources <uri>
mcp-layer templates list
mcp-layer templates <template>

Shorthand form:

mcp-layer tools:echo --text "hello"
mcp-layer prompts:kickoff --json '{"topic":"launch"}'

Input handling

Inputs come from the MCP schema. You can supply them three ways:

• --json '{"key":"value"}' for inline JSON
• --input ./payload.json for JSON files
• --key value for schema properties (flags are generated from input schema fields)

Array and object inputs support a few additional forms:

• Arrays can be repeated: --items one --items two
• Arrays can be JSON: --items '["one","two"]'
• Objects can use dot notation: --meta.tag alpha
• Objects can be JSON: --meta '{"tag":"alpha"}'
• Scalar values are coerced using the schema type (e.g., --count 5, --enabled true).

If a parameter clashes with a CLI flag (like --help), pass tool arguments after --:

mcp-layer tools echo -- --help "not a real help flag"

Output formatting

The CLI formats MCP responses for readability by default:

• Text content prints as plain text.
• Markdown content renders as ANSI Markdown when stdout is a TTY (pipes receive plain text).
• Images and audio show a short hint with MIME type and size.
• Resource links show name, description, and URI.
• Unsupported content types render as a labeled JSON fallback.

Use --raw to emit the raw MCP JSON response (or raw binary bytes when a single binary payload is returned). If multiple content items are present, --raw returns JSON. This makes piping to files straightforward:

mcp-layer tools <tool> --raw > output.json
mcp-layer tools <tool> --raw > payload.bin

Disable markdown rendering with --no-markdown.

Server-provided text is sanitized to strip ANSI escape sequences by default. If you trust the server and want to preserve ANSI output, pass --allow-ansi.

Example:

mcp-layer tools <tool> --allow-ansi

Color output

Color output is enabled by default when stdout is a TTY. Disable it with --no-color or by setting NO_COLOR=1. You can customize the colors via accent and subtle in cli() options.

Per-command help

Use --help after a command to see its flags and examples:

mcp-layer tools echo --help
mcp-layer prompts kickoff --help

When a server is selected, help output uses the server name/version and lists all discovered tools, prompts, resources, and templates for that server.

Output formats

List commands support JSON output:

mcp-layer tools list --format json
mcp-layer resources list --format json

Run/read/render commands render formatted output by default. Use --raw for JSON (or binary bytes when a single binary payload is returned).

Configuration and server selection

@mcp-layer/cli uses @mcp-layer/config to discover MCP server definitions. When multiple servers are configured, choose one with --server:

mcp-layer tools list --server demo

You can also point at a specific config file or directory:

mcp-layer tools list --config ./mcp.json
mcp-layer tools list --config ~/configs

Embedding and custom commands

You can embed the CLI and add custom commands using the same parser and help renderer.

import { cli } from '@mcp-layer/cli';

/**
 * Render the CLI with a custom command.
 * @returns {Promise<void>}
 */
async function main() {
  await cli({ name: 'acme-mcp', description: 'Acme MCP CLI' })
    .command(
      {
        name: 'status',
        description: 'Report CLI configuration state.'
      },
      async function statusCommand(argv) {
        const verbose = Boolean(argv.verbose);
        process.stdout.write(JSON.stringify({ ok: true, verbose }, null, 2));
      }
    )
    .render();
}

main();

API

cli(options)

Creates a CLI instance.

Options:

• name: CLI name displayed in help output.
• version: CLI version string.
• description: CLI description for help output.
• colors: enable or disable color output.
• accent: hex color for headings (default #FFA500).
• subtle: hex color for flag names (default #696969).
• spinner: enable the loading spinner.
• markdown: enable markdown rendering for text output.
• ansi: allow ANSI escape sequences in server-provided text.
• server: default server name.
• config: default config path.

cli().command(options, handler)

Registers a custom command.

• options.name: command name.
• options.description: summary for help output.
• handler(argv): async handler invoked with parsed args.

cli().render([argv])

Executes the CLI. If argv is omitted, it uses process.argv.

Global flags

• --server <name>: select a configured server.
• --config <path>: point at a config file or directory.
• --format <json>: use JSON for list output.
• --json <string>: supply inline JSON input.
• --input <path>: supply JSON input from a file.
• --raw: emit raw JSON (or binary bytes for a single binary payload).
• --no-markdown: disable markdown rendering.
• --allow-ansi: preserve ANSI escape sequences from server text.
• --no-spinner: disable the loading spinner.
• --no-color: disable color output.

Development

pnpm test --filter @mcp-layer/cli