Name: Visier数据分析代理客户端
Author: visier

使用说明

带Web UI的访问者LangGraph MCP客户端

此项目提供了一个LangGraph MCP（模型上下文协议）客户端，用于使用OAuth 2.0授权代码流连接到Visier MCP服务器。它具有一个web UI，允许您与AI代理交互以查询您的Visier数据。

截图

主界面显示服务器连接详细信息、可用的MCP工具和一个简单的代理聊天界面。

单击展开任何工具并查看其描述和参数模式，这正是代理在做出决策时看到的。

问一个问题，看看代理人的推理和反应。

选择一个提示，然后单击“将提示加载到问题中”以使用提示。

特性

OAuth 2.0身份验证：与Visier租户的安全连接
灵活的AI后端：参见 LLM配置部分
代理透明度：查看代理的流式思维过程和最终响应
访客集成：通过MCP工具直接访问您的Visier分析
自由选择权：与当地Olama车型完全免费

建筑

sample-langchain-mcp-client/
├── client/
│   ├── client.py               # Authentication, MCP connection, and app wiring
│   ├── agent_backend.py        # AgentBackend interface and shared chunk types
│   ├── mcp_client_backend.py   # MCPClientBackend interface and factory
│   ├── constants.py            # Shared application constants
│   ├── llm_provider.py         # LangChain LLM provider selection
│   ├── messages.py             # System prompt and messages
│   ├── oauth2.py               # Password grant OAuth provider
│   ├── langchain/
│   │   ├── langchain_mcp_client_backend.py  # LangChain MCP client backend
│   │   └── langchain_agent_backend.py       # LangChain/LangGraph agent backend
│   └── bedrock/
│       ├── bedrock_mcp_client_backend.py    # Bedrock MCP client backend (raw mcp.ClientSession)
│       ├── bedrock_agent_backend.py         # boto3 Bedrock agent backend
├── web/
│   ├── web_ui_server.py        # Web server and HTTP request handling
│   └── web_ui.html             # Frontend interface
├── main.py                     # Entry point script
├── pyproject.toml              # Project dependencies
└── README.md                   # This file

代理后端

两个抽象层将特定于框架的代码与应用程序的其余部分分开。 MCPClientBackend 拥有MCP服务器连接、工具/提示加载和代理创建。 AgentBackend 拥有LLM推理循环。两个后端都实现了相同的接口，并且在运行时可以通过以下方式互换 AGENT_BACKEND.

`AGENT_BACKEND`	`LLM_PROVIDER`	它是如何工作的
`langchain` （默认）	`ollama` / `anthropic` / `bedrock` / `openai` / `azure_openai`	通过LangChain实现LangGraph反应器循环
`boto3`	（始终为基岩）	直接AWS boto3 Converse API循环，代理循环中没有LangChain

先决条件

Python 3.13+
使用OAuth客户端凭据访问Visier租户
必需的Python包（全部安装 uv sync)

所需的环境变量

在运行客户端之前，您必须设置以下环境变量：

访问者MCP服务器变量

`VISIER_OAUTH_CLIENT_ID`

必需的：您的访问者OAuth客户端ID

描述：在您的Visier租户设置中注册的OAuth客户端ID

`VISIER_OAUTH_CLIENT_SECRET`

必需的：您的访问者OAuth客户端密码

描述：在您的Visier租户设置中注册的OAuth客户端密钥

`VISIER_MCP_SERVER_URL`

必需的：您的Visier MCP服务器的URL

描述：Visier租户的MCP服务器端点的基本URL
格式: https://{vanity_name}.app.visier.com/visier-query-mcp

`VISIER_USERNAME` & `VISIER_PASSWORD`

可选的：用于密码授予身份验证流程

描述：如果两者都提供，则使用密码授予而不是授权码流
用例：浏览器OAuth不可用的自动化/无头环境

`VISIER_TENANT_VANITY`

可选的：您的访客租户的虚荣名字

描述：这仅在某些开发场景中需要

代理后端

`AGENT_BACKEND`

可选的：要使用哪个代理循环实现

选项: langchain （默认）， boto3
langchain：使用LangGraph反应代理循环。 LLM_PROVIDER 选择模型。
boto3：直接驾驶Bedrock Converse API。代理循环中没有LangChain。 LLM_PROVIDER 忽略不计，使用基岩。

LLM提供程序配置

`LLM_PROVIDER`

可选的：选择您的AI提供商（仅在以下情况下使用 AGENT_BACKEND=langchain)

选项: ollama, anthropic, bedrock, openai, azure_openai
默认: ollama
示例: export LLM_PROVIDER="bedrock"

`LLM_MODEL_ID`

可选的：特定型号标识符

例子:
- 奥拉马： qwen2.5, llama3.1
- 人类学： claude-3-5-sonnet-20241022
- 基岩（LangChain或boto3）： anthropic.claude-3-5-sonnet-20241022-v2:0
- OpenAI： gpt-4-turbo
- Azure OpenAI： 部署名称 您在Azure OpenAI资源上进行了配置（而不是底层模型名称）。在需要时 LLM_PROVIDER=azure_openai.

AWS基岩变量

`AWS_BEARER_TOKEN_BEDROCK`

Langchain使用基岩时需要：如果使用Langchain代理，则用于访问基岩的AWS承载令牌。

描述：AWS Bedrock身份验证的承载令牌
备注：仅在以下情况下需要 AGENT_BACKEND=langchain 和 LLM_PROVIDER=bedrock。boto3路径不使用，该路径依赖于SigV4签名，不支持Bedrock API密钥。

`AWS_REGION_BEDROCK`

可选的：基岩AWS区域

描述：您的基岩模型可用的AWS区域
默认: us-west-2

AWS凭据

boto3自动解析标准AWS凭据链中的凭据： ~/.aws/credentials → AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY 环境变量→ IAM角色。区域之外不需要额外的环境变量。

人为变量

`ANTHROPIC_API_KEY`

需要人类学：无烟煤API键

描述：用于直接访问Claude的Anthropic API密钥
备注：使用时需要 LLM_PROVIDER=anthropic

OpenAI变量

`OPENAI_API_KEY`

OpenAI需要：OpenAI API密钥

描述：用于GPT模型访问的OpenAI API密钥
备注：使用时需要 LLM_PROVIDER=openai

Azure OpenAI变量

`AZURE_OPENAI_API_KEY`

Azure OpenAI需要：Azure OpenAI API密钥

描述：Azure OpenAI资源的API密钥
备注：使用时需要 LLM_PROVIDER=azure_openai

`AZURE_OPENAI_ENDPOINT`

Azure OpenAI需要：Azure OpenAI资源端点

描述：Azure OpenAI资源的端点URL，通常 https://<your-resource>.openai.azure.com （APIM/代理URL也可以）
备注：使用时需要 LLM_PROVIDER=azure_openai

`AZURE_OPENAI_API_VERSION`

可选的：Azure OpenAI REST API版本

默认: 2024-10-21
描述：Azure显式pin API版本；如果你需要更新的功能，可以跳过这个

安装说明

基本设置（必需）

设置环境变量:

export VISIER_OAUTH_CLIENT_ID="your-client-id"
export VISIER_OAUTH_CLIENT_SECRET="your-client-secret" 
export VISIER_MCP_SERVER_URL="https://{vanity_name}.app.visier.com/visier-query-mcp"

安装依赖项并切换到虚拟环境:
```
uv sync
source .venv/bin/activate
```

LLM设置（选择一个）

选项A：Ollama（免费，当地）- 默认

# 1. Install Ollama from https://ollama.ai
#    Download and install the application for your OS

# 2. Pull qwen2.5 model (required!)
ollama pull qwen2.5

# 3. Optional: Use a different model
ollama pull llama3.1            # Alternative model
export LLM_MODEL_ID="llama3.1"   # Use specific model

# 4. Start Ollama service (if not running automatically)
ollama serve

选项B:AWS Bedrock通过AWS boto3 SDK（推荐用于Bedrock）

在代理循环中使用内联boto3 Converse API-无LangChain。

export AGENT_BACKEND="boto3"
export AWS_REGION_BEDROCK="us-west-2"              # Optional, defaults to us-west-2
export LLM_MODEL_ID="anthropic.claude-3-5-sonnet-20241022-v2:0"

# AWS credentials are resolved from ~/.aws/credentials for boto3 SDK. No AWS_BEARER_TOKEN_BEDROCK needed.

选项C：通过LangChain获取AWS基岩

使用LangChain的ChatBedrockConverse包装器和LangGraph代理循环。

export AGENT_BACKEND="langchain"   # default, can be omitted
export LLM_PROVIDER="bedrock"
export AWS_BEARER_TOKEN_BEDROCK="your-bearer-token"
export AWS_REGION_BEDROCK="us-west-2"  # Optional, defaults to us-west-2

# Optional: Use specific Bedrock model
export LLM_MODEL_ID="anthropic.claude-3-5-sonnet-20241022-v2:0"

选项D：Anthropic Direct（高级云）

export LLM_PROVIDER="anthropic"
export ANTHROPIC_API_KEY="sk-ant-your-api-key"

# Optional: Use specific Claude model
export LLM_MODEL_ID="claude-3-5-sonnet-20241022"

选项E:OpenAI（高级云）

export LLM_PROVIDER="openai"
export OPENAI_API_KEY="sk-your-openai-api-key"

# Optional: Use specific OpenAI model
export LLM_MODEL_ID="gpt-5.3-codex"

选项F：Azure OpenAI

export LLM_PROVIDER="azure_openai"
export AZURE_OPENAI_API_KEY="your-azure-openai-api-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"  # your Azure OpenAI resource endpoint (or APIM/proxy URL)
export LLM_MODEL_ID="your-deployment-name"  # the deployment name you configured on the Azure resource

# Optional
export AZURE_OPENAI_API_VERSION="2024-10-21"  # defaults to 2024-10-21

高级配置

密码授权身份验证（无头）

对于没有浏览器访问权限的自动化环境：

export VISIER_USERNAME="your-visier-username"
export VISIER_PASSWORD="your-visier-password"
# This will use password grant instead of authorization code flow

自定义令牌端点

如果您的Visier租户在本地托管：

export VISIER_TENANT_VANITY="a1b2c"

禁用自动浏览器启动

默认情况下，应用程序会自动将浏览器打开到OAuth登录页面。通过 --skip-browser-open 抑制这种情况——在CI管道或无头环境中很有用。导航至 http://localhost:8001 您将被重定向到OAuth登录页面：

python main.py --skip-browser-open

调试日志

通过设置langchain变量启用详细的LLM交互日志记录：

export LANGCHAIN_VERBOSE="true"

运行应用程序

运行客户端:
```
python main.py
```
要禁用浏览器自动启动（例如在CI/CD无头环境中）：
```
python main.py --skip-browser-open
```
访问Web UI:
- 完成OAuth登录后，您的浏览器将重定向到 http://localhost:8001 自动地
- 如果没有，请导航到 http://localhost:8001 手动地
- 现在，您可以通过web界面与Visier代理进行交互

使用Web界面

web UI提供：

服务器信息：在顶部显示连接的Visier MCP服务器URL
问题输入：向客服提问的文本框
Agent思维：显示代理的推理过程、工具选择和中间步骤
最终响应：来自代理的干净、格式化的最终答案

示例问题

“给我最近一个月的员工人数”
“显示过去3个月的员工人数趋势”
“员工数据的可用维度是什么？”
“按部门统计2025年8月的员工人数”

运作原理

该系统分几个阶段运行：

1.身份验证和设置

使用OAuth 2.0身份验证连接到您的Visier MCP服务器
在上启动本地回调服务器 http://localhost:8000/callback
打开浏览器进行Visier OAuth授权
捕获授权码并将其交换为访问令牌
从Visier服务器检索可用的MCP工具

2.代理创建

倒像 AGENT_BACKEND 选择代理循环实现
boto3 路径：使用boto3直接驱动Bedrock Converse API，在代理循环中不依赖LangChain
langchain 路径 （默认）：使用LangGraph反应代理； LLM_PROVIDER 选择模型（Ollama、Anthropic、通过LangChain的Bedrock或OpenAI）
两个后端都流式传输中间推理步骤和对web UI的最终响应

3.Web界面

在上启动web服务器 http://localhost:8001
OAuth登录完成后，回调重定向到 http://localhost:8001 在同一选项卡中
提供与AI代理的实时交互
显示代理推理和最终响应
注销将重定向回同一选项卡中的OAuth登录页面——没有新的浏览器窗口

4.查询处理

当您提出问题或从模板中选择提示时：

代理规划代理会分析你的问题，并决定使用哪些工具
工具执行：调用适当的Visier MCP工具（如 ask_vee_question)
响应生成：处理工具结果并生成人性化的响应
界面显示：在单独的部分显示思考过程和最终答案

OAuth流

身份验证过程：

在上启动本地服务器 http://localhost:8000/callback
打开浏览器，进入Visier OAuth授权页面
在Visier中登录并授权应用程序
重定向回 http://localhost:8000/callback 带有授权码
自动将代码交换为访问令牌，然后重定向到 http://localhost:8001
连接到Visier MCP服务器并检索可用工具

Web UI端口

OAuth 回调: http://localhost:8000/callback （身份验证期间临时）
网络界面: http://localhost:8001 （主应用程序UI）

安全说明

OAuth凭据：客户端机密和AWS凭据应保持安全
本地服务器：OAuth回调服务器仅在身份验证期间临时运行
令牌存储：访问令牌存储在内存中，不会持久化到磁盘
重定向 URI：确保您的Visier OAuth客户端配置了 http://localhost:8000/callback
AWS访问：确保您的AWS凭据具有适当的基岩权限

故障排除

环境变量

确保设置了所有必需的Visier环境变量
亚马逊云服务：如果要使用Bedrock，请检查AWS凭据
Ollama：确保Ollama已安装并正在运行(ollama serve)
模型：确保您选择的Ollama型号已被拉出(ollama pull <model>)

OAuth问题

在Visier租户设置中验证您的客户端凭据是否正确
确保重定向URI http://localhost:8000/callback 在Visier中配置
检查是否没有其他进程正在使用端口8000

法学硕士问题

AWS Bedrock

验证您的AWS凭据是否具有Bedrock访问权限
确保中指定的型号 LLM_MODEL_ID 在您的AWS区域可用
对于 AGENT_BACKEND=boto3：凭据来自 ~/.aws/credentials.指南：https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html
对于 AGENT_BACKEND=langchain 与 LLM_PROVIDER=bedrock：还确保 langchain-aws 已安装

Ollama

安装：从以下位置安装Olamahttps://ollama.ai
服务确保Ollama正在奔跑(ollama serve)
模型：先拉你想要的模型(ollama pull qwen2.5)
记忆：大型型号可能需要大量RAM（建议8GB+）
连接性：确保Ollama在 http://localhost:11434

连接问题

验证MCP服务器URL是否正确且可访问
检查与Visier服务的网络连接
确保端口8000和8001在本地可用

Web UI问题

如果登录后未重定向，请手动导航到 http://localhost:8001
检查浏览器控制台是否存在JavaScript错误
验证 web_ui.html 文件存在于项目目录中

业绩说明

Ollama：本地模型可能比云API慢，但完全免费
模型大小：较小的型号（如 llama2:7b)速度更快，但能力较差
硬件GPU加速将显著提升Ollama的性能

使用说明

带Web UI的访问者LangGraph MCP客户端

截图

特性

建筑

代理后端

先决条件

所需的环境变量

访问者MCP服务器变量

VISIER_OAUTH_CLIENT_ID

VISIER_OAUTH_CLIENT_SECRET

VISIER_MCP_SERVER_URL

VISIER_USERNAME & VISIER_PASSWORD

VISIER_TENANT_VANITY

代理后端

AGENT_BACKEND

LLM提供程序配置

LLM_PROVIDER

LLM_MODEL_ID

AWS基岩变量

AWS_BEARER_TOKEN_BEDROCK

AWS_REGION_BEDROCK

AWS凭据

人为变量

ANTHROPIC_API_KEY

OpenAI变量

OPENAI_API_KEY

Azure OpenAI变量

AZURE_OPENAI_API_KEY

AZURE_OPENAI_ENDPOINT

AZURE_OPENAI_API_VERSION

安装说明

基本设置（必需）

LLM设置（选择一个）

选项A：Ollama（免费，当地）- 默认

选项B:AWS Bedrock通过AWS boto3 SDK（推荐用于Bedrock）

选项C：通过LangChain获取AWS基岩

选项D：Anthropic Direct（高级云）

选项E:OpenAI（高级云）

选项F：Azure OpenAI

高级配置

密码授权身份验证（无头）

自定义令牌端点

禁用自动浏览器启动

调试日志

运行应用程序

使用Web界面

示例问题

运作原理

1.身份验证和设置

2.代理创建

3.Web界面

4.查询处理

OAuth流

Web UI端口

安全说明

故障排除

环境变量

OAuth问题

法学硕士问题

AWS Bedrock

Ollama

连接问题

Web UI问题

业绩说明

相关 MCP

文件与终端管理MCP服务

图表生成MCP服务器

网页抓取与搜索MCP服务器

ECharts 图表生成 MCP 服务

Excel文件管理分析服务

用户名搜索MCP服务器

`VISIER_OAUTH_CLIENT_ID`

`VISIER_OAUTH_CLIENT_SECRET`

`VISIER_MCP_SERVER_URL`

`VISIER_USERNAME` & `VISIER_PASSWORD`

`VISIER_TENANT_VANITY`

`AGENT_BACKEND`

`LLM_PROVIDER`

`LLM_MODEL_ID`

`AWS_BEARER_TOKEN_BEDROCK`

`AWS_REGION_BEDROCK`

`ANTHROPIC_API_KEY`

`OPENAI_API_KEY`

`AZURE_OPENAI_API_KEY`

`AZURE_OPENAI_ENDPOINT`

`AZURE_OPENAI_API_VERSION`