### Configure Environment Variables

Source: https://github.com/sanjaymarathe/nomad/blob/main/QUICKSTART.md

Copies the example environment file to '.env' and instructs the user to edit it with their API keys. It highlights the minimum required variables for LiveKit, Deepgram, and OpenAI.

```bash
cp .env.example .env
# Edit .env with your API keys
```

```env
LIVEKIT_URL=wss://your-livekit-server.com
LIVEKIT_API_KEY=your-key
LIVEKIT_API_SECRET=your-secret
DEEPGRAM_API_KEY=your-key
OPENAI_API_KEY=your-key
```

--------------------------------

### Start NomadSync Frontend (Bash)

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Instructions to set up and run the NomadSync frontend application. This involves navigating to the frontend directory, installing dependencies, and starting the development server. Users should access the application via the provided localhost URL.

```bash
cd sb_hacks_frontend/y
npm install
npm run dev
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/sanjaymarathe/nomad/blob/main/QUICKSTART.md

Installs project dependencies using pip within a Python virtual environment. It first creates a virtual environment named 'venv' and then activates it. Finally, it installs all packages listed in the 'requirements.txt' file.

```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

--------------------------------

### Start NomadSync Backend and Agent (Bash)

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Provides commands to start the NomadSync backend MCP server and the voice agent. The MCP server handles vendor wallets, while the agent manages user interactions and trip planning. This is part of the quick start guide for the payment demo.

```bash
# Terminal 1: MCP Server (handles vendor wallet)
python mcp_server.py

# Terminal 2: Voice Agent
python agent.py dev
```

--------------------------------

### Start MCP Server

Source: https://github.com/sanjaymarathe/nomad/blob/main/QUICKSTART.md

Starts the MCP (Multi-modal Communication Protocol) server using Uvicorn. This server is essential for handling communication between different modules of the NomadSync backend. The output indicates the server is running on http://0.0.0.0:8000.

```bash
python mcp_server.py
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Installs project dependencies using pip from a requirements file. It assumes a Python virtual environment is already set up.

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

pip install -r requirements.txt
```

--------------------------------

### Start LiveKit Agent

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Starts the LiveKit agent, which manages the voice pipeline, STT, TTS, and LLM interactions. It can be run in development or production mode.

```python
python agent.py dev

# Or for production:
python agent.py start
```

--------------------------------

### Start LiveKit Agent (Python)

Source: https://github.com/sanjaymarathe/nomad/blob/main/IMPLEMENTATION_STATUS.md

Starts the LiveKit agent, written in Python. This agent handles voice input, interacts with the MCP server, and manages real-time communication.

```python
cd nomad
python agent.py dev
```

--------------------------------

### Test MCP Server API Endpoints

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Demonstrates how to test the MCP server's travel search endpoints using curl. It includes examples for searching restaurants, getting activities, and searching hotels.

```bash
# Test restaurant search
curl -X POST http://localhost:8000/tools/search_restaurants \
  -H "Content-Type: application/json" \
  -d '{"location": "San Francisco", "food_type": "Italian"}'

# Test activities
curl -X POST http://localhost:8000/tools/get_activities \
  -H "Content-Type: application/json" \
  -d '{"location": "New York"}'

# Test hotels
curl -X POST http://localhost:8000/tools/search_hotels \
  -H "Content-Type: application/json" \
  -d '{"location": "Paris", "budget_sol": 0.5}'

# List all tools
curl http://localhost:8000/tools
```

--------------------------------

### Test MCP Server

Source: https://github.com/sanjaymarathe/nomad/blob/main/QUICKSTART.md

Executes a test script for the MCP server. This is an optional step to verify the server's functionality before proceeding with the agent setup. It should be run in a separate terminal.

```bash
python test_mcp_server.py
```

--------------------------------

### Install Frontend Dependencies (Bash)

Source: https://github.com/sanjaymarathe/nomad/blob/main/IMPLEMENTATION_STATUS.md

Installs the necessary dependencies for the frontend project located in the `sb_hacks_frontend/y` directory using npm.

```bash
cd sb_hacks_frontend/y
npm install
```

--------------------------------

### List Available MCP Tools (Bash)

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

This snippet demonstrates how to list all available MCP tools by sending a GET request to the /tools endpoint. The response includes the name, description, and parameters for each tool.

```bash
curl http://localhost:8000/tools

# Response:
# {
#   "tools": [
#     {
#       "name": "search_restaurants",
#       "description": "Search for restaurants in a location using Yelp",
#       "parameters": {"location": {"type": "string", "required": true}}
#     },
#     {
#       "name": "get_activities",
#       "description": "Get top-rated activities and attractions"
#     },
#     {
#       "name": "search_hotels",
#       "description": "Search for hotels and accommodations"
#     },
#     {
#       "name": "update_map",
#       "description": "Update the map with a route or path"
#     }
#   ]
# }
```

--------------------------------

### Run MCP Server Tests with Pytest

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Executes tests for the MCP server component using Python's pytest framework. Ensure pytest is installed and the test file path is correct.

```bash
python -m pytest tests/test_mcp_server.py
```

--------------------------------

### Create Mapbox .env.local (Bash)

Source: https://github.com/sanjaymarathe/nomad/blob/main/DEBUGGING.md

This command creates the `.env.local` file in the specified directory with a placeholder for the Mapbox token. This is a crucial step for Mapbox integration in the frontend.

```bash
echo "NEXT_PUBLIC_MAPBOX_TOKEN=pk.your-token" > sb_hacks_frontend/y/.env.local
```

--------------------------------

### Start MCP Server (Python)

Source: https://github.com/sanjaymarathe/nomad/blob/main/IMPLEMENTATION_STATUS.md

Launches the MCP (Multi-tool Control Plane) server, which is implemented in Python. This server provides various tools for the agent to use.

```python
cd nomad
python mcp_server.py
```

--------------------------------

### Restart Next.js Development Server (Bash)

Source: https://github.com/sanjaymarathe/nomad/blob/main/DEBUGGING.md

These commands navigate to the frontend directory and restart the Next.js development server. This is necessary for the server to pick up changes in environment variables, such as the Mapbox token.

```bash
cd sb_hacks_frontend/y
npm run dev
```

--------------------------------

### Test Nomad Agent Connection

Source: https://github.com/sanjaymarathe/nomad/blob/main/FIXES_APPLIED.md

Provides a bash command to test the initialization of the NomadSync Agent. Successful execution should display a confirmation message indicating the agent has started.

```bash
python agent.py dev
# Should see: "🤖 [AGENT START] NomadSync Agent initialized"
```

--------------------------------

### Get Vendor Wallet

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Retrieves the Solana vendor public key, which is necessary for initiating payment transactions.

```APIDOC
## GET /api/solana/vendor

### Description
Returns the Solana vendor public key for payment transactions.

### Method
GET

### Endpoint
/api/solana/vendor

### Parameters
#### Query Parameters
None

### Request Example
```bash
curl http://localhost:8000/api/solana/vendor
```

### Response
#### Success Response (200)
- **vendorPublicKey** (string) - The public key of the vendor on the Solana network.

#### Response Example
```json
{"vendorPublicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"}
```
```

--------------------------------

### Agent Connection Logs (Python)

Source: https://github.com/sanjaymarathe/nomad/blob/main/DEBUGGING.md

This snippet shows the expected output when the agent successfully connects to a room. It's useful for verifying the agent's connection status and identity.

```text
Agent connecting to room: nomadsync-room
Agent identity: <identity>
Starting agent in room...
Agent started successfully
```

--------------------------------

### Get Vendor Public Key (Bash)

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

A cURL command to retrieve the public key of the vendor's Solana wallet from the backend API. This endpoint is useful for obtaining the vendor's address for transactions or display purposes.

```bash
# Get vendor public key
curl http://localhost:8000/api/solana/vendor
```

--------------------------------

### Get Activities via NomadSync MCP Server

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Retrieves top-rated activities and attractions from Yelp Fusion AI based on location, minimum rating, and number of guests. It includes cost estimates per person and essential details for planning.

```bash
curl -X POST http://localhost:8000/tools/get_activities \
  -H "Content-Type: application/json" \
  -d '{ \
    "location": "New York", \
    "num_guests": 2, \
    "min_rating": 4.5 \
  }'

# Response:
# {
#   "location": "New York",
#   "activities": [
#     {
#       "name": "Top of the Rock Observation Deck",
#       "rating": 4.6,
#       "review_count": 5234,
#       "type": "Landmarks & Historical Buildings",
#       "address": "30 Rockefeller Plaza, New York, NY",
#       "coordinates": [40.7587, -73.9787],
#       "estimated_cost_per_person": 40,
#       "estimated_total": 80,
#       "price_display": "$40/person"
#     }
#   ],
#   "coordinates": [40.7128, -74.0060],
#   "count": 5
# }
```

--------------------------------

### Restart Agent (Bash)

Source: https://github.com/sanjaymarathe/nomad/blob/main/DEBUGGING.md

This command restarts the agent process, which is often necessary after configuration changes or to resolve temporary issues. It's a common step in agent debugging.

```bash
python agent.py dev
```

--------------------------------

### Initialize Solana Vendor Wallet

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

This Python code initializes a Solana vendor wallet by loading an existing keypair or generating a new one. It prints the public key and instructions for setting the secret key if a new wallet is created.

```python
from solana_payment import initialize_vendor_wallet, get_vendor_public_key

# On server startup
public_key, is_new = initialize_vendor_wallet()

if is_new:
    print(f"New wallet generated: {public_key}")
    print("Add VENDOR_SECRET_KEY to .env file")
else:
    print(f"Loaded existing wallet: {public_key}")

# Fund on devnet:
# solana airdrop 2 <public_key> --url devnet
```

--------------------------------

### Required Environment Variables for Nomad Project

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

This is a sample .env file listing the required environment variables for configuring the Nomad project. It includes settings for LiveKit, speech services, LLM providers, travel APIs, Solana, and the MCP server.

```bash
# .env file
# LiveKit Configuration
LIVEKIT_URL=wss://your-livekit-server.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxx
LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxxxx

# Speech Services
DEEPGRAM_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxx

# LLM Provider (choose one)
LLM_PROVIDER=anthropic  # or "openai"
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxx

# Travel APIs
YELP_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
MAPBOX_ACCESS_TOKEN=pk.eyJ1xxxxxxxxxxxxxxxx

# Solana Configuration
SOLANA_RPC_URL=https://api.devnet.solana.com
VENDOR_SECRET_KEY=base58_encoded_64_byte_key

# MCP Server
MCP_SERVER_URL=http://localhost:8000
MCP_SERVER_PORT=8000
```

--------------------------------

### Environment Configuration

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Lists the required environment variables for configuring LiveKit, speech services, LLM providers, travel APIs, Solana, and the MCP server.

```APIDOC
## Environment Configuration

### Required Environment Variables

```bash
# .env file
# LiveKit Configuration
LIVEKIT_URL=wss://your-livekit-server.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxx
LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxxxx

# Speech Services
DEEPGRAM_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxx

# LLM Provider (choose one)
LLM_PROVIDER=anthropic  # or "openai"
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxx

# Travel APIs
YELP_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
MAPBOX_ACCESS_TOKEN=pk.eyJ1xxxxxxxxxxxxxxxx

# Solana Configuration
SOLANA_RPC_URL=https://api.devnet.solana.com
VENDOR_SECRET_KEY=base58_encoded_64_byte_key

# MCP Server
MCP_SERVER_URL=http://localhost:8000
MCP_SERVER_PORT=8000
```
```

--------------------------------

### Generate New Vendor Wallet (Bash)

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Illustrates the output when a new vendor wallet is generated by the backend. It provides the public key and instructions on how to add the secret key to the environment variables and fund the wallet on devnet. This is crucial for persisting the vendor's wallet.

```bash
============================================================
  NEW VENDOR WALLET GENERATED
============================================================
Public Key: <vendor-pubkey>

Add this to your .env file:
VENDOR_SECRET_KEY=<base58-encoded-secret>

Fund wallet on devnet:
solana airdrop 2 <vendor-pubkey> --url devnet
============================================================

```

--------------------------------

### Mapbox Token Test Response (JSON)

Source: https://github.com/sanjaymarathe/nomad/blob/main/DEBUGGING.md

This JSON represents the expected response when testing the Mapbox token configuration. It confirms if the token is valid and provides a preview and length.

```json
{ "configured": true, "preview": "pk.eyJ1...", "length": <number> }
```

--------------------------------

### Run Solana Payment Tests with Pytest

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Executes tests for the Solana payment functionality using Python's pytest framework. This helps verify the integrity of payment processing on the Solana blockchain.

```bash
python -m pytest tests/test_solana_payment.py
```

--------------------------------

### Solana Payment Integration

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

APIs for initializing Solana wallets, generating payment transactions, and handling USD to SOL conversion.

```APIDOC
## Solana Payment Integration

### Initialize Vendor Wallet

Loads or generates a new Solana keypair for receiving payments.

```python
from solana_payment import initialize_vendor_wallet, get_vendor_public_key

# On server startup
public_key, is_new = initialize_vendor_wallet()

if is_new:
    print(f"New wallet generated: {public_key}")
    print("Add VENDOR_SECRET_KEY to .env file")
else:
    print(f"Loaded existing wallet: {public_key}")

# Fund on devnet:
# solana airdrop 2 <public_key> --url devnet
```

### Generate Payment Transaction

Creates Solana transfer transactions with automatic USD to SOL conversion.

```python
import asyncio
from solana_payment import generate_payment_transaction, get_sol_price_usd

async def create_payment():
    # Get current SOL price
    sol_price = await get_sol_price_usd()
    print(f"Current SOL price: ${sol_price}")

    # Generate transaction for $100 USD
    result = await generate_payment_transaction(
        amount_usd=100.0,
        recipient_address="7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"
    )

    if result["success"]:
        tx = result["transaction"]
        print(f"Payment: {tx['amount_sol']:.4f} SOL (${tx['amount_usd']})")
        print(f"To: {tx['to']}")
        print(f"Lamports: {tx['amount_lamports']}")
    else:
        print(f"Error: {result['error']}")

asyncio.run(create_payment())

# Output:
# Current SOL price: $200.0
# Payment: 0.5000 SOL ($100.0)
# To: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
# Lamports: 500000000
```
```

--------------------------------

### MCPClient Class Usage

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Demonstrates how to use the MCPClient Python class to interact with the MCP tool server, including connecting, listing tools, and calling tools.

```APIDOC
## MCPClient Class

### Description
Python client for communicating with the MCP tool server. Handles HTTP session management and tool invocation.

### Method
N/A (Class usage)

### Endpoint
N/A (Class usage, connects to server_url)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from mcp_client import MCPClient

async def main():
    # Initialize client (uses MCP_SERVER_URL env var or defaults to localhost:8000)
    client = MCPClient(server_url="http://localhost:8000")

    # Connect to server
    await client.connect()

    # List available tools
    tools = await client.list_tools()
    print(f"Available tools: {[t['name'] for t in tools['tools']]}")

    # Search for restaurants
    restaurants = await client.call_tool(
        "search_restaurants",
        location="San Francisco",
        food_type="sushi",
        num_guests=2
    )
    print(f"Found {restaurants['count']} restaurants")

    # Get activities
    activities = await client.call_tool(
        "get_activities",
        location="Tokyo",
        num_guests=4
    )

    # Calculate route
    route = await client.call_tool(
        "update_map",
        waypoints=["Los Angeles", "San Diego"],
        route_type="driving"
    )
    print(f"Route has {len(route['path'])} path points")

    # Cleanup
    await client.disconnect()

asyncio.run(main())
```

### Response
#### Success Response (200)
Responses vary based on the tool called. See individual tool documentation.

#### Response Example
See individual tool examples within the `call_tool` method usage.
```

--------------------------------

### List Available Tools

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Retrieves the schema of all available MCP tools for client discovery. This helps clients understand what functionalities are available.

```APIDOC
## GET /tools

### Description
Returns the schema of all available MCP tools for client discovery.

### Method
GET

### Endpoint
/tools

### Parameters
#### Query Parameters
None

### Request Example
```bash
curl http://localhost:8000/tools
```

### Response
#### Success Response (200)
- **tools** (array) - A list of available tools, each with a name, description, and parameters.
  - **name** (string) - The name of the tool.
  - **description** (string) - A description of what the tool does.
  - **parameters** (object) - An object defining the parameters for the tool.
    - **location** (object) - Optional. Defines the location parameter for tools that require it.
      - **type** (string) - The data type of the parameter (e.g., "string").
      - **required** (boolean) - Indicates if the parameter is required.

#### Response Example
```json
{
  "tools": [
    {
      "name": "search_restaurants",
      "description": "Search for restaurants in a location using Yelp",
      "parameters": {"location": {"type": "string", "required": true}}
    },
    {
      "name": "get_activities",
      "description": "Get top-rated activities and attractions"
    },
    {
      "name": "search_hotels",
      "description": "Search for hotels and accommodations"
    },
    {
      "name": "update_map",
      "description": "Update the map with a route or path"
    }
  ]
}
```
```

--------------------------------

### Configure Frontend Environment Variables (Env)

Source: https://github.com/sanjaymarathe/nomad/blob/main/IMPLEMENTATION_STATUS.md

Sets up essential environment variables for the frontend application, including LiveKit server details and Mapbox API token. These are typically placed in a `.env.local` file.

```env
LIVEKIT_URL=wss://your-livekit-server.com
LIVEKIT_API_KEY=your-livekit-api-key
LIVEKIT_API_SECRET=your-livekit-api-secret
NEXT_PUBLIC_MAPBOX_TOKEN=your-mapbox-access-token
```

--------------------------------

### Agent Tool: generate_booking_payment

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Creates Solana payment requests for bookings, including a cost breakdown for hotels, activities, and restaurants.

```APIDOC
## Agent Tool: generate_booking_payment

### Description
Creates Solana payment requests with cost breakdown for hotels, activities, and restaurants.

### Method
N/A (Called automatically via voice command or client interaction)

### Endpoint
N/A (Internal tool call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Example usage within the agent or client:
# This tool would likely be called after a search or booking confirmation.

@function_tool()
async def generate_booking_payment(
    self,
    context: RunContext,
    item_type: str,  # e.g., "hotel", "activity", "restaurant"
    item_id: str,    # Unique identifier for the item
    cost: float,     # Total cost of the booking
    currency: str = "SOL", # Default to Solana
    payment_details: dict = None # Optional: specific payment info
) -> dict:
    # Generates a Solana payment request object
    pass
```

### Response
#### Success Response (200)
- **payment_request** (object) - An object containing details for the Solana payment transaction.
  - **transaction_id** (string) - Unique ID for the payment request.
  - **recipient** (string) - The vendor's public key.
  - **amount** (number) - The amount to be paid.
  - **currency** (string) - The currency of the transaction.
  - **status** (string) - The current status of the payment request.

#### Response Example
```json
{
  "payment_request": {
    "transaction_id": "txn_abc123xyz",
    "recipient": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "amount": 150.75,
    "currency": "SOL",
    "status": "pending"
  }
}
```
```

--------------------------------

### Enable Debug Logging in Python

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Configures the Python logging module to display debug messages. This is useful for detailed troubleshooting and understanding application flow during development.

```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

--------------------------------

### POST /tools/get_activities

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Retrieves top-rated activities and attractions based on location, number of guests, and minimum rating. Includes cost estimates.

```APIDOC
## POST /tools/get_activities

### Description
Retrieves top-rated activities and attractions from Yelp Fusion AI, including cost estimates per person.

### Method
POST

### Endpoint
/tools/get_activities

### Parameters
#### Request Body
- **location** (string) - Required - The city or area to search for activities.
- **num_guests** (integer) - Required - The number of people participating in the activity.
- **min_rating** (float) - Optional - The minimum acceptable rating for activities (e.g., 4.5).

### Request Example
```json
{
  "location": "New York",
  "num_guests": 2,
  "min_rating": 4.5
}
```

### Response
#### Success Response (200)
- **location** (string) - The location searched.
- **activities** (array) - A list of matching activities.
  - **name** (string) - The name of the activity.
  - **rating** (float) - The average rating of the activity.
  - **review_count** (integer) - The number of reviews.
  - **type** (string) - The category or type of activity.
  - **address** (string) - The physical address of the activity location.
  - **coordinates** (array) - An array containing latitude and longitude.
  - **estimated_cost_per_person** (float) - Estimated cost per person.
  - **estimated_total** (float) - Estimated total cost for the group.
  - **price_display** (string) - Formatted price display string.
- **coordinates** (array) - The central coordinates for the search area.
- **count** (integer) - The total number of activities found.

#### Response Example
```json
{
  "location": "New York",
  "activities": [
    {
      "name": "Top of the Rock Observation Deck",
      "rating": 4.6,
      "review_count": 5234,
      "type": "Landmarks & Historical Buildings",
      "address": "30 Rockefeller Plaza, New York, NY",
      "coordinates": [40.7587, -73.9787],
      "estimated_cost_per_person": 40,
      "estimated_total": 80,
      "price_display": "$40/person"
    }
  ],
  "coordinates": [40.7128, -74.0060],
  "count": 5
}
```
```

--------------------------------

### Fund Devnet Wallet (Bash)

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Command to airdrop SOL to a Solana devnet wallet address. This is necessary for testing payment flows on the devnet. Ensure the specified address is correct and the Solana CLI is configured for devnet.

```bash
solana airdrop 2 <your-address> --url devnet
```

--------------------------------

### MCP Server Tools API

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

This section details the endpoints for the MCP (Micro-service Communication Protocol) server, which provides various travel search functionalities.

```APIDOC
## POST /tools/search_restaurants

### Description
Searches for restaurants based on location and food type using Yelp.

### Method
POST

### Endpoint
/tools/search_restaurants

### Parameters
#### Request Body
- **location** (string) - Required - The location to search within.
- **food_type** (string) - Required - The type of cuisine to search for.

### Request Example
```json
{
  "location": "San Francisco",
  "food_type": "Italian"
}
```

### Response
#### Success Response (200)
- **restaurants** (array) - A list of restaurant objects found.

#### Response Example
```json
{
  "restaurants": [
    {
      "name": "Example Italian Restaurant",
      "address": "123 Pasta Lane",
      "rating": 4.5
    }
  ]
}
```

## POST /tools/get_activities

### Description
Retrieves a list of activities or attractions for a given location from Tripadvisor.

### Method
POST

### Endpoint
/tools/get_activities

### Parameters
#### Request Body
- **location** (string) - Required - The location for which to find activities.

### Request Example
```json
{
  "location": "New York"
}
```

### Response
#### Success Response (200)
- **activities** (array) - A list of activity objects.

#### Response Example
```json
{
  "activities": [
    {
      "name": "Statue of Liberty",
      "description": "Iconic monument and symbol of freedom."
    }
  ]
}
```

## POST /tools/search_hotels

### Description
Searches for hotels in a specified location within a given budget (in SOL).

### Method
POST

### Endpoint
/tools/search_hotels

### Parameters
#### Request Body
- **location** (string) - Required - The city or area to search for hotels.
- **budget_sol** (number) - Required - The maximum budget in Solana (SOL).

### Request Example
```json
{
  "location": "Paris",
  "budget_sol": 0.5
}
```

### Response
#### Success Response (200)
- **hotels** (array) - A list of hotel objects.

#### Response Example
```json
{
  "hotels": [
    {
      "name": "Budget Hotel Paris",
      "price_sol": 0.45,
      "rating": 3.8
    }
  ]
}
```

## GET /tools

### Description
Lists all available tools on the MCP server.

### Method
GET

### Endpoint
/tools

### Response
#### Success Response (200)
- **tools** (array) - An array of strings, where each string is the name of an available tool.

#### Response Example
```json
{
  "tools": [
    "search_restaurants",
    "get_activities",
    "search_hotels"
  ]
}
```
```

--------------------------------

### Agent Tool: search_restaurants (Python)

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

This Python function tool, search_restaurants, is designed to be triggered by voice commands. It searches for restaurants based on location and food type, automatically detecting the number of guests from room participants. It returns restaurant data including coordinates for map visualization.

```python
# Called automatically when user says: "Find Italian restaurants in San Francisco"
# The agent detects intent and calls the tool:

@function_tool()
async def search_restaurants(
    self,
    context: RunContext,
    location: str,                    # "San Francisco"
    food_type: str = "",              # "Italian"
    num_guests: int = None,           # Auto-detected from room
    max_price_per_person: float = None,
    min_rating: float = None
) -> dict:
    # Returns restaurant data with coordinates for map update
    # Agent speaks: "I found two great options. Cotogna with 4.5 stars,
    # around $55 per person..."
    pass
```

--------------------------------

### MCPClient Python Usage

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

This Python script demonstrates how to use the MCPClient to connect to the MCP server, list available tools, and call various tools like search_restaurants, get_activities, and update_map. It handles asynchronous operations and client connection management.

```python
import asyncio
from mcp_client import MCPClient

async def main():
    # Initialize client (uses MCP_SERVER_URL env var or defaults to localhost:8000)
    client = MCPClient(server_url="http://localhost:8000")

    # Connect to server
    await client.connect()

    # List available tools
    tools = await client.list_tools()
    print(f"Available tools: {[t['name'] for t in tools['tools']]}")

    # Search for restaurants
    restaurants = await client.call_tool(
        "search_restaurants",
        location="San Francisco",
        food_type="sushi",
        num_guests=2
    )
    print(f"Found {restaurants['count']} restaurants")

    # Get activities
    activities = await client.call_tool(
        "get_activities",
        location="Tokyo",
        num_guests=4
    )

    # Calculate route
    route = await client.call_tool(
        "update_map",
        waypoints=["Los Angeles", "San Diego"],
        route_type="driving"
    )
    print(f"Route has {len(route['path'])} path points")

    # Cleanup
    await client.disconnect()

asyncio.run(main())
```

--------------------------------

### Agent Tool: generate_booking_payment (Python)

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

This agent tool, generate_booking_payment, is responsible for creating Solana payment requests. It handles cost breakdowns for various services like hotels, activities, and restaurants, facilitating payment transactions.

```python
# Creates Solana payment requests with cost breakdown for hotels, activities, and restaurants.

```

--------------------------------

### POST /tools/search_restaurants

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Searches for restaurants based on location, cuisine type, number of guests, and minimum rating. Includes cost estimation and Yelp data.

```APIDOC
## POST /tools/search_restaurants

### Description
Searches for restaurants using Yelp Fusion AI MCP. It automatically estimates costs based on price tiers and returns real-time data including ratings, reviews, photos, and coordinates.

### Method
POST

### Endpoint
/tools/search_restaurants

### Parameters
#### Request Body
- **location** (string) - Required - The city or area to search for restaurants.
- **food_type** (string) - Required - The type of cuisine to search for.
- **num_guests** (integer) - Required - The number of guests for the reservation or dining party.
- **min_rating** (float) - Optional - The minimum acceptable rating for restaurants (e.g., 4.0).

### Request Example
```json
{
  "location": "San Francisco",
  "food_type": "Italian",
  "num_guests": 4,
  "min_rating": 4.0
}
```

### Response
#### Success Response (200)
- **location** (string) - The location searched.
- **food_type** (string) - The food type searched.
- **restaurants** (array) - A list of matching restaurants.
  - **name** (string) - The name of the restaurant.
  - **rating** (float) - The average rating of the restaurant.
  - **review_count** (integer) - The number of reviews.
  - **price** (string) - The price range indicator (e.g., '$$$').
  - **address** (string) - The physical address of the restaurant.
  - **coordinates** (array) - An array containing latitude and longitude.
  - **yelp_url** (string) - The URL to the restaurant's Yelp page.
  - **image_url** (string) - A URL to an image of the restaurant.
  - **categories** (array) - A list of cuisine categories.
  - **estimated_cost_per_person** (float) - Estimated cost per person.
  - **estimated_total** (float) - Estimated total cost for the party.
  - **price_display** (string) - Formatted price display string.
- **coordinates** (array) - The central coordinates for the search area.
- **count** (integer) - The total number of restaurants found.
- **num_guests** (integer) - The number of guests specified in the request.

#### Response Example
```json
{
  "location": "San Francisco",
  "food_type": "Italian",
  "restaurants": [
    {
      "name": "Cotogna",
      "rating": 4.5,
      "review_count": 2847,
      "price": "$$$",
      "address": "490 Pacific Ave, San Francisco, CA",
      "coordinates": [37.7969, -122.4034],
      "yelp_url": "https://yelp.com/biz/cotogna-san-francisco",
      "image_url": "https://s3-media1.fl.yelpcdn.com/",
      "categories": ["Italian", "Wine Bars"],
      "estimated_cost_per_person": 55,
      "estimated_total": 220,
      "price_display": "$55/person"
    }
  ],
  "coordinates": [37.7749, -122.4194],
  "count": 5,
  "num_guests": 4
}
```
```

--------------------------------

### LiveKit Data Channel - Map Updates

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

This describes the structure of data broadcasted through LiveKit data channels for real-time map updates.

```APIDOC
## LiveKit Data Channel Message Format

### Description
When a search tool is triggered, the agent broadcasts map updates via LiveKit Data Channels to synchronize frontend map views.

### Method
N/A (LiveKit Data Channel Broadcast)

### Endpoint
N/A (LiveKit Data Channel)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (Data Channel Message)
- **type** (string) - The type of update, expected to be `"MAP_UPDATE"`.
- **coordinates** (array) - A two-element array representing latitude and longitude `[latitude, longitude]`.
- **data** (object) - An object containing additional data related to the map update, which may include search results.
  - **location** (string) - The location associated with the map update.
  - **restaurants** (array) - (Optional) A list of restaurant objects if the update is related to a restaurant search.

#### Response Example
```json
{
  "type": "MAP_UPDATE",
  "coordinates": [37.7749, -122.4194],
  "data": {
    "location": "San Francisco",
    "restaurants": [
      {
        "name": "Example Restaurant",
        "address": "123 Main St"
      }
    ]
  }
}
```
```

--------------------------------

### Generate Solana Payment Transaction (Python)

Source: https://github.com/sanjaymarathe/nomad/blob/main/README.md

Generates a Solana payment transaction using Pyth Network for USD to SOL conversion. It builds the transfer transaction and returns the data required for frontend signing. This function is intended for use in backend services that need to initiate payments.

```python
from solana_payment import generate_payment_transaction

# Generate payment transaction
result = await generate_payment_transaction(
    amount_usd=100.0,
    recipient_address="YourSolanaAddressHere"
)

print(result)
```

--------------------------------

### Agent Tool: update_map

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Generates route paths for map visualization based on user travel plans. It geocodes locations, calculates routes using Mapbox, and broadcasts updates to the frontend.

```APIDOC
## Agent Tool: update_map

### Description
Generates route paths for map visualization when users describe travel plans. It geocodes locations, calculates route via Mapbox, and broadcasts ROUTE_UPDATE to the frontend via LiveKit data channel.

### Method
N/A (Called automatically via voice command)

### Endpoint
N/A (Internal tool call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Called when user says: "Plan a trip from Oakland to Berkeley"

@function_tool()
async def update_map(
    self,
    context: RunContext,
    waypoints: list[str] = None,      # ["Oakland", "Berkeley"]
    route_description: str = "",
    route_type: str = "driving"       # "driving", "walking", "transit"
) -> dict:
    # Geocodes locations, calculates route via Mapbox
    # Broadcasts ROUTE_UPDATE to frontend via LiveKit data channel
    # Returns: {"path": [[lat, lng], ...], "bounds": {...}, "waypoints": [...]} 
    pass
```

### Response
#### Success Response (200)
- **path** (array) - An array of [latitude, longitude] pairs representing the route.
- **bounds** (object) - An object containing the north, south, east, and west boundaries of the route.
  - **north** (number)
  - **south** (number)
  - **east** (number)
  - **west** (number)
- **waypoints** (array) - The list of geocoded waypoints used for the route.
- **distance** (number) - The total distance of the route in meters.
- **duration** (number) - The estimated duration of the route in seconds.

#### Response Example
```json
{
  "location": "Oakland", "coordinates": [37.8044, -122.2712],
  "location": "Berkeley", "coordinates": [37.8716, -122.2727],
  "location": "San Francisco", "coordinates": [37.7749, -122.4194]
],
"path": [[37.8044, -122.2712], [37.8200, -122.2650], ...],
"bounds": {"north": 37.8716, "south": 37.7749, "east": -122.2650, "west": -122.4194},
"distance": 24500,
"duration": 1800,
"message": "Route calculated from Mapbox Directions API with 3 waypoints"
}
```
```

--------------------------------

### Generate Booking Payment Agent Tool

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

This Python function is triggered when a user requests to book hotels and activities. It calculates costs and returns a payment status, indicating a pending confirmation.

```python
from nomad.context import RunContext

@function_tool()
async def generate_booking_payment(
    self,
    context: RunContext,
    hotel_cost: float = 0.0,       # Paid now via Solana
    activities_cost: float = 0.0,  # Paid now via Solana
    restaurant_cost: float = 0.0,  # Pay later at venue
    item_description: str = "booking"
) -> dict:
    # Agent speaks: "Your booking total is $500 for hotels and activities.
    # Restaurants $150 you'll pay at each venue. Ready to confirm?"
    # Returns: {"status": "pending_confirmation", "paid_now_usd": 500, ...}
    pass
```

--------------------------------

### Search Restaurants via NomadSync MCP Server

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Searches for restaurants based on location, food type, minimum rating, and number of guests. It utilizes Yelp Fusion AI, provides cost estimations, and returns detailed restaurant information including ratings, reviews, and coordinates.

```bash
curl -X POST http://localhost:8000/tools/search_restaurants \
  -H "Content-Type: application/json" \
  -d '{ \
    "location": "San Francisco", \
    "food_type": "Italian", \
    "num_guests": 4, \
    "min_rating": 4.0 \
  }'

# Response:
# {
#   "location": "San Francisco",
#   "food_type": "Italian",
#   "restaurants": [
#     {
#       "name": "Cotogna",
#       "rating": 4.5,
#       "review_count": 2847,
#       "price": "$$$",
#       "address": "490 Pacific Ave, San Francisco, CA",
#       "coordinates": [37.7969, -122.4034],
#       "yelp_url": "https://yelp.com/biz/cotogna-san-francisco",
#       "image_url": "https://s3-media1.fl.yelpcdn.com/",
#       "categories": ["Italian", "Wine Bars"],
#       "estimated_cost_per_person": 55,
#       "estimated_total": 220,
#       "price_display": "$55/person"
#     }
#   ],
#   "coordinates": [37.7749, -122.4194],
#   "count": 5,
#   "num_guests": 4
# }
```

--------------------------------

### Agent Tool: confirm_payment

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

This tool is triggered when a user confirms a payment verbally. It initiates the wallet popup for transaction signing.

```APIDOC
## POST /api/tools/confirm_payment

### Description
Confirms a previously prepared payment, triggering the wallet popup for transaction signing on the frontend.

### Method
POST

### Endpoint
/api/tools/confirm_payment

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **status** (string) - Indicates that the payment execution has been triggered, e.g., "payment_execution_triggered".

#### Response Example
```json
{
  "status": "payment_execution_triggered"
}
```
```

--------------------------------

### Solana Payment Integration (Python)

Source: https://github.com/sanjaymarathe/nomad/blob/main/IMPLEMENTATION_STATUS.md

Python script responsible for integrating Solana payment functionality. It includes logic for generating payment transactions and fetching price data from CoinGecko.

```python
# nomad/solana_payment.py
# Handles Solana payment transactions and price feeds
```

--------------------------------

### POST /tools/search_hotels

Source: https://context7.com/sanjaymarathe/nomad/llms.txt

Searches for hotels and accommodations, calculating room needs based on guests and duration. Provides cost estimates per night and total.

```APIDOC
## POST /tools/search_hotels

### Description
Searches for hotels and accommodations, automatically calculating the number of rooms needed based on the guest count. Returns nightly rates and total cost estimates.

### Method
POST

### Endpoint
/tools/search_hotels

### Parameters
#### Request Body
- **location** (string) - Required - The city or area to search for hotels.
- **num_guests** (integer) - Required - The total number of guests.
- **nights** (integer) - Required - The number of nights for the stay.
- **min_rating** (float) - Optional - The minimum acceptable rating for hotels (e.g., 4.0).

### Request Example
```json
{
  "location": "Paris",
  "num_guests": 4,
  "nights": 3,
  "min_rating": 4.0
}
```

### Response
#### Success Response (200)
- **location** (string) - The location searched.
- **hotels** (array) - A list of matching hotels.
  - **name** (string) - The name of the hotel.
  - **rating** (float) - The average rating of the hotel.
  - **review_count** (integer) - The number of reviews.
  - **price** (string) - The price range indicator (e.g., '$$$').
  - **address** (string) - The physical address of the hotel.
  - **coordinates** (array) - An array containing latitude and longitude.
  - **amenities** (array) - A list of available amenities.
  - **estimated_cost_per_night** (float) - Estimated cost per night.
  - **estimated_total** (float) - Estimated total cost for the stay.
  - **price_display** (string) - Formatted price display string.
- **coordinates** (array) - The central coordinates for the search area.
- **count** (integer) - The total number of hotels found.
- **num_guests** (integer) - The number of guests specified in the request.
- **num_rooms** (integer) - The calculated number of rooms required.
- **nights** (integer) - The number of nights specified in the request.

#### Response Example
```json
{
  "location": "Paris",
  "hotels": [
    {
      "name": "Hotel Le Marais",
      "rating": 4.5,
      "review_count": 1823,
      "price": "$$$",
      "address": "12 Rue des Archives, Paris",
      "coordinates": [48.8566, 2.3522],
      "amenities": ["WiFi", "Parking", "Accessible"],
      "estimated_cost_per_night": 280,
      "estimated_total": 1680,
      "price_display": "$280/night"
    }
  ],
  "coordinates": [48.8566, 2.3522],
  "count": 5,
  "num_guests": 4,
  "num_rooms": 2,
  "nights": 3
}
```
```

--------------------------------

### LiveKit Voice Agent (Python)

Source: https://github.com/sanjaymarathe/nomad/blob/main/IMPLEMENTATION_STATUS.md

The core Python script for the LiveKit voice agent. It handles voice processing, event handling, and interaction with other services like the MCP server.

```python
# nomad/agent.py
# Contains the LiveKit voice agent implementation
```

--------------------------------

### MCP Server (Python)

Source: https://github.com/sanjaymarathe/nomad/blob/main/IMPLEMENTATION_STATUS.md

The Python script for the FastAPI-based MCP (Multi-tool Control Plane) server. It exposes endpoints for various tools, including `search_restaurants`, `get_activities`, `search_hotels`, and `update_map`.

```python
# nomad/mcp_server.py
# FastAPI server with tool endpoints
```