npm package: @stqry/mcp-server
Description: MCP server for STQRY Builder API
Latest version: 0.2.5

# @stqry/mcp-server

MCP server for the STQRY Builder API. Auto-generates tools from the STQRY OpenAPI spec, letting LLMs (Claude, ChatGPT, etc.) manage tours, screens, collections, media, and more through natural language.

## Features

- **66 API tools** auto-generated from the STQRY OpenAPI spec
- **Multi-project support** — switch between STQRY projects mid-session
- **4 regions** — US, Canada, EU, Australia
- **LLM-friendly descriptions** for key tools
- **stdio transport** for use with Claude Desktop, Cursor, and other MCP clients

## Prerequisites

- Node.js >= 18
- A STQRY Builder API key (one per project)

## Installation

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

## Configuration

Create `~/.stqry-mcp.json`:

```json
{
  "projects": {
    "museum-of-art": {
      "apiKey": "your-api-key",
      "region": "us",
      "description": "Museum of Art production"
    },
    "history-center": {
      "apiKey": "another-api-key",
      "region": "eu",
      "description": "History Center staging"
    }
  },
  "defaultProject": "museum-of-art"
}
```

| Field | Required | Description |
|-------|----------|-------------|
| `projects` | Yes | At least one project |
| `projects.*.apiKey` | Yes | STQRY API key (`X-Api-Token` header) |
| `projects.*.region` | Yes | `us`, `ca`, `eu`, or `au` |
| `projects.*.description` | No | Human-readable label |
| `defaultProject` | No | Must match a project key if set |

### Regions

| Region | API Base URL |
|--------|-------------|
| `us` | `https://api-us.stqry.com` |
| `ca` | `https://api-ca.stqry.com` |
| `eu` | `https://api-eu.stqry.com` |
| `au` | `https://api-au.stqry.com` |

## Usage

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "stqry": {
      "command": "node",
      "args": ["/absolute/path/to/stqry-mcp/dist/index.js"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "stqry": {
      "command": "node",
      "args": ["/absolute/path/to/stqry-mcp/dist/index.js"]
    }
  }
}
```

### Direct (stdio)

```bash
node dist/index.js
```

### MCP Inspector

Debug and explore available tools:

```bash
npm run inspect
```

## Tools

### Project Management

| Tool | Description |
|------|-------------|
| `stqry_list_projects` | List all configured projects and show which is active |
| `stqry_switch_project` | Switch the active project for subsequent API calls |

### API Tools

Tools follow the naming convention `stqry_{resource}_{action}`. Key resources:

| Resource | Actions | Description |
|----------|---------|-------------|
| `screens` | list, get, create, update, delete | Tour stops, exhibits, POIs |
| `collections` | list, get, create, update, delete | Tours, lists, menus |
| `collection_items` | list, create, update, delete, update_positions | Items within collections |
| `story_sections` | list, create, update, delete, update_positions | Content blocks within screens |
| `media_items` | list, get, create, update, delete | Images, audio, video, AR models |
| `codes` | list, get, create, update, delete | Promotional/access codes |
| `uploaded_files` | list, presigned | File uploads via S3 presigned URLs |
| `projects` | get | Project details |

Sub-item resources for story sections: `story_section_badge_items`, `story_section_link_items`, `story_section_media_items`, `story_section_opening_time_items`, `story_section_price_items`, `story_section_social_items`.

All tools include path parameters as required inputs and query parameters as optional inputs. Tools that modify data accept a `body` object with the request payload.

## Development

```bash
npm run dev          # Watch mode (recompile on change)
npm test             # Run tests
npm run test:watch   # Watch mode tests
npm run build        # Production build
```

### Project Structure

```
src/
├── index.ts                  # Entry point, stdio transport
├── server.ts                 # MCP server setup & tool routing
├── config/loader.ts          # Config loading & Zod validation
├── openapi/
│   ├── parser.ts             # OpenAPI spec → MCP tool generation
│   └── overrides.ts          # LLM-friendly description overrides
├── client/stqry-client.ts    # HTTP client for STQRY API
├── tools/project-tools.ts    # Project list/switch tools
└── types/index.ts            # Shared TypeScript types
spec/
└── stqry-openapi.json        # Bundled OpenAPI 3.1.0 spec
```

## License

Proprietary — STQRY.