Scoutt

scoutt is a Bun + TypeScript CLI that discovers MCP tools, invokes them, and can generate a tool-specific CLI from an MCP server schema.

The package/bin name is scoutt.

Features

• Discover tools from MCP servers via tools/list.
• Invoke any discovered tool via tools/call.
• Generate a Commander-based CLI from MCP tool schemas.
• Support auth via explicit headers/token, env vars, or stored credentials.
• Support OAuth 2.0 device flow for servers that expose OAuth metadata.
• Parse both JSON and SSE (text/event-stream) MCP HTTP responses.

Requirements

• Bun (runtime/build/test)
• Node-compatible environment for the built artifact (dist/index.js)

Install

bun install

Quick Start

# show help
bunx scoutt --help

# list tools
bunx scoutt list-tools --server https://your-mcp-server.com

# run a tool with JSON args
bunx scoutt run some_tool --server https://your-mcp-server.com --args '{"query":"hello"}'

# generate a CLI file from server tools
bunx scoutt generate --server https://your-mcp-server.com --out ./generated-cli.ts

CLI Commands

Top-level commands:

• list-tools
• generate
• run
• auth

list-tools

List all tools from an MCP HTTP endpoint.

bunx scoutt list-tools --server <url> [--token <token>] [--header "Key: Value"]...

Options:

• --server <url> (required): MCP server URL.
• --token <token>: Bearer token (also supports env or stored auth).
• --header "Key: Value": Repeatable additional HTTP headers.

generate

Generate a TypeScript CLI source file from discovered MCP tools.

bunx scoutt generate --server <url> [--out <path>] [--token <token>] [--header "Key: Value"]...

Options:

• --server <url> (required)
• --out <path>: Output path (default: ./generated-cli.ts)
• --token <token>
• --header "Key: Value" (repeatable)

Output behavior:

• Emits Commander commands per MCP tool.
• Maps schema fields to CLI flags (snake_case → kebab-case flags).
• Embeds tool schema into generated command handlers.
• Generated command handlers call invokeTool from scoutt/runner.

run <toolName>

Invoke a specific tool directly.

bunx scoutt run <toolName> --server <url> [--args <json>] [--token <token>] [--header "Key: Value"]...

Options:

• <toolName> (required): Exact tool name.
• --server <url> (required)
• --args <json>: JSON object string (default: {}).
• --token <token>
• --header "Key: Value" (repeatable)

Example:

bunx scoutt run search_docs \
  --server https://api.example.com/mcp \
  --args '{"query":"oauth device flow","limit":5}'

auth

Manage stored credentials for MCP servers.

auth login

Store a bearer token, or run OAuth device flow.

# bearer token login
bunx scoutt auth login --server <url> --token <token>

# import bearer token once from env var
bunx scoutt auth login --server <url> --token-from-env <ENV_VAR_NAME>

# OAuth device flow login
bunx scoutt auth login --server <url> --client-id <id> [--client-secret <secret>] [--scope <scope>]

Options:

• --server <url> (required)
• --token <token>: If provided, saves direct bearer token.
• --token-from-env <ENV_VAR_NAME>: Imports token once from environment variable and stores it for the server.
• --client-id <id>: Required for OAuth flow unless provided by env.
• --client-secret <secret>: Optional OAuth client secret.
• --scope <scope>: Optional scope (default fallback is mcp:tools).

auth status

bunx scoutt auth status --server <url>

Shows whether credentials exist for the server, auth type, and expiry when available.

auth logout

bunx scoutt auth logout --server <url>

Removes stored credentials for the server.

Authentication Resolution Order

For list-tools, generate, and run, auth is resolved in this order:

1. Explicit CLI headers/token (--header, --token)
2. Stored credentials (from credentials file)

If an Authorization header is already set via --header or --token, stored auth is not added.

Environment Variables

• MCP_OAUTH_CLIENT_ID: OAuth client ID fallback for auth login
• SCOUTT_OAUTH_CLIENT_ID: Alternate OAuth client ID fallback
• MCP_OAUTH_CLIENT_SECRET: OAuth client secret fallback
• SCOUTT_OAUTH_CLIENT_SECRET: Alternate OAuth client secret fallback
• SCOUTT_CREDENTIALS_FILE: Override credentials file path

Credential Storage

Default credentials file:

~/.scoutt/credentials.json

Behavior:

• Credentials are keyed by normalized server URL (trailing / removed).
• File is created with mode 0600 when written.
• Stored auth supports both bearer_token and oauth2 payloads.

MCP Protocol Behavior

• Uses JSON-RPC method tools/list for discovery.
• Uses JSON-RPC method tools/call for execution.
• Sends Accept: application/json, text/event-stream.
• Handles MCP responses delivered as:
  • Plain JSON payloads
  • SSE streams (data: events), using the last JSON-RPC event payload

Schema Mapping and Validation

When invoking tools (run and generated CLI commands):

• Arguments are normalized so these keys map to the schema key:
  • schema key (e.g. repo_name)
  • kebab-case flag form (repo-name)
  • Commander camelCase (repoName)
• Values are coerced by schema type:
  • strings → number/integer
  • strings → boolean ("true"/others)
  • strings → JSON for object/array fields
• Input is validated with Zod based on MCP schema:
  • required fields
  • enum values
  • object/array nesting
  • anyOf/oneOf branches
  • nullable types (null support)
• Unknown keys are currently allowed (passthrough).

For generation (generate):

• Schema properties become flag definitions.
• Type mapping includes:
  • boolean → boolean flag (--flag)
  • number/integer → value flag (--flag <value>)
  • array → variadic flag (--flag <value...>)
  • object → JSON-valued flag
• Enum/default metadata is appended into generated option descriptions.

Input Sanitization

Before tools/call, string arguments are sanitized by removing these characters:

• `
• $
• \
• ;
• |
• &

This is a defensive input cleanup step in the current runner implementation.

Examples

Open MCP server (no auth):

bunx scoutt list-tools --server https://mcp.deepwiki.com/mcp

Bearer token via option:

bunx scoutt list-tools --server https://api.githubcopilot.com/mcp/ --token "<token>"

Custom headers (repeatable):

bunx scoutt list-tools --server https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer <token>" \
  --header "X-Custom-Header: value"

Credential lifecycle:

bunx scoutt auth login --server https://api.githubcopilot.com/mcp/ --token "<token>"
bunx scoutt auth status --server https://api.githubcopilot.com/mcp/
bunx scoutt auth logout --server https://api.githubcopilot.com/mcp/

Development

Scripts:

bun run dev           # runs src/index.ts
bun run build         # bun build src/index.ts --outdir dist --target node
bun run start         # run built CLI via node dist/index.js
bun run typecheck     # tsc --noEmit
bun run lint          # eslint + prettier check
bun run lint:fix      # eslint --fix + prettier write
bun run format        # prettier write
bun run format:check  # prettier check

Test example:

bun test src/generator/schemaMapper.test.ts

Package/Binary

• NPM package name: scoutt
• Binary name: scoutt
• Build output entry: dist/index.js
• Published files include: dist, templates

Project Structure

src/
  index.ts              # CLI entrypoint and command registration
  commands/             # list-tools, generate, run, auth commands
  auth/                 # credentials and OAuth device flow
  discovery/            # MCP discovery client
  generator/            # schema-to-flags + code emission
  runner/               # tool invocation, coercion, validation
  utils/                # headers, payload parsing, sanitization
templates/
  command.hbs           # command template artifact

Current Limitations

• run --args must be valid JSON (invalid JSON throws immediately).
• Generated CLI imports scoutt/runner, so the runtime project should have scoutt installed.
• OAuth auto-refresh on token expiry is not implemented.