commands-rtk

MCP server that executes shell commands via MCP tools - with streaming spawn, automatic RTK token reduction, persistent caching, and full execution logging.

• Streaming spawn - uses spawn (not exec), no maxBuffer ceiling, pipes stdout/stderr directly

• Auto-RTK - transparently wraps commands with RTK for ~90% token reduction

• Timeout + cancellation - AbortController cancels stream collection immediately, SIGKILL terminates process tree

• Persistent cache - results cached in ~/.local/share/state/commands-rtk/command-cache.json across sessions

• Execution logger - append-only JSONL with auto-rotation, gzip compression, archive listing

• Safe file writes - write_file with base64 content avoids JSON serialization breakage on special characters

• URI resolver - resolve_uri resolves scheme://path to absolute file paths via shared TOML config

Includes

• ✅ License - This repository contains a LICENSE file

• ✅ Prompts - This MCP Server includes prompts users can invoke

• ✅ Resources - This MCP Server includes resources for attaching and managing context data

Related MCP server: Whisper CLI MCP Server

Requirements

• Node.js 24+ (ESM, "type": "module" in package.json)

• rtk CLI - install via curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

Installation

npx (no install)

npx commands-rtk                    # Run MCP server (downloads on demand)
npx commands-rtk setup              # Apply one-time patches (rtk fix, etc.)

npm (global install)

npm install -g commands-rtk
commands-rtk setup                  # One-time patch setup

From source

git clone https://github.com/Ev3lynx727/server-commands-rtk.git
cd server-commands-rtk
npm install
npm run build
npm run setup                       # One-time patch setup (rebuilds rtk from source if needed)

npx (no install, MCP client config)

{
  "mcpServers": {
    "commands-rtk": {
      "command": "npx",
      "args": ["commands-rtk"],
      "env": {}
    }
  }
}

First run: Run npx commands-rtk setup once before first use to apply one-time patches.

Global install (MCP client config)

{
  "mcpServers": {
    "commands-rtk": {
      "command": "commands-rtk",
      "args": [],
      "env": {}
    }
  }
}

OpenCode

{
  "mcp": {
    "commands-rtk": {
      "type": "local",
      "command": ["node", "/path/to/commands-rtk/dist/index.js"],
      "enabled": true,
      "timeout": 60000
    }
  }
}

Tools

Schema

How commands-rtk processes an MCP tool call:

The flow: server.ts receives tools/call → Zod.parse() validates → executor.ts spawns with rtk prefix → result cached + logged → JSON-RPC response returned.

Usage

// Auto-RTK (default) - ~90% token reduction
run_process({command: "ls -la"})

// Bypass RTK filtering entirely
run_process({command: "ls -la"})

// Explicitly enable/disable RTK
run_process({command: "ls -la"})

// Override default timeout (60s) per call
run_process({command: "sleep 30", timeout_ms: 5000})

// Set working directory and attach metadata
run_process({
  command: "npm test",
  cwd: "/path/to/project",
  description: "run unit tests",
  model_used: "claude-sonnet-4",
  timeout_ms: 30000
})

// Force cache bypass
run_process({command: "npm install", clear_cache: true})

execution_log

// Tail last 100 entries
execution_log({limit: 100})

// Include rotated archives for full history
execution_log({limit: 500, include_archives: true})

write_file

MCP tool parameters are JSON-serialized. Content with quotes, backticks, or long special-character strings can break the JSON framing. Use write_file with base64 encoding:

write_file({
  path: "/tmp/output.txt",
  content_b64: "SGVsbG8gV29ybGQ="
})

resolve_uri

resolve_uri({uri: "headquarters://."})
// { scheme: "headquarters", relativePath: ".", absolutePath: "/home/ev3lynx/headquarters" }

resolve_uri({uri: "datasets://train/run-001.parquet"})
// { scheme: "datasets", relativePath: "train/run-001.parquet", absolutePath: "/home/ev3lynx/datasets/memory-graph/train/run-001.parquet" }

Schemes are loaded from ~/.config/uri-resolver/config.toml (primary) with MCP_RESOURCE_ROOTS as fallback. scheme://. resolves to the base directory.

list_archives

list_archives()
// Returns: { archives: ["file1.jsonl.gz", ...], count: 7 }

Configuration (rtk-hook.toml)

Example:

[execution]
timeout_ms = 60000
max_buffer_mb = 10
max_log_entries = 1000
max_archives = 50
compress_archives = true

[cache]
debounce_ms = 2000

State Files

All runtime state lives under ~/.local/share/state/commands-rtk/:

~/.local/share/state/commands-rtk/
├── command-cache.json      # Persistent command cache
└── execution-log.jsonl     # Append-only execution log

Created automatically on first run (mkdirSync with recursive: true).

Cache

• File: command-cache.json - persistent JSON, survives server restart

• Key: SHA-256 hash of (command + cwd)

• Stats: Hit/miss counters via get_cache_stats

• Flush: Written to disk on every mutation + on SIGTERM/SIGINT

Execution Log

• File: execution-log.jsonl - append-only, one JSON object per line

• Rotation: When max_log_entries reached, half of entries archived. Rotated files land alongside the active log as execution-log-{timestamp}.jsonl.gz

• Per-entry metadata: timestamp, key, command, rtk_filtered, rtk_rewritten, cached, success, exitCode, duration_ms, error_type, stdout/stderr, stdout_lines/stderr_lines, model_used

MCP Resources & URI Resolution

Resource templates and URI resolution share a unified scheme registry loaded from two sources (TOML wins):

1. Primary: ~/.config/uri-resolver/config.toml — shared with the standalone uri-resolver MCP server

2. Fallback: MCP_RESOURCE_ROOTS env var — for deployment-specific overrides

export MCP_RESOURCE_ROOTS='{"headquarters": "~/headquarters"}'

Each scheme registers a resource template {scheme}://{path} and is queryable via the resolve_uri tool. Path traversal is denied via startsWith() guard.

Response Format

All tools return JSON:

{
  "cached": false,
  "key": "sha256-hash",
  "command": "echo hello",
  "result": {
    "success": true,
    "stdout": "hello\n",
    "stderr": "",
    "exitCode": 0,
    "duration_ms": 12,
    "error_type": null
  },
  "rtk_filtered": true,
  "rtk_rewritten": true
}

Error types: timeout, not_found (ENOENT), permission_error (EACCES/EPERM), memory_error (ENOMEM), unknown_error.

Timeout returns exitCode: 124 with message in stderr.

Token Savings

Environment Variables

Credit

This project would not work without RTK — the Rust token reducer that filters shell command output for ~90% token savings.

License

MIT