npm package: @marteye/studio-mcp
Description: MCP server for Studio with tools to manipulate Studio data using the studiojs SDK
Author: MartEye
Latest version: 1.0.5

# MCP Studio Server

A Model Context Protocol server providing comprehensive tools for managing livestock auction data through the [MartEye Studio](https://www.npmjs.com/package/@marteye/studiojs) 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)
```bash
npx @marteye/studio-mcp
```

### Claude Desktop

To use with Claude Desktop, add the server config:

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

### Local Development

Clone and build:

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

## Configuration

Set your Studio API key as an environment variable:

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

```bash
npm run build
```

### Testing

```bash
# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch
```

### Type Checking

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