使用说明

realfast.ai Salesforce MCP服务器0.6.0

使用克劳德桌面使用此服务器，您可以交互式地探索、分析和管理您的Salesforce组织！

这是模型上下文协议（MCP）服务器，通过OAuth2身份验证提供对Salesforce组织的安全访问，使AI模型能够通过标准化的工具和资源查询和探索Salesforce数据。

✅ 目前正在工作：12个经过生产验证的工具，OAuth2身份验证，全面的Salesforce API覆盖范围，以及Claude Desktop集成

关于我们

realfast.ai 是Salesforce的AI原生实施合作伙伴，将深度数据和AI专业知识与Salesforce专业知识相结合。

我们使用人工智能来更好地运输和更快。我们帮助您做同样的事情！

🚀 特性

OAuth2-PKCE身份验证：使用加密令牌存储进行基于浏览器的安全身份验证
对象元数据工具：全面的Salesforce对象模式探索
Claude桌面集成：通过MCP协议与Claude Desktop无缝集成
类型安全：具有严格类型检查的完整TypeScript实现
生产就绪：全面的错误处理、日志记录和配置管理
可扩展架构：模块化设计，用于添加其他Salesforce工具

✅ 当前实施的工具（共10个）

核心数据访问工具：

describe_object -具有记录类型的全面对象元数据和字段信息
list_objects -列出所有具有过滤和分页功能的Salesforce对象
soql_query -执行带有防注入和分页功能的SOQL查询
get_record -通过字段选择和关系遍历按ID检索特定记录
sosl_search -具有结果排名和字段权限的多对象文本搜索

字段元数据工具：

get_picklist_values -通过依赖关系分析和安全过滤检索选择列表字段值

查询分析工具：

validate_soql -无需执行SOQL语法验证和安全分析
explain_query_plan -查询性能分析和优化建议

组织上下文工具：

get_org_limits -组织API限制和使用统计监测
get_user_info -具有隐私净化功能的当前用户配置文件信息

附加功能：

OAuth2-PKCE身份验证流，具有自动令牌刷新功能
Claude桌面通过stdio传输集成
可配置位置的加密令牌存储
全面的日志记录和错误处理

🚧 计划的功能

MCP资源的资源提供者
高级查询工具（SOSL搜索）
实用工具（组织限制、用户信息）

🛠 安装

先决条件

Node.js 18.0或更高版本
tsx（TypeScript执行器）： npm install -g tsx
配置了OAuth2互联应用程序的Salesforce组织
Claude Desktop（用于MCP集成）

从源安装

git clone https://github.com/your-org/salesforce-mcp-server.git
cd salesforce-mcp-server
npm install

⚡ 快速开始

1.配置Salesforce互联应用程序

逐步连接应用程序设置

登录Salesforce:
- 转到您的Salesforce组织（生产、沙盒或开发人员版）
- 引导到设置（齿轮图标→ 设置）
创建新的连接应用程序:
- 在快速查找中，搜索“应用程序管理器”
- 点击 应用程序管理器 → 新连接的应用程序
基本信息:
- 已连接的应用程序名称: MCP Salesforce Server （或您喜欢的名字）
- API名称：自动生成（例如。， MCP_Salesforce_Server)
- 联系邮箱：您的电子邮件地址
- 描述: MCP server for AI access to Salesforce data
API（启用OAuth设置）:
- ✅ 检查 启用OAuth设置
- 回调URL: http://localhost:8080/callback
- 选定的OAuth作用域 （加上这三个）：
  - Access the identity URL service (id)
  - Perform requests at any time (refresh_token)
  - Access and manage your data (api)
Web应用程序设置:
- ✅ 检查 Web服务器流需要密码
- ✅ 检查 刷新令牌流需要密码
安全设置 （推荐）：
- IP放松: Relax IP restrictions
- 刷新令牌策略: Refresh token is valid until revoked
保存并等待:
- 点击保存
- 等待2-10分钟，让已连接的应用程序传播

检索凭据

获取客户端ID和密码:
- 回到 应用程序管理器
- 查找您已连接的应用程序→ 视图
- 复制 消费者密钥 （这是你的 SFDC_CLIENT_ID)
- 点击 单击以显示 消费者秘密旁边（这是你的 SFDC_CLIENT_SECRET)
获取实例URL:
- 您的Salesforce实例URL格式：
  - 生产： https://yourcompany.my.salesforce.com
  - 沙箱： https://yourcompany--sandbox.sandbox.my.salesforce.com
  - 开发商： https://yourcompany-dev-ed.develop.my.salesforce.com

解决连接的应用程序问题

常见问题：

“invalid_client_id”错误：创建已连接应用程序后等待2-10分钟
“redirect_uri_mismatch”错误：确保回调URL准确无误 http://localhost:8080/callback
“范围不足”错误：验证是否已选择所有三个OAuth作用域
SSL/TLS错误：确保您的Salesforce组织拥有正确的SSL证书

安全注意事项：

Connected应用程序使用PKCE（代码交换证明密钥）来增强安全性
客户端密钥仅用于刷新令牌流，不用于初始身份验证
所有令牌都使用AES-256-GCM加密进行本地加密
不以纯文本形式存储敏感数据

2.设置环境变量

cp .env.sample .env
# Edit .env with your Salesforce credentials and file paths

所需的环境变量：

SFDC_CLIENT_ID=<your_connected_app_client_id>
SFDC_CLIENT_SECRET=<your_connected_app_client_secret>
SFDC_INSTANCE_URL=https://your-org.my.salesforce.com
MCP_LOG_FILE="/absolute/path/to/your/project/server.log"
SFDC_TOKEN_FILE="/absolute/path/to/your/project/.salesforce-tokens.enc"

3.添加到Claude桌面配置

将此添加到您的Claude桌面 claude_desktop_config.json:

{
  "mcpServers": {
    "salesforce": {
      "command": "tsx",
      "args": ["/absolute/path/to/salesforce-mcp-server/src/stdio-server.ts"],
      "env": {
        "SFDC_CLIENT_ID": "your_connected_app_client_id",
        "SFDC_CLIENT_SECRET": "your_connected_app_client_secret",
        "SFDC_INSTANCE_URL": "https://your-org.my.salesforce.com",
        "SFDC_API_VERSION": "v59.0",
        "MCP_LOG_FILE": "/absolute/path/to/your/project/server.log",
        "SFDC_TOKEN_FILE": "/absolute/path/to/your/project/.salesforce-tokens.enc"
      }
    }
  }
}

4.测试集成

重新启动克劳德桌面
开始新的对话

尝试使用describe_object工具：

Can you describe the Account object in Salesforce?

服务器将在首次使用时自动打开浏览器进行OAuth2身份验证。

⚙️ 配置

环境变量

变量	描述	必填	默认
`SFDC_CLIENT_ID`	OAuth2已连接应用程序客户端ID	是	-
`SFDC_CLIENT_SECRET`	OAuth2已连接应用程序客户端密码	是	-
`SFDC_INSTANCE_URL`	Salesforce实例URL	是	-
`SFDC_API_VERSION`	Salesforce API版本	否	`v59.0`
`SFDC_TOKEN_FILE`	加密令牌存储路径	否	`.salesforce-tokens.enc`
`MCP_LOG_FILE`	服务器日志文件的路径	否	-（日志到stdout）

配置示例

看 .env.sample 完整示例：

# Required Salesforce OAuth2 Configuration
SFDC_CLIENT_ID=3MVG9...your_client_id
SFDC_CLIENT_SECRET=9CF743...your_client_secret
SFDC_INSTANCE_URL=https://your-org.my.salesforce.com

# File Paths (use absolute paths for Claude Desktop)
MCP_LOG_FILE="/absolute/path/to/your/project/server.log"
SFDC_TOKEN_FILE="/absolute/path/to/your/project/.salesforce-tokens.enc"

# Optional Settings
SFDC_API_VERSION=v59.0

🔐 认证

服务器使用 OAuth2-PKCE（代码交换证明密钥） Salesforce的安全身份验证流程。

OAuth2安装过程

在Salesforce中创建互联应用 （详见上述步骤）：
- 导航到安装程序→ 应用程序管理器→ 新连接的应用程序
- 使用适当的作用域和回调URL配置OAuth设置
- 启用秘密要求以增强安全性
- 等待2-10分钟进行传播
配置环境:
- 复制 消费者密钥 像 SFDC_CLIENT_ID
- 复制 消费者秘密 像 SFDC_CLIENT_SECRET
- 将组织的实例URL设置为 SFDC_INSTANCE_URL
- 配置日志记录和令牌存储的文件路径
身份验证流程详细信息:

初始身份验证：
- 首次使用工具会触发OAuth2-PKCE流
- 本地HTTP服务器启动于 localhost:8080
- 浏览器打开Salesforce登录页面
- 用户登录并授予权限
- 交换访问/刷新令牌的授权码
- 使用AES-256-GCM加密并存储在本地的令牌
后续使用：
- 从本地存储加载加密令牌
- 用于API调用的访问令牌
- 令牌过期时自动刷新
- 无需浏览器交互
安全功能:
- PKCE流程：防止授权码被拦截
- 状态参数：CSRF攻击防御
- 本地存储：没有凭据的云存储
- 加密：AES-256-GCM，每个令牌随机IV
- 范围限制：仅要求最低权限
身份验证故障排除:

浏览器问题：
- 如果浏览器未打开：手动访问 http://localhost:8080/auth
- 如果回调失败：检查端口8080的防火墙设置
- 如果登录循环：清除Salesforce Cookie并重试
令牌问题：
- 删除令牌文件以强制重新身份验证： rm .salesforce-tokens.enc
- 检查令牌文件权限（只能由用户读取）
- 验证实例URL是否与您的组织完全匹配
权限错误：
- 确保连接的应用程序具有所有三个必需的OAuth作用域
- 检查用户是否在Salesforce中启用了API访问
- 验证对象访问的配置文件权限

安全功能

PKCE（RFC 7636）：防止授权码被拦截
AES-256-GCM加密：安全的本地令牌存储
状态参数：CSRF保护
自动令牌刷新：无缝重新身份验证

🛠 可用工具

✅ 目前已实施

`describe_object`

获取任何Salesforce对象的全面元数据和模式信息。

输入:

{
  "objectName": "Account"
}

退货:

对象属性（名称、标签、键前缀、权限）
完整的字段元数据（类型、长度、约束、关系）
字段级权限和可编辑性
记录类型信息
标准与自定义对象分类

示例用法:

Can you describe the Account object structure?
Which fields are required when creating a new Contact?
What are the field types and constraints for the Opportunity object?

`list_objects`

列出所有支持过滤和分页的可用Salesforce对象。

输入:

{
  "objectType": "all",  // "all", "standard", or "custom"
  "limit": 100          // 1-500, default 100
}

退货:

对象名称和标签
标准分类与自定义分类
带有计数信息的分页结果
可按对象类型筛选

示例用法:

What objects are available in this Salesforce org?
Show me all custom objects
List the first 50 standard objects

`soql_query`

执行具有全面安全验证和分页支持的SOQL查询。

输入:

{
  "query": "SELECT Id, Name FROM Account WHERE Type = 'Customer' LIMIT 10",
  "limit": 200  // Optional: 1-2000, default 200
}

特性:

安全：通过危险模式检测防止SOQL注入
分页：可配置的记录限制（1-2000）
验证：查询语法和结构验证
清洁输出：删除Salesforce元数据以提高可读性

示例用法:

Show me all Accounts where Type is 'Customer'
Query the last 5 Opportunities created this month
Find all Contacts with email addresses containing '@salesforce.com'

`get_record`

通过可选字段选择按ID检索特定的Salesforce记录。

输入:

{
  "objectName": "Account",
  "recordId": "001000000001AAA",
  "fields": ["Id", "Name", "Type", "CreatedDate"]  // Optional
}

特性:

ID验证：Salesforce ID格式验证（15或18个字符）
字段选择：指定要检索的字段（可选）
关系支持：处理关系字段和嵌套对象
干净的格式：具有适当现场组织的可读输出

示例用法:

Get the Account record with ID 001000000001AAA
Show me the Contact record 003000000001BBB with just Name and Email fields
Retrieve the full details for Opportunity 006000000001CCC

🚧 计划工具

计划在未来实施以下工具：

高级查询工具

search：跨多个对象执行SOSL搜索

发现工具

get_picklist_values：获取指定字段的选择列表值

实用工具

get_limits：检索组织限制和使用统计信息
get_user_info：获取当前用户信息

📊 资源

MCP资源计划在未来实施，以公开Salesforce数据：

对象: salesforce://object/{objectType} -对象元数据和模式
记录: salesforce://record/{objectType}/{recordId} -个人记录数据
报告: salesforce://report/{reportId} -报告定义和结果

目前，所有功能都可以通过工具界面获得。

🧪 发展

设置

git clone https://github.com/your-org/salesforce-mcp-server.git
cd salesforce-mcp-server
npm install

可用脚本

npm run dev          # Start development server with auto-reload
npm run build        # Build for production
npm run test         # Run unit tests (335 tests)
npm run test:functional # Run functional E2E validation (12 tools)
npm run test:integration # Run integration tests
npm run test:all     # Run all tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Generate coverage report
npm run type-check   # Run TypeScript type checking
npm run lint         # Run ESLint
npm run lint:fix     # Fix ESLint issues
npm run format       # Format code with Prettier
npm run ci           # Run full CI pipeline (includes functional tests)

项目结构

src/
├── config.ts        # Configuration management
├── errors.ts        # Error handling and types
├── types.ts         # TypeScript type definitions
├── tools.ts         # MCP tool implementations
├── salesforce-client.ts # Salesforce API client
├── server.ts        # Main MCP server implementation
├── stdio-server.ts  # stdio transport server
├── http-server.ts   # HTTP transport server
└── index.ts         # Entry point

src/test/
├── setup.ts         # Test environment setup
└── integration/     # Integration test files

🧪 测试

运行测试

# Run unit tests (335 tests)
npm test

# Run functional tests (all 12 tools validation)
npm run test:functional

# Run integration tests (with real Salesforce API)
npm run test:integration

# Run all tests with coverage
npm run test:coverage

# Run specific test file
npm test config.test.ts

# Run tests in watch mode
npm run test:watch

# Run complete CI pipeline
npm run ci

测试环境

框架：Vitest用于单元和集成测试
功能测试：基于tsx的E2E工具验证（成功率75%）
覆盖：v8覆盖率提供商，覆盖率超过80%
测试计数：335个单元测试+12个功能工具验证
速度：功能测试的亚秒级执行

功能测试

功能测试套件通过现实场景验证了所有12个MCP工具：

npm run test:functional

测试结果：

✅ 9/12工具工作 （成功率75%）
总执行时间4ms
验证JSON和人类可读的响应
不需要外部依赖

工作工具：

describe_object、list_objects、soql_query
get_record、sosl_search、get_cent_items
validate_soql、describe_layout、get_picklist_values

这在开发和CI/CD集成过程中提供了快速反馈。

手动测试

使用Claude Desktop测试服务器：

设置 .env 具有真实Salesforce凭据的文件
使用服务器配置Claude Desktop

使用自然语言测试工具：

Can you describe the Account object in Salesforce?
What fields are available on the Contact object?

🤝 贡献

我们欢迎捐款！请查看我们的贡献指南了解详情。

开发工作流程

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
按照我们的编码标准进行更改
添加新功能的测试
确保所有测试通过(npm run ci)
使用常规提交格式提交
推到您的分支
打开拉取请求

代码质量

TypeScript严格模式已启用
使用TypeScript规则的ESLint
代码格式化的预处理
Husky用于预提交挂钩
需要常规提交

📈 状态

当前版本：0.6.0（开发）

第三期：核心MCP工具(✅ 完成)

✅ OAuth2-PKCE浏览器身份验证流程
✅ 使用AES-256-GCM加密令牌存储
✅ 自动令牌刷新处理
✅ Claude桌面通过stdio传输集成
✅ describe_object 工具实施
✅ list_objects 具有过滤和分页功能的工具
✅ soql_query 防注射和分页工具
✅ get_record 具有字段选择和关系支持的工具
✅ 175项测试通过，覆盖率超过80%
✅ 使用真实的Salesforce数据验证生产

下一阶段：MCP资源和高级功能（第4阶段）

看项目_平面.md 详细的路线图。

📄 许可证

此项目根据BSL许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 支持

🐛 问题追踪

🙏 致谢

模型上下文协议对于MCP规范
jsforce 用于Salesforce API集成
Salesforce公司由于其全面的API

由以下材料制成❤️ + AI by 真快

使用说明

realfast.ai Salesforce MCP服务器0.6.0

关于我们

🚀 特性

✅ 当前实施的工具（共10个）

🚧 计划的功能

📋 目录

🛠 安装

先决条件

从源安装

⚡ 快速开始

1.配置Salesforce互联应用程序

逐步连接应用程序设置

检索凭据

解决连接的应用程序问题

2.设置环境变量

3.添加到Claude桌面配置

4.测试集成

⚙️ 配置

环境变量

配置示例

🔐 认证

OAuth2安装过程

安全功能

🛠 可用工具

✅ 目前已实施

describe_object

list_objects

soql_query

get_record

🚧 计划工具

高级查询工具

发现工具

实用工具

📊 资源

🧪 发展

设置

可用脚本

项目结构

🧪 测试

运行测试

测试环境

功能测试

手动测试

🤝 贡献

开发工作流程

代码质量

📈 状态

📄 许可证

🆘 支持

🙏 致谢

相关 MCP

Salesforce MCP服务器

Salesforce MCP服务

任务管理协议服务器

Salesforce集成MCP服务器

Salesforce连接器

Dynamics 365商业中央模型协议服务器

`describe_object`

`list_objects`

`soql_query`

`get_record`