Proxy CLI

The proxy-cli is a command-line interface tool designed as a wrapper around @contextvm/sdk's NostrMCPProxy. It allows you to connect to MCP servers using the ContextVM protocol through the nostr network, and use it as local mcp server in any mcp client.

Quick Start

curl -fsSL https://raw.githubusercontent.com/contextvm/proxy-cli/main/install.sh | bash

Overview

This CLI enables you to configure and run NostrMCPProxy, forming an integral part of the ContextVM ecosystem. It allows you to connect to MCP servers exposed through the nostr network and use them as if they were local MCP servers.

The tool supports configuration through multiple sources with clear precedence:

1. CLI Flags (Highest Priority): Command-line arguments take precedence over other configuration methods.
2. Environment Variables: Values set in the environment override configuration file settings.
3. Configuration File (Lowest Priority): A YAML configuration file (ctxproxy.config.yml) provides default settings that can be overridden by environment variables or CLI flags.

Installation

From binaries

💡Tip: You can use the Quick Start method to install the CLI. If you prefer to install it manually, you can follow the instructions below.

💡Tip: Choose this installation method if you don't have Deno installed in your system, and you don't want to install it. You can download the latest release from the releases page.

Instructions:

• Pick the appropriate binary for your system (Linux, macOS, Windows).
• Download the binary and make it executable (e.g., chmod +x proxy-cli-linux).
• Move the binary to a directory in your system's PATH (e.g., /usr/local/bin).

With Deno

💡Tip: This installation method is recommended if you have Deno installed in your system.

Instructions:

• You can just run it with deno run -A jsr:@contextvm/proxy-cli.
• You can also install it with deno install -A proxy-cli jsr:@contextvm/proxy-cli.

Note: The -A flag grants the cli all the permissions. If you want to run or install it with scoped permissions, you can use deno run --allow-net --allow-read --allow-env jsr:@contextvm/proxy-cli.

Usage

Configuration Precedence

The proxy-cli loads configuration in the following order of precedence, where higher numbers override lower numbers:

1. CLI Flags: --private-key, --relays, --server-pubkey, --encryption-mode
2. Environment Variables: CTXPROXY_PRIVATE_KEY, CTXPROXY_RELAYS, CTXPROXY_SERVER_PUBKEY, CTXPROXY_ENCRYPTION_MODE
3. Configuration File: ctxproxy.config.yml

Example Configuration File (ctxproxy.config.example.yml)

You can create a ctxproxy.config.yml file in your project root or working directory to store default configurations.

# ctxproxy.config.yml
privateKey: "your_64_character_hex_private_key_here"
relays:
  - "wss://relay.damus.io"
  - "wss://nostr-pub.wellorder.net"
  - "wss://nostr.bitcoiner.social"
serverPubkey: "your_64_character_hex_server_public_key_here"
encryptionMode: "optional"  # Options: optional(default), required, disabled

Running the Proxy CLI

You can run the proxy-cli using the methods described above.

Using deno:

deno run -A jsr:@contextvm/proxy-cli [options]

Replace [options] with CLI flags to override configuration settings.

Example with CLI flags:

deno run -A jsr:@contextvm/proxy-cli --private-key "your_private_key_here" --relays "wss://relay.com" --server-pubkey "server_public_key_here" --encryption-mode "required"

This command will start the proxy, overriding the settings from the configuration file or environment variables if they exist with the provided CLI values.

Basic usage with configuration file:

proxy-cli

Override configuration with CLI flags:

proxy-cli --private-key "your_private_key_here" --server-pubkey "server_public_key_here"

Using environment variables:

export CTXPROXY_PRIVATE_KEY="your_private_key_here"
export CTXPROXY_SERVER_PUBKEY="server_public_key_here"
proxy-cli

Available Commands

• proxy-cli start: Start the proxy (default command)
• proxy-cli --version: Show version information
• proxy-cli --help: Show help message
• proxy-cli init: Initialize a configuration file

Configuration Options

Required Parameters

• privateKey: Your Nostr private key in HEX format (min 64 chars)
• relays: List of Nostr relay URLs to connect to (at least one required)
• serverPubkey: The public key of the server to connect to in HEX format

Optional Parameters

• encryptionMode: Message encryption requirement (default: "optional")
  • "optional": Use encryption if available, but allow unencrypted
  • "required": Only accept encrypted messages
  • "disabled": Disable encryption completely

Development

Prerequisites

• Deno 2.x

Running from Source

deno task start

Running Tests

deno task test