nexus-tui

A terminal dashboard for browsing, testing, and managing MCP (Model Context Protocol) server connections.

Built with Bubble Tea and Lip Gloss.

Features

• Multi-server connections — connect to multiple MCP servers simultaneously
• Tool browser — scrollable list of discovered tools with descriptions and parameter schemas
• Interactive REPL — typed input fields (string, number, integer, boolean, JSON) generated from tool schemas
• Formatted output — colorized JSON pretty-print with raw toggle (Ctrl+R)
• Dynamic layout — REPL expands on response, resets with Esc
• Config builder — interactive --init wizard to generate your config file
• Debug logging — full request/response log with --debug

Install

Prerequisites: Go 1.25+

# Clone the repo
git clone https://github.com/ironystock/nexus-tui.git
cd nexus-tui

# Build
go build -o bin/nexus-tui ./cmd/nexus-tui/

# Or run directly
go run ./cmd/nexus-tui/

Usage

Quick start

Generate a config file with the interactive builder:

nexus-tui --init

This will prompt you for a server name, URL, and optional bearer token, then write nexus.yaml.

Config format

Create a nexus.yaml in the project root (or pass --config path/to/config.yaml):

servers:
  - name: "My Server"
    url: "https://example.com/mcp"
    headers:
      Authorization: "Bearer YOUR_TOKEN_HERE"

Run

nexus-tui                          # uses ./nexus.yaml
nexus-tui --config my-config.yaml  # custom config path
nexus-tui --debug                  # log requests/responses to nexus-debug.log

Keybindings

Key	Action
Tab / Shift+Tab	Cycle panels (or next field in REPL)
j / k	Navigate lists
Enter	Select server or tool
Ctrl+S	Execute tool call
Ctrl+R	Toggle raw/formatted output
Esc	Back / reset layout
q	Quit

Coming Soon

• History panel — browse past tool calls and responses
• Search & filter — find tools quickly across large catalogs
• Horizontal scroll — handle wide JSON output
• Inline validation — required field checks before execution
• Multi-server workflows — chain tool calls across servers

Contributing

Contributions are welcome! Please open an issue or pull request.

# Run tests
go test ./...

# Vet
go vet ./...

# Tidy modules
go mod tidy

Project structure

cmd/nexus-tui/     Entry point, CLI flags
internal/
  app/             Root Bubble Tea model, layout orchestration
  config/          YAML config loading, interactive builder
  mcp/             Streamable HTTP client, protocol types, server registry
  ui/              Panels: connections, tool browser, REPL, history, status bar, styles

Guidelines

• Keep Update() pure — side effects go in tea.Cmd functions
• Never mutate model state from a goroutine — send a tea.Msg
• Wrap errors with context: fmt.Errorf("context: %w", err)
• Styles live in internal/ui/styles.go

License

MIT