Sisense MCP服务器

Sisense本地MCP服务器

一种模型上下文协议（MCP）服务器，通过标准化接口提供对Sisense数据和分析的访问。该服务器允许AI助手和其他MCP客户端与Sisense仪表板、数据源进行交互，并执行查询。

特性

• 🔌 MCP协议支持 -完整模型上下文协议实现
• 📊 Sisense集成 -访问仪表板、数据源和分析
• 🛠️ 工具支持 -8个用于Sisense操作的内置工具
• 📚 资源访问 -浏览和阅读Sisense仪表板作为资源
• 🔐 认证 -支持Sisense API代币
• 🧪 综合测试 -Jest的全面测试覆盖
• 📝 TypeScript -完全类型化，具有现代TypeScript功能
• 🎨 代码质量 -ESLint、Prettier和现代开发工具

先决条件

• Node.js>=22.0.0
• npm>=10.0.0
• 访问Sisense实例+SDK API

安装

1. 克隆存储库：

   复制

   git clone git@github.com:dshappir/sisense-local-mcp-server.git
   cd sisense-local-mcp-server
   

2. 安装依赖项：

   复制

   npm install
   

3. 设置环境变量：

   复制

   cp env.example .env
   

   编辑 .env 使用您的Sisense配置：

   复制

   # Sisense Configuration
   SISENSE_URL=https://your-sisense-instance.com
   SISENSE_API_KEY=your-api-key
   
   # Server & Debug Settings
   ...
   

4. 构建项目：

   复制

   npm run build
   

配置光标

要将此MCP服务器与Cursor IDE一起使用，请执行以下步骤：

第一步：构建项目

确保在配置Cursor之前构建项目（见上文）。 这将创建 dist/ 包含已编译JavaScript文件的目录。

第二步：获取绝对路径

您需要构建服务器文件的绝对路径(dist/index.js).您可以通过以下方式获得：

在macOS/Linux上：

pwd  # Shows current directory
# Example output: /Users/username/sisense-local-mcp-server
# Full path would be: /Users/username/sisense-local-mcp-server/dist/index.js

在Windows上：

cd
REM Example output: C:\Users\username\sisense-local-mcp-server
REM Full path would be: C:\Users\username\sisense-local-mcp-server\dist\index.js

步骤3：在游标设置中配置

1. 打开光标设置：

   • 按 Cmd + Shift + P （Mac）或 Ctrl + Shift + P, （Windows/Linux）打开命令面板
   • 选择 View: Open MCP Settings

2. 添加新的MCP服务器：

   • 点击 + Add New MCP Server 按钮

3. 配置服务器： 在 mcp.json 打开文件进行编辑，添加以下JSON片段，更新 args 相应的路径：

   复制

        "sisense": {
            "command": "node",
            "args": [
                "${userHome}/sisense-local-mcp-server/dist/index.js"
            ],
            "env": {
                "SISENSE_URL": "<running Sisense instance URL>",
                "SISENSE_API_KEY": "<Sisense API key>"
            }
        }
   

   关闭选项卡（保存文件）。

4. 管理MCP服务器：

   • 在 Installed MCP servers 您应该看到一个名为的新条目 sisense
   • 它旁边应该有一个绿点，表示它正在运行。如果没有，请尝试禁用/启用它，然后重新启动Cursor
   • 它应该显示它启用了工具

步骤4：验证配置

• 尝试让Cursor使用Sisense工具之一，例如：
  • “列出所有sisense数据模型”
  • “获取有关sisense服务器的信息”

光标配置故障排除

如果服务器未启动或工具不可用：

1. 检查构建状态：

   • 确保你已经跑过了 npm run build 成功地
   • 这 dist/ 目录应存在并包含已编译的文件

2. 检查路径：

   • 确保绝对路径 dist/index.js 是正确的
   • 验证文件是否存在： ls dist/index.js （Mac/Linux）或 dir dist\index.js （Windows）

3. 检查Sisense设置：

   • 验证Sisense实例是否存在，以及是否在指定的URL上工作
   • 确保API密钥正确且最新

4. 检查游标日志：

   • 打开Cursor的开发人员控制台查看错误消息
   • 查找MCP服务器连接错误

5. 手动测试：

   • 尝试手动运行服务器以确保其正常工作：
     复制

     echo '{"jsonrpc":"2.0", "id":1, "method":"tools/list", "params":{}}' | node dist/index.js
     

   • 服务器应无错误启动（它将等待stdin上的输入）
   • 显示可用工具的JSON输出，包括输入/输出配置

用法

发展模式

在开发模式下以热重新加载启动服务器：

npm run dev

生产模式

构建并启动服务器：

npm run build
npm start

测试

运行测试套件：

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

代码质量

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Check formatting
npm run format:check

# Type checking
npm run type-check

调试

该项目已配置为使用Node.js检查器使用Cursor/VS Code进行调试。

命令行调试

# Debug production build (--inspect)
npm run debug

# Debug production build (--inspect-brk - breaks on first line)
npm run debug:brk

# Debug development mode (--inspect)
npm run debug:dev

# Debug development mode (--inspect-brk - breaks on first line)
npm run debug:dev:brk

游标/VS代码调试

1. 在Cursor/VS Code中打开项目

2. 转到调试面板 （Ctrl+Shift+D/Cmd+Shift+D）

3. 选择调试配置：

   • Debug Production (--inspect) -调试构建的应用程序
   • Debug Production (--inspect-brk) -使用启动时中断调试构建的应用程序
   • Debug Development (--inspect) -直接调试TypeScript源代码
   • Debug Development (--inspect-brk) -调试启动时中断的TypeScript源代码
   • Attach to Process -附加到已运行的调试进程
   • Debug Tests -调试Jest测试

4. 设置断点 通过单击行号旁边的檐槽

5. 启动调试 按F5或单击播放按钮

调试配置详细信息

• 生产调试 在中使用编译的JavaScript dist/
• 开发调试 直接使用TypeScript源文件 tsx
• 环境变量 设置为最佳调试（LOGLEVEL=调试，debug=真）
• 源地图 已启用以进行正确的TypeScript调试
• 节点内部 排除在调试之外，以获得更清晰的体验

附加到外部流程

如果您已经有一个进程在运行 --inspect 或 --inspect-brk:

1. 启动您的流程： npm run debug 或 npm run debug:brk
2. 在调试面板中选择“附加到进程”
3. 调试器将连接到端口9229上正在运行的进程

可用工具

MCP服务器提供以下工具：

服务器信息

• get_server_info -获取有关Sisense服务器的信息

数据源

• list_data_sources -列出所有可用数据源
• list_cubes -列出所有可用的多维数据集
• get_cube_metadata -获取特定多维数据集的元数据

仪表盘

• list_dashboards -列出所有仪表板
• get_dashboard -获取特定仪表板的详细信息
• get_dashboard_widgets -从特定仪表板获取小部件

查询执行

• execute_query -对Sisense执行查询

可用资源

服务器将Sisense仪表板作为MCP资源公开：

• sisense://dashboard/{id} -以JSON格式访问仪表板数据

配置

环境变量

项目结构

src/
├── config/
│   └── environment.ts      # Environment configuration
├── server/
│   └── mcp-server.ts       # Main MCP server implementation
├── services/
│   └── sisense.ts          # Sisense API service
├── types/
│   └── index.ts            # TypeScript type definitions
├── utils/
│   └── logger.ts           # Logging utility
└── index.ts                # Application entry point

tests/
├── setup.ts                # Test setup
├── services/
│   └── sisense.test.ts     # Sisense service tests
├── server/
│   └── mcp-server.test.ts  # MCP server tests
└── utils/
    └── logger.test.ts      # Logger tests

发展

代码的风格

本项目使用：

• TypeScript 严格的类型检查
• ESLint 用于代码过滤
• 更漂亮 用于代码格式化
• 开玩笑 用于测试

添加新工具

1. 将工具定义添加到 getAvailableTools() 在 mcp-server.ts
2. 在中实现工具逻辑 callTool() 方法
3. 添加相应的方法 SisenseService 如有需要
4. 为新工具编写测试

添加新资源

1. 在中添加资源处理 getAvailableResources() 和 readResource() 方法
2. 实现资源获取逻辑
3. 为新资源类型添加测试

故障排除

常见问题

1. 身份验证错误

   • 验证您的Sisense凭据是否正确
   • 检查Sisense URL是否可访问
   • 确保您正在使用令牌或用户名/密码身份验证

2. 连接问题

   • 验证Sisense URL是否正确且可访问
   • 检查网络连接
   • 确保防火墙设置正确

3. 构建问题

   • 确保你使用的是Node.js>=22.0.0
   • 清除node_modules并重新安装： rm -rf node_modules && npm install
   • 检查TypeScript配置

调试模式

通过设置启用调试日志记录 DEBUG=true 在你的 .env 文件：

DEBUG=true
LOG_LEVEL=debug

贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature-name
3. 进行更改
4. 运行测试： npm test
5. 运行linting： npm run lint
6. 提交您的更改： git commit -m 'Add feature'
7. 推到分支： git push origin feature-name
8. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

对于问题和疑问：

1. 检查上面的故障排除部分
2. 审查存储库中的现有问题
3. 使用有关您问题的详细信息创建新问题