A complete guide to install, configure, and use the MCP server for shell command execution, caching, and logging within Copilot CLI.
server-commands-rtk is a Model Context Protocol (MCP) server that provides intelligent shell command execution for AI agents with:
- Streaming execution — no output buffering limits
- Auto-RTK filtering — ~90% token reduction on large outputs
- Smart caching — deduplicates identical commands
- Persistent logging — all executions recorded with metadata
- Safe file writes — handles special characters via base64
- Timeout control — configurable per-command timeout + graceful cancellation
Estimated token savings: ls -la (25K tokens) → 3K tokens (88% reduction)
- Node.js 24+ (ESM support)
- rtk CLI installed:
curl -LsSf https://ev3lynx.github.io/rtk/install.sh | sh - Copilot CLI installed and authenticated
Clone or navigate to the repository:
cd ~/server/server-commands-rtk
npm install
npm run buildOutput: TypeScript compiled to dist/index.js
Register the local MCP server:
copilot mcp add server-commands-rtk -- node /home/ev3lynx/server/server-commands-rtk/dist/index.jsVerify registration:
copilot mcp listExpected output:
server-commands-rtk
Type: local
Command: node /home/ev3lynx/server/server-commands-rtk/dist/index.js
Tools: * (all)
Source: User
Test that Copilot can communicate with the server:
bash ~/server/server-commands-rtk/test-rtk.sh | node ~/server/server-commands-rtk/dist/index.jsExpected: Server responds with JSON-RPC results (initialize, run_process, get_cache_stats, etc.)
Once registered, Copilot CLI has access to these tools:
| Tool | Purpose |
|---|---|
run_process |
Execute shell commands with optional RTK filtering |
get_cache_stats |
Show cache hit/miss counts |
execution_log |
Read recent execution entries |
cached_commands |
List all cached command keys |
clear_command_cache |
Wipe cache (use carefully) |
list_archives |
Show rotated log archive files |
write_file |
Write files safely with base64 content |
In Copilot CLI, use the ! prefix to run shell commands:
! ls -la /home/ev3lynx/server/server-commands-rtk
! npm list
! git status
! uname -a
Under the hood: Copilot invokes run_process with auto-RTK filtering enabled (90% token reduction).
Ask Copilot to show cache stats:
> Show me the cache statistics for server-commands-rtk
Copilot invokes get_cache_stats and displays:
{
"hits": 5,
"misses": 42
}Ask Copilot to show recent executions:
> Show the last 10 execution log entries
Copilot invokes execution_log with limit: 10 and displays timestamp, command, cache status, exit code, and errors.
For debugging, disable RTK filtering in tool parameters:
! ls -la (with use_rtk_filter: false)
Result: Full unfiltered output (higher token cost, useful for manual inspection).
Run the same command twice to test caching:
! echo "test cache"
! echo "test cache"
Then check cache stats:
> Show cache stats
Expected: hits increments by 1 on second call.
For files with special characters (quotes, backticks, etc.), ask Copilot to use write_file:
> Create a file with this content:
Content: "Hello \"World\" with `backticks`"
Path: /tmp/test.txt
Copilot will:
- Base64 encode the content
- Call
write_filewith base64 parameter - Server decodes and writes safely
Located at: ~/server/server-commands-rtk/rtk-hook.toml
[execution]
timeout_ms = 60000 # Command timeout (milliseconds)
max_buffer_mb = 10 # Max stdout/stderr per command
max_log_entries = 1000 # Entries before log rotation
max_archives = 50 # Max rotated archives kept
compress_archives = true # Gzip compress rotated logs
[cache]
debounce_ms = 2000 # Duplicate command debounce windowWhen invoking via Copilot, you can override the timeout:
! long-running-command (with timeout_ms: 120000)
Every command execution is logged to .execution-log.jsonl:
{
"timestamp": 1782727383912,
"key": "64edc19c86187aba",
"command": "uname -a",
"cached": false,
"result": {
"success": true,
"stdout": "Linux DESKTOP-VQN0VVJ ...",
"exitCode": 0,
"duration_ms": 131,
"error_type": null
},
"rtk_filtered": true
}Query the log via Copilot:
# Via Copilot CLI
> Show the last 5 execution log entries
# Manual query
tail -n 20 ~/server/server-commands-rtk/.execution-log.jsonl | jq .Cache keys are derived from: SHA256(command + cwd)
Same command in same directory → cache hit.
Same command in different directory → cache miss.
Warning: This wipes all cached results.
copilot --mcp run-process clear_command_cacheOr ask Copilot:
> Clear the command cache for server-commands-rtk
| 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% |
Example: In a long Copilot session, auto-RTK saves thousands of tokens automatically.
copilot mcp list
# Output: No MCP servers configuredFix: Re-register the server:
copilot mcp add server-commands-rtk -- node /home/ev3lynx/server/server-commands-rtk/dist/index.jscd ~/server/server-commands-rtk
npm run verifyShould compile without errors. If TypeScript errors occur:
npm install # Reinstall dependencies
npm run build --verboseIncrease timeout_ms in rtk-hook.toml or per-command:
[execution]
timeout_ms = 120000 # 2 minutesCheck max_buffer_mb:
[execution]
max_buffer_mb = 50 # Increase from 10 to 50Verify cache file exists:
ls -lh ~/server/server-commands-rtk/.command-cache.jsonCheck cache stats:
> Show cache stats
If stuck at 0 hits, cache is recording but deduplication may depend on exact command + cwd match.
Set RTK_MODEL_USED to track which model executed commands:
export RTK_MODEL_USED="claude-sonnet-4"
copilot # Launches Copilot with model metadata in logsSet custom SERVER_DIR:
export SERVER_DIR="/custom/path/to/server"
node ~/server/server-commands-rtk/dist/index.jsAdd to ~/.opencode/config.json:
{
"mcp": {
"server-commands-rtk": {
"type": "local",
"command": ["node", "/home/ev3lynx/server/server-commands-rtk/dist/index.js"],
"enabled": true,
"timeout": 60000
}
}
}Then restart your agent — run_process and other tools are available.
# Build
npm run build
# Register with Copilot
copilot mcp add server-commands-rtk -- node /path/to/dist/index.js
# List registered servers
copilot mcp list
# Test connectivity
bash test-rtk.sh | node dist/index.js
# View recent logs
tail -n 20 .execution-log.jsonl | jq .
# View cache stats
jq . .command-cache.json | head -20
# In Copilot CLI:
! <command> # Execute with RTK filtering
> Show cache stats # Query cache statistics
> Show last 10 execution entries # Query execution log┌─────────────────────┐
│ Copilot CLI │
└──────────┬──────────┘
│ (JSON-RPC over stdio)
▼
┌──────────────────────────────────┐
│ server-commands-rtk (MCP server) │
├──────────────────────────────────┤
│ Tools: │
│ - run_process (with RTK filter) │
│ - get_cache_stats │
│ - execution_log │
│ - cached_commands │
│ - write_file (base64) │
├──────────────────────────────────┤
│ Storage: │
│ - .command-cache.json (persist) │
│ - .execution-log.jsonl (append) │
│ - .execution-log.archives/ (gz) │
└──────────────────────────────────┘
- Register the server —
copilot mcp add ... - Verify connectivity —
copilot mcp list - Test execution — In Copilot CLI, try
! ls -la - Monitor performance — Ask Copilot to show cache stats and execution logs
- Tune configuration — Adjust
rtk-hook.tomlas needed
MIT — server-commands-rtk is open source and available at https://github.com/ev3lynx727/server-commands-rtk
- Report issues: GitHub Issues
- Feature requests: GitHub Discussions
- Direct feedback: @ev3lynx727 on GitHub
For deeper integration details, see the project's local documentation (in develop branch):
- OPENCODE_INTEGRATION.md — Complete OpenCode agent configuration, architecture, and per-agent tool setup
- 000_user_experiences.md — MCP JSON serialization issues &
write_filebase64 encoding (token cost analysis) - BENCHMARK.md — Performance benchmarks and RTK token savings validation
- GitHub Repository: https://github.com/ev3lynx727/server-commands-rtk
- Project Root: ~/server/server-commands-rtk/
- MCP Configuration: ~/.config/opencode/opencode.jsonc
- Server Config: ~/server/server-commands-rtk/rtk-hook.toml