企业官网建设流程全解析

MCP Toolbox for Databases：用 vector-assist-delete-spec 工具删除 Vector Assist 向量规格

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

在 MCP Toolbox for Databases（开源的数据库 MCP 服务器）中，vector-assist-delete-spec是 Cloud SQL for PostgreSQL 集成里 Vector Assist 工具族的一员，负责按spec_id删除一个已存在的向量规格及其关联元数据。本文以官方工具文档为骨架，结合仓库中的工具实现、预置配置与集成测试，完整讲解该工具的参数定义、YAML 配置方式、底层 SQL 调用链与验证手段，读完你即可在自己的 Toolbox 配置中正确注册该破坏性工具，并理解它从 MCP 调用到 PostgreSQLvector_assist.delete_spec函数执行的完整路径。

工具定位：Vector Assist 规格生命周期中的“删除”环节

vector-assist-delete-spec工具的核心职责只有一件事：使用唯一的spec_id删除一个已存在的向量规格（vector specification）。官方文档给出了明确的使用边界：

• 当用户明确请求删除、移除或清理一个“在 Vector Assist 工具语境下创建的”向量规格时，才应使用此工具；
• 底层实现是连接到目标数据库，执行 PostgreSQL 的vector_assist.delete_spec函数。

Vector Assist 是 Cloud SQL for PostgreSQL 提供的一套向量工作负载管理能力。本工具不是孤立存在的，它与同目录下的其他工具共同构成一个完整的规格生命周期闭环（各工具的文档见 vector-assist-define-spec、vector-assist-modify-spec、vector-assist-apply-spec、vector-assist-get-spec、vector-assist-list-specs、vector-assist-generate-query 与 vector-assist-improve-query-recall）：

1. define：针对目标表定义向量规格（索引类型、量化、目标召回率等约束）；
2. modify：调整已有规格的约束条件；
3. apply：将规格的推荐方案实际应用到数据库；
4. get / list：查询单个或多个规格；
5. generate / improve：基于规格生成向量检索 SQL、调优召回率；
6. delete：清理不再需要的规格，即本文主角。

前置要求与兼容数据源

数据库侧：必须安装 vector_assist 扩展

官方文档给出了明确提示：

确保目标 PostgreSQL 数据库已安装所需的vector_assist扩展，否则该工具无法成功执行。

仓库中的集成测试也印证了这一点：tests/cloudsqlpg/cloud_sql_pg_vectorassist_test.go 在搭建测试环境时会执行CREATE EXTENSION IF NOT EXISTS vector_assist（setupVectorAssistTable函数），并在测试结束后DROP EXTENSION清理。

需要特别留意一个适用前提：该集成测试目前被显式跳过，原因是“Vector Assist 曾对所有 Cloud SQL for PostgreSQL 实例临时禁用”（见 集成测试 中的t.Skip调用及注释）。也就是说，在你的 Cloud SQL for PostgreSQL 实例上使用前，应确认该实例的 Vector Assist 功能当前处于可用状态，否则vector_assist.delete_spec函数本身可能不存在或不可用。

数据源侧：兼容的 Source 类型

从源码结构看，该工具对数据源的要求被定义为一个接口（工具实现）：

type compatibleSource interface { PostgresPool() *pgxpool.Pool RunSQL(context.Context, string, []any) (any, error) }

即数据源必须提供pgxpool连接池以及一个可执行带命名参数的RunSQL方法。在仓库的 internal/sources 目录下，postgres、cloud-sql-postgres、alloydb-postgres三个源均实现了PostgresPool()与RunSQL()方法（如 cloud-sql-postgres 源），可以推断它们是本文工具的主要兼容数据源；cockroachdb源同样对外暴露了PostgresPool()方法。

针对本文档所属的 Cloud SQL for PostgreSQL 集成，典型的source配置如下（字段说明见 Cloud SQL for PostgreSQL Source）：

kind: source name: my-cloud-sql-pg-source type: cloud-sql-postgres project: my-project-id region: us-central1 instance: my-instance database: my_db user: ${USER_NAME} password: ${PASSWORD} # ipType: "private"

其中ipType可取public、private或psc（默认public），user/password缺省时自动走 IAM 认证。该源还支持readOnly字段：设为true时在数据库会话级别强制执行只读（cloudsql_session_read_only=locked）并抑制写能力工具。由于vector-assist-delete-spec被标记为破坏性工具（见下文），将源配置为readOnly: true是不合理的——删除操作必然要求写权限。

参数与配置参考

调用参数（Parameters）

工具接受如下输入参数（与 工具实现 中的参数定义一致）：

参数按工具定义标注为必填或可选；底层函数可能对可选参数做进一步校验，以确保返回响应前所有必要数据可用。spec_id在源码中通过parameters.WithStringRequired(true)显式声明为必填。

配置字段（Reference）

源码中的Config结构（工具实现）与上表完全对应：Type与Source均带validate:"required"校验，Description可选，另支持annotations字段用于覆盖工具注解。若未提供description，Initialize会使用内置默认描述（与官方文档给出的措辞一致），保证 Agent 端始终能看到规范的用途说明。

最小配置示例

官方文档给出的 YAML 配置示例：

kind: tool name: delete_spec type: vector-assist-delete-spec source: my-database-source description: "This tool deletes an existing vector specification using its spec_id. Use this tool when a user explicitly requests to delete, remove, or clean up an existing vector specification which was created in the context of the vector assist tools."

预置配置中的实际用法

仓库自带的 Cloud SQL for PostgreSQL 预置配置 cloud-sql-postgres.yaml 展示了生产环境更简练的写法——description直接省略，依赖内置默认值：

kind: tool name: delete_spec type: vector-assist-delete-spec source: cloudsql-pg-source

同一文件中还注册了完整的 Vector Assist 工具族（define_spec、modify_spec、apply_spec、generate_query、delete_spec、list_specs、get_spec、improve_query_recall，见 预置配置），并将它们统一收进一个vectorassist工具组（group 定义），组描述为“通过表达意图与性能需求即可搭建并优化生产级向量工作负载”。将delete_spec与list_specs、get_spec同组暴露，便于 Agent 在“先列出/查看规格、再按需删除”的对话流中正确串联工具。

源码深潜：一次删除调用的完整链路

该工具的实现在 vectorassistdeletespec.go，调用链路清晰且短小：

1. 工具注册

const resourceType string = "vector-assist-delete-spec" func init() { if !tools.Register(resourceType, newConfig) { panic(fmt.Sprintf("tool type %q already registered", resourceType)) } }

init阶段将vector-assist-delete-spec这一类型名注册进全局工具工厂，Toolbox 解析kind: tool配置时按type字段找到对应工厂并反序列化 YAML 为Config（newConfig，使用goccy/go-yaml解码器）。

2. 固定 SQL：命名参数绑定

const deleteSpecQuery = ` SELECT vector_assist.delete_spec(spec_id => @spec_id::TEXT); `

注意这里使用 pgx 的命名参数@spec_id，并在 SQL 中显式将参数转型为TEXT，这与文档中“spec_id为字符串类型”的定义一致，避免了客户端拼接 SQL 的注入风险——参数值始终由驱动侧绑定。

3. 破坏性注解：让 Agent 知道这是个危险操作

Initialize中有一个容易被忽略但很重要的细节（工具实现）：

tools.GetAnnotationsOrDefault(cfg.Annotations, tools.NewDestructiveAnnotations)

当用户未显式提供annotations时，工具默认使用 NewDestructiveAnnotations：

func NewDestructiveAnnotations() *ToolAnnotations { readOnly := false destructive := true return &ToolAnnotations{ ReadOnlyHint: &readOnly, DestructiveHint: &destructive, } }

这是 MCP 规范中的工具注解：readOnlyHint: false、destructiveHint: true。对于接入的 Agent/客户端而言，这意味着调用前应当取得用户确认、且不应把该工具与只读查询工具同等对待。这也解释了为什么文档反复强调“仅在用户明确请求删除时使用该工具”。

4. Invoke：校验数据源并执行

func (t Tool) Invoke(ctx context.Context, s sources.Source, params parameters.ParamValues, accessToken tools.AccessToken) (any, util.ToolboxError) { source, ok := s.(compatibleSource) if !ok { return nil, util.NewClientServerError("source used is not compatible with the tool", http.StatusInternalServerError, nil) } paramsMap := params.AsMap() namedArgs := pgx.NamedArgs{} for key, value := range paramsMap { namedArgs[key] = value } resp, err := source.RunSQL(ctx, deleteSpecQuery, []any{namedArgs}) if err != nil { return nil, util.ProcessGeneralError(err) } return resp, nil }

执行顺序为：

1. 断言源实现了compatibleSource接口，否则返回 500 级错误“source used is not compatible with the tool”；ValidateSource在更早期（工具初始化/装配阶段）做同样的类型断言，把配置错误尽早暴露；
2. 将 MCP 传入的参数值映射为pgx.NamedArgs；
3. 通过source.RunSQL在数据源连接池上执行SELECT vector_assist.delete_spec(...)；
4. 数据库错误经util.ProcessGeneralError归一化为 Toolbox 标准错误结构返回给 MCP 客户端；成功时透传数据库响应。

由于 SQL 是SELECT形式（对存储过程/函数取返回值），工具自身不额外加事务或COMMIT；删除语义完全由vector_assist.delete_spec函数承担。

测试与验证

仓库为该工具提供了两级测试：

单元测试：YAML 配置解析

vectorassistdeletespec_test.go 的TestParseFromYaml用一段与官方文档示例同构的配置验证解析结果：

kind: tool name: delete-spec-tool type: vector-assist-delete-spec description: a test description source: a-source

并断言解析出的Config各字段（名称、类型、源、描述）与期望值完全一致，保证文档示例可直接通过服务端配置解析。

集成测试：HTTP 调用端到端验证

tests/cloudsqlpg/cloud_sql_pg_vectorassist_test.go 中的RunVectorAssistDeleteSpecToolInvokeTest（测试主体）启动真实 Toolbox 服务后，向 REST 端点POST /api/tool/delete_spec/invoke发送请求，验证两类行为：

• 合法参数：{"spec_id": "va_spec_001"}，期望 HTTP 200 且结果中包含delete_spec（即函数返回体标识删除动作）；
• 缺少spec_id：{}，期望结果中包含"error"字段——必填参数在工具层即被拦截。

该测试与define_spec、modify_spec、apply_spec、generate_query等测试串联在TestVectorAssistIntegration中，形成“定义 → 修改 → 应用 → 查询 → 删除”的完整生命周期验证（测试在 AddVectorAssistConfig 中批量注册了全部 8 个 Vector Assist 工具）。再次提醒：由于 Vector Assist 功能在 Cloud SQL 上的可用性会变化（测试中有t.Skip与说明注释），实际部署时请以你所在实例的功能状态为准。

小结

vector-assist-delete-spec是 MCP Toolbox for Databases 中 Cloud SQL for PostgreSQL 集成里 Vector Assist 工具族的收尾工具：

• 配置上：只需type: vector-assist-delete-spec、source（指向实现了PostgresPool/RunSQL的 PostgreSQL 系源）与可选description三个字段，调用参数仅有必填的字符串spec_id；
• 实现上：以 pgx 命名参数绑定执行固定的vector_assist.delete_spec(spec_id => @spec_id::TEXT)，参数经驱动绑定，避免 SQL 注入；
• 语义上：默认携带destructiveHint: true注解，提示 Agent 这是破坏性操作，应仅在用户明确请求删除时调用；
• 前提上：目标库必须安装vector_assist扩展，且 Cloud SQL 实例的 Vector Assist 功能处于可用状态。

配合预置配置 cloud-sql-postgres.yaml 中的vectorassist工具组，你可以把“列出规格 → 查看详情 → 删除规格”的能力一次性交给 Agent，完成向量规格的全生命周期治理。

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