What can you do with this server?

An MCP server for executing shell commands with automatic RTK-based token reduction (~90%), persistent caching, and comprehensive execution logging. * run_process: Execute shell commands with optional RTK auto-filtering, configurable working directory, timeout, description, and per-call cache bypass. Supports streaming output to avoid maxBuffer limitations. * get_cache_stats: View cache hit/miss counts and total cached entries. * clear_command_cache: Wipe all persistently cached command results. * cached_commands: List all cached command keys with timestamps. * execution_log: Retrieve the last N entries from the append-only JSONL execution log, including metadata like duration, exit code, and RTK filtering status. Supports historical archives. * list_archives: List all rotated execution log archive files. * write_file: Write files using base64-encoded content to safely handle special characters that could break JSON serialization. * resolve_uri: Resolve scheme://path URIs to absolute file paths using a TOML config or environment variable.

How do I use server-commands-rtk?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@server-commands-rtk list files in current directory" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

server-commands-rtk

by Ev3lynx727

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

commands-rtk

License: MIT npm version server-commands-rtk MCP server

server-commands-rtk MCP server

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

Tool	Description
`run_process`	Execute a shell command with RTK auto-filtering
`get_cache_stats`	Show cache hit/miss counts and entry count
`clear_command_cache`	Wipe all cached command results
`cached_commands`	List all cached command keys and timestamps
`execution_log`	Read execution log entries, optionally from archives
`list_archives`	List rotated `.jsonl.gz` archive files
`write_file`	Write a file from base64 content (safe for special characters)
`resolve_uri`	Resolve `scheme://path` to absolute file path via TOML config or `MCP_RESOURCE_ROOTS`

Schema

How commands-rtk processes an MCP tool call:

commands-rtk MCP Server Schema

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)

Section	Key	Default	Description
`[execution]`	`timeout_ms`	`60000`	Default per-command timeout (overridable per call)
`[execution]`	`max_buffer_mb`	`10`	Max stdout/stderr collected per command
`[execution]`	`max_log_entries`	`1000`	Entries kept in active log before rotation
`[execution]`	`max_archives`	`50`	Max rotated archive files retained
`[execution]`	`compress_archives`	`true`	Compress rotated logs with gzip
`[cache]`	`debounce_ms`	`2000`	Window for deduplicating identical commands

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):

Primary: ~/.config/uri-resolver/config.toml — shared with the standalone uri-resolver MCP server
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

Command	Raw Tokens	RTK Tokens	Savings
`ls -la`	~25,000	~3,000	88%
`tree`	~50,000	~5,000	90%
`git diff`	~15,000	~500	97%
`npm install`	~5,000	~200	96%

Environment Variables

Variable	Required	Description
`SERVER_DIR`	No	Custom server root (defaults to directory containing `dist/`)
`RTK_MODEL_USED`	No	Override for `model_used` in execution log metadata
`MCP_RESOURCE_ROOTS`	No	JSON object mapping scheme names to directory paths (fallback, TOML config is primary)
`LOG_LEVEL`	No	Log level (`error`, `warn`, `info`, `debug`)

Credit

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

License

MIT

Available Tools

8 tools

cached_commandsA

List all cached commands

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It describes a simple read operation with no side effects, which is transparent enough. However, it does not disclose potential behaviors like pagination, data freshness, or access restrictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (3 words) and front-loaded with the key action and resource. Every word earns its place with zero fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameter-free listing tool, the description is adequate. It tells the agent exactly what the tool does. However, given no output schema or annotations, a bit more context about the return format or scope (e.g., 'all' cached commands) would enhance completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema is empty and coverage is 100%, so the baseline is 4. The description implies no filtering, consistent with the schema. No additional parameter information is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'List all cached commands' specifies a clear verb ('List') and resource ('cached commands'), making the tool's purpose immediately obvious. It naturally distinguishes from sibling tools like 'clear_command_cache' and 'get_cache_stats'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'get_cache_stats' or 'clear_command_cache'. The description gives no context about prerequisites, conditions, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

clear_command_cacheB

Clear all cached commands

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the action ('clear') but does not disclose potential side effects (e.g., does it affect running processes? Is it reversible? Are there permission requirements?). This is insufficient for a destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the core action. It is appropriately concise but could be slightly expanded with context without becoming too long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (no parameters, no output schema, no annotations), the description is minimally adequate. However, it lacks context about what 'cached commands' are, the scope of clearing (e.g., global or per-session), and whether it affects other tools like 'cached_commands' or 'execution_log'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema coverage is 100%. The description does not need to add parameter details. It provides the action, which is sufficient for a parameterless tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Clear all cached commands' uses a specific verb ('clear') and resource ('cached commands'), clearly indicating the action and scope. It distinguishes from sibling tools like 'cached_commands' (which likely reads or lists cache) and 'get_cache_stats' (which provides statistics).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when or when not to use the tool. No mention of prerequisites, side effects, or alternatives. For instance, it might be used after command changes or to free memory, but this is not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

execution_logC

Get execution log (last N entries, optionally including archives)

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`include_archives`	No	Include rotated archive files for full history

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are absent, so description must convey behavioral traits. It only states 'Get' (read-only) and the option to include archives. No mention of idempotency, access control, rate limits, or potential performance impact of large logs. Minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—one sentence fragment conveying core purpose. It is front-loaded and avoids fluff. However, it could be slightly more structured without adding length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without an output schema, the description should explain return format or structure. It does not. Additionally, it lacks behavior details (e.g., ordering, default limit). Given the tool's simplicity, more context is needed for proper usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% (only include_archives has schema description). The tool description adds explanation for 'limit' (last N entries) and clarifies 'include_archives' (optionally), though the latter is redundant. It provides adequate but not exceptional value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'Get' and resource 'execution log' with options. It provides a general sense of the tool's purpose, though it could be more specific about the log context (e.g., system vs. process). It partially distinguishes from sibling 'list_archives' by focusing on logs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives (e.g., list_archives for archive files). No context about prerequisites or scenarios. The description implies basic usage but fails to set usage boundaries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_cache_statsC

Get cache statistics

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; the description implies a read-only operation but does not explicitly state it. No details on side effects or prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise (two words), but lacks detail on return value and usage context. Could be slightly expanded without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no description of what statistics are returned. Incomplete for a tool that produces output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist (100% schema coverage), so the description adds no parameter information but is not required to.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool retrieves cache statistics, distinguishing it from sibling tools like cached_commands and clear_command_cache. However, it does not specify what type of statistics (e.g., hit rate, size).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description gives no context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_archivesA

List all rotated log archive files for dataset pipeline

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description is minimal. It does not disclose behavioral traits such as side effects, permissions, or rate limits. The description only states the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words. Front-loaded with the main action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a simple tool with no parameters and no output schema. However, it lacks detail on what the archive files are or what the output looks like, leaving some ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so schema coverage is 100%. The description adds no param info, but none is needed. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list) and the resource (rotated log archive files) with a specific context (for dataset pipeline). It distinguishes from sibling tools which focus on caching and execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description implies usage for listing archives, but no exclusions or context for when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_uriA

Resolve a scheme:// URI to an absolute file path. Uses schemes registered via MCP_RESOURCE_ROOTS env var (headquarters://, vaults://, etc.). scheme://. resolves to the base directory.

ParametersJSON Schema

Name	Required	Description	Default
`uri`	Yes	URI to resolve, e.g. headquarters://docs/api.md or vaults://.

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses key behaviors: resolves to absolute paths, uses registered schemes, and special handling of 'scheme://.' for the base directory. It does not cover error cases or missing schemes, but is adequate for the tool's simplicity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The most important information is front-loaded, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only one parameter, no output schema, and low complexity, the description is complete enough. It explains purpose, usage dependency, and edge case (dot for base directory).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, providing a baseline of 3. The description adds value by giving explicit examples and the special case of 'scheme://.', which enhances understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool resolves a scheme:// URI to an absolute file path, using a specific verb and resource. It distinguishes itself from siblings which are about commands, cache, and file operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context about when to use (to resolve URIs) and mentions the dependency on MCP_RESOURCE_ROOTS env var. However, it does not explicitly state when not to use or provide alternatives, though siblings are unrelated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_processC

Run shell command. Auto-prefixed with rtk for token minimization (60-90% savings).

ParametersJSON Schema

Name	Required	Description
`cwd`	No
`command`	Yes
`model_used`	No	Model name that executed this command (for training metadata)
`timeout_ms`	No	Per-command timeout in milliseconds (overrides server default)
`clear_cache`	No
`description`	No

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose all behavioral traits. It mentions auto-prefixing but omits critical details such as whether commands are destructive, output handling, failure modes, or permission requirements. The token saving claim is useful but insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short at two sentences and front-loaded with the action. However, it sacrifices necessary detail for brevity. It is efficient but incomplete, resulting in a mediocre conciseness score.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters, no output schema, and no annotations, the description is severely inadequate. It does not cover parameter meanings, return values, error states, or interaction with sibling tools. The description fails to provide a complete understanding of the tool's capabilities.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 33% (2 of 6 parameters have descriptions). The tool description adds no parameter context, leaving most parameters (cwd, command, clear_cache, description) completely unexplained. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Run shell command' as a specific verb and resource. While it does not explicitly differentiate from sibling tools like cached_commands or execution_log, the core action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions auto-prefixing with rtk for token savings, which is a usage hint, but it provides no guidance on when to use this tool versus alternatives like cached_commands or resolve_uri. No context on prerequisites or best practices.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_fileA

Write a file with base64-encoded content. Use this instead of write/filesystem_write_file when content contains special chars that break JSON serialization.

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes	Absolute path to output file
`content_b64`	Yes	Base64-encoded file content

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the key behavioral trait of base64 encoding and handling special characters. However, it does not mention other behaviors like overwriting existing files or required permissions, which are reasonable expectations for a file write tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The first sentence states the action, the second provides usage guidance. Efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple file write tool with no output schema, the description is complete. It explains what it does, how to use it, and when to prefer it over an alternative. The two parameters are fully described in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. The description adds context about why base64 encoding is used, which enhances understanding beyond the schema. However, the schema already clearly describes the parameters, so the description adds moderate additional meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Write a file with base64-encoded content.' It clearly identifies the verb (write), resource (file), and distinguishing feature (base64 encoding). It also distinguishes from the sibling tool 'write/filesystem_write_file' by mentioning special character handling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'Use this instead of write/filesystem_write_file when content contains special chars that break JSON serialization.' This clearly states when to use this tool and offers a specific alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv0.2.3Jul 7, 2026

Changedexecution_log1 field changed

addedInput schema / properties / include_archives

Added value: +{
+  "default": false,
+  "description": "Include rotated archive files for full history",
+  "type": "boolean"
+}

Addedlist_archives
Addedresolve_uri

Changedrun_process3 fields changed

addedInput schema / properties / timeout_ms

Added value: +{
+  "description": "Per-command timeout in milliseconds (overrides server default)",
+  "type": "number"
+}

removedInput schema / properties / use_raw

Removed value: -{
-  "default": false,
-  "description": "Run raw command without RTK filtering (bypasses auto-RTK)",
-  "type": "boolean"
-}

removedInput schema / properties / use_rtk_filter

Removed value: -{
-  "default": true,
-  "description": "Auto-wrap with RTK for token-minimized output (default: true)",
-  "type": "boolean"
-}

6 tool updatesv0.2.0Jun 20, 2026
- First observedcached_commands
- First observedclear_command_cache
- First observedexecution_log
- First observedget_cache_stats
- First observedrun_process
- First observedwrite_file

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0

Scored 2026-07-07 02:01 across 8 tools

Disambiguation5/5

Each tool targets a distinct action or resource: cache listing/clearing/stats, log retrieval/archives, URI resolution, process execution, and file writing. No overlapping purposes.

Naming Consistency5/5

All tool names use consistent snake_case and follow a verb_noun pattern (e.g., list_archives, run_process, write_file). No mixed conventions.

Tool Count5/5

8 tools is well-scoped for a command server utility set. Each tool serves a clear need without excess or deficiency.

Completeness4/5

Covers core operations (run, write, cache management, logging, URI resolution). Minor gap: no tool to delete or manipulate archive files, but core workflows are covered.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

KodyOAuth
io.github.kentcdodds
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
Developer Tools Code Execution Command Line
2616
supportsheep
io.github.pooriaarab
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Customer Support Content Management Systems Marketing
1
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
MoneMeeOAuth
com.monemee
Remote MCP server for creating and selling digital products via MoneMee. It lets AI agents create, publish, and sell digital products such as e-books, AI prompt packs, software, courses without a human touching a dashboard. Docs: https://monemee.com/mcp Sign up on Monemee to get a token.
Art & Culture Browser Automation
1

Related MCP Servers

mcp-shell
Shell Access Command Line
sonirico
A
license
Not graded
quality
A
maintenance
Give hands to AI. MCP server to run shell commands securely, auditably, and on demand.
Updated 8 days ago (2026-09-04 10:58 UTC)
105
GPL 3.0
Whisper CLI MCP Server
yhsung
A
license
Not graded
quality
D
maintenance
An MCP server that provides shell command execution and OpenAI Whisper transcription capabilities for audio files.
Updated a year ago (2025-07-18 07:47 UTC)
1
MIT
MCP Background Job Server
Shell Access Code Execution Developer Tools
dylan-gluck
A
license
A
quality
D
maintenance
An MCP server that enables coding agents to execute and manage long-running shell commands asynchronously with capabilities for process monitoring, interaction, and lifecycle management.
Updated a year ago (2025-08-06 02:03 UTC)
7
13
MIT
MCP Terminal Tool Server
Shell Access Command Line OS Automation
gkgaurav31
F
license
B
quality
D
maintenance
An MCP server that enables users to execute arbitrary shell commands on their local machine and receive the output. It provides a terminal tool for running system commands through MCP-compatible clients using the Python SDK.
Updated a year ago (2025-08-05 17:07 UTC)
1
-