Sample Langchain MCP Client

带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.

先决条件

• 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
• 默认: 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

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

安装说明

基本设置（必需）

1. 设置环境变量:

   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"

1. 安装依赖项并切换到虚拟环境:

   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"

高级配置

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

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

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"

调试日志记录

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

export LANGCHAIN_VERBOSE="true"

运行应用程序

1. 运行客户端:

   python main.py

1. 访问Web UI:

- web界面将在浏览器中自动打开 - 如果没有，请导航到 http://localhost:8001 - 现在，您可以通过web界面与Visier代理进行交互

使用Web界面

web UI提供：

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

示例问题

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

运作原理

该系统分几个阶段运行：

1.身份验证和设置

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

2.代理创建

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

3.Web界面

1. 在上启动web服务器 http://localhost:8001
2. 在默认浏览器中自动打开web UI
3. 提供与AI代理的实时交互
4. 显示代理推理和最终响应

4.查询处理

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

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

OAuth流

身份验证过程：

1. 在上启动本地服务器 http://localhost:8000/callback
2. 打开浏览器，进入Visier OAuth授权页面
3. 在Visier中登录并授权应用程序
4. 使用授权码重定向回本地服务器
5. 自动将代码交换为访问令牌
6. 连接到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 serve)
• 模型：确保您选择的Ollama型号已被拉出(ollama pull )

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 已安装

奥拉玛

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

连接问题

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

Web UI问题

• 如果UI没有自动打开，请手动导航到 http://localhost:8001
• 检查浏览器控制台是否存在JavaScript错误
• 验证 web_ui.html 文件存在于项目目录中

业绩说明

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