MCP

🚀 Florentine.ai MCP Server - MongoDB と MySQL データと会話する

Florentine.ai のモデルコンテキストプロトコル (MCP) サーバーを使用すると、MongoDB と MySQL データの自然言語クエリを直接カスタム AI エージェントまたは AI デスクトップアプリに統合できます。

AI エージェントが質問を MCP サーバーに転送し、データベースクエリに変換された後、クエリ結果がエージェントに返されてさらに処理されます。

また、いくつかの追加機能も備えています。例えば：

• マルチテナント利用のための安全なデータ分離
• 自動スキーマ探索
• 自動埋め込み作成によるセマンティックベクトル検索/RAG サポート
• 高度なルックアップサポート
• キーの除外

注意: API を探している場合は、こちらで見つけることができます。

🚀 クイックスタート

Florentine.ai MCP サーバーを使用することで、MongoDB と MySQL データに対する自然言語クエリをカスタム AI エージェントや AI デスクトップアプリに統合できます。以下のセクションでは、必要な前提条件、インストール方法、利用可能なツール、引数、認証方法、LLM アカウントの接続方法、統合モード、戻り値の種類、マルチテナント利用のための安全なデータ分離、セッション管理、エラーハンドリングなどについて詳しく説明します。

✨ 主な機能

• 自然言語で MongoDB と MySQL データをクエリできる。
• マルチテナント利用のための安全なデータ分離機能を提供する。
• 自動スキーマ探索やセマンティックベクトル検索/RAG サポートなどの追加機能を備えている。

📦 インストール

MCP サーバーの詳細なドキュメントは、こちらのドキュメントで確認できます。

npx を使用して簡単にサーバーを実行できます。Claude Desktop (claude_desktop_config.json) の例を次に示します。

{
  "mcpServers": {
    "florentine": {
      "command": "npx",
      "args": ["-y", "@florentine-ai/mcp", "--mode", "static"],
      "env": {
        "FLORENTINE_TOKEN": "<FLORENTINE_API_KEY>"
      }
    }
  }
}

前提条件

• Node.js >= v18.0.0
• Florentine.ai アカウント（こちらで無料アカウントを作成）
• 接続されたデータベースと、Florentine.ai アカウント内で少なくとも 1 つの分析済みかつアクティブなコレクション/テーブル
• Florentine.ai API キー（アカウントダッシュボードで確認できます）

💻 使用例

利用可能なツール

• florentine_list_collections --> 現在クエリ可能なすべてのアクティブなコレクション/テーブルをリストします。説明、キー、値のタイプが含まれます。
• florentine_ask --> 質問を受け取り、クエリ、クエリ結果、または回答を返します（returnTypes 設定によります）。

引数

認証

Florentine.ai MCP サーバーは、API キーを使用してリクエストを認証します。API キーは、アカウントダッシュボードで表示および管理できます。キーは、MCP サーバーの設定に ENV 変数として追加する必要があります。

"env": {
  "FLORENTINE_TOKEN": "<FLORENTINE_API_KEY>"
}

LLM アカウントの接続

Florentine.ai は自分のキーを持ち込むモデルとして機能するため、MCP リクエストで LLM API キー（OpenAI、Google、Anthropic、Deepseek）を提供する必要があります。

LLM API キーを追加する方法は 2 つあります。

オプション 1: LLM キーをアカウントに保存する（推奨）

LLM プロバイダーに接続する最も簡単な方法は、Florentine.ai ダッシュボードに LLM API キーを保存することです。

• API キーを追加します。
• LLM プロバイダー（OpenAI、Deepseek、Google、または Anthropic）を選択します。
• 保存をクリックします。

オプション 2: MCP サーバー設定の環境変数内で LLM キーを提供する

Florentine.ai アカウントにキーを保存したくない場合、または複数の LLM キーを使用したい場合は、MCP サーバー設定内でキーを渡すことができます。

"env": {
  "LLM_SERVICE": "<YOUR_LLM_SERVICE>",
  "LLM_KEY": "<YOUR_LLM_API_KEY>"
}

注意: MCP サーバー設定の環境変数内で LLM_KEY を提供すると、アカウントに保存されているキーが上書きされます。

統合モード

MCP サーバー設定の args 配列で、動作モードを static または dynamic に設定する必要があります。

"args": [
  "-y",
  "@florentine-ai/mcp",
  "--mode",
  "static"
]

静的モード

既存の外部 MCP クライアント（Claude Desktop や Dive AI などの MCP 対応デスクトップアプリ）に Florentine.ai を統合する場合は、静的モードを使用します。

static モードでは、すべてのパラメータ（戻り値の種類、必須入力など）を設定 JSON 内の環境変数として設定します。これは、これらのパラメータは設定構成を変更するまで静的に維持され、Florentine.ai へのすべてのリクエストとともに送信されることを意味します。次の例を参照してください。

{
  "mcpServers": {
    "florentine": {
      "command": "npx",
      "args": ["-y", "@florentine-ai/mcp", "--mode", "static"],
      "env": {
        "FLORENTINE_TOKEN": "<FLORENTINE_API_KEY>",
        "SESSION_ID": "6f7d62f9-8ceb-456b-b7ef-6bd869c3b13a",
        "LLM_SERVICE": "openai",
        "LLM_KEY": "<YOUR_OPENAI_KEY>",
        "RETURN_TYPES": "[\"result\"]",
        "REQUIRED_INPUTS": "[{\"keyPath\":\"accountId\",\"value\":\"507f1f77bcf86cd799439011\"}]"
      }
    }
  }
}

環境変数

動的モード

独自のカスタム MCP クライアントに Florentine.ai を統合する場合は、動的モードを使用します。

動的モードでは、すべてのパラメータ（戻り値の種類、必須入力など）を直接 florentine_ask ツールに渡すことができます。これは、Florentine.ai に転送されるすべてのリクエストに個別のパラメータ（例えばユーザー ID）を動的に注入できることを意味します。

値を動的に渡すには、カスタムクライアント/エージェント内で florentine_ask ツールメソッドを上書きする必要があります。標準の @modelcontextprotocol TypeScript SDK を使用した次の例を見てみましょう。

import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { fetchUserSpecificData } from './userService.js';

// Create the MCP client instance
const mcpClient = new Client({
  name: 'florentine',
  version: '1.0.0'
});

// Define MCP setup configuration
const mcpSetupConfig = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@florentine-ai/mcp', '--mode', 'dynamic'],
  env: {
    FLORENTINE_TOKEN: '<FLORENTINE_API_KEY>'
  }
});

// Connect the MCP client
await mcpClient.connect(mcpSetupConfig);

// Save original callTool function to variable
const originalCallTool = mcpClient.callTool;

// Fetch and add florentine_ask parameters dynamically (mock implementation)
const enhanceAskParameters = async ({ question }: { question: string }) => {
  return {
    question,
    // Mocking user data fetch (i.e. returnTypes, requiredInputs, etc.),
    // replace with actual implementation
    ...(await fetchUserSpecificData({ userId: '<USER_ID>' }))
  };
};

// Overwrite callTool function with custom implemention
// enhancing florentine_ask method with dynamically injected parameters
mcpClient.callTool = async (params, resultSchema, options) => {
  if (params.name === 'florentine_ask')
    params.arguments = await enhanceAskParameters(
      params.arguments as unknown as { question: string }
    );
  return await originalCallTool(params, resultSchema, options);
};

// Call to florentine_ask tool will automatically enhance parameters
const result = await mcpClient.callTool({
  name: 'florentine_ask',
  arguments: {
    question: 'Who won the last tabletennis match?'
  }
});

例の解説

上記の例で何が起こっているかを詳しく見てみましょう。

まず、MCP クライアントを作成して接続します。

const mcpClient = new Client({
  name: 'florentine',
  version: '1.0.0'
});

const mcpSetupConfig = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@florentine-ai/mcp', '--mode', 'dynamic'],
  env: {
    FLORENTINE_TOKEN: '<FLORENTINE_API_KEY>'
  }
});

await mcpClient.connect(mcpSetupConfig);

注意: dynamic モードでも env 変数を使用できます。ただし、パラメータを動的に指定すると、これらのパラメータの既存の env 値が上書きされます。

次に、元の callTool 関数を変数に保存します。

const originalCallTool = mcpClient.callTool;

次に、質問を入力として受け取り、ユーザーの追加パラメータ（例えば returnTypes、requiredInputs など）を取得し、マージされたパラメータを返す enhanceAskParameters 関数を作成します。

const enhanceAskParameters = async ({ question }: { question: string }) => {
  return {
    question,
    // Example function that fetches additional data, e.g. user-specfic requiredInputs
    ...(await fetchUserSpecificData({ userId: '<USER_ID>' }))
  };
};

次に、元の callTool 関数を、enhanceAskParameters からのパラメータで florentine_ask ツールを強化する実装で上書きし、変数 originalCallTool に保存した元の callTool 関数を呼び出します。

mcpClient.callTool = async (params, resultSchema, options) => {
  if (params.name === 'florentine_ask')
    params.arguments = await enhanceAskParameters(
      params.arguments as unknown as { question: string }
    );
  return await originalCallTool(params, resultSchema, options);
};

最後に、質問を指定して florentine_ask ツールを呼び出し、ユーザー固有のパラメータを動的に注入することができます。

const result = await mcpClient.callTool({
  name: 'florentine_ask',
  arguments: {
    question: 'Who won the last tabletennis match?'
  }
});

重要: florentine_ask の実装を上書きせずに動的モードを使用しないようにしてください。 上書きしない場合、クライアント/エージェントは florentine_ask ツールの MCP サーバー側の実装をすべての追加パラメータで直接使用します。 そのため、クライアント/エージェントは returnTypes、requiredInputs などにどの値を入力するかを独自に決定します。 これにより、予期しない動作が発生し、エラーや誤った結果につながります。

florentine_ask パラメータ

戻り値の種類

デフォルトでは、florentine_ask ツールは Florentine.ai アカウントで構成された結果タイプ（デフォルト: result）を返します。次の 3 つのステップの任意の組み合わせを含む returnTypes 配列を指定することで、リクエストごとにこれを上書きできます。

1. クエリ生成: 質問がデータベースクエリ（MongoDB アグリゲーションパイプラインまたは MySQL クエリ）に変換されます。
2. クエリ実行: 提供された接続文字列を使用して、クエリがデータベースに対して実行されます。
3. 回答生成: 構造化された結果が自然言語の回答に変換されます。

戻り値の種類の提供

returnTypes 配列を含めるには、2 つのオプションがあります。

• MCP 設定構成の RETURN_TYPES env 変数として（static および dynamic モードで可能）
• florentine_ask ツールの returnTypes パラメータとして（dynamic モードでのみ可能）

env 変数としては、値を文字列化された JSON 配列として提供します。

"env": {
  "RETURN_TYPES": "[\"query\",\"result\",\"answer\"]"
}

ツールパラメータとしては、値を配列として提供します。

{
  "returnTypes": ["query", "result", "answer"]
}

戻り値の種類の構成

次のいずれかの組み合わせを含む returnTypes 配列を指定することで、返されるステップを選択できます。

マルチテナント利用のための安全なデータ分離

クエリが提供された値に基づいてデータをフィルタリングすることを確認することで、安全なデータ分離を有効にすることができます。これらの値を Required Inputs と呼びます。

これらの値は、LLM によるクエリ生成後、Florentine.ai 変換レイヤーによってクエリに追加されます。したがって、Florentine.ai は各ユーザーが自分に権限のあるデータのみを取得することを保証できます。

キーはアカウント内で Required Input として定義されます。その方法については、公式ドキュメントのセクションを参照してください。

必須入力の提供

requiredInputs 配列を含めるには、2 つのオプションがあります。

• MCP 設定構成の REQUIRED_INPUTS env 変数として（static および dynamic モードで可能）
• florentine_ask ツールの requiredInputs パラメータとして（dynamic モードでのみ可能）

env 変数としては、値を文字列化された JSON 配列として提供します。

"env": {
  "REQUIRED_INPUTS": "[{\"keyPath\":\"userId\",\"value\":\"507f1f77bcf86cd799439011\"}]"
}

ツールパラメータとしては、値を配列として提供します。

"requiredInputs": [
    {
      "keyPath": "userId",
      "value": "507f1f77bcf86cd799439011"
    }
  ]

複数のコレクション/テーブルに同じ keyPath の必須入力があり、コレクション/テーブルごとに異なる value がある場合は、database と collections 配列を提供することもできます。

{
  "requiredInputs": [
    {
      "keyPath": "name",
      "value": "Sesame Street",
      "database": "rentals",
      "collections": ["houses"]
    },
    {
      "keyPath": "name",
      "value": { "$in": ["Ernie", "Bert"] },
      "database": "rentals",
      "collections": ["tenants"]
    }
  ]
}

必須入力の構成

サポートされる値のタイプ

キーの値のタイプに応じて、Required Input 値として提供できるオプションが異なります。

使用例

注意: ツールパラメータ入力としての例のみを提供します。env 実装の場合は、キー名を REQUIRED_INPUTS に変更し、JSON を文字列化します。

例のタイプ: String

ユースケース: ユーザーは、自分が頻繁に対戦するプレーヤーの統計のみを表示できる必要があります。 解決策: プレーヤー名で 4 人のプレーヤーのグループへのアクセスを制限します。

const res = await FlorentineAI.ask({
  question: 'Which player had the most wins?',
  requiredInputs: [
    {
      keyPath: 'name',
      value: { $in: ['Megan', 'Frank', 'Jen', 'Bob'] }
    }
  ]
});

例のタイプ: ObjectId

ユースケース: ユーザーは、自分の製品の収益のみを表示できる必要があります。 解決策: アカウント ID で特定のアカウントへのアクセスを制限します。

const res = await FlorentineAI.ask({
  question: 'Whats the revenue of my products?',
  requiredInputs: [
    {
      keyPath: 'accountId',
      value: '507f1f77bcf86cd799439011'
    }
  ]
});

例のタイプ: Boolean

ユースケース: すべての顧客分析は、有料顧客に対してのみ実行する必要があります。 解決策: isPaidAccount で有料顧客のみへのアクセスを制限します。

const res = await FlorentineAI.ask({
  question: 'How many customers registered in the last year?',
  requiredInputs: [
    {
      keyPath: 'isPaidAccount',
      value: true
    }
  ]
});

例のタイプ: Number

ユースケース: 従業員は、特定の金額未満の支払い情報のみを表示できる必要があります。 解決策: 金額で 10,000 未満の支払いへのアクセスを制限します。

const res = await FlorentineAI.ask({
  question: 'List all payments we received.',
  requiredInputs: [
    {
      keyPath: 'amount',
      value: { $lt: 10000 }
    }
  ]
});

例のタイプ: Date

ユースケース: 財務データの分析は、特定の年のみを含む必要があります。 解決策: transactionDate で 2024 年のすべての取引へのアクセスを制限します。

const res = await FlorentineAI.ask({
  question: 'What was our revenue, profit and margin per month?',
  requiredInputs: [
    {
      keyPath: 'transactionDate',
      value: {
        $gte: '2023-01-01T00:00:00Z',
        $lt: '2024-01-01T00:00:00Z'
      }
    }
  ]
});

セッション

セッションにより、Florentine.ai はサーバー側のチャット履歴を有効にすることができます。

通常、MCP サーバーを含むクライアント/エージェントは自分自身でチャット履歴を追跡するため、セッションを追加することは必ずしも必須ではありません。

ただし、Florentine.ai がコンテキストをよりよく理解し、結果の品質を向上させるのに役立つ場合があります。

セッションの提供

sessionId を含めるには、2 つのオプションがあります。

• MCP 設定構成の SESSION_ID env 変数として（static および dynamic モードで可能）
• florentine_ask ツールの sessionId パラメータとして（dynamic モードでのみ可能）

env 変数として:

"env": {
  "SESSION_ID": "<YOUR_SESSION_ID>"
}

ツールパラメータとして:

{
  "sessionId": "<YOUR_SESSION_ID>"
}

エラー

MCP サーバーツール呼び出しからのすべてのエラーは、この一貫した JSON 構造に従います。

{
  "error": {
    "name": "FlorentineApiError",
    "statusCode": 500,
    "message": "The provided Florentine API key is invalid. You can find the key in your account settings: https://florentine.ai/settings",
    "errorCode": "INVALID_TOKEN",
    "requestId": "abc123"
  }
}

カスタムクライアントのエラーハンドリング

エラーオブジェクトは、content 配列内の文字列化された JSON として返されます。

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"name\":\"FlorentineApiError\",\"statusCode\":401,\"message\":\"The provided Florentine API key is invalid. You can find the key in your account settings: https://florentine.ai/settings\",\"errorCode\":\"INVALID_TOKEN\",\"requestId\":\"uhv99g\"}}"
    }
  ],
  "isError": true
}

text 内の JSON を解析し、カスタムクライアント/エージェント内でさまざまなエラーをハンドリングできます。

一般的なエラー