Vertex CLI

A command-line tool for looking up Nostr profiles using the Vertex API. This tool allows you to search for Nostr profiles by query and check your credit balance.

Installation

To install dependencies:

bun install

Usage

Interactive Mode

Run without any arguments to enter interactive mode:

bun index.ts

In interactive mode, you can run multiple commands after logging in once. Available commands:

• lookup <query> - Look up Nostr profiles
• credits - Check credit balance
• help - Show available commands
• exit - Exit interactive mode

Command Line Mode

Run specific commands directly:

# Look up profiles
bun index.ts lookup "alice" --nsec nsec1...

# Check credit balance
bun index.ts credits --nsec nsec1...

# Show help
bun index.ts --help

Options

• --nsec <key> - Your Nostr private key (nsec format). If not provided, you'll be prompted to enter it.
• --query <query> - Search query for profile lookup
• --sort <method> - Sort method (global or local)

Examples

# Enter interactive mode
bun index.ts

# Single command with nsec
bun index.ts lookup "alice" --nsec nsec1...

# Single command, will prompt for nsec
bun index.ts lookup "alice"

# Check credits
bun index.ts credits --nsec nsec1...

Authentication

This tool requires a Nostr private key (nsec format) for authentication with the Vertex API. You can provide it via the --nsec flag or enter it when prompted.

MCP Server

This project includes a Model Context Protocol (MCP) server that allows external clients to interact with the Vertex API through a standardized interface.

Starting the MCP Server

You can start the MCP server in several ways:

# Using CLI argument
bun index.ts mcp --nsec nsec1...

# Using environment variable
VERTEX_KEY=nsec1... bun index.ts mcp

# Direct execution of MCP server
bun common/mcp.ts --nsec nsec1...
VERTEX_KEY=nsec1... bun common/mcp.ts

MCP Server Tools

The MCP server exposes two tools:

1. lookup - Profile Lookup

Search for Nostr profiles by query with various sorting options.

Parameters:

• query (string, required): Search query to find Nostr profiles
• sort (string, optional): Sort method - global (default), personalized, or followers
• limit (number, optional): Maximum number of profiles to return (1-100, default: 10)

Response:

{
  "profiles": [
    {
      "pubkey": "nostr_public_key",
      "relays": ["wss://relay1.example.com", "wss://relay2.example.com"]
    }
  ]
}

2. credits - Credit Balance

Check your current credit balance on the Vertex network.

Parameters: None

Response:

{
  "balance": 1000
}

MCP Client Integration

To use this MCP server with an MCP client, add it to your client configuration:

{
  "mcpServers": {
    "vertex-lookup": {
      "command": "bun",
      "args": ["/path/to/profile-lookup-cvm/common/mcp.ts"],
      "env": {
        "VERTEX_KEY": "nsec1..."
      }
    }
  }
}

MCP Server Features

• Standardized Interface: Uses the Model Context Protocol for consistent tool access
• Error Handling: Comprehensive error handling with structured error responses
• Input Validation: Validates all input parameters with clear error messages
• Resource Management: Properly manages Vertex API connections and cleanup
• Flexible Authentication: Supports both CLI arguments and environment variables

Features

• Profile Lookup: Search for Nostr profiles by query
• Credit Balance: Check your Vertex API credit balance
• Interactive Mode: Run multiple commands in a session
• Command Line Mode: Execute single commands directly
• MCP Server: Expose functionality via Model Context Protocol for external clients
• Secure Authentication: Uses Nostr private keys for API authentication

This project was created using bun init in bun v1.2.21. Bun is a fast all-in-one JavaScript runtime.