# Cube.js TypeScript MCP Server

This is a standalone Model Context Protocol (MCP) server for [Cube.js](https://cube.dev/), written in TypeScript using the official `@cubejs-client/core` SDK. 

It provides advanced AI assistants (like Claude, Cursor, etc.) with semantic layer visibility and multi-dimensional querying capabilities over your data.

## Features
- **`discover_entities`**: Introspects the Cube.js metadata (`/meta`) and explains the available Cubes, Dimensions, and Measures to the LLM.
- **`execute_query`**: Executes semantic queries (`/load`) with support for Cube query fields like filters, sorting, time dimensions, pagination, timezone, and result truncation.

## Prerequisites
- Node.js (v18 or higher recommended)
- A running instance of Cube.js

## Quick Start

You can run the published MCP server directly without installing it manually:
```bash
npx -y @mob999/cube_mcp
```

## Local Development & Build

1. **Install dependencies:**
   ```bash
   npm install
   ```

2. **Build the TypeScript source:**
   ```bash
   npm run build
   ```
   *This compiles the TypeScript code into the `dist/` directory.*

## Development & Testing
- **Run Tests:** `npm test`
- **Lint Code:** `npm run lint`

## Query Features

`execute_query` supports:

- `measures`
- `dimensions`
- `filters`
- `timeDimensions`
- `segments`
- `limit`
- `rowLimit`
- `offset`
- `order`
- `timezone`
- `renewQuery`
- `ungrouped`
- `responseFormat`
- `total`

Example:

```json
{
  "entity_name": "Components",
  "measures": ["Components.count"],
  "dimensions": ["Components.id"],
  "timeDimensions": [
    {
      "dimension": "Components.createdAt",
      "granularity": "day",
      "dateRange": ["2026-01-01", "2026-01-31"]
    }
  ],
  "order": [
    { "member": "Components.count", "direction": "desc" },
    { "member": "Components.id", "direction": "asc" }
  ],
  "limit": 100,
  "rowLimit": 500,
  "offset": 0,
  "timezone": "UTC",
  "responseFormat": "compact",
  "total": true
}
```

## Configuration

By default, the server expects your Cube.js API to be available at `http://localhost:4000/cubejs-api/v1`. 

You can override this by setting the `CUBEJS_API_URL` environment variable.

To integrate this semantic layer into Cursor or any other MCP-compatible IDE/Agent, configure it as a **stdio** tool.

**Example `mcp.json` / Client Configuration:**

```json
{
  "mcpServers": {
    "CubeSemanticLayer": {
      "command": "npx",
      "args": ["-y", "@mob999/cube_mcp"],
      "env": {
        "CUBEJS_API_URL": "http://localhost:4000/cubejs-api/v1"
      }
    }
  }
}
```

*Note: The `-y` flag allows `npx` to automatically download and run the package without prompting for confirmation.*