MCP Toolbox for Databases 的 AI Agent 上下文与风格指南：从 GEMINI.md 看开源 MCP 数据库服务器的开发规范

MCP Toolbox for Databases 的 AI Agent 上下文与风格指南：从 GEMINI.md 看开源 MCP 数据库服务器的开发规范

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox

本指南以仓库根目录的 GEMINI.md（与CLAUDE.md、AGENTS.md、.gemini/styleguide.md符号链接共享）为骨架，系统讲解 MCP Toolbox for Databases 这一 Go 语言开源 MCP 服务器项目的整体架构、开发工作流、文档构建与版本化机制，以及面向 AI Agent 的严格编码与文档规范。读完本文，你将掌握该项目"如何新增一个数据源、新增一个工具、正确撰写文档"的完整套路，并能对照源码（internal/sources、internal/tools、cmd）验证每条规范的实现依据。

项目概览：面向数据库的 MCP 服务器

MCP Toolbox for Databases是一个基于 Go 的开源项目，旨在为各类数据源与服务提供 Model Context Protocol（MCP）工具能力，让大语言模型（LLM）能够安全、高效地与数据库及其他工具交互。其核心思路可以概括为三层：

• 数据源（Source）：Postgres、BigQuery、Cloud SQL、Firestore、MongoDB 等数据库/服务的连接实现，位于 internal/sources；
• 工具（Tool）：针对每个数据源实现的具体操作，位于 internal/tools；
• MCP 原语：Prompt（internal/prompts）、Resource/Resource Template（internal/resources）、Group（internal/group）——Group 用于将工具、提示词、资源及其模板按作用域组织在一起。

在运行时层面，入口位于 cmd/root.go：根命令toolbox通过 cobra 注册了invoke、skills、serve、migrate四个子命令，并支持--disable-reload（关闭配置文件动态热加载）、--ignore-unknown-tools（跳过未知工具类型而非启动失败）、--poll-interval（配置更新轮询秒数）等持久化标志。

技术栈与关键目录

技术栈

关键目录速览

• cmd/：应用入口点（root 命令与子命令）；
• internal/sources/：各数据库源实现（如 Postgres、BigQuery）；
• internal/tools/：各源对应工具实现；
• internal/prompts/：MCP 提示词实现；
• internal/resources/：MCP 资源与资源模板实现（如 text、file 类型）；
• internal/group/：将工具、提示词、资源及资源模板按作用域分组；
• tests/：集成测试；
• evals/：评测集与评测配置，用于配合 EvalBench 评测预置工具配置；
• docs/en：项目文档，逻辑上分为四部分——documentation/（概念，Section I）、integrations/（数据库连接与工具的参考架构，Section II）、samples/（教程与示例，Section III）、reference/（CLI 信息与 FAQ，Section IV）。

开发工作流：构建、运行与测试

环境前置条件

• Go 1.23 或更高版本；
• Docker（构建容器镜像、运行部分测试）；
• 若做集成测试，需可访问必要的 Google Cloud 资源。

构建与运行

GEMINI.md 给出的核心操作序列如下：

# 1. 构建二进制 go build -o toolbox # 2. 运行服务器（默认监听 5000 端口） go run . # 3. 查看帮助 go run . --help # 4. 测试端点 curl http://127.0.0.1:5000

与这一流程相互印证的是 cmd/root.go 中的run函数：它会先加载配置（opts.LoadConfig）、初始化server.NewServer，随后根据--stdio标志选择 Stdio 传输或 HTTP 监听（支持通过--cert-file/--key-file启用 TLS）；当配置为自定义且未禁用热加载时，还会启动watchChanges协程，通过 fsnotify 监听 YAML 配置文件变化，配合 100ms 防抖（debounce）触发服务动态重载。

测试

• 单元测试：

go test -race -v ./cmd/... ./internal/...

• 集成测试（按数据源目录运行，新增源需登记到.ci/integration.cloudbuild.yaml）：

go test -race -v ./tests/alloydbpg

• Lint：

golangci-lint run --fix

开发文档：本地构建与版本化发布

本地运行文档站

文档站点基于 Hugo 构建，并借助 Pagefind 生成全文搜索索引。由于 Pagefind 依赖物理文件，hugo server单独运行时搜索栏不会有数据，必须先构建本地索引：

cd .hugo npm ci # 先生成搜索索引（development 环境用于屏蔽分析埋点） hugo --environment development && npx pagefind --site public --output-path static/pagefind # 再启动服务器 hugo server

版本化工作流

文档构建会自动生成标准 HTML，同时产出 AI 友好的文本文件（llms.txt与llms-full.txt），这也是"文档面向 Agent/LLM 可检索"设计的具体落地。仓库中存在 6 套部署工作流，并行部署到 GitHub Pages 与 Cloudflare Pages，所有部署工作流都会自动执行npx pagefind --site public生成按版本隔离的搜索索引：

1. 开发中文档部署：合并到main的提交部署到/dev/路径，默认版本号为Dev；
2. 版本化文档部署：新的 GitHub Release 部署到/<version>/与根路径，release 标签自动注入为文档版本。注意：合并 release PR 前，开发者必须手动将新版本加入hugo.toml的[[params.versions]]下拉数组；
3. 旧版本文档重建：手动工作流，通过在 GitHub Actions UI 显式传入目标 tag 来重建旧版本。

编码规范：命名、分支与提交

工具命名（Tool Naming）

命名规则非常明确，且直接对应工具注册时的type字符串：

• Tool Name（工具名）：snake_case，例如list_collections、run_query。不得包含产品名（避免firestore_list_collections这类冗余前缀）；
• Tool Type（工具类型）：kebab-case，例如firestore-list-collections。必须包含产品名。

这一点在源码中有清晰印证：internal/tools/postgres/postgressql/postgressql.go 中const resourceType string = "postgres-sql"，并在init()里调用tools.Register(resourceType, newConfig)完成注册；工具名则由 YAML 配置中的name字段决定（如execute_sql）。

分支与提交规范

• 分支命名：feat/、fix/、docs/、chore/前缀，例如feat/add-gemini-md；
• 提交信息：遵循 Conventional Commits 格式<type>(<scope>): <description>，例如feat(source/postgres): add new connection option，支持的类型有feat、fix、docs、chore、test、ci、refactor、revert、style。

PR 标题与类型

PR 标题格式：<type>[optional scope]: <description>。类型与版本变更影响的关系如下表：

Scope 约定

针对特定源或工具提交的 PR必须附加源或工具名作为 scope，格式为<type>/<kind>：

• source/postgres、source/cloudsql-mysql
• tool/mssql-sql、tool/list-tables
• auth/google

多 scope 规则：同类型多 scope 用逗号分隔，如feat(source/postgres,source/alloydbpg): ...；跨类型（如同时新增数据源与工具）则省略类型前缀，如feat(new-db): adding support for new-db source and tool。

PR 描述模板

每个 PR 必须包含：1. Description（变更的问题/功能、影响与方案摘要）、2. PR Checklist（提交前开 issue、人工审阅 diff、测试与 lint 通过、源码变更不降低覆盖率、必要时更新文档、破坏性变更加!）、3. Issue Reference（格式Fixes #<issue_number>）。

新增功能：数据源与工具的完整实现路径

新增一个数据源

1. 创建目录internal/sources/<newdb>；
2. 在internal/sources/<newdb>/<newdb>.go中定义Config与Source结构体；
3. 实现SourceConfig接口（SourceConfigType、Initialize）；
4. 实现Source接口（SourceType、ToConfig）；
5. 实现init()完成源注册；
6. 在internal/sources/<newdb>/<newdb>_test.go添加单元测试。

源码层面的注册机制位于 internal/sources/sources.go：sourceRegistry是一个map[string]SourceConfigFactory，Register在类型重复时返回false拒绝覆盖，DecodeConfig则按类型查找工厂并解码配置，未知类型会返回unknown source type错误。Source接口还要求IsReadOnly()，这与工具层"只读源自动抑制写工具"的机制联动（见下文）。

新增一个工具

这是 GEMINI.md 着墨最多的部分，也是理解整个工具体系的钥匙：

1. 创建目录internal/tools/<newdb>/<toolname>；
2. 定义Config结构体，必须内嵌tools.ConfigBase（带yaml:",inline"），以自动获得共享的name、description、authRequired、scopesRequired字段及其 getter——只添加工具特有字段，不要重复声明共享字段；
3. 定义Tool结构体，必须内嵌tools.BaseTool[Config]，不要重新声明GetName、GetDescription、Manifest、GetParameters、Authorized、RequiresClientAuthorization、GetAuthTokenHeaderName、EmbedParams等样板方法，它们已由BaseTool继承；
4. 实现ToolConfig接口（ToolConfigType、Initialize）。在Initialize中通过tools.NewBaseTool(cfg, annotations, manifest, staticParameters)构造工具；
5. 只实现BaseTool未提供的方法：Invoke与ToConfig。仅当行为与默认不同时才覆写继承方法（如EmbedParams、RequiresClientAuthorization、GetAuthTokenHeaderName）；
6. 实现init()完成工具注册；
7. 添加单元测试。

权威参考实现：internal/tools/postgres/postgressql/postgressql.go。剖析该文件可以看到完整范式：

• 工具类型常量"postgres-sql"与init()注册（L31-L37）；
• Config内嵌tools.ConfigBase并声明type、source、statement、parameters、templateParameters、annotations等特有字段（L52-L60）；
• Initialize中检查description必填、合并模板参数与普通参数，并默认采用NewDestructiveAnnotations（写型工具注解，L68-L85）；
• Tool内嵌tools.BaseTool[Config]，仅实现Invoke、EmbedParams、GetSourceName、ToConfig、ValidateSource（L89-L133）。

与之对应的底层机制，在 internal/tools/tools.go 中：

• 工具注册表toolRegistry与Register/DecodeConfig（L36-L66）；
• ConfigBase统一承载共享字段（L204-L226）；
• BaseTool[T]提供Manifest、StaticManifest、Authorized、EmbedParams等默认实现，NewBaseTool还会扫描静态参数中的secure参数设置hasSecureParams（L231-L299）；
• 注解体系NewReadOnlyAnnotations/NewDestructiveAnnotations/NewWriteAnnotations（L83-L104）以及ShouldSuppress：当数据源处于只读模式且工具的ReadOnlyHint显式为false时，写型工具会被自动抑制，避免 Agent 在只读源上执行写操作（L306-L330）。

预置配置（Prebuilt Configs）

仓库为各数据源内置了开箱即用的 YAML 配置，通过 Goembed打包进二进制，见 internal/prebuiltconfigs/prebuiltconfigs.go。以 internal/prebuiltconfigs/tools/postgres.yaml 为例，一个文件内用---分隔多个文档块，按kind区分：

• kind: source：定义名为postgresql-source的源，类型postgres，支持${POSTGRES_HOST:localhost}形式的环境变量插值并带默认值；
• kind: tool：声明execute_sql（类型postgres-execute-sql）、list_tables、list_active_queries等原生工具，以及大量type: postgres-sql的 SQL 化工具——它们通过statement直接定义查询语句，用templateParameters实现参数化模板（如get_query_plan的EXPLAIN (FORMAT JSON) {{.query}};），这正是上文postgressql工具类型的实战用法；
• kind: toolset：将工具按场景聚合，例如data（增删查改类）、monitor（list_query_stats、get_query_plan等）、health（list_top_bloated_tables、list_invalid_indexes等）、replication等。

文档规范：CI 强制的集成文档结构

仓库对文档采用 CI 强制校验（违规会直接导致构建失败），规则极其严格，面向"文档即代码、可机器校验"的工程化目标。

通用原则

• 新增源文档：写到docs/en/integrations/<source_name>/source.md，且根级_index.md只能包含 frontmatter，不允许任何正文；
• 新增原生工具文档：写到docs/en/integrations/<source_name>/tools/<tool_name>.md，tools/_index.md同样只能有 frontmatter；
• 新增资源文档：写到docs/en/documentation/configuration/resources/<resource_type>.md；
• 新增集成示例：加到docs/en/integrations/<source_name>/samples/，samples/_index.md只能有 frontmatter；
• 工具继承（共享工具）：使用底层引擎工具的托管数据库（如 Cloud SQL Postgres 复用 Postgres 工具）通过在tools/_index.md的 frontmatter 中配置shared_tools参数映射继承工具，该文件同样只能含 frontmatter；
• 新增顶级目录：若为文档站添加全新顶级分区，必须同步更新.hugo/layouts/index.llms.txt与.hugo/layouts/index.llms-full.txt中的 "Diátaxis Narrative Framework" 段落，保持 AI 上下文与站点结构一致。

源页面约束（integrations/**/source.md）

1. 文件必须命名为source.md，_index.md仅作空结构目录包装（只有 YAML frontmatter）；
2. linkTitle必须恒为Source；
3. frontmatter 的title必须以 "Source" 结尾（如title: "Postgres Source"）；
4. 正文禁止出现 H1（#）标题；
5. H2 必须按固定顺序：## About（必需）→## Available Tools（可选）→## Requirements（可选）→## Example（必需）→## Reference（必需）→## Advanced Usage（可选）→## Troubleshooting（可选）→## Additional Resources（可选）；
6. 若生成## Available Tools段落，其下必须包含{{< list-tools >}}shortcode。

工具页面约束（integrations/**/tools/*.md）

1. 所有原生工具必须位于嵌套的tools/子目录，且该目录须含只含 frontmatter 的_index.md；
2. 正文禁止 H1；
3. H2 固定顺序：## About（必需）→## Compatible Sources（可选）→## Requirements（可选）→## Parameters（可选）→## Example（必需）→## Output Format（可选）→## Reference（可选）→## Advanced Usage（可选）→## Troubleshooting（可选）→## Additional Resources（可选）；
4. 生成## Compatible Sources时必须包含{{< compatible-sources >}}shortcode；
5. title必须与工具 kebab-case 名称完全一致（如title: "arcadedb-execute-sql"），不要追加 "Tool" 字样（区别于以 "Source" 结尾的源页面）。

示例架构与维护约束

示例文件在 UI 的 Samples 区聚合展示，但物理文件按作用域分散存放：

1. 快速入门：docs/en/documentation/getting-started/；
2. 集成专属示例：docs/en/integrations/<source_name>/samples/；
3. 通用/跨类示例：docs/en/samples/。

维护规则方面：frontmatter 必须包含sample_filters且使用严格枚举——以.hugo/data/filters.yaml为准获取允许的数据源、语言、框架与类别清单；新增过滤器时用Title Case（每个单词首字母大写、空格分隔），不要用 snake_case 或小写。同时必须设置is_sample: true防止示例被 Samples Gallery 过滤掉。

预置配置文档与资源约束

• 预置配置文档统一放在prebuilt-configs/目录，因为主索引页documentation/configuration/prebuilt-configs/_index.md使用{{< list-prebuilt-configs >}}shortcode，只识别命名为prebuilt-configs的目录；
• 撰写前务必先核对 internal/prebuiltconfigs/tools 中数据源的kind，再选择对应的集成目录；
• docs/目录下禁止添加超过 24MB 的文件。

给 Agent 与开发者的行动清单

对照 GEMINI.md 与本文梳理的源码证据，在仓库中工作的 AI Agent 与开发者应遵循如下要点：

1. 先看注册机制再动手：新增源或工具前，先阅读 internal/sources/sources.go 与 internal/tools/tools.go 中的Register/DecodeConfig实现，理解"类型字符串 → 工厂函数 → 配置解码"的注册链路；
2. 复用而非重写：新工具一律内嵌tools.ConfigBase与tools.BaseTool[Config]，参考 postgressql.go 这个范式文件，只实现Invoke与ToConfig；
3. 命名即契约：工具名 snake_case 且不含产品名，工具类型 kebab-case 且必含产品名；提交、分支、PR 严格遵循 Conventional Commits 与 scope 约定；
4. 文档遵守 CI 顺序：source/tool 页面按规定的 H2 顺序编写、_index.md只放 frontmatter、示例配置sample_filters枚举与is_sample: true，避免破坏文档构建；
5. 留意文档站特性：本地开发先hugo --environment development && npx pagefind --site public --output-path static/pagefind再hugo server；版本发布记得手动更新hugo.toml的[[params.versions]]。

【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox