@standardbeagle/mcp-tui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 MCP-TUI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# MCP-TUI
+
+A Go-based test client for Model Context Protocol (MCP) servers with both interactive TUI and CLI modes.
+
+## Features
+
+- **Interactive TUI Mode**: Browse and interact with MCP servers using a terminal user interface
+- **CLI Mode**: Scriptable command-line interface for automation
+- **Multiple Transport Types**: Support for stdio, SSE, and HTTP connections
+- **Server Inspection**: List available tools, resources, and prompts
+- **Dynamic Tool Forms**: Automatically generated forms based on tool schemas
+- **Tool Execution**: Call MCP tools with properly validated arguments
+- **Type Conversion**: Automatic conversion of string inputs to required types (numbers, booleans, arrays)
+- **Progress Tracking**: Real-time progress display for long-running operations with elapsed time
+- **Scrollable Output**: Large results can be scrolled with arrow keys, PgUp/PgDn
+- **Clipboard Support**: Paste with right-click (Windows Terminal) or terminal's paste shortcut
+
+## Installation
+
+### Via Go Install
+
+```bash
+go install github.com/standardbeagle/mcp-tui@latest
+```
+
+### Via npm/npx
+
+```bash
+# Install globally
+npm install -g @standardbeagle/mcp-tui
+
+# Or use directly with npx
+npx @standardbeagle/mcp-tui
+```
+
+### Build from Source
+
+```bash
+git clone https://github.com/standardbeagle/mcp-tui.git
+cd mcp-tui
+go build -o mcp-tui .
+```
+
+## Usage
+
+### Interactive Mode (Default)
+
+Start the interactive TUI:
+
+```bash
+mcp-tui
+```
+
+Use Tab to switch between connection types (STDIO/SSE/HTTP), enter connection details, and navigate with arrow keys.
+
+#### Testing with Sample Server
+
+To test with the official MCP sample server:
+
+1. In the TUI, select STDIO connection
+2. Enter command: `npx`
+3. Enter args: `@modelcontextprotocol/server-everything stdio`
+4. Press Enter to connect
+
+The sample server includes tools that demonstrate various MCP features:
+- **echo**: Simple text echo
+- **add**: Number addition (demonstrates type conversion)
+- **longRunningOperation**: Configurable delay (tests progress tracking)
+- **sampleLLM**: LLM sampling demonstration
+- **printEnv**: Shows environment variables
+- **getTinyImage**: Returns an image
+- **annotatedMessage**: Demonstrates content annotations
+
+### CLI Mode
+
+The CLI mode provides Git-like subcommands for interacting with MCP servers.
+
+#### Basic Connection Options
+
+All commands require connection parameters:
+- `--type`: Server type (stdio, sse, or http)
+- `--cmd`: Command for stdio servers
+- `--args`: Arguments for stdio command (comma-separated)
+- `--url`: URL for SSE or HTTP servers
+- `--json`: Output results in JSON format
+
+#### Tool Commands
+
+List available tools:
+```bash
+mcp-tui --cmd npx --args "@modelcontextprotocol/server-everything,stdio" tool list
+```
+
+Get detailed information about a tool:
+```bash
+mcp-tui --cmd npx --args "@modelcontextprotocol/server-everything,stdio" tool describe echo
+```
+
+Call a tool with arguments:
+```bash
+mcp-tui --cmd npx --args "@modelcontextprotocol/server-everything,stdio" tool call echo message="Hello World"
+mcp-tui --cmd npx --args "@modelcontextprotocol/server-everything,stdio" tool call add a=5 b=3
+```
+
+#### Resource Commands
+
+List available resources:
+```bash
+mcp-tui --cmd python --args "server.py" resource list
+```
+
+Read a resource by URI:
+```bash
+mcp-tui --cmd python --args "server.py" resource read "file:///path/to/resource"
+```
+
+#### Prompt Commands
+
+List available prompts:
+```bash
+mcp-tui --url "http://localhost:8000" --type http prompt list
+```
+
+Get a prompt with arguments:
+```bash
+mcp-tui --url "http://localhost:8000" --type http prompt get complex_prompt temperature=0.7 style=formal
+```
+
+#### JSON Output
+
+All commands support JSON output for scripting:
+```bash
+# Get tools as JSON
+mcp-tui --cmd npx --args "@modelcontextprotocol/server-everything,stdio" --json tool list
+
+# Pipe to jq for processing
+mcp-tui --cmd npx --args "@modelcontextprotocol/server-everything,stdio" --json tool list | jq '.[].name'
+```
+
+## Connection Types
+
+- **stdio**: Connect to MCP servers via standard input/output
+- **sse**: Connect via Server-Sent Events
+- **http**: Connect via HTTP streaming
+
+## Requirements
+
+- Go 1.20+ (for building from source)
+- Node.js 14+ (for npm installation)
+
+## Dependencies
+
+- [bubbletea](https://github.com/charmbracelet/bubbletea) - TUI framework
+- [lipgloss](https://github.com/charmbracelet/lipgloss) - Terminal styling
+- [cobra](https://github.com/spf13/cobra) - CLI framework  
+- [mcp-go](https://github.com/mark3labs/mcp-go) - MCP protocol implementation
+
+## Interactive Controls
+
+- **Tab**: Switch connection types
+- **Arrow Keys/j/k**: Navigate menus
+- **Enter**: Select/Execute
+- **q/Ctrl+C**: Quit
+- **Backspace**: Edit input fields
+
+## Publishing
+
+### For Go Module Maintainers
+
+1. Update the module path in `go.mod` to your GitHub repository
+2. Tag a release:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+3. The module will be available via `go install github.com/standardbeagle/mcp-tui@latest`
+
+### For npm Package Maintainers
+
+1. Update the repository URLs in `package.json`
+2. Build binaries for all platforms
+3. Create a GitHub release with the binaries
+4. Publish to npm:
+   ```bash
+   npm publish
+   ```
+
+## Building Release Binaries
+
+To build binaries for multiple platforms:
+
+```bash
+# Linux amd64
+GOOS=linux GOARCH=amd64 go build -o dist/mcp-tui_linux_amd64 .
+
+# macOS amd64
+GOOS=darwin GOARCH=amd64 go build -o dist/mcp-tui_darwin_amd64 .
+
+# macOS arm64
+GOOS=darwin GOARCH=arm64 go build -o dist/mcp-tui_darwin_arm64 .
+
+# Windows amd64
+GOOS=windows GOARCH=amd64 go build -o dist/mcp-tui_windows_amd64.exe .
+```
+
+## License
+
+MIT

package/bin/mcp-tui.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+const { execFile } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+// Determine the binary name based on the platform
+function getBinaryName() {
+  const platform = os.platform();
+  const arch = os.arch();
+  
+  let binaryName = 'mcp-tui';
+  
+  if (platform === 'win32') {
+    binaryName += '.exe';
+  }
+  
+  return binaryName;
+}
+
+// Get the path to the binary
+function getBinaryPath() {
+  const binaryName = getBinaryName();
+  const binaryDir = path.join(__dirname, '..', 'binaries');
+  const binaryPath = path.join(binaryDir, binaryName);
+  
+  return binaryPath;
+}
+
+// Execute the binary
+function runBinary() {
+  const binaryPath = getBinaryPath();
+  
+  // Check if binary exists
+  if (!fs.existsSync(binaryPath)) {
+    console.error(`Error: Binary not found at ${binaryPath}`);
+    console.error('Please run "npm install" to download the binary.');
+    process.exit(1);
+  }
+  
+  // Make sure the binary is executable (Unix-like systems)
+  if (process.platform !== 'win32') {
+    try {
+      fs.chmodSync(binaryPath, 0o755);
+    } catch (err) {
+      console.error(`Error setting executable permissions: ${err.message}`);
+    }
+  }
+  
+  // Pass through all arguments
+  const args = process.argv.slice(2);
+  
+  // Execute the binary
+  const child = execFile(binaryPath, args, { stdio: 'inherit' });
+  
+  child.on('error', (err) => {
+    console.error(`Error executing binary: ${err.message}`);
+    process.exit(1);
+  });
+  
+  child.on('exit', (code) => {
+    process.exit(code);
+  });
+}
+
+// Run the binary
+runBinary();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@standardbeagle/mcp-tui",
+  "version": "0.1.0",
+  "description": "A Terminal User Interface (TUI) and CLI for Model Context Protocol (MCP) servers",
+  "main": "index.js",
+  "bin": {
+    "mcp-tui": "bin/mcp-tui.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/standardbeagle/mcp-tui.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "tui",
+    "terminal",
+    "cli",
+    "ai",
+    "llm"
+  ],
+  "author": "standardbeagle",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/standardbeagle/mcp-tui/issues"
+  },
+  "homepage": "https://github.com/standardbeagle/mcp-tui#readme",
+  "dependencies": {
+    "node-fetch": "^3.3.2"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const https = require('https');
+const { execSync } = require('child_process');
+
+const REPO = 'standardbeagle/mcp-tui';
+const VERSION = require('../package.json').version;
+
+function getPlatformInfo() {
+  const platform = os.platform();
+  const arch = os.arch();
+  
+  // Map Node.js platform/arch to Go's GOOS/GOARCH
+  const platformMap = {
+    'darwin': 'darwin',
+    'linux': 'linux',
+    'win32': 'windows'
+  };
+  
+  const archMap = {
+    'x64': 'amd64',
+    'arm64': 'arm64',
+    'arm': 'arm'
+  };
+  
+  return {
+    goos: platformMap[platform] || platform,
+    goarch: archMap[arch] || arch,
+    platform: platform,
+    arch: arch
+  };
+}
+
+function getBinaryName() {
+  const { platform } = getPlatformInfo();
+  let binaryName = 'mcp-tui';
+  if (platform === 'win32') {
+    binaryName += '.exe';
+  }
+  return binaryName;
+}
+
+async function downloadBinary() {
+  const { goos, goarch } = getPlatformInfo();
+  const binaryName = getBinaryName();
+  
+  // Construct the download URL
+  const downloadUrl = `https://github.com/${REPO}/releases/download/v${VERSION}/mcp-tui_${VERSION}_${goos}_${goarch}.tar.gz`;
+  
+  console.log(`Downloading mcp-tui binary for ${goos}/${goarch}...`);
+  console.log(`URL: ${downloadUrl}`);
+  
+  const binariesDir = path.join(__dirname, '..', 'binaries');
+  const binaryPath = path.join(binariesDir, binaryName);
+  
+  // Create binaries directory
+  if (!fs.existsSync(binariesDir)) {
+    fs.mkdirSync(binariesDir, { recursive: true });
+  }
+  
+  // For development, try to build from source if available
+  if (fs.existsSync(path.join(__dirname, '..', '..', 'go.mod'))) {
+    console.log('Development mode: Building from source...');
+    try {
+      const projectRoot = path.join(__dirname, '..', '..');
+      execSync(`go build -o ${binaryPath} .`, {
+        cwd: projectRoot,
+        stdio: 'inherit'
+      });
+      console.log('Binary built successfully!');
+      return;
+    } catch (err) {
+      console.log('Failed to build from source, attempting download...');
+    }
+  }
+  
+  // Download binary from releases
+  return new Promise((resolve, reject) => {
+    https.get(downloadUrl, (response) => {
+      if (response.statusCode === 302 || response.statusCode === 301) {
+        // Follow redirect
+        https.get(response.headers.location, (redirectResponse) => {
+          handleResponse(redirectResponse);
+        }).on('error', reject);
+      } else {
+        handleResponse(response);
+      }
+      
+      function handleResponse(res) {
+        if (res.statusCode !== 200) {
+          reject(new Error(`Failed to download binary: ${res.statusCode}`));
+          return;
+        }
+        
+        const tarPath = path.join(binariesDir, 'mcp-tui.tar.gz');
+        const file = fs.createWriteStream(tarPath);
+        
+        res.pipe(file);
+        
+        file.on('finish', () => {
+          file.close();
+          
+          // Extract the tar.gz file
+          try {
+            execSync(`tar -xzf ${tarPath} -C ${binariesDir}`, {
+              stdio: 'inherit'
+            });
+            
+            // Remove the tar file
+            fs.unlinkSync(tarPath);
+            
+            // Make binary executable
+            if (process.platform !== 'win32') {
+              fs.chmodSync(binaryPath, 0o755);
+            }
+            
+            console.log('Binary downloaded and extracted successfully!');
+            resolve();
+          } catch (err) {
+            reject(new Error(`Failed to extract binary: ${err.message}`));
+          }
+        });
+      }
+    }).on('error', reject);
+  });
+}
+
+// Main installation
+async function install() {
+  try {
+    await downloadBinary();
+  } catch (err) {
+    console.error('Installation failed:', err.message);
+    console.error('\nYou can manually download the binary from:');
+    console.error(`https://github.com/${REPO}/releases`);
+    process.exit(1);
+  }
+}
+
+install();