Salesforce Ai Agent Mcp Server

Salesforce AI Agent MCP 服务

一个生产级 Model Context Protocol（MCP）服务，可让 Claude 直接以结构化方式访问 Jira Cloud、Salesforce（Tooling + Metadata API）和 n8n 工作流。

专为 Salesforce Developer AI Agent 项目构建——这是一个自动化流水线，可读取 Jira 故事、解读 Salesforce 配置需求，并将元数据（自定义字段、验证规则等）直接部署到 Salesforce。

---

架构

Claude Desktop / Claude Code / VS Code
           │  (stdio or SSE)
           ▼
  salesforce-ai-agent-mcp
  ┌───────────────────────────┐
  │  Tools (12 total)         │
  │  ├── Jira (4 tools)       │──► Jira Cloud REST API v3
  │  ├── Salesforce (6 tools) │──► Salesforce Tooling + Metadata APIs
  │  └── n8n (2 tools)        │──► n8n Webhook + REST API
  └───────────────────────────┘

---

先决条件

• Node.js ≥ 18
• npm ≥ 9
• 拥有 API 令牌的 Jira Cloud 账户
• 配置了 Connected App（OAuth 2.0）的 Salesforce 组织
• n8n 实例（可选，用于工作流编排）

---

安装

cd salesforce-ai-agent-mcp
npm install
npm run build

---

配置

将 .env.example 复制为 .env，并填写凭据：

cp .env.example .env

Jira

变量	描述
JIRA_BASE_URL	例如：https://your-org.atlassian.net
JIRA_EMAIL	Atlassian 账户邮箱
JIRA_API_TOKEN	在 Atlassian API Tokens 生成

Salesforce

你需要一个启用了 Username-Password OAuth flow 的 Connected App。

1. 在 Salesforce Setup 中，依次选择 App Manager → New Connected App
2. 启用 OAuth 设置
3. 添加范围：api、refresh_token
4. 复制 Consumer Key → SF_CLIENT_ID
5. 复制 Consumer Secret → SF_CLIENT_SECRET

变量	描述
SF_LOGIN_URL	https://login.salesforce.com（生产环境）或 https://test.salesforce.com（沙盒）
SF_CLIENT_ID	Connected App Consumer Key
SF_CLIENT_SECRET	Connected App Consumer Secret
SF_USERNAME	Salesforce 用户名
SF_PASSWORD	Salesforce 密码
SF_SECURITY_TOKEN	在 Setup → Personal Information → Reset Security Token 中重置
SF_API_VERSION	API 版本，例如 v61.0（默认值）

n8n

变量	描述
N8N_BASE_URL	n8n 实例 URL，例如 https://your-n8n.com
N8N_API_KEY	在 n8n Settings → API → Create API Key 中生成

---

使用方法

stdio 模式（Claude Desktop / Claude Code / VS Code）

npm start
# or for development:
npm run dev

SSE 模式（用于远程/n8n 集成）

npm run start:sse
# or for development:
npm run dev:sse

SSE 模式下可用的端点：

• GET http://localhost:3000/sse — 客户端在此连接
• POST http://localhost:3000/messages?sessionId=<id> — 客户端在此发送消息
• GET http://localhost:3000/health — 存活探针

覆盖端口：

MCP_PORT=8080 npm run start:sse

---

连接到 Claude Desktop

将以下内容添加到 claude_desktop_config.json：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "salesforce-ai-agent": {
      "command": "node",
      "args": ["/absolute/path/to/salesforce-ai-agent-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your_token",
        "SF_LOGIN_URL": "https://login.salesforce.com",
        "SF_CLIENT_ID": "your_client_id",
        "SF_CLIENT_SECRET": "your_client_secret",
        "SF_USERNAME": "[email protected]",
        "SF_PASSWORD": "yourpassword",
        "SF_SECURITY_TOKEN": "yourSecurityToken",
        "N8N_BASE_URL": "https://your-n8n.com",
        "N8N_API_KEY": "your_n8n_api_key"
      }
    }
  }
}

---

连接到 Claude Code（VS Code 扩展）

将以下内容添加到 VS Code 的 settings.json（或通过 MCP 扩展界面添加）：

{
  "mcp.servers": {
    "salesforce-ai-agent": {
      "command": "node",
      "args": ["${workspaceFolder}/salesforce-ai-agent-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your_token",
        "SF_LOGIN_URL": "https://login.salesforce.com",
        "SF_CLIENT_ID": "your_client_id",
        "SF_CLIENT_SECRET": "your_client_secret",
        "SF_USERNAME": "[email protected]",
        "SF_PASSWORD": "yourpassword",
        "SF_SECURITY_TOKEN": "yourSecurityToken",
        "N8N_BASE_URL": "https://your-n8n.com",
        "N8N_API_KEY": "your_n8n_api_key"
      }
    }
  }
}

或者，本项目根目录下的 mcp.json 文件与 VS Code 的 MCP 扩展兼容；将其放在工作区根目录下即可自动检测。

---

可用工具（共 12 个）

Jira 工具

jira_get_story

根据问题键获取 Jira 故事。返回摘要、描述、验收标准、状态、标签及所有自定义字段。

issueKey: "SFDC-123"

jira_update_story_status

将 Jira 故事转换为新的工作流状态。

issueKey: "SFDC-123"
targetStatus: "In Progress"   # must match an available transition

jira_post_comment

向 Jira 故事发布评论（AI Agent 用于汇报结果或请求澄清）。

issueKey: "SFDC-123"
body: "Deployed Customer_Tier__c field to Account. Deployment ID: 0Af..."

jira_search_stories

基于 JQL 搜索故事。

jql: "label = \"sf-config\" AND status = \"To Do\" AND project = SFDC"
maxResults: 25

---

Salesforce 工具

salesforce_get_object_fields

描述 Salesforce 对象上的所有字段。

objectName: "Account"

salesforce_create_custom_field

通过 Tooling API 创建自定义字段。

objectName: "Account"
fieldLabel: "Customer Tier"
fieldApiName: "Customer_Tier"     # __c added automatically
fieldType: "Picklist"
picklistValues: ["Platinum", "Gold", "Silver", "Bronze"]
description: "Tier classification for account segmentation"

查找关系字段示例：

objectName: "Case"
fieldLabel: "Related Contract"
fieldApiName: "Related_Contract"
fieldType: "Lookup"
referenceTo: "Contract"

salesforce_create_validation_rule

通过 Tooling API 创建验证规则。

objectName: "Account"
ruleName: "Require_Phone_For_Hot_Leads"
errorConditionFormula: "AND(Rating = \"Hot\", ISBLANK(Phone))"
errorMessage: "Phone number is required for Hot-rated accounts"
errorDisplayField: "Phone"
active: true

salesforce_deploy_metadata

从 base64 编码的 ZIP 文件触发元数据部署。

zipFile: "<base64-encoded-zip>"
checkOnly: false
testLevel: "RunLocalTests"
rollbackOnError: true

salesforce_get_deployment_status

轮询部署状态。

deploymentId: "0AfXXXXXXXXXXXXX"

salesforce_query

执行 SOQL 以进行验证和确认。

soql: "SELECT Id, Name, Customer_Tier__c FROM Account WHERE Rating = 'Hot' LIMIT 10"

---

n8n 工具

n8n_trigger_workflow

通过 Webhook URL 触发 n8n 工作流。

webhookUrl: "https://your-n8n.com/webhook/abc123"
payload: {
  "issueKey": "SFDC-123",
  "environment": "sandbox",
  "triggeredBy": "claude"
}

n8n_get_execution_status

检查 n8n 执行状态。

executionId: "12345"

---

AI Agent 工作流示例

You: "Process Jira story SFDC-456 and deploy the Salesforce configuration"

Claude:
1. jira_get_story(issueKey: "SFDC-456")
   → reads requirements: "Add Customer_Tier picklist to Account"

2. salesforce_get_object_fields(objectName: "Account")
   → confirms Customer_Tier__c doesn't exist yet

3. salesforce_create_custom_field(
     objectName: "Account",
     fieldLabel: "Customer Tier",
     fieldApiName: "Customer_Tier",
     fieldType: "Picklist",
     picklistValues: ["Platinum", "Gold", "Silver"]
   )
   → creates the field

4. salesforce_query(soql: "SELECT QualifiedApiName FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = 'Account' AND QualifiedApiName = 'Customer_Tier__c'")
   → verifies the field was created

5. jira_post_comment(
     issueKey: "SFDC-456",
     body: "✅ Customer_Tier__c picklist field created on Account object with values: Platinum, Gold, Silver."
   )

6. jira_update_story_status(issueKey: "SFDC-456", targetStatus: "Done")

---

日志记录

所有日志都会以结构化 JSON 的形式写入 stderr，因此不会干扰 MCP stdio 传输。

通过环境变量控制日志级别：

LOG_LEVEL=debug npm start    # debug | info | warn | error

---

开发

# Type-check only
npm run typecheck

# Build
npm run build

# Dev with hot reload (stdio)
npm run dev

# Dev with hot reload (SSE)
npm run dev:sse

---

项目结构

salesforce-ai-agent-mcp/
├── src/
│   ├── index.ts              # Entry point — stdio & SSE transport setup
│   ├── server.ts             # McpServer creation & tool registration
│   ├── tools/
│   │   ├── jira.ts           # Jira tool definitions (4 tools)
│   │   ├── salesforce.ts     # Salesforce tool definitions (6 tools)
│   │   └── n8n.ts            # n8n tool definitions (2 tools)
│   ├── clients/
│   │   ├── jiraClient.ts     # Jira REST API v3 client
│   │   ├── salesforceClient.ts  # Salesforce Tooling/Metadata API + OAuth
│   │   ├── n8nClient.ts      # n8n webhook + REST API client
│   │   └── logger.ts         # Structured JSON logger (stderr)
│   └── types/
│       └── index.ts          # Shared TypeScript types
├── .env.example              # All required environment variables
├── mcp.json                  # VS Code MCP extension manifest
├── package.json
├── tsconfig.json
└── README.md