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 ProtocolMCP工具能力让大语言模型LLM能够安全、高效地与数据库及其他工具交互。其核心思路可以概括为三层数据源SourcePostgres、BigQuery、Cloud SQL、Firestore、MongoDB 等数据库/服务的连接实现位于 internal/sources工具Tool针对每个数据源实现的具体操作位于 internal/toolsMCP 原语Promptinternal/prompts、Resource/Resource Templateinternal/resources、Groupinternal/group——Group 用于将工具、提示词、资源及其模板按作用域组织在一起。在运行时层面入口位于 cmd/root.go根命令toolbox通过 cobra 注册了invoke、skills、serve、migrate四个子命令并支持--disable-reload关闭配置文件动态热加载、--ignore-unknown-tools跳过未知工具类型而非启动失败、--poll-interval配置更新轮询秒数等持久化标志。技术栈与关键目录技术栈类别选型说明语言Go1.23所有运行时实现文档HugoExtended Edition v0.146.0文档站构建容器化Docker镜像构建与部分测试CI/CDGitHub Actions、Google Cloud Build自动化流水线Lintinggolangci-lint代码静态检查关键目录速览cmd/应用入口点root 命令与子命令internal/sources/各数据库源实现如 Postgres、BigQueryinternal/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 信息与 FAQSection 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.yamlgo test -race -v ./tests/alloydbpgLintgolangci-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生成按版本隔离的搜索索引开发中文档部署合并到main的提交部署到/dev/路径默认版本号为Dev版本化文档部署新的 GitHub Release 部署到/version/与根路径release 标签自动注入为文档版本。注意合并 release PR 前开发者必须手动将新版本加入hugo.toml的[[params.versions]]下拉数组旧版本文档重建手动工作流通过在 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。类型与版本变更影响的关系如下表Type含义影响的版本号BREAKING CHANGE任何此类型或带!的变更均为破坏性 API 变更如fix!: description、feat!: descriptionmajorfeat新增功能minorfix修复 bug 或拼写错误patchciCI 配置或脚本变更n/adocs文档相关变更n/achore其他零散小任务n/aperf改进性能的源码变更n/arefactor重构源码但不破坏测试、不减少覆盖率n/arevert回滚他人提交n/astyle仅格式化/空白调整的源码变更n/atest测试文件变更n/abuild项目构建与依赖相关变更n/aScope 约定针对特定源或工具提交的 PR必须附加源或工具名作为 scope格式为type/kindsource/postgres、source/cloudsql-mysqltool/mssql-sql、tool/list-tablesauth/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。新增功能数据源与工具的完整实现路径新增一个数据源创建目录internal/sources/newdb在internal/sources/newdb/newdb.go中定义Config与Source结构体实现SourceConfig接口SourceConfigType、Initialize实现Source接口SourceType、ToConfig实现init()完成源注册在internal/sources/newdb/newdb_test.go添加单元测试。源码层面的注册机制位于 internal/sources/sources.gosourceRegistry是一个map[string]SourceConfigFactoryRegister在类型重复时返回false拒绝覆盖DecodeConfig则按类型查找工厂并解码配置未知类型会返回unknown source type错误。Source接口还要求IsReadOnly()这与工具层只读源自动抑制写工具的机制联动见下文。新增一个工具这是 GEMINI.md 着墨最多的部分也是理解整个工具体系的钥匙创建目录internal/tools/newdb/toolname定义Config结构体必须内嵌tools.ConfigBase带yaml:,inline以自动获得共享的name、description、authRequired、scopesRequired字段及其 getter——只添加工具特有字段不要重复声明共享字段定义Tool结构体必须内嵌tools.BaseTool[Config]不要重新声明GetName、GetDescription、Manifest、GetParameters、Authorized、RequiresClientAuthorization、GetAuthTokenHeaderName、EmbedParams等样板方法它们已由BaseTool继承实现ToolConfig接口ToolConfigType、Initialize。在Initialize中通过tools.NewBaseTool(cfg, annotations, manifest, staticParameters)构造工具只实现BaseTool未提供的方法Invoke与ToConfig。仅当行为与默认不同时才覆写继承方法如EmbedParams、RequiresClientAuthorization、GetAuthTokenHeaderName实现init()完成工具注册添加单元测试。权威参考实现internal/tools/postgres/postgressql/postgressql.go。剖析该文件可以看到完整范式工具类型常量postgres-sql与init()注册L31-L37Config内嵌tools.ConfigBase并声明type、source、statement、parameters、templateParameters、annotations等特有字段L52-L60Initialize中检查description必填、合并模板参数与普通参数并默认采用NewDestructiveAnnotations写型工具注解L68-L85Tool内嵌tools.BaseTool[Config]仅实现Invoke、EmbedParams、GetSourceName、ToConfig、ValidateSourceL89-L133。与之对应的底层机制在 internal/tools/tools.go 中工具注册表toolRegistry与Register/DecodeConfigL36-L66ConfigBase统一承载共享字段L204-L226BaseTool[T]提供Manifest、StaticManifest、Authorized、EmbedParams等默认实现NewBaseTool还会扫描静态参数中的secure参数设置hasSecureParamsL231-L299注解体系NewReadOnlyAnnotations/NewDestructiveAnnotations/NewWriteAnnotationsL83-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增删查改类、monitorlist_query_stats、get_query_plan等、healthlist_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.mdtools/_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文件必须命名为source.md_index.md仅作空结构目录包装只有 YAML frontmatterlinkTitle必须恒为Sourcefrontmatter 的title必须以 Source 结尾如title: Postgres Source正文禁止出现 H1#标题H2 必须按固定顺序## About必需→## Available Tools可选→## Requirements可选→## Example必需→## Reference必需→## Advanced Usage可选→## Troubleshooting可选→## Additional Resources可选若生成## Available Tools段落其下必须包含{{ list-tools }}shortcode。工具页面约束integrations/**/tools/*.md所有原生工具必须位于嵌套的tools/子目录且该目录须含只含 frontmatter 的_index.md正文禁止 H1H2 固定顺序## About必需→## Compatible Sources可选→## Requirements可选→## Parameters可选→## Example必需→## Output Format可选→## Reference可选→## Advanced Usage可选→## Troubleshooting可选→## Additional Resources可选生成## Compatible Sources时必须包含{{ compatible-sources }}shortcodetitle必须与工具 kebab-case 名称完全一致如title: arcadedb-execute-sql不要追加 Tool 字样区别于以 Source 结尾的源页面。示例架构与维护约束示例文件在 UI 的 Samples 区聚合展示但物理文件按作用域分散存放快速入门docs/en/documentation/getting-started/集成专属示例docs/en/integrations/source_name/samples/通用/跨类示例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 与开发者应遵循如下要点先看注册机制再动手新增源或工具前先阅读 internal/sources/sources.go 与 internal/tools/tools.go 中的Register/DecodeConfig实现理解类型字符串 → 工厂函数 → 配置解码的注册链路复用而非重写新工具一律内嵌tools.ConfigBase与tools.BaseTool[Config]参考 postgressql.go 这个范式文件只实现Invoke与ToConfig命名即契约工具名 snake_case 且不含产品名工具类型 kebab-case 且必含产品名提交、分支、PR 严格遵循 Conventional Commits 与 scope 约定文档遵守 CI 顺序source/tool 页面按规定的 H2 顺序编写、_index.md只放 frontmatter、示例配置sample_filters枚举与is_sample: true避免破坏文档构建留意文档站特性本地开发先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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 ProtocolMCP工具能力让大语言模型LLM能够安全、高效地与数据库及其他工具交互。其核心思路可以概括为三层数据源SourcePostgres、BigQuery、Cloud SQL、Firestore、MongoDB 等数据库/服务的连接实现位于 internal/sources工具Tool针对每个数据源实现的具体操作位于 internal/toolsMCP 原语Promptinternal/prompts、Resource/Resource Templateinternal/resources、Groupinternal/group——Group 用于将工具、提示词、资源及其模板按作用域组织在一起。在运行时层面入口位于 cmd/root.go根命令toolbox通过 cobra 注册了invoke、skills、serve、migrate四个子命令并支持--disable-reload关闭配置文件动态热加载、--ignore-unknown-tools跳过未知工具类型而非启动失败、--poll-interval配置更新轮询秒数等持久化标志。技术栈与关键目录技术栈类别选型说明语言Go1.23所有运行时实现文档HugoExtended Edition v0.146.0文档站构建容器化Docker镜像构建与部分测试CI/CDGitHub Actions、Google Cloud Build自动化流水线Lintinggolangci-lint代码静态检查关键目录速览cmd/应用入口点root 命令与子命令internal/sources/各数据库源实现如 Postgres、BigQueryinternal/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 信息与 FAQSection 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.yamlgo test -race -v ./tests/alloydbpgLintgolangci-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生成按版本隔离的搜索索引开发中文档部署合并到main的提交部署到/dev/路径默认版本号为Dev版本化文档部署新的 GitHub Release 部署到/version/与根路径release 标签自动注入为文档版本。注意合并 release PR 前开发者必须手动将新版本加入hugo.toml的[[params.versions]]下拉数组旧版本文档重建手动工作流通过在 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。类型与版本变更影响的关系如下表Type含义影响的版本号BREAKING CHANGE任何此类型或带!的变更均为破坏性 API 变更如fix!: description、feat!: descriptionmajorfeat新增功能minorfix修复 bug 或拼写错误patchciCI 配置或脚本变更n/adocs文档相关变更n/achore其他零散小任务n/aperf改进性能的源码变更n/arefactor重构源码但不破坏测试、不减少覆盖率n/arevert回滚他人提交n/astyle仅格式化/空白调整的源码变更n/atest测试文件变更n/abuild项目构建与依赖相关变更n/aScope 约定针对特定源或工具提交的 PR必须附加源或工具名作为 scope格式为type/kindsource/postgres、source/cloudsql-mysqltool/mssql-sql、tool/list-tablesauth/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。新增功能数据源与工具的完整实现路径新增一个数据源创建目录internal/sources/newdb在internal/sources/newdb/newdb.go中定义Config与Source结构体实现SourceConfig接口SourceConfigType、Initialize实现Source接口SourceType、ToConfig实现init()完成源注册在internal/sources/newdb/newdb_test.go添加单元测试。源码层面的注册机制位于 internal/sources/sources.gosourceRegistry是一个map[string]SourceConfigFactoryRegister在类型重复时返回false拒绝覆盖DecodeConfig则按类型查找工厂并解码配置未知类型会返回unknown source type错误。Source接口还要求IsReadOnly()这与工具层只读源自动抑制写工具的机制联动见下文。新增一个工具这是 GEMINI.md 着墨最多的部分也是理解整个工具体系的钥匙创建目录internal/tools/newdb/toolname定义Config结构体必须内嵌tools.ConfigBase带yaml:,inline以自动获得共享的name、description、authRequired、scopesRequired字段及其 getter——只添加工具特有字段不要重复声明共享字段定义Tool结构体必须内嵌tools.BaseTool[Config]不要重新声明GetName、GetDescription、Manifest、GetParameters、Authorized、RequiresClientAuthorization、GetAuthTokenHeaderName、EmbedParams等样板方法它们已由BaseTool继承实现ToolConfig接口ToolConfigType、Initialize。在Initialize中通过tools.NewBaseTool(cfg, annotations, manifest, staticParameters)构造工具只实现BaseTool未提供的方法Invoke与ToConfig。仅当行为与默认不同时才覆写继承方法如EmbedParams、RequiresClientAuthorization、GetAuthTokenHeaderName实现init()完成工具注册添加单元测试。权威参考实现internal/tools/postgres/postgressql/postgressql.go。剖析该文件可以看到完整范式工具类型常量postgres-sql与init()注册L31-L37Config内嵌tools.ConfigBase并声明type、source、statement、parameters、templateParameters、annotations等特有字段L52-L60Initialize中检查description必填、合并模板参数与普通参数并默认采用NewDestructiveAnnotations写型工具注解L68-L85Tool内嵌tools.BaseTool[Config]仅实现Invoke、EmbedParams、GetSourceName、ToConfig、ValidateSourceL89-L133。与之对应的底层机制在 internal/tools/tools.go 中工具注册表toolRegistry与Register/DecodeConfigL36-L66ConfigBase统一承载共享字段L204-L226BaseTool[T]提供Manifest、StaticManifest、Authorized、EmbedParams等默认实现NewBaseTool还会扫描静态参数中的secure参数设置hasSecureParamsL231-L299注解体系NewReadOnlyAnnotations/NewDestructiveAnnotations/NewWriteAnnotationsL83-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增删查改类、monitorlist_query_stats、get_query_plan等、healthlist_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.mdtools/_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文件必须命名为source.md_index.md仅作空结构目录包装只有 YAML frontmatterlinkTitle必须恒为Sourcefrontmatter 的title必须以 Source 结尾如title: Postgres Source正文禁止出现 H1#标题H2 必须按固定顺序## About必需→## Available Tools可选→## Requirements可选→## Example必需→## Reference必需→## Advanced Usage可选→## Troubleshooting可选→## Additional Resources可选若生成## Available Tools段落其下必须包含{{ list-tools }}shortcode。工具页面约束integrations/**/tools/*.md所有原生工具必须位于嵌套的tools/子目录且该目录须含只含 frontmatter 的_index.md正文禁止 H1H2 固定顺序## About必需→## Compatible Sources可选→## Requirements可选→## Parameters可选→## Example必需→## Output Format可选→## Reference可选→## Advanced Usage可选→## Troubleshooting可选→## Additional Resources可选生成## Compatible Sources时必须包含{{ compatible-sources }}shortcodetitle必须与工具 kebab-case 名称完全一致如title: arcadedb-execute-sql不要追加 Tool 字样区别于以 Source 结尾的源页面。示例架构与维护约束示例文件在 UI 的 Samples 区聚合展示但物理文件按作用域分散存放快速入门docs/en/documentation/getting-started/集成专属示例docs/en/integrations/source_name/samples/通用/跨类示例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 与开发者应遵循如下要点先看注册机制再动手新增源或工具前先阅读 internal/sources/sources.go 与 internal/tools/tools.go 中的Register/DecodeConfig实现理解类型字符串 → 工厂函数 → 配置解码的注册链路复用而非重写新工具一律内嵌tools.ConfigBase与tools.BaseTool[Config]参考 postgressql.go 这个范式文件只实现Invoke与ToConfig命名即契约工具名 snake_case 且不含产品名工具类型 kebab-case 且必含产品名提交、分支、PR 严格遵循 Conventional Commits 与 scope 约定文档遵守 CI 顺序source/tool 页面按规定的 H2 顺序编写、_index.md只放 frontmatter、示例配置sample_filters枚举与is_sample: true避免破坏文档构建留意文档站特性本地开发先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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考