主控节点

Name: 主控节点
Author: florentine-ai

作者：florentine-ai5 星标更新：2025-10-07

安装使用来源：spider==github.com

项目介绍

Florentine.ai MCP Server - 与您的MongoDB数据对话

Florentine.ai模型上下文协议（MCP）服务器允许您将自然语言查询功能直接集成到自定义AI代理或AI桌面应用程序中。

问题由AI代理转发给MCP服务器，转换成MongoDB聚合操作，并将聚合结果返回给代理进行进一步处理。

此外，还有一些额外的功能，例如：

安全的数据隔离用于多租户使用
自动模式探索
语义向量搜索/RAG支持，带有自动嵌入创建
高级查找支持
排除键

注意： 如果您正在寻找我们的API，请在这里查看。

内容

前提条件
安装
可用工具
参数
认证
连接您的LLM账户
- 选项1：在您的账户中保存LLM密钥（推荐）
- 选项2：在MCP服务器配置环境变量中提供LLM密钥
集成模式
- 静态模式
  - 环境变量
- 动态模式
  - 示例分解
  - florentine_ask 参数
返回类型
- 提供返回类型
- 返回类型配置
多租户使用的安全数据隔离
会话
- 提供会话
错误
- 自定义客户端错误处理
- 常见错误

前提条件

Node.js >= v18.0.0
一个Florentine.ai账户（免费注册）
已连接的数据库以及至少一个已分析并激活的集合
一个Florentine.ai API密钥（您可以在账户仪表板找到）

安装

有关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>"
      }
    }
  }
}

可用工具

florentine_list_collections --> 列出所有当前可查询的活动集合。包括描述、键和值类型。
florentine_ask --> 接收一个问题并返回一个聚合、聚合结果或答案（取决于returnTypes设置）。

参数

变量	必需	允许的值	描述
`--mode`	是	`static`, `dynamic`	`static`（用于现有的外部MCP客户端，如Claude Desktop）或`dynamic`（用于自己的自定义MCP客户端）。参见集成模式部分。
`--debug`	否	`true`	启用日志记录到外部文件。如果设置了此选项，则需要同时设置`--logpath`。
`--logpath`	否	绝对日志文件路径	日志文件的路径。如果设置了此选项，则需要同时设置`--debug`。

认证

Florentine.ai MCP服务器使用API密钥来验证请求。您可以在账户仪表板查看和管理您的API密钥。该密钥必须作为ENV变量添加到MCP服务器的配置设置中：

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

连接您的LLM账户

Florentine.ai采用自带密钥模型，因此您需要在MCP请求中提供您的LLM API密钥（OpenAI、Google、Anthropic、Deepseek）。

您有两种方式可以添加您的LLM API密钥：

选项1：在您的账户中保存LLM密钥（推荐）

连接到您的LLM提供商最简单的方法是在Florentine.ai仪表板中保存您的LLM API密钥。

添加您的API密钥
选择您的LLM提供商（OpenAI、Deepseek、Google或Anthropic）
点击保存

添加您的LLM密钥

选项2：在MCP服务器配置环境变量中提供LLM密钥

如果您不希望将密钥存储在您的Florentine.ai账户中，或者想要使用多个LLM密钥，您可以在MCP服务器配置中传递密钥：

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

参数	描述	允许的值
`LLM_SERVICE`	指定要使用的LLM提供商。	`openai`,`google`,`anthropic` 或 `deepseek`
`LLM_KEY`	您提供的LLM服务的API密钥。	有效的API密钥字符串

注意： 如果您在MCP服务器配置的环境变量中提供了LLM_KEY，它将覆盖您账户中存储的任何密钥。

集成模式

您需要在MCP服务器配置的args数组中设置操作模式为static或dynamic：

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

静态模式

静态模式应在将Florentine.ai集成到现有的外部MCP客户端时使用，例如像Claude Desktop或Dive AI这样的MCP就绪桌面应用。

在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\"}]"
      }
    }
  }
}

环境变量

变量	必需	类型	描述
`FLORENTINE_TOKEN`	是	字符串	您的Florentine.ai API密钥，从仪表板复制。
`SESSION_ID`	否	字符串	客户端的会话ID。用于服务器端聊天历史记录。参见会话部分。
`LLM_SERVICE`	否	字符串	指定要使用的LLM提供商。仅在未在您的Florentine.ai账户中保存LLM密钥时需要。参见连接您的LLM账户部分。
`LLM_KEY`	否	字符串	您提供的LLM服务的API密钥。仅在未在您的Florentine.ai账户中保存LLM密钥时需要。参见连接您的LLM账户部分。
`RETURN_TYPES`	否	字符串化的JSON	`florentine_ask`工具调用的返回类型。参见返回类型部分。
`REQUIRED_INPUTS`	否	字符串化的JSON	必需的输入。参见必需的输入部分。

动态模式

动态模式应在将Florentine.ai集成到您自己的自定义MCP客户端时使用。

在动态模式下，您可以直接将所有参数（如返回类型、必需的输入等）传递给florentine_ask工具。这意味着您可以动态注入每个请求的个别参数（即用户ID）。

为了能够动态传递值，您需要在自定义客户端/代理中重写florentine_ask工具方法。请参阅以下使用标准@modelcontextprotocolTypeScript SDK的示例：

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

// 创建MCP客户端实例
const mcpClient = new Client({
  name: 'florentine',
  version: '1.0.0'
});

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

// 连接MCP客户端
await mcpClient.connect(mcpSetupConfig);

// 将原始callTool函数保存到变量
const originalCallTool = mcpClient.callTool;

// 动态获取并添加florentine_ask参数（模拟实现）
const enhanceAskParameters = async ({ question }: { question: string }) => {
  return {
    question,
    // 模拟用户数据获取（例如returnTypes、requiredInputs等），
    // 替换为实际实现
    ...(await fetchUserSpecificData({ userId: '<USER_ID>' }))
  };
};

// 使用自定义实现重写callTool函数
// 使用动态注入的参数增强florentine_ask方法
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: '谁赢得了上一场比赛？'
  }
});

示例分解

让我们详细看看上面示例中的内容。

首先，我们创建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;

然后，我们创建一个enhanceAskParameters函数，该函数接收一个问题作为输入，获取用户的附加参数（例如returnTypes、requiredInputs等），并返回合并的参数：

const enhanceAskParameters = async ({ question }: { question: string }) => {
  return {
    question,
    // 示例函数，获取附加数据，例如用户特定的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: '谁赢得了上一场比赛？'
  }
});

重要： 确保在使用动态模式时始终重写florentine_ask实现。如果您不重写它，您的客户端/代理将直接使用MCP服务器端的florentine_ask工具实现，包含所有附加参数。因此，客户端/代理将自行决定如何填充returnTypes、requiredInputs等值。这将导致意外行为，并导致错误和错误的结果。

florentine_ask 参数

变量	必需	类型	描述
`sessionId`	否	字符串	客户端的会话ID。用于服务器端聊天历史记录。参见会话部分。
`returnTypes`	否	`Array<String>`	`florentine_ask`工具调用的返回类型。参见返回类型部分。
`requiredInputs`	否	`Array<Object>`	必需的输入。参见必需的输入部分。

返回类型

默认情况下，florentine_ask工具返回提供的问题的聚合结果。然而，您可以选择以下三个步骤中的任意组合：

聚合生成：问题被转换为MongoDB聚合查询。
查询执行：聚合使用您提供的连接字符串在数据库上运行。
答案生成：结构化结果被转换为自然语言答案。

提供返回类型

您有两种方式包含returnTypes数组：

在您的MCP设置配置中的RETURN_TYPES环境变量（可能在static和dynamic模式下）
作为florentine_ask工具的returnTypes参数（仅在dynamic模式下可能）

作为环境变量，您以字符串化的JSON数组形式提供值：

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

作为工具参数，您以数组形式提供值：

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

返回类型配置

您可以通过指定returnTypes数组中的任意组合来选择您想要返回的这些步骤：

`returnTypes` 值	描述	响应中的预期键
`"aggregation"`	返回生成的MongoDB聚合管道，使用的数据库和集合以及AI对聚合能否正确回答问题的信心评分（范围从0到10）。	`confidence`, `database`, `collection`, `aggregation`
`"result"`	返回执行聚合后得到的原始查询结果。	`result`
`"answer"`	根据执行聚合后得到的结果返回自然语言响应。	`answer`

多租户使用的安全数据隔离

您可以通过确保聚合管道根据提供的值过滤数据来启用安全的数据隔离，我们称之为必需的输入。

这些值由Florentine.ai转换层在LLM生成聚合之后添加到管道中。因此，Florentine.ai可以保证每个用户只能检索其有权访问的数据。

键在您的账户中定义为必需的输入，请参阅官方文档中的相关章节了解如何操作。

提供必需的输入

您有两种方式包含requiredInputs数组：

在您的MCP设置配置中的REQUIRED_INPUTS环境变量（可能在static和dynamic模式下）
作为florentine_ask工具的requiredInputs参数（仅在dynamic模式下可能）

作为环境变量，您以字符串化的JSON数组形式提供值：

"env": {
  "REQUIRED_INPUTS": "[{\"keyPath\":\"userId\",\"