AI导哈

AI助手集成服务器

一个将Salesforce Agentforce与AI助手（如Claude和ChatGPT）集成的MCP服务器，通过FastMCP提供对Salesforce数据和功能的对话式访问。

  • by salesforce-misc
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 salesforce-misc/agentforce-mcp-server

使用说明

MCP服务器代理

这是一个MCP（模型上下文协议）服务器，它将Salesforce Agentforce与Claude和ChatGPT等人工智能助手集成在一起。它使用FastMCP在人工智能模型和Salesforce的代理平台之间架起了一座桥梁，实现了对Salesforce数据和功能的对话式访问。

开发命令

运行服务器

# Quick start (uses run_server.sh script)
./run_server.sh

# Manual start (activate venv first)
source .venv/bin/activate  # or venv/bin/activate
python server.py

# Development with auto-reload
uvicorn server:app --reload

安装

对于在公司PyPI限制下工作的Salesforce开发人员：

python -m venv .venv
source .venv/bin/activate
python -m pip install fastmcp --index-url https://pypi.org/simple/ --no-cache-dir
pip install -r requirements.txt

对于其他人：

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

环境设置

cp .env.example .env
# Edit .env with your configuration

生成JWT密钥：

openssl rand -hex 32

建筑

核心组件

  1. 服务器.py -主MCP服务器有三个集成层：

    • MCP协议（克劳德）：服务器发送事件端点位于 /mcp 克劳德桌面/代码
    • REST API（ChatGPT）：标准REST端点位于 /api/* 用于ChatGPT操作
    • OAuth2流：完整的授权服务器位于 /oauth/* 用于用户身份验证

  2. auth.py -Salesforce OAuth2实施：

    • 使用PKCE实现OAuth2授权码流
    • 充当OAuth2代理：重定向到Salesforce进行身份验证，然后发布自己的JWT令牌
    • 根据MCP授权规范支持动态客户端注册（DCR）
    • 双PKCE验证：客户端→服务器（ChatGPT）和服务器→赛富时
    • 手柄 resource JWT观众参数(aud)装订
    • 使用Redis进行状态存储（具有内存回退功能）

  3. agentforce.py -Salesforce代理平台客户端：

    • 管理代理会话生命周期（创建、令牌管理、消息排序）
    • 处理401错误时的自动令牌刷新
    • 通过会话ID和序列号维护对话上下文

会话管理架构

服务器实现了 双层会话系统 为了保持对话上下文：

第1层：MCP会话（x-openai-Session标头）

  • ChatGPT发送 x-openai-session 每个请求的标题
  • 通过Redis/内存缓存映射到Agentforce会话
  • 密钥： mcp_session:{x-openai-session}
  • TTL:15分钟（会话延迟秒=900）

第二层：代理会话

  • 通过调用Agentforce引导+会话创建端点创建
  • 存储的数据： {agentforce_session_id, access_token, sequence_id}
  • 会话在同一ChatGPT对话中跨MCP工具调用持续存在
  • 通过创建新会话自动处理401令牌到期

流量：

  1. ChatGPT调用工具→ agentforce_chat 提取物 x-openai-session 从请求上下文
  2. 使用以下命令在Redis中查找缓存的Agentforce会话 mcp_session_id
  3. 如果找到，请继续使用现有 agentforce_session_id, access_token, sequence_id
  4. 如果未找到，请创建新的Agentforce会话
  5. 处理后，使用TTL将更新的会话数据缓存回Redis

OAuth2流详细信息

服务器充当 OAuth2代理 ChatGPT和Salesforce之间，符合 MCP授权规范:

ChatGPT                        Your Server                      Salesforce
   |                               |                               |
   |-- POST /oauth/register ------>|                               |
   |<-- 201 {client_id} ---------- |                               |
   |                               |                               |
   |-- GET /oauth/authorize ------>|                               |
   |   (code_challenge, resource)  |-- redirect to SF login ------>|
   |                               |   (SF code_challenge)         |
   |                               |<-- GET /oauth/callback -------|
   |                               |   (SF auth code)              |
   |<-- redirect with our code --- |                               |
   |                               |                               |
   |-- POST /oauth/token -------->|                               |
   |   (code_verifier)            |-- exchange SF code + creds --->|
   |                              |<-- SF access_token ----------- |
   |                              |-- GET /userinfo --------------->|
   |                              |<-- user info ------------------|
   |<-- {access_token (JWT)} ---- |                               |
   |                               |                               |
   |-- POST /mcp (Bearer token) ->|                               |
   |   (middleware verifies JWT)   |                               |

  1. 动态客户端注册 (POST /oauth/register):

    • ChatGPT注册自己并接收 client_id
    • 在启动OAuth之前，MCP授权规范要求

  2. 授权 (GET /oauth/authorize):

    • 接受 code_challenge, code_challenge_method，以及 resource 来自ChatGPT
    • 为Salesforce分支生成单独的PKCE对
    • 用途 SALESFORCE_CLIENT_ID 从env变量（回退到请求 client_id)
    • 重定向到Salesforce服务器的PKCE挑战

  3. 回调 (GET /oauth/callback):

    • 接收Salesforce授权码
    • 创建服务器自己的授权代码（存储SF代码、SF代码验证器、客户端代码挑战、资源）
    • 使用服务器代码重定向到ChatGPT

  4. 代币交换 (POST /oauth/token):

    • 验证ChatGPT的PKCE： SHA256(code_verifier) == stored code_challenge
    • 使用服务器端凭据交换Salesforce代码(SALESFORCE_CLIENT_ID/SALESFORCE_CLIENT_SECRET)
    • 从Salesforce获取用户信息
    • 返回JWT访问令牌 aud 设置为 resource 参数

MCP端点身份验证

这 /mcp 端点在以下位置运行 允许模式:

  • 无令牌：请求传递（匿名/noauth模式）
  • 有效令牌：请求通过（身份验证模式）
  • 令牌无效/过期：返回 401 随着 WWW-Authenticate 标题指向 /.well-known/oauth-protected-resource

这允许MCP工具同时适用于未经身份验证和经过身份验证的客户端。

Redis集成

Redis有两个用途（都有用于本地开发的内存回退）：

  1. OAuth2状态存储:

    • 存储PKCE状态、授权码、DCR客户端注册
    • 对OAuth2安全性（CSRF保护）至关重要
    • 前缀： oauth_state:, auth_code:, dcr_client:

  2. 会话缓存:

    • 缓存代理会话映射到 x-openai-session 标头
    • 前缀： mcp_session:
    • 生存dyno重启Heroku
    • 回到记忆中的格言(_local_sessions)促进地方发展

环境变量

关键变量：


# Salesforce MIAW / Agentforce (Required)
SALESFORCE_SCRT_URL=""                    # Your Salesforce SCRT URL
SALESFORCE_ORG_ID=""                      # Your Salesforce Organization ID
SALESFORCE_ES_DEVELOPER_NAME=""           # Embedded Service Deployment Developer Name
SALESFORCE_CAPABILITIES_VERSION="258"     # Default is 258

# OAuth2 (Optional — for MCP auth spec / DCR flow)
SALESFORCE_CLIENT_ID=""                   # Connected App consumer key
SALESFORCE_CLIENT_SECRET=""               # Connected App consumer secret

# Server URL (for OAuth callback redirect_uri)
# Local: http://localhost:8000
# Heroku: https://your-app.herokuapp.com
SERVER_URL=http://localhost:8000

# JWT Settings (for signing access tokens)
# Generate with: openssl rand -hex 32
JWT_SECRET=your-secret-key-change-this
ACCESS_TOKEN_EXPIRATION_HOURS=24

Redis是可选的——服务器会回退到内存存储中进行本地开发。在Heroku上，设置 REDIS_URL 通过Redis插件。

端点参考

健康与探索：

  • GET / -带有正常运行时间和状态的仪表板用户界面
  • GET /health -JSON健康检查

OAuth2发现（MCP认证规范）：

  • GET /.well-known/oauth-authorization-server -OAuth2服务器元数据（RFC 8414）
  • GET /.well-known/openid-configuration -OpenID连接发现
  • GET /.well-known/oauth-protected-resource -受保护的资源元数据

OAuth2流：

  • POST /oauth/register -动态客户端注册（DCR）
  • GET /oauth/authorize -启动OAuth2流（支持PKCE+ resource 参数）
  • GET /oauth/callback -Salesforce回拨
  • POST /oauth/token -令牌的交换代码（验证客户端PKCE）
  • GET /oauth/status -检查OAuth2配置

REST API（ChatGPT）：

  • POST /api/agentforce -直接代理聊天（需要OAuth2）
  • GET /api/tools -列出可用的MCP工具
  • GET /api/me -获取经过身份验证的用户信息（需要OAuth2）

MCP协议：

  • POST /mcp -MCP流式HTTP端点（带和不带身份验证）

文档：

  • GET /openapi.yaml -用于ChatGPT集成的OpenAPI规范

部署

Heroku：

  • 使用Procfile： web: uvicorn server:app --host 0.0.0.0 --port $PORT
  • 需要Heroku Redis插件才能用于生产环境
  • 在Heroku仪表板中设置环境变量或使用 .heroku-deploy.sh 脚本

当地：

  • 继续运行 0.0.0.0:8000 默认情况下（可通过HOST/PORT环境变量配置）
  • Redis对于本地开发是可选的（回退到内存存储）

Salesforce互联应用程序设置

使用OAuth2时，您的Salesforce Connected应用程序必须具有以下功能 回调URL 已配置：

https://your-server.com/oauth/callback

回调URL必须完全匹配 {SERVER_URL}/oauth/callback。如果您也在使用ChatGPT的连接器，请同时添加其重定向URI：

https://chatgpt.com/connector_platform_oauth_redirect

安全说明

  • 定期旋转JWT_SECRET
  • OAuth2实现了双PKCE:客户端→服务器（ChatGPT）和服务器→赛富时
  • 访问令牌在24小时后过期（可通过Access_TOKEN_EXPIRATION_hours配置）
  • JWT代币包括 aud 索赔与 resource 参数（如果存在）
  • 这 /mcp 端点允许匿名访问；401拒绝无效令牌

相关 MCP