🤖 FES助理：您的代理Sisense副驾驶

⚠️ 实验项目通知

Sisense现场工程社区贡献工具

该项目是Sisense Field Engineering开发的一个实验工具，旨在促进客户学习和探索Sisense的能力。虽然由现场工程部维护，但它是“按原样”共享的，以鼓励反馈和实验。

重要免责声明：此工具不是Sisense核心产品发布生命周期的一部分，也不会经历与一般可用（GA）Sisense功能相同的验证、支持或认证过程。它旨在补充而不是取代官方支持的Sisense功能。

______________________________________________________________________

技术和安全注意事项

部署和执行控制

本地SDK使用（PySisense）：所有处理逻辑都在您的机器或服务器上本地运行。没有数据传输给Sisense现场工程部。
自托管组件（FES助手/MCP服务器）：这些组件专为在您自己的环境（本地或VPC）中部署而设计。您可以完全控制基础设施、安全配置、访问控制和日志。

数据和LLM处理

LLM功能状态：默认情况下，FES助手摘要功能已禁用。
数据传输：启用摘要功能后，通过Sisense SDK检索到的响应可能会发送到您选择的大型语言模型（LLM）提供商进行处理。
第三方客户端：当将MCP服务器与第三方客户机（例如IDE代理或Claude desktop等桌面助理）一起使用时，从Sisense检索到的数据会直接传递给客户的LLM。
客户责任：客户有责任选择符合其组织数据隐私和安全要求的LLM提供商。

______________________________________________________________________

关于FES助理

FES Assistant是一个基于MCP的代理工具包，用于Sisense环境操作。它帮助您使用自然语言自动化治理检查、迁移和日常管理工作流程，因此您可以在不编写一次性API脚本的情况下协调任务。

______________________________________________________________________

🚀 为什么每个Sisense用户都需要副驾驶：

📈 对于仪表板设计师： 立即找到仪表板，审核您自己的小部件，并在不深入菜单的情况下进行环境良好检查。
🏗️ 对于数据设计者： 模型优化的专业副驾驶——查找未使用的字段，审核M2M关系，并通过自然语言聊天构建数据模型。
🛡️ 管理员： 用于环境/租户迁移、批量治理和全平台代码编排的自动化引擎。

______________________________________________________________________

FES Assistant architecture

*有关完整的端到端执行流（包括SSE流、进度传播和变异批准循环），请参阅 Execution_Flow.md.*

______________________________________________________________________

关键代理能力

自主基础设施审计： 让代理在整个环境中查找多对多关系、未使用的数据模型字段或孤立资产。
零接触迁移： 通过内置的安全循环和确认步骤，对仪表板和数据模型执行复杂的跨租户移动。
协议优先集成： 作为一个 流式HTTP MCP服务器，允许您使用此UI或将Sisense“工具”直接插入Claude Desktop等外部代理。
实时进度可见性： 建于 服务器发送事件（SSE） 为长时间运行的迁移和批量任务提供实时流媒体更新（V2）。
隐私第一逻辑： 包括手册 摘要切换 确保原始数据响应在需要时保留在您的基础架构中。

______________________________________________________________________

🏗️ 架构与流程

FES Assistant构建为模块化堆栈，以确保您可以在需要时独立使用MCP服务器：

编排者： A. 流线型UI (frontend/app.py)用于任务控制。
大脑： A. 后端API+代理层 (backend/api_server.py)它处理计划、工具选择和确认循环。
桥：一 MCP流式HTTP服务器 (mcp_server/server.py)将AI意图转化为 PySisense SDK操作。

MCP服务器文档：元管理MCP服务器

______________________________________________________________________

快速链接

.env.example

config_prod.sh

frontend/app.py

backend/api_server.py

backend/runtime.py

backend/agent/llm_agent.py

backend/agent/mcp_client.py

mcp_server/server.py

mcp_server/tools_core.py

Execution_Flow.md

refresh_registry.sh

______________________________________________________________________

特性

UI中的两种主要模式

- 与部署聊天 - 连接到单个Sisense部署，并与可以检查和操作该环境的代理进行通信。 - 在部署之间迁移 - 连接来源和目标 Sisense环境，并使用迁移工具移动资产。

SSE进度流（V2）

- UI流代理转动并显示实时进度更新。 - 进度被记录到每次运行的“运行日志”中，并在助手响应下呈现。 - 特别适用于长时间迁移和批量操作。

基于PySisense的MCP驱动工具

- PySisense SDK方法被包装为MCP工具，并通过 工具注册表JSON. - 工具涵盖了访问管理、数据模型、仪表板、迁移和井检查等领域。

两个LLM后端（可配置）

- 切换 Azure OpenAI 和 copula模型服务 通过改变环境变量。 - 代理层抽象于提供者之上，因此应用程序的其余部分行为相同。

通过确认回路实现安全

- 对于 创建/修改/删除/迁移-样式操作，代理使用 确认循环: - 代理解释它计划做什么（哪些资产、哪些环境、发生了什么变化）。 - UI向用户显示此计划。 - 该操作仅在明确确认后执行。

可选的“无摘要”隐私模式

- 您可以禁用通过环境变量和（可选）UI切换将工具结果发送回LLM。 - 在该模式下，工具仍在运行，但助手只返回轻量级状态消息。

______________________________________________________________________

建筑

高水位流量：

用户与溪流在 frontend/app.py.
UI调用 后端API (backend/api_server.py)通过HTTP（例如 /health, /tools, /agent/turn).
后端：

- 管理 每会话MCP客户端 和状态在 backend/runtime.py. - 用途 backend/agent/llm_agent.py 用于规划、工具选择、突变批准和总结。 - 用途 backend/agent/mcp_client.py 调用MCP服务器（JSON-RPC over Streamable HTTP）。 - 当UI请求时，通过SSE将进度流式传输到UI。

这 MCP流式HTTP服务器 (mcp_server/server.py):

- 暴露 /health. - 显示MCP端点 /mcp/ 实施MCP 流式HTTP （JSON-RPC）。 - 对于支持流式传输的工具调用，请使用 上海证券交易所 包含： - JSON-RPC通知（进度），然后 - 具有匹配请求id的最终JSON-RPC响应消息。 - 用途 mcp_server/tools_core.py 将工具ID映射到PySisense SDK调用。 - 从以下位置读取工具注册表JSON config/.

PySisense使用Sisense REST API与您的Sisense部署进行通信。

文件夹结构

Root/
  backend/
    agent/
      __init__.py
      llm_agent.py        # LLM orchestration: planning, tool selection, approvals, optional summarization
      mcp_client.py       # MCP Streamable HTTP client (JSON-RPC over POST /mcp/, supports SSE tool progress)
    __init__.py
    runtime.py            # Session pool, long-lived McpClient per UI session, progress bridging
    api_server.py         # FastAPI backend (JSON + SSE on /agent/turn; exposes /health and /tools)

  config/
    tools.registry.json                 # Base tool registry generated from the SDK
    tools.registry.with_examples.json   # Registry enriched with LLM examples

  frontend/
    app.py               # Streamlit UI (SSE client for backend /agent/turn)

  images/
    FES_ASSISTANT_AD.png
    ui1.png
    ui2.png

  logs/                  # Runtime logs (rotated; not committed)

  mcp_server/
    server.py            # MCP Streamable HTTP server (/mcp/ JSON-RPC, /health; SSE for streaming tools/call)
    tools_core.py        # Registry loading, SDK client construction, tool dispatch, emit/progress integration

  scripts/
    __init__.py
    01_build_registry_from_sdk.py       # Introspects PySisense SDK and builds tools.registry.json
    02_add_llm_examples_to_registry.py  # Uses an LLM to add examples; writes tools.registry.with_examples.json
    README.md                           # Notes for the scripts

  .env.example
  .gitignore
  .dockerignore
  LICENSE
  README.md
  Execution_Flow.md
  refresh_registry.sh
  requirements.txt

  # Docker-related files
  Dockerfile.backend        # Image for backend FastAPI service
  Dockerfile.ui             # Image for Streamlit UI
  Dockerfile.mcp            # Image for MCP Streamable HTTP server
  docker-compose.yml        # Local/dev docker-compose (uses .env)
  docker-compose.prod.yml   # Example production compose (uses real env vars)
  config_prod.sh            # Example script to export prod env vars (no secrets)

______________________________________________________________________

先决条件

Python 3.11+
Sisense Fusion部署（或多个，用于迁移用例）
访问至少一个LLM提供者：

- Azure OpenAI，或 - copula模型服务

（可选但推荐）Docker+Docker Compose用于容器化运行

______________________________________________________________________

环境配置

该项目保持 LLM凭据和服务配置 在环境变量中。\ Sisense基本URL和令牌直接输入Streamlit UI，并仅存储在当前浏览器会话的会话状态中。

对于本地开发，您可以使用 .env 文件（参见 .env.example).\ 在Docker/生产环境中，您应该在每个容器上设置与真实环境变量相同的值（例如通过 --env-file, docker-compose env_file:，或采购 config_prod.sh).

1） UI（Streamlit）配置

阅读者 frontend/app.py:

FES_LOG_LEVEL\

UI进程的日志级别： DEBUG, INFO, WARNING, ERROR.

FES_BACKEND_URL\

UI每次调用的后端FastAPI服务器的URL。\ 例子： http://localhost:8001

FES_UI_IDLE_TIMEOUT_HOURS\

Streamlit会话的空闲超时时间（小时）。超过时，UI会清除 st.session_state.

FES_ALLOW_SUMMARIZATION_TOGGLE\

控制是否在UI中启用“允许摘要”复选框。

- true → 用户可以在每个会话中切换 - false → 复选框已禁用且始终处于关闭状态

2）后端（FastAPI）配置

阅读者 backend/api_server.py 和 backend/agent/llm_agent.py:

FES_LOG_LEVEL\

与UI相同；控制后端日志记录。

ALLOW_SUMMARIZATION\

后端硬终止开关，用于将工具结果（Sisense数据）发送到LLM。

- true → 允许（取决于UI切换） - false → 从未被送往法学硕士

LLM_PROVIDER\

要使用哪个LLM后端： azure 或 databricks.

Azure OpenAI（当 LLM_PROVIDER=azure):

AZURE_OPENAI_ENDPOINT
AZURE_OPENAI_DEPLOYMENT
AZURE_OPENAI_API_KEY
AZURE_OPENAI_API_STYLE （通常 v1)

docker（当 LLM_PROVIDER=databricks):

DATABRICKS_HOST
DATABRICKS_TOKEN
LLM_ENDPOINT

可选LLM重试调优：

LLM_HTTP_MAX_RETRIES
LLM_HTTP_RETRY_BASE_DELAY

3）后端→ MCP客户端配置（SSE感知）

阅读者 backend/agent/mcp_client.py:

PYSISENSE_MCP_HTTP_URL\

MCP流式HTTP服务器的基本URL。客户来电 /mcp/ 在这个基本URL下。

PYSISENSE_MCP_HTTP_TIMEOUT\

MCP呼叫的默认超时（秒）。\ 注意：流式工具调用消除了读取超时（无限制），因此长时间运行的迁移可以流式传输进度。

MCP_HTTP_MAX_RETRIES 和 MCP_HTTP_RETRY_BASE_DELAY\

重新调整MCP呼叫。建议对长时间运行/非幂等工具保持较低的重试率。

可选SSE行为：

MCP_AUTO_SUBSCRIBE\

如果 true，MCP客户端启动一个可选的长期 GET /mcp/ 连接上的SSE订阅。\ 这对于在GET流上发出进度而不是（或除了）POST响应的服务器很有用。

MCP_STREAMING_TOOL_IDS\

以逗号分隔的工具ID列表被视为“流敏感”（长时间运行）。\ 对于这些工具，客户端会删除读取超时并期望SSE响应。

4） MCP工具服务器/PySsense配置

阅读者 mcp_server/tools_core.py 和 mcp_server/server.py:

PYSISENSE_REGISTRY_PATH\

工具注册表JSON的路径。\ 违约： config/tools.registry.with_examples.json

ALLOW_MODULES\

要公开的模块的可选逗号分隔列表。\ 例子： ALLOW_MODULES=access,datamodel

PYSISENSE_SDK_DEBUG\

可选标志传递给 SisenseClient.from_connection(debug=...).\ 设置为 true 或 false.建议：取消设置（或 false)正常使用。

MCP工具命名（克劳德兼容性）

MCP_TOOL_NAME_MODE\

Claude Desktop拒绝包含以下内容的工具名称 . 在工具/列表发现期间。 - claude → 发布下划线工具名称（推荐） - canonical → 发布虚线工具id（旧版）

服务器在工具调用时仍将接受下划线和虚线名称。

并发上限（单工作者友好型）

这些措施减少了长时间运行的迁移造成的线路阻塞，同时将MCP服务器保持在单个工作器上：

PYSISENSE_MAX_CONCURRENT_MIGRATIONS （默认值： 1)\

允许同时运行的最大迁移数。

PYSISENSE_MAX_CONCURRENT_READ_TOOLS （默认值： 5)\

迁移运行时允许并发运行的短/读工具的最大数量。

5） Sisense配置（在UI中输入，而不是在 `.env`)

在 与部署聊天 模式：

Sisense域名（基本URL）
API令牌
验证SSL标志

在 在部署之间迁移 模式：

源域+源API令牌（+源SSL标志）
目标域+目标API令牌（+目标SSL标志）

这些凭据通过Streamlit表单提供，用于构建 SisenseClient MCP工具服务器内的实例，并且不会持久化。

______________________________________________________________________

工具注册表生成

MCP服务器使用 工具注册表JSON 它描述了可用的工具、参数、描述和示例。

有两个阶段：

config/tools.registry.json –直接从PySisense SDK构建。
config/tools.registry.with_examples.json –相同的注册表，但增加了示例。

脚本在 scripts/ 对此负责：

01_build_registry_from_sdk.py\

反思PySisense SDK类，解析文档字符串，推断参数的JSON模式，标记工具，并写入 config/tools.registry.json.

02_add_llm_examples_to_registry.py\

阅读 config/tools.registry.json，使用LLM为每个工具生成示例，并写入 config/tools.registry.with_examples.json.

refresh_registry.sh 是一个方便的包装器，用于重建这两个注册表。

在运行时，只有JSON文件 config/ 需要。

______________________________________________________________________

本地运行（无Docker）

这是一个简单的三进程开发设置。

创建并激活虚拟环境

python3.11 -m venv .venv
source .venv/bin/activate     # Windows: .venv\Scripts\activate

安装依赖项

pip install --upgrade pip
pip install -r requirements.txt

创建 .env （参见 .env.example)

启动MCP流式HTTP服务器

在终端1中：

uvicorn mcp_server.server:app --host 0.0.0.0 --port 8002 --workers 1

为什么 --workers 1:

MCP Streamable HTTP会话是有状态的，除非添加粘性路由，否则运行多个工作进程可能会中断会话连续性。
该项目依赖于单个worker，并使用并发上限+流式进度来在长时间迁移期间保持响应。

启动后端API

在2号航站楼：

uvicorn backend.api_server:app --host 0.0.0.0 --port 8001

启动Streamlit用户界面

在3号航站楼：

streamlit run frontend/app.py

打开用户界面

Streamlit将打印本地URL（通常 http://localhost:8501).

______________________________________________________________________

克劳德桌面集成（MCP远程）

您可以使用以下命令将Claude Desktop直接连接到PySisense MCP HTTP服务器 mcp-remote.

1）启动MCP服务器

确保MCP服务器正在运行：

uvicorn mcp_server.server:app --host 0.0.0.0 --port 8002 --workers 1

要在连接Claude Desktop之前对MCP服务器进行健全性检查，请运行：

npx -y @modelcontextprotocol/inspector

这将启动检查器并打开浏览器UI。检查器生成本地会话URL

2）配置Claude桌面

步骤：

打开克劳德桌面。
转到设置。
在...之下 开发者，选择 编辑配置。这将打开 claude_desktop_config.json.
添加以下配置：

{
  "mcpServers": {
    "my-local-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8002/mcp/"]
    }
  }
}

保存文件后重新启动Claude Desktop。

3）避免在Claude中暴露Sisense凭据

为了避免将Sisense域/令牌放入Claude中，请将它们设置为运行MCP服务器的计算机上的环境变量（例如在该计算机的 .env).

MCP服务器的tools_core.py包含可选的默认租户回退逻辑，当客户端在调用底层SDK方法之前省略环境变量时，该逻辑会填充Sisense域和令牌。

在MCP服务器主机上添加以下环境变量：

PYSISENSE_USE_DEFAULT_TENANT=true
PYSISENSE_DEFAULT_DOMAIN="https://your-sisense-domain"
PYSISENSE_DEFAULT_TOKEN="your-api-token"
PYSISENSE_DEFAULT_SSL=false

重要提示：您不需要告诉Claude传递空域/令牌字段。如果MCP服务器上启用了默认租户回退，则服务器可以从其环境中填充它们。

Claude Desktop中关于SSE的注释：

MCP服务器支持SSE进度流。
一些MCP客户端可能尚未在主UI中呈现进度事件（它们可能只出现在日志中）。这不会影响Streamlit UI路径，它完全支持端到端的SSE进度。

______________________________________________________________________

使用Docker运行（本地/dev）

该仓库包含三个Dockerfiles和一个 docker-compose.yml 地方发展：

–流线型UI
–FastAPI后端
–MCP工具服务器
–同时运行所有三个

1）创建一个 `.env` 本地Docker

创建 .env 在项目根目录中使用LLM和服务配置（与环境配置部分中的键相同）。\ 此文件未提交到git，也未烘焙成图像。

2）构建并启动堆栈

从项目根：

docker compose up --build --force-recreate

然后打开：

UI： http://localhost:8501
后端文档： http://localhost:8001/docs
MCP健康状况： http://localhost:8002/health

有用的Docker命令

停止堆栈：

docker compose down

硬重置（删除容器、映像、卷和构建缓存）：

docker compose down --rmi all --volumes --remove-orphans
docker builder prune -a -f

______________________________________________________________________

生产方式部署（示例）

对于生产，您通常：

将构建的映像推送到注册表（Docker Hub、ECR等）
使用单独的编写文件（例如 )
在主机上或通过编排器设置环境变量

包含一个示例非秘密env脚本： config_prod.sh.

秘密像 AZURE_OPENAI_API_KEY 或 DATABRICKS_TOKEN 应通过安全通道（SSM参数存储、秘密管理器等）提供。

苏格兰和南方能源公司关于生产反向代理的说明：

确保您的代理/负载平衡器支持SSE，并且不缓冲响应。
常见要求包括禁用代理缓冲和增加长期响应的空闲超时。

______________________________________________________________________

使用应用程序

1）与部署聊天

选择 与部署聊天.
输入Sisense域、API令牌和SSL首选项。
点击连接.

示例问题：

“列出所有仪表板。”
“显示‘Analysts’组中的所有用户。”
“查找数据模型XYZ中未使用的所有字段。”

对于写操作（创建/更新/删除），您将在执行前看到一个确认步骤。

2）在部署之间迁移

切换到 在部署之间迁移.
填写源和目标Sisense环境（域+令牌+SSL）。
连接两者。

请求示例：

“将此仪表板从源迁移到目标。”
迁移所有数据模型，覆盖现有数据模型
“迁移这三个仪表板并在目标上复制它们。”

屏幕截图：

FES Assistant UI

______________________________________________________________________

日志记录

日志文件被写入 logs/ （git忽略）。
在可能的情况下，令牌等敏感值在写入日志之前会被擦除。
对于生产，将日志级别设置为 INFO 或 WARNING 而不是 DEBUG.

______________________________________________________________________

🔒 安全和部署最佳实践

虽然这是一个实验工具，但我们建议您在部署时采用以下“安全第一”的方法：

身份验证： 在组织的SSO、VPN或安全反向代理（例如，带Auth的Nginx）后面部署UI和后端。
凭证管理： 使用专用的有限权限Sisense服务帐户，并确保您的LLM API密钥安全存储（例如，通过环境机密而非硬编码）。
网络隔离： 实施网络级限制（防火墙/VPC规则），以便只有受信任的内部主机才能访问后端和MCP服务器端点。
服务范围： 如果通过mcp-remote使用Claude Desktop，如果服务器不在本地计算机上，请确保使用安全的隧道方法（例如SSH隧道、Tailscale）。

______________________________________________________________________

⚖️ 社区免责声明和责任保障

重要提示：实地开发的生态系统扩展

这些工具是由Sisense Field Engineering开发的社区贡献项目不 Sisense官方产品功能，不属于标准Sisense SLA、支持或安全认证。

本地库执行（PySisense SDK）： 作为通过PyPI安装的Python包，所有逻辑都在您的工作站或服务器上本地执行。从未向Sisense现场工程部传输任何数据。
自托管应用程序（MCP服务器和FES助手）： 这些旨在部署在您自己的专用网络或VPC中。您保持对托管环境、日志和安全配置的完全所有权。
LLM数据披露和总结：

- FES助理： 提供手册 摘要切换默认情况下，LLM只会看到您的提示和工具定义来确定意图。可选地，启用后，将来自SDK的原始响应（可能包含元数据或特定工具级数据）发送到LLM以生成自然语言摘要。 - MCP服务器： 当与第三方客户端（如Claude Desktop、IDE代理）一起使用时，通过SDK检索到的所有数据都会直接传递给主机客户端的LLM以生成响应。

职责： 通过使用这些工具，客户/用户确认Sisense元数据和API响应将由他们选择的LLM提供商处理。客户是 全权负责 确保其LLM提供商（OpenAI、Anthropic、Databricks Foundation Models API等）符合其组织的数据隐私和安全标准。
责任与风险： 提供这些工具 “原样” 用于实验目的。Sisense及其员工不对安全漏洞、第三方LLM数据泄露或环境中断负责。
非生产建议： 我们强烈建议在沙盒环境中测试这些工具，并使用专用的有限权限Sisense服务帐户。

______________________________________________________________________

演示

https://github.com/user-attachments/assets/1ef44ff2-21c4-4be9-8a3f-8761f0641d6e

______________________________________________________________________

许可证

该项目根据MIT许可证获得许可。请参阅 LICENSE 文件以获取详细信息。

Pysisense MCP Chatbot

快速接入

详细介绍

🤖 FES助理：您的代理Sisense副驾驶

⚠️ 实验项目通知

Sisense现场工程社区贡献工具

技术和安全注意事项

部署和执行控制

数据和LLM处理

推荐使用指南

关于FES助理

🚀 为什么每个Sisense用户都需要副驾驶：

关键代理能力

🏗️ 架构与流程

快速链接

特性

建筑

文件夹结构

先决条件

环境配置

1） UI（Streamlit）配置

2） 后端（FastAPI）配置

3） 后端→ MCP客户端配置（SSE感知）

4） MCP工具服务器/PySsense配置

MCP工具命名（克劳德兼容性）

并发上限（单工作者友好型）

5） Sisense配置（在UI中输入，而不是在 .env)

工具注册表生成

本地运行（无Docker）

克劳德桌面集成（MCP远程）

1） 启动MCP服务器

2） 配置Claude桌面

3） 避免在Claude中暴露Sisense凭据

使用Docker运行（本地/dev）

1） 创建一个 .env 本地Docker

2） 构建并启动堆栈

有用的Docker命令

生产方式部署（示例）

使用应用程序

1） 与部署聊天

2） 在部署之间迁移

日志记录

🔒 安全和部署最佳实践

⚖️ 社区免责声明和责任保障

演示

相关项目

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

2）后端（FastAPI）配置

3）后端→ MCP客户端配置（SSE感知）

5） Sisense配置（在UI中输入，而不是在 `.env`)

1）启动MCP服务器

2）配置Claude桌面

3）避免在Claude中暴露Sisense凭据

1）创建一个 `.env` 本地Docker

2）构建并启动堆栈

1）与部署聊天

2）在部署之间迁移