MCP Studio Server

A Model Context Protocol server providing comprehensive tools for managing livestock auction data through the MartEye Studio platform.

Features

• Market Management - Access market information and settings
• Sales Operations - Create, update, and manage auction sales
• Lot Management - Full CRUD operations on auction lots
• Customer Management - Handle buyer and seller information
• Configuration Tools - Manage product codes, tax rates, and adjustments
• Search Functionality - Query across all market data
• Real-time Data - Access live auction information
• Type Safety - Full TypeScript support with Zod validation

API

The server implements 22 MCP tools organized into these categories:

Market Tools

• get_market - Retrieve market information
• get_market_settings - Get default market configuration

Sales Tools

• list_sales - List sales within date ranges
• get_sale - Get detailed sale information
• create_sale - Create new auction sales
• update_sale - Modify existing sales

Lot Tools

• list_lots - List all lots in a sale
• get_lot - Get detailed lot information
• create_lot - Create new lots
• update_lot - Modify existing lots
• delete_lot - Remove lots from sales

Customer Tools

• list_customers - List all market customers
• get_customer - Get customer details
• create_customer - Add new customers
• get_customer_by_account_number - Find customers by account

Configuration Tools

• list_product_codes - Get product configurations
• get_product_code - Get specific product details
• list_tax_rates - Get tax configurations
• get_tax_rate - Get specific tax rates
• list_adjustments - Get adjustment configurations
• get_adjustment - Get specific adjustments

Search Tools

• search_market - Search across market data

Lot Item Tools

• create_lot_item - Add items to lots
• update_lot_item - Modify lot items
• delete_lot_item - Remove items from lots

Installation

NPX (Recommended)

npx @marteye/studio-mcp

Claude Desktop

To use with Claude Desktop, add the server config:

{
  "mcpServers": {
    "studio": {
      "command": "npx",
      "args": ["@marteye/studio-mcp"],
      "env": {
        "STUDIO_API_KEY": "your-studio-api-key"
      }
    }
  }
}

Local Development

Clone and build:

git clone <repository-url>
cd studio-mcp
npm install
npm run build
npm start

Configuration

Set your Studio API key as an environment variable:

export STUDIO_API_KEY="your-studio-api-key"

Or create a .env file:

STUDIO_API_KEY=your-studio-api-key

Usage Examples

Once connected to your MCP client, you can interact with Studio using natural language:

• "Show me all sales for market abc123 this week"
• "Create a new customer with name John Smith in market abc123"
• "List all lots in sale xyz789"
• "Search for customers named Smith in market abc123"
• "Get the product codes for market abc123"
• "Create a new lot in sale xyz789 with product code SHEEP"

Authentication

All operations require a valid Studio API key. Obtain your API key from your MartEye Studio account and set it as the STUDIO_API_KEY environment variable.

Security Note: Never commit API keys to version control. Use environment variables or secure configuration management.

Error Handling

The server provides detailed error responses for:

• Authentication failures - Invalid or missing API keys
• Validation errors - Invalid parameter formats or missing required fields
• Resource not found - Non-existent markets, sales, lots, or customers
• Rate limiting - API usage limits exceeded
• Network issues - Connection problems with Studio API

Development

Build

npm run build

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Type Checking

npm run typecheck

Data Types

The server handles comprehensive livestock auction data:

• Markets - Auction house information and settings
• Sales - Auction events with timing and product specifications
• Lots - Groups of items being auctioned
• Customers - Buyer and seller profiles with addresses
• Product Codes - Item categorization and pricing rules
• Tax Rates - Jurisdiction-specific tax configurations
• Adjustments - Commission and fee structures

License

MIT