TUI MCP Server

An MCP (Model Context Protocol) server that enables AI agents to interact with terminal-based applications through interminai.

Features

• 10 MCP tools for complete TUI control: start, input, output, status, wait, resize, signal, stop, debug, observe
• Session management with automatic inactivity timeout cleanup
• Security with configurable command allowlist and blocked patterns
• Escape sequence support for arrow keys, function keys, and special characters
• Configurable session timeouts and security policies via environment variables

Prerequisites

• Go 1.25+
• interminai installed and available in PATH

Installation

# Clone the repository
git clone git@github.com:fridegAI/tui-mcp.git
cd tui-mcp

# Build
go build -o tui-mcp ./cmd/tui-mcp

# Or install globally
go install ./cmd/tui-mcp

Configuration

The server can be configured using environment variables. These can be set in the MCP client configuration.

MCP Client Configuration

Make sure to add the environment variables to the env object in your MCP client configuration.

Example (Generic JSON):

{
  "mcpServers": {
    "tui": {
      "command": "/path/to/tui-mcp",
      "env": {
        "SESSION_TIMEOUT": "10m",
        "ALLOWED_COMMANDS": "gdb,python,bash",
        "BLOCKED_PATTERNS": "rm"
      }
    }
  }
}

MCP Tools

Usage Example

Agent: Start vim to edit a file
→ tui.start {"command": "vim test.txt", "rows": 24, "cols": 80}
← {"session_id": "/tmp/interminai-xxx/socket", "pid": 12345}

Agent: Type some text
→ tui.input {"session_id": "...", "text": "iHello World"}

Agent: Save and quit
→ tui.input {"session_id": "...", "text": "\e:wq\r"}

Agent: Cleanup
→ tui.stop {"session_id": "..."}

Escape Sequences

The tui.input tool supports C-style escapes (\r, \n, \t, \e) and hex escapes (\xHH).

Arrow Keys

The escape sequence for arrow keys depends on the terminal's Cursor Mode (Normal vs Application).

Tip: Use tui.debug to inspect the current termios mode if keys are not behaving as expected.

Security

The server enforces a strict allowlist policy by default.

Default Policy

• Allowed Commands:
  • Read commands: head, tail, less, more
  • Text editors: vim, nvim, vi, nano, emacs
  • Version control: git
  • System information: htop, top, man
  • Network tools: netstat, ping, traceroute, nc
• Blocked Patterns:
  • Recursive deletion: rm -rf, rm -fr, rm -r /, rm -f /
  • File system operations: mkfs, dd if=
  • Device writes: > /dev/
  • File permissions: chmod -R 777, chown -R

Customization

You can extend the allowed list or add new blocked patterns via environment variables:

• ALLOWED_COMMANDS: Add specific tools required for your workflow (e.g., gdb, python, bash).
• BLOCKED_PATTERNS: Block specific arguments or dangerous command combinations (e.g., rm).

Development

# Run tests
go test -v ./...

# Build
go build -o tui-mcp ./cmd/tui-mcp

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License