Official Ampersand AI SDKs

Ampersand 公式 AI SDK

このリポジトリには、Ampersand の公式 AI SDK と公式 MCP サーバーが含まれています。

• AI SDK - AI エージェントが顧客の SaaS ツールとの連携を管理し、操作するためのツールを提供する、Ampersand 公式 AI SDK です。
• MCP サーバー - Ampersand AI SDK のツールを提供する、Ampersand 公式 MCP サーバーです。

examples ディレクトリには、よく使われるエージェントフレームワークで AI SDK を使用する方法の例が含まれています。

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
   

このシンプルなテストでは、Vercel AI SDK で checkConnection ツールを使用して、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 サーバーを介して、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をご覧ください。