npm package: @golocalinteractive/storage-essentials-mcp
Description: MCP server for Storage Essentials API V2
Latest version: 1.1.0

# Storage Essentials MCP Server (Read-Only)

Model Context Protocol (MCP) server for querying Storage Essentials API V2. This is a **read-only** server that provides access to retrieve data without creating or modifying records.

## Features

- **Read-Only Operations**: Safe querying of companies, facilities, units, and promotions
- **V2 API Support**: Full access to V2 REST API endpoints
- **Auto-authentication**: Automatic token management and refresh
- **Environment Support**: Local, Staging, and Production environments
- **Type-safe**: Full TypeScript implementation with type definitions
- **Client-side Pagination**: Built-in pagination support for large datasets

## Installation

```bash
npm install
npm run build
```

## Configuration

### Environment Variables

The following environment variables are required:

```bash
# Required
SE_API_KEY=your_api_key_here

# Optional (defaults to staging)
SE_ENVIRONMENT=staging  # Options: local, staging, production
SE_BASE_URL=https://api-storageessentials.golocaldev.com  # Override default URL
```

### Claude Desktop Configuration

Add to your Claude Desktop config file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "storage-essentials": {
      "command": "npx",
      "args": ["@golocalinteractive/storage-essentials-mcp"],
      "env": {
        "SE_API_KEY": "your_api_key_here",
        "SE_ENVIRONMENT": "staging"
      }
    }
  }
}
```

## Available Tools

**Naming Convention:** Tools follow a plural/singular pattern - plural names (e.g., `GetCompanies`) return collections, singular names (e.g., `GetCompany`) require an ID parameter.

### Companies

- `seV2GetCompanies` - Get all companies
- `seV2GetCompany` - Get a specific company (requires `company_id`)
- `seV2GetCompanyCredentials` - Get all credentials for a company (requires `company_id`)
- `seV2GetCompanyRentals` - Get all rentals for a company (requires `company_id`)

### Facilities

- `seV2GetFacilities` - Get all facilities (with optional company filter)
- `seV2GetFacility` - Get a specific facility (requires `facility_id`)

### Units

- `seV2GetUnits` - Get all units for a facility (filterable by status, type) **with pagination support** (requires `facility_id`)
- `seV2GetUnit` - Get a specific unit (requires `facility_id` and `unit_id`)

### Unit Types & Categories

- `seV2GetUnitTypes` - Get all unit types for a facility (e.g., 5x5, 10x10) **with pagination support** (requires `facility_id`)
- `seV2GetUnitCategories` - Get all unit categories for a facility (e.g., Climate Controlled) (requires `facility_id`)

### Promotions

- `seV2GetPromotions` - Get all promotions for a facility (requires `facility_id`)
- `seV2GetPromotion` - Get a specific promotion (requires `facility_id` and `promotion_id`)

## Usage Examples

### Example 1: Get All Facilities

```typescript
// Using seV2GetFacilities tool
{
  "search": "Kansas City"  // Optional search filter
}
```

### Example 2: Get Available Units with Pagination

```typescript
// Using seV2GetUnits tool
{
  "facility_id": "12345",
  "status": "Available",
  "page": 1,
  "per_page": 20
}
```

### Example 3: Get Company Details

```typescript
// Using seV2GetCompany tool
{
  "company_id": "67890"
}
```

### Example 4: List Promotions for a Facility

```typescript
// Using seV2GetPromotions tool
{
  "facility_id": "12345"
}
```

## Development

### Running in Development Mode

```bash
npm run dev
```

### Building

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

## Local Testing with Claude Code

### Step 1: Build the Project

```bash
npm install
npm run build
```

### Step 2: Get Your API Key

For developers investigating, use the api_key from the companies table you're currently investigating.

### Step 3: Update Claude Desktop Configuration

On macOS, the configuration file is located at:

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

Open the file and add the MCP server configuration:

```json
{
  "mcpServers": {
    "storage-essentials": {
      "command": "npx",
      "args": ["@golocalinteractive/storage-essentials-mcp"],
      "env": {
        "SE_API_KEY": "your_actual_api_key_here",
        "SE_ENVIRONMENT": "staging"
      }
    }
  }
}
```

**Important:**

- Replace `/Users/{user}/Projects/hack/claude/se-mcp` with the actual absolute path to your project
- Replace `your_actual_api_key_here` with your real API key
- Set `SE_ENVIRONMENT` to `local`, `staging`, or `production`

### Step 4: Restart Claude Desktop

Completely quit and restart Claude Desktop for the changes to take effect.

### Step 5: Verify Installation

In Claude Code, you should now see the Storage Essentials MCP tools available. Try a simple test:

```
Can you list the available Storage Essentials facilities?
```

This will use the `seV2FacilitiesList` tool.

### Troubleshooting

**Problem: Tools not appearing**

- Verify the path in the config is absolute and correct
- Check that `build/index.js` exists in your project directory
- Ensure Claude Desktop was fully restarted (not just window closed)

**Problem: Authentication errors**

- Verify your `SE_API_KEY` is correct
- Check the `SE_ENVIRONMENT` matches where your API key is valid
- Look at Claude Desktop logs for detailed error messages

**Problem: "Command not found" or similar errors**

- Make sure you ran `npm run build` successfully
- Check that `node` is available in your PATH
- Verify the shebang (`#!/usr/bin/env node`) is at the top of `build/index.js`

### Viewing Logs

Claude Desktop logs can help debug issues:

- macOS: `~/Library/Logs/Claude/`

## Project Structure

```
src/
  index.ts          # Main MCP server entry point
  types.ts          # TypeScript type definitions
  auth.ts           # Authentication manager
  utils.ts          # Utility functions
  v2/
    base.ts         # Base class for V2 operations
    index.ts        # V2 API endpoint handlers
```

## API Versioning

- **V2 API**: Uses Accept header `application/vnd.storageessentials.v2+json`
- RESTful endpoints under `/api/*` prefix
- Bearer token authentication with automatic refresh

## Authentication Flow

1. Server initializes with `SE_API_KEY` from environment
2. First API call triggers automatic authentication via `/login` endpoint
3. Token is cached and automatically refreshed before expiry
4. All subsequent requests use the cached Bearer token

## Error Handling

The server provides detailed error messages for:

- Missing required parameters
- Authentication failures
- API request errors
- Invalid tool names

Errors are returned in the format:

```json
{
  "content": [{ "type": "text", "text": "Error: <error message>" }],
  "isError": true
}
```

## License

MIT

## Support

For issues or questions, please refer to the Storage Essentials API documentation or contact support.