内容
# Cube.js TypeScript MCP 服务器
这是一个独立的模型上下文协议（MCP）服务器，用于 [Cube.js](https://cube.dev/)，使用官方的 `@cubejs-client/core` SDK 以 TypeScript 编写。
它为高级 AI 助手（如 Claude、Cursor 等）提供语义层可见性和多维查询能力，以查询您的数据。
## 功能特点
- **`discover_entities`**: introspect Cube.js 元数据（`/meta`）并向 LLM 解释可用的 Cubes、Dimensions 和 Measures。
- **`execute_query`**: 执行语义查询（`/load`）并支持 Cube 查询字段，如过滤器、排序、时间维度、分页、时区和结果截断。
## 前置条件
- Node.js（推荐 v18 或更高版本）
- 运行中的 Cube.js 实例
## 快速开始
您可以直接运行已发布的 MCP 服务器，而无需手动安装：
```bash
npx -y @mob999/cube_mcp
```
## 本地开发与构建
1. **安装依赖：**
```bash
npm install
```
2. **构建 TypeScript 源代码：**
```bash
npm run build
```
*这将 TypeScript 代码编译到 `dist/` 目录。*
## 开发与测试
- **运行测试：** `npm test`
- **代码检查：** `npm run lint`
## 查询功能
`execute_query` 支持：
- `measures`
- `dimensions`
- `filters`
- `timeDimensions`
- `segments`
- `limit`
- `rowLimit`
- `offset`
- `order`
- `timezone`
- `renewQuery`
- `ungrouped`
- `responseFormat`
- `total`
示例：
```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
}
```
## 配置
默认情况下，服务器期望您的 Cube.js API 可在 `http://localhost:4000/cubejs-api/v1` 访问。
您可以通过设置 `CUBEJS_API_URL` 环境变量来覆盖此设置。
要将此语义层集成到 Cursor 或其他支持 MCP 的 IDE/Agent 中，请将其配置为 **stdio** 工具。
**示例 `mcp.json` / 客户端配置：**
```json
{
"mcpServers": {
"CubeSemanticLayer": {
"command": "npx",
"args": ["-y", "@mob999/cube_mcp"],
"env": {
"CUBEJS_API_URL": "http://localhost:4000/cubejs-api/v1"
}
}
}
}
```
*注意：`-y` 标志允许 `npx` 自动下载和运行软件包，而无需提示确认。*
