内容
# 规划分析MCP服务器套件
通过 [模型上下文协议](https://modelcontextprotocol.io) 实现对 **IBM规划分析 / TM1** 的自然语言查询和交互式可视化。
与 **任何TM1部署** 配合使用 — 在本地、IBM云或作为服务的规划分析。不同于IBM官方的`pa-cube-mcp`工具（需要PAaaS + watsonx Orchestrate），本套件直接通过TM1py连接到TM1 REST API。
## 内容
| 软件包 | 语言 | 传输 | 目的 |
|---------|----------|-----------|---------|
| [`planning_analytics_mcp`](planning_analytics_mcp/) | Python 3.10+ | stdio | 核心数据服务器 — 查询立方体、浏览维度、执行MDX |
| [`planning_analytics_mcp_app`](planning_analytics_mcp_app/) | Node.js 18+ | 可流式HTTP | 可选UI层 — 交互式表格、图表、仪表盘 |
数据服务器可独立工作。添加应用服务器后，您可以在Claude Desktop、ChatGPT或其他支持 [MCP应用扩展](https://apps.extensions.modelcontextprotocol.io/) 的MCP主机中，将查询结果呈现为交互式视图。
## 架构
```
┌──────────────────────────────────────────────────────────┐
│ MCP主机（Claude Desktop / ChatGPT / Cursor / VS Code） │
│ │
│ ┌───────────────────┐ ┌─────────────────────────┐ │
│ │ 数据服务器 │ │ 应用服务器 │ │
│ │ （Python，stdio） │ │ （Node.js，HTTP :3001） │ │
│ │ │ │ │ │
│ │ pa_list_cubes │ │ pa_app_explore_cubes │ │
│ │ pa_execute_mdx │ │ pa_app_show_mdx_results│ │
│ │ pa_query_cube │ │ pa_app_dashboard │ │
│ │ ...8个工具 │ │ ...3个交互式视图 │ │
│ └─────────┬─────────┘ └─────────────────────────┘ │
└─────────────┼─────────────────────────────────────────────┘
│ TM1py
▼
TM1 REST API（OData v4）
│
▼
IBM规划分析 / TM1
```
大型语言模型使用Python工具获取数据，然后可选地将结果传递给应用工具进行可视化显示。
## 快速入门
### 1. 数据服务器（必需）
```bash
cd planning_analytics_mcp
pip install -e .
export TM1_ADDRESS="您的TM1服务器"
export TM1_PORT="8010"
export TM1_USER="admin"
export TM1_PASSWORD="您的密码"
export TM1_SSL="true"
# 验证连接
PA_MCP_DEBUG=1 python -m planning_analytics_mcp.server
```
### 2. 应用服务器（可选）
```bash
cd planning_analytics_mcp_app
npm install
npm run build
PA_APP_PORT=3001 npm start
```
### 3. 在MCP主机上注册
`claude_desktop_config.json`:
```json
{
"mcpServers": {
"planning-analytics": {
"command": "planning-analytics-mcp",
"env": {
"TM1_ADDRESS": "您的TM1服务器",
"TM1_PORT": "8010",
"TM1_USER": "admin",
"TM1_PASSWORD": "您的密码",
"TM1_SSL": "true"
}
},
"planning-analytics-app": {
"url": "http://localhost:3001/mcp"
}
}
}
```
重启主机后，询问： *"TM1服务器上有哪些立方体可用？"*
## 文档
- **[入门指南（Markdown）](docs/GETTING_STARTED.md)** — 两个服务器的完整设置、故障排除、环境参考
- **[入门指南（Word）](docs/Planning_Analytics_MCP_Getting_Started_Guide.docx)** — 相同内容，格式化为打印/共享
- [数据服务器README](planning_analytics_mcp/README.md)
- [应用服务器README](planning_analytics_mcp_app/README.md)
## 工具
### 数据服务器（`planning_analytics_mcp`）
| 工具 | 描述 |
|------|-------------|
| `pa_list_cubes` | 列出立方体及其元数据；按名称过滤，隐藏控制立方体 |
| `pa_get_cube_dimensions` | 立方体的维度、层次结构和成员计数 |
| `pa_get_dimension_members` | 按层次结构、级别或父节点过滤的成员 |
| `pa_lookup_members` | 按子字符串搜索维度成员 |
| `pa_execute_mdx` | 执行原始MDX并返回格式化结果 |
| `pa_query_cube` | 立方体上下文 + MDX模板，用于自然语言问题 |
| `pa_get_cube_sample_data` | 带有自动生成MDX的样本数据 |
| `pa_server_info` | TM1服务器名称、版本、配置 |
所有工具均为只读，并支持 `markdown` 和 `json` 响应格式。
### 应用服务器（`planning_analytics_mcp_app`）
| 工具 | 视图 |
|------|------|
| `pa_app_explore_cubes` | 具有搜索和可展开维度的交互式立方体树 |
| `pa_app_show_mdx_results` | 可排序表格 + 条形图/折线图/饼图，CSV导出，刷新 |
| `pa_app_dashboard` | 多面板仪表盘：KPI卡片、图表、表格 |
每个应用工具都包含纯文本备用方案，以便不支持MCP应用的主机仍能获得可用的输出。
## 要求
- Python 3.10+（数据服务器）
- Node.js 18+（应用服务器，可选）
- 网络访问您的TM1 REST API
- TM1凭证 — 用户名/密码（本地），API密钥（云）
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
