# Vertex CLI

A command-line tool for looking up Nostr profiles using the [Vertex API](https://vertexlab.io/). This tool allows you to search for Nostr profiles by query and check your credit balance.

## Installation

To install dependencies:

```bash
bun install
```

## Usage

### Interactive Mode

Run without any arguments to enter interactive mode:

```bash
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:

```bash
# 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

```bash
# 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:

```bash
# 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:**

```json
{
  "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:**

```json
{
  "balance": 1000
}
```

### MCP Client Integration

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

```json
{
  "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](https://bun.com) is a fast all-in-one JavaScript runtime.