JinDaGe - toolfront MCP Details

article

README

🚀 ToolFront

AI 智能体缺乏关于您数据库的上下文信息，而团队成员则不断重写相同的查询，因为过往的工作成果往往会丢失。ToolFront 将智能体与您的数据库连接起来，并为它们提供您团队经过验证的查询模式，这样智能体和团队成员就可以相互学习，从而更快地交付成果。

✨ 主要特性

⚡ 一步设置：通过单个命令或配置，将 Cursor、GitHub Copilot 和 Claude 等编码智能体连接到您的所有数据库。
🔒 隐私至上：您的数据永远不会离开您的本地环境，并且仅通过安全的 MCP 服务器在智能体和数据库之间共享。
🧠 协作学习：您的团队使用 ToolFront 越多，您的 AI 智能体就越能理解您的数据库和查询模式。此功能需要 API 密钥。

🚀 快速开始

ToolFront 通过 MCP 服务器在您的计算机上运行，MCP 是一种安全协议，允许应用程序为大语言模型提供上下文信息。

前提条件

uv 或 Docker 用于运行 MCP 服务器（我们推荐使用 uv）
您数据库的 数据库连接 URL - 详见下文
API 密钥（可选）以激活协作学习 - 详见下文

在您的 IDE 中运行 ToolFront

首先，通过点击上面的设置按钮或导航到您 IDE 的 MCP 设置来创建一个 MCP 配置：

| IDE | 设置说明 | 文档 | |-----|-------------------|---------------| | Cursor | 设置 → Cursor 设置 → MCP 工具（或创建 .cursor/mcp.json 文件） | Cursor 文档 | | GitHub Copilot (VSCode) | Copilot 图标 → 编辑偏好设置 → Copilot Chat → MCP | GitHub Copilot 文档 | | Windsurf | 插件图标 → 插件商店 → 手动添加（或编辑 ~/.codeium/windsurf/mcp_config.json） | Windsurf 文档 | | Claude Code | 运行 claude mcp add toolfront uvx toolfront [database-urls] --api-key YOUR-API-KEY | Claude Code 文档 |

然后，使用您的数据库连接 URL 和可选的 API 密钥编辑 MCP 配置：

编辑 UV 配置

{
  // 配置文件的其余部分
  "toolfront": {
    "command": "uvx",
    "args": [
      "toolfront",
      "snowflake://user:pass@org",
      "postgresql://user:pass@host:port/db",
      # 在此处添加其他数据库 URL
      "--api-key", "YOUR-API-KEY"  // 可选
    ]
  }
}

编辑 Docker 配置

{
  // 配置文件的其余部分
  "toolfront": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "antidmg/toolfront",
      "snowflake://user:pass@org",
      "postgresql://user:pass@host:port/db",
      # 在此处添加其他数据库 URL
      "--api-key", "YOUR-API-KEY"  // 可选
    ]
  }
}

现在您已经设置好了！您现在可以向您的编码助手询问有关您数据库的问题了。

💡 使用建议

版本控制：您可以固定到特定版本以确保一致性。对于 UV，请使用 toolfront==0.1.x；对于 Docker，请使用 antidmg/toolfront:0.1.x。

在终端中运行 ToolFront

要在 IDE 之外使用 ToolFront，请直接在终端中使用您的数据库 URL 和可选的 API 密钥运行它：

# 使用 UV
uvx toolfront "snowflake://user:pass@org" "postgresql://user:pass@host:port/db" --api-key "YOUR-API-KEY"

# 使用 Docker  
docker run -i antidmg/toolfront "snowflake://user:pass@org" "postgresql://user:pass@host:port/db" --api-key "YOUR-API-KEY"

💡 使用建议

本地主机数据库：当连接到在本地主机上运行的数据库时，请在镜像名称之前添加 --network host。

协作上下文学习

数据团队不断重写相同的查询，因为过往的工作成果往往被孤立、分散或丢失。ToolFront 通过上下文学习教会 AI 智能体您的团队如何使用您的数据库。有了 ToolFront，您的智能体可以：

推理历史查询模式
记住相关的表和模式
参考您和您团队成员的工作

⚠️ 重要提示

上下文学习目前处于公开测试阶段。要申请 API 密钥，请发送电子邮件至 Esteban esteban@kruskal.ai 或加入我们的 Discord 服务器。

数据库

ToolFront 支持以下数据库：

| 数据库 | URL 格式 | 文档 | |----------|------------|---------------| | BigQuery | bigquery://{project-id}?credentials_path={path-to-service-account.json} | Google Cloud 文档 | | Databricks | databricks://token:{token}@{workspace}.cloud.databricks.com/{catalog}?http_path={warehouse-path} | Databricks 文档 | | DuckDB | duckdb://{path-to-database.duckdb} | DuckDB 文档 | | MySQL | mysql://{user}:{password}@{host}:{port}/{database} | MySQL 文档 | | PostgreSQL | postgres://{user}:{password}@{hostname}:{port}/{database-name} | PostgreSQL 文档 | | Snowflake | snowflake://{user}:{password}@{account}/{database} | Snowflake 文档 | | SQL Server | mssql://{user}:{password}@{server}:{port}/{database} 或 sqlserver://{user}:{password}@{server}:{port}/{database} | SQL Server 文档 | | SQLite | sqlite://{path-to-database.sqlite} | SQLite 文档 |

如果您没有找到您使用的数据库，请提交一个问题或拉取请求，或者在我们的 Discord 中告诉我们！

💡 使用建议

SSH 隧道：对于位于 SSH 堡垒后面的数据库，请在您的 URL 中添加 SSH 参数：postgresql://user:pass@db:5432/database?ssh_host=bastion&ssh_user=ubuntu&ssh_password=pass 或使用 ssh_key_path=/path/to/key.pem 进行密钥认证。

处理本地数据文件？ 在您的配置中添加 duckdb://:memory: 以分析本地的 Parquet、CSV、Excel 或 JSON 文件。

工具

MCP 工具是 AI 智能体可以调用的函数，用于与外部系统进行交互。ToolFront 附带了七个数据库工具：

| 工具 | 描述 | 需要 API 密钥 | |------|-------------|------------------| | test | 测试数据源连接是否正常 | ✗ | | discover | 发现并列出所有已配置的数据库和文件源 | ✗ | | scan | 使用正则表达式、模糊匹配或 TF-IDF 相似度搜索表 | ✗ | | inspect | 检查表模式，显示列名、数据类型和约束 | ✗ | | sample | 从表中检索示例行，以了解数据内容和格式 | ✗ | | query | 对数据库执行只读 SQL 查询，并进行错误处理 | ✗ | | learn | 检索相关查询或表以进行上下文学习 | ✓ |

常见问题解答

ToolFront 与其他数据库 MCP 有何不同？

ToolFront 有三个关键优势：多数据库支持、隐私至上的架构 和 协作学习。

多数据库支持：虽然一些通用的 MCP 服务器恰好支持多个数据库，但大多数数据库 MCP 一次只能与一个数据库配合使用，这迫使您为每个连接管理单独的 MCP 服务器。而 ToolFront 可以在一个地方连接到您的所有数据库。

隐私至上的架构：其他多数据库解决方案会将您的数据通过云进行路由，这会产生出口费用，并带来严重的隐私、安全和访问控制问题。而 ToolFront 将所有数据都保留在本地。

协作学习：数据库 MCP 只是公开原始的数据库操作。而 ToolFront 更进一步，它会教会您的 AI 智能体您团队工作中成功的查询模式，帮助它们学习您特定的模式和数据关系，从而随着时间的推移不断改进。

协作学习与智能体记忆有何不同？

智能体记忆为个人存储对话历史，而 ToolFront 的协作学习则会记住您团队和数据库之间的关系查询模式。

当一名团队成员查询数据库时，这些知识将可供使用 ToolFront 的其他团队成员使用。该系统会通过学习您团队的集体数据库交互，随着时间的推移变得更加智能。

协作学习期间会收集哪些数据？

使用 API 密钥时，ToolFront 仅记录您的 AI 智能体生成的查询语法及其描述。它永远不会收集您的实际数据库内容或个人信息。有关详细信息，请参阅 tools.py 中的 query 和 learn 函数。

ToolFront 如何保障我的数据安全？

本地执行：所有数据库连接和查询都在您的机器上运行
不暴露机密信息：数据库凭证永远不会与 AI 智能体共享
只读操作：只允许对数据库执行安全的只读查询
无数据传输：您的数据库内容永远不会离开您的环境
安全的 MCP 协议：智能体和数据库之间直接通信，无需第三方存储

如何排查连接问题？

直接从命令行使用您的数据库 URL 运行 uvx toolfront 或 docker run 命令。ToolFront 会在启动前自动测试所有连接，如果任何连接失败，会显示详细的错误消息。

如果您仍然遇到问题，请使用上面数据库部分中的示例仔细检查您的数据库 URL。

支持与社区

如果您在使用 ToolFront 时需要帮助，我们随时为您提供支持：

Discord：加入我们的社区服务器，获取实时帮助和参与讨论
问题反馈：在 GitHub 问题中报告错误或请求功能

贡献

有关如何为 ToolFront 做出贡献的指南，请参阅 CONTRIBUTING.md。

📄 许可证

ToolFront 根据 MIT 许可证发布。这意味着您可以自由使用、修改和分发该软件，但需遵守 MIT 许可证的条款和条件。完整的许可证文本请参阅仓库中的 LICENSE 文件。

toolfront