购物助手-MCP服务器
购物助手应用程序的模型上下文协议（MCP）服务器。此服务器将AI代理功能暴露给两者 MCP客户端 （克劳德桌面）和 OpenAPI/REST客户端 （ChatGPT企业版）。
🚀 快速入门指南
- ChatGPT企业设置→ -修复“已连接但无操作”问题
- 视觉指南→ -了解MCP与OpenAPI/REST
- 快速命令→ -测试并配置您的服务器
这个服务器是什么？
此服务器提供 两个接口 与购物助手功能相同：
- MCP协议 （适用于Claude Desktop）-服务器发送事件上的JSON-RPC
- OpenAPI/REST （适用于ChatGPT Enterprise）-标准HTTP REST端点
这两个界面都为购物操作提供了相同的6个工具。
特性
- 目录代理：搜索和浏览产品目录
- 购物车代理：管理购物车操作
- 交易代理：查找优惠和促销活动
- 付款代理人：处理付款操作
- 双协议支持：MCP+OpenAPI/REST
- OAuth2身份验证：具有JWKS验证的企业级安全
建筑
┌─────────────────────┐
│ Claude Desktop │
│ (MCP Client) │
└──────────┬──────────┘
│ MCP Protocol (SSE)
↓
┌─────────────────────┐
│ MCP Server │
│ Port: 3001 │
└──────────┬──────────┘
│ HTTP (SDK)
↓
┌─────────────────────┐
│ LangGraph Agents │
│ Port: 2024 │
└─────────────────────┘先决条件
- Node.js 20+
- LangGraph代理服务器正在运行（请参阅购物助手代理仓库）
安装
npm install配置
创建 .env.local 文件：
# MCP Server
MCP_SERVER_PORT=3001
# LangGraph Agents (required)
LANGGRAPH_API_URL=http://localhost:2024
# Authentication Mode (choose one)
MCP_AUTH_MODE=oauth2 # Options: 'oauth2', 'api-key', 'hybrid', 'none'
# Generic OAuth2 Authentication (recommended - for MCP_AUTH_MODE=oauth2)
# The MCP server will verify OAuth2 access tokens from clients using standard JWT/JWKS
# Required: JWKS endpoint for public key verification
OAUTH2_JWKS_URI=https://your-auth-server/.well-known/jwks.json
# Optional: Verify token issuer (iss claim)
OAUTH2_ISSUER=https://your-auth-server/
# Optional: Verify token audience (aud claim)
OAUTH2_AUDIENCE=your-api-identifier
# Optional: Restrict which OAuth2 clients can access the MCP
ALLOWED_MCP_CLIENTS=client-id-1,client-id-2
# Optional: Require specific scopes
REQUIRED_MCP_SCOPES=mcp:read,mcp:execute
# Legacy API Key Authentication (for MCP_AUTH_MODE=api-key)
# Deprecated: Use OAuth2 for better security
MCP_API_KEY=your-secure-key
# External APIs (optional)
SAFEWAY_API_KEY=your-api-key发展
# Start MCP server
npm run dev
# The server will run on:
# SSE endpoint: http://localhost:3001/sse
# Health check: http://localhost:3001/healthMCP检验员测试
# Start the inspector
npm run mcp:inspect这将打开一个web UI，您可以在其中交互式地测试MCP工具。
与MCP客户端一起使用
克劳德桌面
- 启动MCP服务器：
npm run dev
- 更新Claude桌面配置(
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"shopping-assistant": {
"command": "node",
"args": [
"/path/to/shopping-assistant-mcp/dist/mcp/server.js"
],
"env": {
"LANGGRAPH_API_URL": "http://localhost:2024",
"MCP_SERVER_PORT": "3001"
}
}
}
}- 重新启动克劳德桌面
ChatGPT企业版
ChatGPT Enterprise集成需要OAuth2身份验证和OpenAPI模式发现。
快速设置:
- 配置Azure AD OAuth2（见下文）
- 启动MCP服务器：
npm run dev - 测试发现端点：
./test-chatgpt-endpoints.sh - 在ChatGPT Enterprise中，添加一个指向服务器的新操作
完整指南：参见 docs/CHATGPT_ENTERPRISE_INTEGRATION.md 有关详细的设置说明。
可用工具:
search_products-搜索产品add_to_cart-将商品添加到购物车view_cart-查看购物车checkout-完成结账add_payment_method-添加付款方式get_deals-查找优惠和促销活动
项目结构
shopping-assistant-mcp/
├── src/
│ ├── mcp/
│ │ ├── server.ts # Main MCP server
│ │ ├── tools.ts # MCP tool definitions
│ │ ├── auth.ts # Authentication
│ │ └── handlers.ts # Tool handlers
│ └── lib/ # Shared utilities
├── package.json
├── tsconfig.json
└── README.md生产部署
构建
npm run build跑
npm start码头工人
# Build
docker build -t shopping-assistant-mcp .
# Run
docker run -p 3001:3001 \
-e LANGGRAPH_API_URL=http://agents:2024 \
shopping-assistant-mcpAPI终点
健康检查
GET /healthMCP协议端点
SSE端点（适用于Claude Desktop等MCP客户端）
POST /sse这是MCP客户端使用服务器发送事件与服务器通信的主要端点。
工具执行（ChatGPT Enterprise的REST风格）
POST /tools/{tool_name}每个工具的REST端点（例如。， /tools/search_products, /tools/add_to_cart).
发现端点（适用于ChatGPT Enterprise）
OpenID连接发现
GET /.well-known/openid-configuration返回OAuth2提供程序配置（颁发者、令牌端点、JWKS URI）。
OAuth保护的资源元数据
GET /.well-known/oauth-protected-resource将此服务器声明为受OAuth2保护的资源。
OpenAPI 规范
GET /.well-known/openapi.json返回描述所有可用工具/操作的OpenAPI 3.0模式。
行动清单
GET /.well-known/ai-plugin.json返回带有人类可读描述的ChatGPT操作清单。
测试所有端点:
./test-chatgpt-endpoints.sh安全
认证
MCP服务器支持三种身份验证模式：
1.OAuth2身份验证（推荐）
服务器使用标准JWT/JWKS验证来验证OAuth2访问令牌：
它是如何工作的：
- 客户端从您的OAuth2提供程序获取访问令牌
- 客户端在请求中包含令牌：
Authorization: Bearer - MCP服务器使用JWKS（公钥）验证令牌签名
- MCP服务器验证颁发者、受众、过期和范围
- 可选地，客户端可以包含用户令牌：
X-User-Token: Bearer
配置：
MCP_AUTH_MODE=oauth2
# Required: JWKS endpoint for token verification
OAUTH2_JWKS_URI=https://your-auth-server/.well-known/jwks.json
# Optional: Verify token issuer (iss claim)
OAUTH2_ISSUER=https://your-auth-server/
# Optional: Verify token audience (aud claim)
OAUTH2_AUDIENCE=your-api-identifier
# Optional: Whitelist allowed clients
ALLOWED_MCP_CLIENTS=client-id-1,client-id-2
# Optional: Require specific scopes
REQUIRED_MCP_SCOPES=mcp:read,mcp:execute支持的OAuth2提供程序：
- 身份验证0:
OAUTH2_JWKS_URI=https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json - 八月:
OAUTH2_JWKS_URI=https://YOUR_DOMAIN.okta.com/oauth2/default/v1/keys - Azure AD:
OAUTH2_JWKS_URI=https://login.microsoftonline.com/TENANT_ID/discovery/v2.0/keys - 钥匙斗篷:
OAUTH2_JWKS_URI=https://YOUR_DOMAIN/auth/realms/REALM/protocol/openid-connect/certs - 任何OAuth2/OIDC提供商 发布JWKS公钥
双令牌模式：
- 访问令牌（必需）：证明调用应用程序已获得授权
- 用户令牌（可选）：为个性化操作提供用户上下文
请求示例：
curl -X POST http://localhost:3001/sse \
-H "Authorization: Bearer " \
-H "X-User-Token: Bearer "2.API密钥认证（旧版）
简单的API密钥验证（已弃用，请改用OAuth2）：
MCP_AUTH_MODE=api-key
MCP_API_KEY=your-secure-key请求标头： X-MCP-API-Key: your-secure-key
3.混合动力模式
同时支持OAuth2和API密钥身份验证：
MCP_AUTH_MODE=hybrid服务器将接受OAuth2令牌或API密钥。
4.无身份验证
禁用身份验证（不建议用于生产）：
MCP_AUTH_MODE=none设置OAuth2
MCP服务器可与任何OAuth2/OIDC提供程序配合使用。以下是如何配置通用提供程序：
任何OAuth2提供程序（通用设置）
- 查找您的JWKS URI：
- 寻找 .well-known/jwks.json 或公钥端点 - 这通常可以通过以下方式发现 /.well-known/openid-configuration
- 配置MCP服务器：
OAUTH2_JWKS_URI=https://your-provider/path/to/jwks.json
OAUTH2_ISSUER=https://your-provider/ # Optional
OAUTH2_AUDIENCE=your-api-id # Optional- 客户端使用客户端凭据获取令牌：
curl -X POST https://your-provider/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=" \
-d "client_secret=" \
-d "audience=" # If required- 使用MCP令牌：
curl -X POST http://localhost:3001/sse \
-H "Authorization: Bearer "提供商特定示例
身份验证0:
OAUTH2_JWKS_URI=https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json
OAUTH2_ISSUER=https://YOUR_DOMAIN.auth0.com/
OAUTH2_AUDIENCE=https://api.your-domain.com/mcpAzure AD（Microsoft 登录 ID）：
OAUTH2_JWKS_URI=https://login.microsoftonline.com/YOUR_TENANT_ID/discovery/v2.0/keys
OAUTH2_ISSUER=https://sts.windows.net/YOUR_TENANT_ID/
# Or for v2 tokens: OAUTH2_ISSUER=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
OAUTH2_AUDIENCE=YOUR_APPLICATION_ID八 ：
OAUTH2_JWKS_URI=https://YOUR_DOMAIN.okta.com/oauth2/default/v1/keys
OAUTH2_ISSUER=https://YOUR_DOMAIN.okta.com/oauth2/default
OAUTH2_AUDIENCE=api://default钥匙斗篷：
OAUTH2_JWKS_URI=https://YOUR_DOMAIN/auth/realms/YOUR_REALM/protocol/openid-connect/certs
OAUTH2_ISSUER=https://YOUR_DOMAIN/auth/realms/YOUR_REALM
OAUTH2_AUDIENCE=your-client-id跨域资源共享
CORS配置为允许来自以下位置的连接：
- 克劳德桌面
- 本地开发（localhost）
对于生产，配置 Access-Control-Allow-Origin 适当。
监控
日志
服务器记录所有请求和工具执行：
[MCP] Server starting...
[MCP] Available tools: catalog_search, cart_view, cart_add...
[MCP] Tool execution: catalog_search
[MCP] Success: Found 12 productsLangSmith追踪
启用调试跟踪：
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_...
LANGCHAIN_PROJECT=shopping-assistant-mcp故障排除
❌ ChatGPT Enterprise：“已连接，但没有操作/工具”
问题：ChatGPT显示为已连接，但不列出任何操作。
原因：ChatGPT配置为MCP协议，而不是OpenAPI/REST。
解决方案：参见 解决方案.md 详细修复。
快速修复:
- 删除当前的ChatGPT连接
- 添加新操作：从导入
http://your-server:3001/.well-known/openapi.json - 配置OAuth2身份验证
如何验证：检查日志 POST /tools/* （正确）vs SSE connection （错误）
服务器无法启动
- 检查端口3001是否可用：
lsof -i :3001 - 验证Node.js版本（20+）：
node --version - 检查.env配置
工具不工作
- 确保LangGraph代理服务器正在运行（端口2024）
- 验证.env中的LANGRAPH_API_URL
- 测试健康终点：
curl http://localhost:3001/health
身份验证错误
- 验证.env中的OAuth2配置
- 测试令牌终结点：
curl https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token - 检查JWKS URI是否可访问
- 检查网络连接
Claude Desktop无法连接
- 验证服务器是否正在运行：
curl http://localhost:3001/health - 检查Claude Desktop配置路径
- 配置更改后重新启动Claude Desktop
相关存储库
- 购物助理代理：LangGraph代理实现
- 购物助理聊天：Next.js web界面
许可证
麻省理工学院