Demo Shop Chat

聊天主机

一个开源的、兼容MCP的聊天界面，用于发现和交互 通用商业协议（UCP） MCP服务器。Chat Host连接人工智能模型和商业系统，通过自然对话实现代理产品发现、结账和支付流程。

目录

• 特性
• 技术栈
• 先决条件
• 快速启动（演示模式）
• 完整设置（带身份验证和数据库）
• 环境变量
• 运行应用程序
• 运作原理

- 聊天流程 - MCP服务器连接 - UCP检查流程 - 嵌入式校验协议（ECP） - 认证 - 护栏和适度 - 聊天记录和持久性

• 主要路线
• API 参考
• 数据库模式
• UCP合规中心
• 管理员仪表板
• 项目结构
• 建筑与设计决策
• 贡献
• 许可证

______________________________________________________________________

特性

• MCP服务器发现 --通过URL连接到任何兼容MCP的服务器并浏览其工具
• UCP合规中心 --根据UCP规范（工具检查+配置文件发现）验证MCP服务器 /ucp
• MCP-UI渲染 --通过以下方式呈现MCP服务器返回的交互式UI组件 @mcp-ui/client
• 嵌入式检查（ECP） --通过JSON-RPC消息传递从UCP服务器托管嵌入式签出iframe
• OpenAI集成 -使用OpenAI的Responses API进行AI聊天，并提供完整的工具调用支持
• 护栏 -通过OpenAI moderation API进行输入/输出调节，可编辑系统指令
• 身份验证（可选） --AWS Cognito OAuth，支持JWT验证、AES-256-GCM令牌加密和铁会话Cookie
• 聊天记录 --带有滑出式侧边栏的持久聊天会话和消息历史记录
• 管理员仪表板 --用户管理、会话查看器和审核日志位于 /admin
• 示范模式 --无需任何数据库或身份验证设置即可运行，以实现快速的本地开发

技术栈

______________________________________________________________________

先决条件

• Node.js 18+ 和 npm
• OpenAI API密钥 （所有模式都需要）
• Neon Postgres数据库 （仅在启用身份验证时需要）
• AWS Cognito应用程序 （仅在启用身份验证时需要）

快速启动（演示模式）

演示模式运行应用程序，无需身份验证、数据库或Cognito。模拟用户(john.doe@example.com 具有管理员角色）被自动注入，并且直接从浏览器调用OpenAI API。

1.克隆并安装：

git clone https://github.com/anthropics/agentic-commerce-discovery.git
cd agentic-commerce-discovery/chat-host
npm install

2.创建环境文件：

cp .env.example .env.local

3.编辑 .env.local 具有最低要求值：

# The only required variable for demo mode
OPENAI_API_KEY=sk-...

# Demo mode — no database or Cognito needed
NEXT_PUBLIC_AUTH_ENABLED=false

4.启动开发服务器：

npm run dev

5.打开 http://localhost:3000.

您将立即看到聊天界面，无需登录。从侧边栏连接MCP服务器，开始与工具支持人员聊天。

______________________________________________________________________

完整设置（带身份验证和数据库）

当 NEXT_PUBLIC_AUTH_ENABLED=true，该应用程序使用AWS Cognito进行身份验证，使用Neon Postgres进行数据持久化，并通过带有护栏的服务器端代理路由所有OpenAI调用。

1.设置Neon Postgres

创建一个 霓虹 数据库并复制连接字符串。

2.设置AWS Cognito

1. 使用托管UI创建Cognito用户池。
2. 创建应用程序客户端（注意客户端ID）。
3. 将回调URL配置为 http://localhost:3000 （以及您的生产URL）。
4. 注意您的用户池ID、地区和Cognito域前缀。

3.配置环境变量

cp .env.example .env.local

填写所有值（参见 环境变量 完整参考）。

4.运行数据库迁移

# Generate migration files from the Drizzle schema
npm run db:generate

# Apply migrations to your Neon database
npm run db:migrate

或者用于无需迁移文件的快速开发：

npm run db:push

5.（可选）为管理员用户添加种子

npm run db:seed

注： 用户在第一次登录Cognito时也会自动创建，因此播种是可选的。用户得到 admin 如果他们的电子邮件在 ADMIN_EMAILS 或者它们属于 admin Cognito的团队。

6.启动应用程序

npm run dev

______________________________________________________________________

环境变量

创建一个 .env.local 文件在 chat-host 目录。以下是完整的参考文献：

必需（所有模式）

仅演示模式

身份验证切换

启用身份验证时需要(NEXT_PUBLIC_AUTH_ENABLED=true)

可选的

护栏

生成加密密钥

# Generate TOKEN_ENCRYPTION_KEY (64 hex chars = 32 bytes)
openssl rand -hex 32

# Generate SESSION_COOKIE_SECRET (32+ random characters)
openssl rand -base64 32

______________________________________________________________________

运行应用程序

______________________________________________________________________

运作原理

聊天流程

聊天系统使用OpenAI的Responses API和MCP工具调用。以下是端到端流程：

1. 用户发送消息 在聊天UI中。
2. 消息已添加 保存到内存中的聊天存储，并（在启用身份验证时）保存到数据库。
3. OpenAI被称为 使用对话历史记录+可用的MCP工具：

- 所有OpenAI调用都会通过 POST /api/chat 服务器端。在调用模型之前，服务器运行 输入调节。收到响应后，它运行 输出调节来自可编辑markdown文件的系统指令通过 instructions 参数。

1. 如果模型返回工具调用：

- 每个工具调用都是通过以下方式对连接的MCP服务器执行的 mcpClient.callTool(). - UCP结账工具会自动注入元数据（配置文件URL、幂等性密钥、模拟买家信息）。 - 工具结果呈现为文本、MCP-UI组件或UCP结账卡。

1. 如果模型仅返回文本，它在聊天中呈现为markdown。

MCP服务器连接

该应用程序可以同时连接到多个MCP服务器：

1. 管理用户 请参阅侧栏中的服务器面板。输入MCP服务器URL并单击 连接.
2. 应用程序调用服务器的 initialize 方法，然后 tools/list 以发现可用的工具。
3. 连接的服务器及其工具被持久化 localStorage 跨浏览器会话。
4. 来自所有连接服务器的所有工具都被聚合并作为可用函数发送到OpenAI。
5. 当调用工具时，应用程序会根据拥有该工具的服务器将调用路由到正确的服务器。

MCP客户端(src/lib/mcp-client.ts)管理每个服务器URL的会话，包括有状态服务器的MCP会话ID。

UCP检查流程

当连接了符合UCP的MCP服务器时，AI可以管理完整的结账：

1. 浏览产品 --模型调用 list_products, get_product，或 recommend_products.
2. 创建结账 — create_checkout 带有行项目（产品ID为字符串）。应用程序自动注入：

- meta["ucp-agent"].profile 统一资源定位符 - 模拟买家信息（电子邮件、first_name、last_name）

1. 更新结账 — update_checkout 添加/修改买家信息或行项目。
2. 完成结账 — complete_checkout 自动生成 idempotency-key 在meta中。提供模拟支付工具用于演示。
3. 取消结账 — cancel_checkout 具有自动生成的幂等性密钥。

结账响应被解析并呈现为显示状态、行项目、总计和买家信息的样式卡。

嵌入式校验协议（ECP）

如果UCP服务器支持嵌入式签出（由 continue_url 和 embedded 在结账响应中绑定），应用程序可以在iframe中托管支付UI：

1. 结账卡显示 “嵌入式结账” 按钮。
2. 点击它会打开一个指向服务器的iframe continue_url.
3. iframe和主机通过JSON-RPC消息进行通信：

- ec.ready --iframe发出已加载的信号 - ec.payment.instruments_change_request --iframe请求支付工具（应用程序提供模拟工具） - ec.success --付款完成 - ec.error --付款失败

看 src/components/chat/ecp-embed.tsx 为了全面实施。

认证

当 NEXT_PUBLIC_AUTH_ENABLED=true，该应用程序使用三层身份验证架构：

第1层——JWT验证（Cognito JWKS）

1. 用户点击 登录 并被重定向到Cognito托管UI。
2. 登录后，Cognito重定向回 /?code=....
3. 前端通过调用Cognito令牌端点来交换令牌（id_token、access_token和refresh_token）的代码。
4. 代币被发送到 POST /api/auth/exchange.
5. 服务器根据Cognito的JWKS端点（缓存在内存中）验证JWT签名。

第2层——加密令牌存储（AES-256-GCM）

• OAuth令牌在存储到 user_oauth_accounts 桌子。
• 每个加密使用一个随机的12字节IV，并产生一个16字节的身份验证标签。
• 存储为单个base64字符串： IV + auth_tag + ciphertext.
• 这可以防止数据库受损时令牌暴露。

第3层——会话Cookie（铁会话）

• 令牌交换后，加密 iron-session cookie设置包含： userId, email, role, tenantId, isLoggedIn.
• Cookie设置： httpOnly, secure （仅生产）， sameSite=lax，7天到期。
• 所有后续的API调用都从此cookie读取身份验证。每次请求都不会发送JWT。

用户创建：

用户在第一次登录Cognito时会在数据库中自动创建，不需要手动播种。交换端点：

• 通过Cognito查找用户 sub （外部用户ID）
• 如果未找到，请通过电子邮件进行检查（采用现有用户）
• 如果仍然找不到，则创建一个新用户

管理员角色：

用户得到 admin 角色如果：

• 他们的电子邮件在 ADMIN_EMAILS 环境变量，OR
• 他们属于一个 admin Cognito集团

令牌刷新：

POST /api/auth/refresh 解密存储的刷新令牌，调用Cognito的 REFRESH_TOKEN_AUTH 并更新所存储的访问令牌。

护栏和适度

护栏系统有三个实施层（计划增加四个）：

1.输入审核 （在调用模型之前）

• 用途 openai.moderations.create({ model: "omni-moderation-latest" }) 在最新的用户消息上。
• 如果被标记，请求将被阻止，并返回中性拒绝。
• 被控制 GUARDRAILS_INPUT_MODERATION.

2.输出调节 （在返回响应之前）

• 对助手的文本输出进行审核。
• 如果被标记，响应将被替换为安全拒绝，任何工具调用都将被删除。
• 被控制 GUARDRAILS_OUTPUT_MODERATION.

3.系统说明 （模型行为塑造）

• 从可编辑文件加载 src/lib/guardrails/system-instructions.md.
• 作为注射 instructions OpenAI Responses API调用中的参数。
• 在开发模式下，每次请求时都会重新读取文件（不需要重新启动）。
• 在生产环境中，文件在首次读取后会被缓存。

失败关闭行为：

• 当 GUARDRAILS_FAIL_CLOSED=true 并且审核API出错，请求被阻止而不是被允许通过。

自定义系统提示：

编辑 src/lib/guardrails/system-instructions.md 改变模型的行为。默认提示将助手的范围限定为购物和结账主题。在开发模式下，更改会立即生效，而无需重新启动服务器。

看 docs/guardrail-simple.md 用于包括计划层（范围门、工具分配列表、领域分配列表、速率限制）在内的完整护栏设计。

聊天记录和持久性

启用身份验证时：

1. A. 聊天会话 当聊天页面加载或用户点击“新建聊天”时，在数据库中创建。
2. 每个用户和助手的消息都是 阴影持续存在 --以非阻塞方式写入数据库 fetch 如果发生错误，呼叫将自动失败。
3. 这 滑出式菜单 （汉堡包图标）显示多达50个最近的会话，并带有消息预览和计数。
4. 单击会话会从数据库加载其消息。
5. 会话包括元数据： traceId, requestId, clientContext （JSONB）。

在演示模式下，聊天记录仅保存在内存中，并在页面刷新时丢失。

______________________________________________________________________

主要路线

______________________________________________________________________

API 参考

聊天

会话

消息

认证

管理员（必填 admin 角色）

______________________________________________________________________

数据库模式

Drizzle ORM管理的五张桌子（见 src/lib/db/schema.ts):

users

user_oauth_accounts

为每个用户存储加密的OAuth令牌。访问令牌和刷新令牌在存储前用AES-256-GCM加密。

chat_sessions

跟踪聊天会话生命周期： active 或 ended，带有开始/结束时间戳和可选的跟踪/请求ID。

chat_messages

个人信息 role （用户/助理/系统），内容，可选 contentRedacted, modelName，以及JSONB metadata 用于工具调用、UI资源等。

audit_events

安全审计跟踪 eventType, eventStatus, eventSource, payloadJson （JSONB）， errorMessageRedacted，以及 latencyMs.当前日志 auth.token_exchange 影子模式下的事件（非阻塞，永不失败请求）。

______________________________________________________________________

UCP合规中心

这 /ucp 页面验证MCP服务器是否符合 UCP规范它执行两阶段检查：

第1阶段——MCP工具检查

连接到MCP服务器并验证是否存在所有5个必需的结账工具：

可选产品发现工具(list_products, get_product, recommend_products)被跟踪，但不影响合规性。

第2阶段——配置文件发现

获取 GET {origin}/.well-known/ucp 并验证：

• ucp.version 存在
• dev.ucp.shopping MCP服务条目存在有效的端点、架构和规范URL
• 所有架构/规范URL都来自 https://ucp.dev （命名空间治理）
• dev.ucp.shopping.checkout 宣布能力
• （警告）存在嵌入式服务入口（ECP）
• （警告） signing_keys 阵列存在

合规裁决

如何使用

1. 导航至 /ucp.
2. 粘贴MCP服务器URL并单击 添加并扫描.
3. 结果立即显示。点击 全部重新扫描 重新检查。
4. 服务器URL保存在 localStorage.

看 docs/UCP-compliance-check.md 为了彻底崩溃。

______________________________________________________________________

管理员仪表板

可在以下网址访问 /admin （要求 admin 角色）。

用户(/admin/users)

• 通过电子邮件搜索用户
• 查看用户详细信息：电子邮件、角色、状态、创建日期
• 切换用户状态（活动/非活动）
• 每页20个用户，带分页

会议(/admin/sessions)

• 查看所有用户的所有聊天会话
• 显示用户电子邮件、邮件计数、时间戳
• 单击会话以查看其完整的消息历史记录
• 每页20个会话，带分页

审核日志(/admin/audit)

• 按事件类型、用户ID、日期范围筛选
• 目前跟踪 auth.token_exchange 事件（成功/失败）
• 显示事件类型、状态、源、有效载荷JSON、延迟、时间戳
• 每页50个事件，带分页

______________________________________________________________________

项目结构

src/
├── app/
│   ├── api/
│   │   ├── chat/route.ts              # OpenAI Responses API proxy + guardrails
│   │   ├── sessions/route.ts          # Chat session CRUD (POST create, GET list)
│   │   ├── messages/route.ts          # Message CRUD (POST create, GET list by session)
│   │   ├── auth/
│   │   │   ├── exchange/route.ts      # Cognito token → session cookie exchange
│   │   │   ├── refresh/route.ts       # Refresh access token via stored refresh token
│   │   │   ├── logout/route.ts        # Destroy session cookie
│   │   │   └── me/route.ts            # Get current authenticated user
│   │   └── admin/
│   │       ├── users/route.ts         # List/update users (admin only)
│   │       ├── sessions/route.ts      # List all sessions (admin only)
│   │       └── audit/route.ts         # List audit events (admin only)
│   ├── admin/                         # Admin UI pages (users, sessions, audit)
│   ├── ucp/page.tsx                   # UCP Compliance Center
│   ├── layout.tsx                     # Root layout with AuthProvider
│   └── page.tsx                       # Main chat page
├── components/
│   ├── auth/
│   │   ├── auth-provider.tsx          # useAuth() React context + Cognito OAuth flow
│   │   ├── login-dialog.tsx           # Login prompt shown when not authenticated
│   │   └── user-menu.tsx              # User avatar dropdown (logout, admin link)
│   ├── chat/
│   │   ├── chat-container.tsx         # Orchestrates the full chat loop (messages → OpenAI → tools → render)
│   │   ├── chat-input.tsx             # Text input with send button
│   │   ├── message-bubble.tsx         # Renders text (markdown), MCP-UI resources, checkout cards
│   │   ├── checkout-card.tsx          # UCP checkout display card (status, items, totals, pay button)
│   │   ├── ecp-embed.tsx             # Embedded Checkout Protocol iframe host (JSON-RPC messaging)
│   │   ├── server-panel.tsx           # MCP server connection manager (add/remove/connect)
│   │   └── slide-out-menu.tsx         # Chat history sidebar (sessions list, new chat, user menu)
│   ├── admin/
│   │   └── admin-shell.tsx            # Admin layout wrapper with navigation
│   └── ui/                            # shadcn/ui primitives (button, dialog, scroll-area, etc.)
└── lib/
    ├── mcp-client.ts                  # MCP protocol client (connect, callTool, readResource, session mgmt)
    ├── ucp-utils.ts                   # UCP compliance checks + checkout response parsing
    ├── chat-store.ts                  # In-memory chat state (messages, loading, subscribe/notify)
    ├── render-mode-store.ts           # Toggle between "classic" and "mcp-apps" UI render modes
    ├── mock-user.ts                   # Mock user data for demo mode
    ├── utils.ts                       # Tailwind class merge utility (cn)
    ├── auth/
    │   ├── cognito.ts                 # JWT verification using jose + Cognito JWKS endpoint
    │   ├── crypto.ts                  # AES-256-GCM encrypt/decrypt for OAuth token storage
    │   └── session.ts                 # iron-session helpers (getSession, requireAuth, requireAdmin)
    ├── db/
    │   ├── index.ts                   # Lazy-initialized Neon Postgres connection (proxy pattern)
    │   ├── schema.ts                  # Drizzle ORM schema (5 tables: users, oauth, sessions, messages, audit)
    │   └── seed.ts                    # Admin user seeder (reads ADMIN_EMAILS)
    ├── guardrails/
    │   ├── index.ts                   # moderateInput(), moderateOutput(), getSystemInstructions()
    │   └── system-instructions.md     # Editable system prompt (reloaded on every request in dev)
    └── services/
        └── audit.ts                   # Shadow-mode audit event logger (non-blocking, never fails requests)

______________________________________________________________________

建筑与设计决策

双模式OpenAI调用

在 演示模式 (NEXT_PUBLIC_AUTH_ENABLED=false)，使用Responses API从浏览器直接调用OpenAI。在 身份验证模式，所有电话都通过 POST /api/chat 服务器端代理，它添加了审核护栏和系统指令。两条路径都产生相同的归一化结果 LLMResponse 格式。

延迟数据库初始化

Neon-Postgres连接使用代理模式(src/lib/db/index.ts)这会将实际连接延迟到第一个数据库查询。这意味着在演示模式下，即使导入了模式模块，也永远不会接触数据库。

阴影模式持久性

聊天消息和审核事件的所有数据库写入都是 发射后不管 --包裹在 .catch(() => {}) 或者尝试/捕获默默吞下错误的块。这确保了数据库故障永远不会破坏用户的聊天体验。权衡的结果是，消息偶尔可能会丢失。

加密令牌存储

OAuth令牌在存储到数据库中之前使用AES-256-GCM进行加密。每次加密都会生成一个随机的12字节IV和16字节认证标签。密钥是一个32字节的值，来自 TOKEN_ENCRYPTION_KEY。即使数据库受到损害，这也可以防止令牌暴露。

MCP会话缓存

MCP服务器连接通过服务器URL缓存在内存中。可以同时连接多个服务器，调用OpenAI时聚合所有服务器的工具。注意：此缓存是针对每个进程的，不会在无服务器实例之间共享。

UCP元数据注入

聊天容器会自动将UCP所需的元数据注入到签出工具参数中：

• meta["ucp-agent"].profile 所有结账工具的URL
• meta["idempotency-key"] 为了 complete_checkout 和 cancel_checkout
• 模拟买家信息 create_checkout 和 update_checkout

这简化了AI模型的工作——它不需要知道这些协议要求。

可编辑的系统说明

系统提示位于markdown文件中(src/lib/guardrails/system-instructions.md)而不是硬编码。在开发过程中，每次请求都会重新阅读。在生产中，它被缓存。这允许运营团队在不部署代码更改的情况下修改护栏行为。

______________________________________________________________________

贡献

欢迎捐款。请先打开一个问题，讨论您想更改的内容。

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/my-feature)
3. 进行更改
4. 跑linting(npm run lint)
5. 承诺并推动
6. 打开拉取请求

许可证

请参阅 许可证 存储库根目录中的文件。