AI导哈

Salesforce知识文章搜索API

轻量级API，通过SOQL over REST搜索和获取Salesforce知识文章，提供HTTP和MCP两种接口。

  • by markcoleman
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 markcoleman/knowledge-mcp

使用说明

知识MCP API

轻量级API，通过REST上的SOQL搜索和获取Salesforce知识文章。通过HTTP（Express）和MCP（Model Context Protocol）公开端点。

前提条件

  • Node.js 18+（用20测试）
  • 已安装pnpm(npm install -g pnpm 如果需要）
  • Salesforce Connected App已配置为JWT Bearer（服务器到服务器） sf_jwt.crt 证书已上传

设置

  1. 复制env模板并填写凭据：

    cp .env.example .env
# edit .env with SALESFORCE_CLIENT_ID, SALESFORCE_USERNAME, and SALESFORCE_JWT_KEY_PATH (defaults to ./sf_jwt.key)

  2. 安装deps：

    pnpm install

  3. 运行HTTP API服务器：

    pnpm dev

    服务器正在监听 http://localhost:3000 默认情况下。

  4. 或者运行MCP服务器：

    pnpm start:mcp

    MCP服务器正在监听 http://localhost:3001/mcp 默认情况下。集 MCP_PORT 更改端口。

日志记录

  • 请求日志以基本颜色编码打印到控制台。
  • 当 /articles/search 返回结果后，服务器会记录一行绿色的“找到N篇文章”；没有结果会记录一条黄线。
  • 通过以下方式控制冗长 LOG_LEVEL (debug, info, warn, error, silent).

HTTP端点

  • GET /articles/search?q=printer&limit=20
    • 按配置语言的标题搜索已发布的知识文章。
  • GET /articles/:id
    • 获取Id发布的一篇知识文章。

两个端点都返回 { data: ... } 关于成功和 { error: { message } } 失败。

MCP工具

MCP服务器通过两个工具公开相同的功能：

  • 搜索_文章：按标题搜索Salesforce知识文章

    • 参数：
      • q （必填）：与文章标题匹配的搜索词
      • limit （可选）：最大结果数（1-50，默认20）

  • 获取_文章：按ID获取单个Salesforce知识文章

    • 参数：
      • id （必填）：Salesforce文章ID（15-18个字母数字字符）

MCP客户端配置

MCP服务器作为HTTP服务器运行。要连接MCP客户端，请执行以下操作：

  1. 启动MCP服务器： pnpm start:mcp
  2. 配置您的MCP客户端以连接到 http://localhost:3001/mcp

Claude Desktop或其他支持HTTP传输的MCP客户端示例：

{
  "mcpServers": {
    "knowledge-mcp": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

服务器使用Streamable HTTP传输，它支持SSE流和直接HTTP响应。

备注

  • SOQL查询使用 Knowledge__kav 默认情况下为对象；用以下方式覆盖 SALESFORCE_ARTICLE_OBJECT 如果你的组织不同。
  • 令牌检索使用OAuth 2.0 JWT承载授权 SALESFORCE_LOGIN_URL 并缓存到接近到期。
  • 语言过滤器默认为 en_US 通过 SALESFORCE_KNOWLEDGE_LANGUAGE.
  • 文章正文字段默认为 ArticleBody；用以下命令覆盖 SALESFORCE_ARTICLE_BODY_FIELD 如果您的文章类型使用了不同的富格文本/答案字段。
  • 添加额外字段以进行查询 SALESFORCE_ARTICLE_ADDITIONAL_FIELDS （逗号分隔。， Content__c,Question__c).
  • 要返回文章对象中的每个可查询字段，请设置 SALESFORCE_ARTICLE_SELECT_ALL_FIELDS=true （使用对象描述；可能会增加有效载荷大小）。

JWT设置快速入门

  1. 生成密钥对（私钥保持在本地，证书上传到已连接的应用程序）：
    openssl genrsa -out sf_jwt.key 2048
openssl req -new -x509 -key sf_jwt.key -out sf_jwt.crt -days 3650 -subj "/CN=sf-jwt"
  2. 在Salesforce中，编辑Connected App：
    • 上传 sf_jwt.crt 在“为OAuth使用数字签名”下。
    • 使用JWT承载流启用OAuth设置。
    • 添加中指定的用户 SALESFORCE_USERNAME 添加到应用程序的配置文件/权限集。
  3. 使用 .env 如上所述的值。
  • 设置用户
  • 分配权限
  • 已连接的应用程序
  • 证书上传
  • 许可证集
  • 将用户分配到权限集
  • 为已连接的应用程序分配权限集
  • 将知识管理员分配给集成用户
  • 如果您的文章类型使用自定义正文字段，请设置 SALESFORCE_ARTICLE_BODY_FIELD 在 .env
  • 如果你想返回额外的字段（例如。， Content__c, Question__c)，set SALESFORCE_ARTICLE_ADDITIONAL_FIELDS
  • 集 SALESFORCE_ARTICLE_SELECT_ALL_FIELDS=true 如果您希望返回每个可查询字段

相关 MCP