Official Ampersand AI SDKs

Ampersand 官方 AI SDK

此代码库包含 Ampersand 官方 AI SDK 和官方 MCP 服务。

• AI SDK - Ampersand 官方 AI SDK，提供工具供 AI Agent 管理并与客户 SaaS 工具的集成进行交互。
• MCP 服务 - Ampersand 官方 MCP 服务，提供 Ampersand AI SDK 中的工具。

examples 目录包含如何将 AI SDK 与热门 Agent 框架配合使用的示例。

Ampersand 是一个帮助 AI 构建者为其智能应用添加 B2B SaaS 集成的平台。要了解详情，请访问我们的网站。

Ampersand AI SDK

安装

npm install @amp-labs/ai
# or
yarn add @amp-labs/ai
# or
pnpm add @amp-labs/ai

使用方法

SDK 提供了多个模块，可根据你偏好的框架选用：

与 Vercel AI SDK 配合使用

import { createRecord, updateRecord } from "@amp-labs/ai/aisdk";

// Use in your AI agent configuration
const tools = [createRecord, updateRecord];

与 Mastra 配合使用

import { createRecord, updateRecord } from "@amp-labs/ai/mastra";

// Use in your Mastra workflow
const tools = [createRecord, updateRecord];

测试

test 目录包含 AI SDK 的端到端测试。

运行简单测试

先决条件：

• OpenAI API 密钥（AI 模型必需）
• Ampersand API 凭据

1. 在 test/.env 中配置环境变量：

   OPENAI_API_KEY=your_openai_api_key_here
   AMPERSAND_API_KEY=your_ampersand_api_key_here
   AMPERSAND_PROJECT_ID=your_project_id_here
   AMPERSAND_GROUP_REF=your_group_ref_here
   

2. 运行测试：

   # From the root directory
   pnpm --filter ai-e2e-test test:simple
   
   # Or from the test directory
   cd test
   pnpm test:simple
   

此简单测试演示了如何将 checkConnection 工具与 Vercel AI SDK 配合使用，以验证 Salesforce 连接。

测试本地更改

该测试通过 pnpm 工作区链接使用你的本地 SDK 构建版本。如需测试对 SDK 的修改：

1. 修改 sdk/lib/ 中的 SDK 源文件

2. 重新构建 SDK：

   pnpm --filter @amp-labs/ai build
   

3. 重新运行测试以验证更改：

   pnpm --filter ai-e2e-test test:simple
   

测试将使用 sdk/dist/ 中刚构建的 SDK，让你可以快速迭代 SDK 更改。

Ampersand MCP 服务

通过此多租户 MCP 服务，将 Agent 连接到 Ampersand 提供的 150 多个连接器。我们在此将 Ampersand 平台提供的基础功能作为原生工具开放。

连接到远程 MCP 服务

在 Cursor IDE 中使用时，将以下内容添加到 mcp.json；使用 Claude 桌面应用时，则添加到 claude_desktop_config.json。

以 SSE 模式运行服务时

如果你的 MCP 客户端支持请求头：

{
  "mcpServers": {
    "@amp-labs/mcp-server": {
      "url": "https://mcp.withampersand.com/v1/sse?project=<AMPERSAND_PROJECT_ID>&integrationName=<AMPERSAND_INTEGRATION_NAME>&groupRef=<AMPERSAND_GROUP_REF>",
      "headers": {
        "x-api-key": "<AMPERSAND_API_KEY>"
      }
    }
  }
}

如果你的 MCP 客户端不支持请求头，可以在查询参数中传递 API 密钥：

{
  "mcpServers": {
    "@amp-labs/mcp-server": {
      "url": "https://mcp.withampersand.com/v1/sse?apiKey=<AMPERSAND_API_KEY>&project=<AMPERSAND_PROJECT_ID>&integrationName=<AMPERSAND_INTEGRATION_NAME>&groupRef=<AMPERSAND_GROUP_REF>"
    }
  }
}

以 stdio 模式运行服务时

{
  "mcpServers": {
    "@amp-labs/mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@amp-labs/mcp-server@latest",
        "--transport",
        "stdio",
        "--project",
        "<AMPERSAND_PROJECT_ID>",
        "--integrationName",
        "<AMPERSAND_INTEGRATION_NAME>",
        "--groupRef",
        "<AMPERSAND_GROUP_REF>"
      ],
      "env": {
        "AMPERSAND_API_KEY": "<AMPERSAND_API_KEY>"
      }
    }
  }
}

连接到本地 MCP 服务

有关更多信息，请参阅 mcp-server README。

许可证

本项目采用 MIT 许可证。

详情请参阅 LICENSE。

贡献

欢迎贡献！详情请参阅 CONTRIBUTING.md 文件。