Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Select an option

  • Save Ev3lynx727/0b1193494f474560883be9a4ce1ab70c to your computer and use it in GitHub Desktop.

Select an option

Save Ev3lynx727/0b1193494f474560883be9a4ce1ab70c to your computer and use it in GitHub Desktop.
Complete guide: Integrating server-commands-rtk MCP server with GitHub Copilot CLI

Integrating server-commands-rtk with GitHub Copilot CLI

A complete guide to install, configure, and use the MCP server for shell command execution, caching, and logging within Copilot CLI.

What is server-commands-rtk?

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)


Prerequisites

  • Node.js 24+ (ESM support)
  • rtk CLI installed: curl -LsSf https://ev3lynx.github.io/rtk/install.sh | sh
  • Copilot CLI installed and authenticated

Step 1: Build server-commands-rtk

Clone or navigate to the repository:

cd ~/server/server-commands-rtk
npm install
npm run build

Output: TypeScript compiled to dist/index.js


Step 2: Register MCP Server with Copilot CLI

Register the local MCP server:

copilot mcp add server-commands-rtk -- node /home/ev3lynx/server/server-commands-rtk/dist/index.js

Verify registration:

copilot mcp list

Expected output:

server-commands-rtk
  Type: local
  Command: node /home/ev3lynx/server/server-commands-rtk/dist/index.js
  Tools: * (all)
  Source: User

Step 3: Verify MCP Connection

Test that Copilot can communicate with the server:

bash ~/server/server-commands-rtk/test-rtk.sh | node ~/server/server-commands-rtk/dist/index.js

Expected: Server responds with JSON-RPC results (initialize, run_process, get_cache_stats, etc.)


Available MCP Tools

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

Usage in Copilot CLI

Basic Command Execution

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

Query Cache Statistics

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
}

Query Execution Log

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.

Bypass RTK Filtering (Full Output)

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

Cache Hits Demo

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.

Write Files Safely

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:

  1. Base64 encode the content
  2. Call write_file with base64 parameter
  3. Server decodes and writes safely

Configuration (rtk-hook.toml)

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 window

Adjust Timeout Per Command

When invoking via Copilot, you can override the timeout:

! long-running-command (with timeout_ms: 120000)

Execution Log & Caching

Persistent Execution Log

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
}

View Recent Executions

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 Key (SHA-256 Hash)

Cache keys are derived from: SHA256(command + cwd)

Same command in same directory → cache hit.
Same command in different directory → cache miss.

Clear Cache

Warning: This wipes all cached results.

copilot --mcp run-process clear_command_cache

Or ask Copilot:

> Clear the command cache for server-commands-rtk

Token Savings (Auto-RTK Filtering)

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.


Troubleshooting

MCP Server Not Found

copilot mcp list
# Output: No MCP servers configured

Fix: Re-register the server:

copilot mcp add server-commands-rtk -- node /home/ev3lynx/server/server-commands-rtk/dist/index.js

Build Fails

cd ~/server/server-commands-rtk
npm run verify

Should compile without errors. If TypeScript errors occur:

npm install  # Reinstall dependencies
npm run build --verbose

Commands Timeout

Increase timeout_ms in rtk-hook.toml or per-command:

[execution]
timeout_ms = 120000  # 2 minutes

Large Output Truncated

Check max_buffer_mb:

[execution]
max_buffer_mb = 50  # Increase from 10 to 50

Cache Not Working

Verify cache file exists:

ls -lh ~/server/server-commands-rtk/.command-cache.json

Check cache stats:

> Show cache stats

If stuck at 0 hits, cache is recording but deduplication may depend on exact command + cwd match.


Advanced: Custom Environment Variables

Set RTK_MODEL_USED to track which model executed commands:

export RTK_MODEL_USED="claude-sonnet-4"
copilot  # Launches Copilot with model metadata in logs

Set custom SERVER_DIR:

export SERVER_DIR="/custom/path/to/server"
node ~/server/server-commands-rtk/dist/index.js

Integration with OpenCode / Other Agents

Add 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.


Quick Reference

# 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

Architecture Overview

┌─────────────────────┐
│   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) │
└──────────────────────────────────┘

Next Steps

  1. Register the server — copilot mcp add ...
  2. Verify connectivity — copilot mcp list
  3. Test execution — In Copilot CLI, try ! ls -la
  4. Monitor performance — Ask Copilot to show cache stats and execution logs
  5. Tune configuration — Adjust rtk-hook.toml as needed

License

MIT — server-commands-rtk is open source and available at https://github.com/ev3lynx727/server-commands-rtk


Support & Feedback


Related Documentation (Local)

For deeper integration details, see the project's local documentation (in develop branch):

Quick Links

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment