feat(mcp): human-written table/column descriptions for the schema catalog (#1212)

Synced from sferarc/pgbeam@8dee15f

Author: SferaDev

src/generated/describe-map.gen.ts

@@ -94,6 +94,9 @@ export const describeByOperationId: Record<string, DescribeEndpoint> = {
   "listReplicas": {"operationId":"listReplicas","method":"GET","path":"/v1/databases/{database_id}/replicas","summary":"List replicas","description":"Lists all read replicas for a database.","parameters":[{"name":"database_id","in":"path","required":true,"type":"string","description":"Unique database identifier (prefixed, e.g. db_xxx)."}],"requestBodyType":"","requestBodyRequired":false,"responseType":"{ next_page_token?: string; replicas: ({ created_at: string; database_id: string; host: string; id: string; port: number; ssl_mode: \"disable\" | \"allow\" | \"prefer\" | \"require\" | \"verify-ca\" | \"verify-full\"; updated_at: string })[] }","responseStatus":"200"},
   "createReplica": {"operationId":"createReplica","method":"POST","path":"/v1/databases/{database_id}/replicas","summary":"Add a replica","description":"Adds a read replica to a database.","parameters":[{"name":"database_id","in":"path","required":true,"type":"string","description":"Unique database identifier (prefixed, e.g. db_xxx)."}],"requestBodyType":"{ host: string; port: number; ssl_mode?: \"disable\" | \"allow\" | \"prefer\" | \"require\" | \"verify-ca\" | \"verify-full\" }","requestBodyRequired":true,"responseType":"{ created_at: string; database_id: string; host: string; id: string; port: number; ssl_mode: \"disable\" | \"allow\" | \"prefer\" | \"require\" | \"verify-ca\" | \"verify-full\"; updated_at: string }","responseStatus":"201"},
   "deleteReplica": {"operationId":"deleteReplica","method":"DELETE","path":"/v1/databases/{database_id}/replicas/{replica_id}","summary":"Delete a replica","description":"Removes a read replica from a database.","parameters":[{"name":"database_id","in":"path","required":true,"type":"string","description":"Unique database identifier (prefixed, e.g. db_xxx)."},{"name":"replica_id","in":"path","required":true,"type":"string","description":"Unique replica identifier (prefixed, e.g. rep_xxx)."}],"requestBodyType":"","requestBodyRequired":false,"responseType":"","responseStatus":"204"},
+  "listSchemaAnnotations": {"operationId":"listSchemaAnnotations","method":"GET","path":"/v1/projects/{project_id}/schema-annotations","summary":"List schema annotations","description":"Lists the project's human-written table and column descriptions. These are surfaced to connected agents through the MCP schema catalog.\n","parameters":[{"name":"project_id","in":"path","required":true,"type":"string","description":"Unique project identifier (prefixed, e.g. prj_xxx)."},{"name":"page_size","in":"query","required":false,"type":"number","description":"Maximum number of items to return (1-100, default 20)."},{"name":"page_token","in":"query","required":false,"type":"string","description":"Opaque token for cursor-based pagination."}],"requestBodyType":"","requestBodyRequired":false,"responseType":"{ annotations: ({ column_name?: string; created_at: string; description: string; id: string; project_id: string; schema_name?: string; table_name: string; updated_at: string })[]; next_page_token?: string }","responseStatus":"200"},
+  "putSchemaAnnotation": {"operationId":"putSchemaAnnotation","method":"PUT","path":"/v1/projects/{project_id}/schema-annotations","summary":"Create or replace a schema annotation","description":"Attaches an operator-written description to a table (omit column_name) or a column. Keyed by (schema_name, table_name, column_name); an existing annotation with the same key is replaced.\n","parameters":[{"name":"project_id","in":"path","required":true,"type":"string","description":"Unique project identifier (prefixed, e.g. prj_xxx)."}],"requestBodyType":"{ column_name?: string; description: string; schema_name?: string; table_name: string }","requestBodyRequired":true,"responseType":"{ column_name?: string; created_at: string; description: string; id: string; project_id: string; schema_name?: string; table_name: string; updated_at: string }","responseStatus":"200"},
+  "deleteSchemaAnnotation": {"operationId":"deleteSchemaAnnotation","method":"DELETE","path":"/v1/projects/{project_id}/schema-annotations","summary":"Delete a schema annotation","description":"Removes a single annotation identified by its natural key. Omit column_name to delete a table-level annotation, and omit schema_name to match the unqualified form.\n","parameters":[{"name":"project_id","in":"path","required":true,"type":"string","description":"Unique project identifier (prefixed, e.g. prj_xxx)."},{"name":"table_name","in":"query","required":true,"type":"string","description":"Relation (table or view) the annotation describes."},{"name":"schema_name","in":"query","required":false,"type":"string","description":"Optional schema. Omit to match the unqualified form."},{"name":"column_name","in":"query","required":false,"type":"string","description":"Optional column. Omit to delete a table-level annotation."}],"requestBodyType":"","requestBodyRequired":false,"responseType":"","responseStatus":"204"},
   "listSelfHostEnrollments": {"operationId":"listSelfHostEnrollments","method":"GET","path":"/v1/organizations/{org_id}/self-host-enrollments","summary":"List self-host enrollments","description":"Lists an organization's self-host enrollments. Tokens are never returned.","parameters":[{"name":"org_id","in":"path","required":true,"type":"string","description":"Unique organization identifier."}],"requestBodyType":"","requestBodyRequired":false,"responseType":"{ enrollments: ({ created_at: string; created_by?: string; description?: string; expires_at?: string; id: string; last_seen_at?: string; org_id: string; region_label?: string; revoked_at?: string })[] }","responseStatus":"200"},
   "createSelfHostEnrollment": {"operationId":"createSelfHostEnrollment","method":"POST","path":"/v1/organizations/{org_id}/self-host-enrollments","summary":"Issue a self-host enrollment token","description":"Issues an enrollment token a self-hosted (BYOC) proxy uses to authenticate to the control plane's config/audit gRPC stream. The token is returned once and cannot be retrieved again. Requires the Scale or enterprise plan.","parameters":[{"name":"org_id","in":"path","required":true,"type":"string","description":"Unique organization identifier."}],"requestBodyType":"{ description?: string; expires_at?: string; region_label?: string }","requestBodyRequired":false,"responseType":"{ enrollment: { created_at: string; created_by?: string; description?: string; expires_at?: string; id: string; last_seen_at?: string; org_id: string; region_label?: string; revoked_at?: string }; token: string }","responseStatus":"201"},
   "revokeSelfHostEnrollment": {"operationId":"revokeSelfHostEnrollment","method":"DELETE","path":"/v1/organizations/{org_id}/self-host-enrollments/{enrollment_id}","summary":"Revoke a self-host enrollment","description":"Revokes an enrollment so its token can no longer authenticate a proxy. Connected proxies keep their last-known config until they reconnect.","parameters":[{"name":"org_id","in":"path","required":true,"type":"string","description":"Unique organization identifier."},{"name":"enrollment_id","in":"path","required":true,"type":"string","description":"Unique enrollment identifier."}],"requestBodyType":"","requestBodyRequired":false,"responseType":"","responseStatus":"204"},

src/generated/index.ts

@@ -46,6 +46,7 @@ export type { DeleteHoneytokenPathHoneytokenId, DeleteHoneytokenPathProjectId, D
 export type { DeletePolicyProfilePathPolicyId, DeletePolicyProfilePathProjectId, DeletePolicyProfileRequestConfig, DeletePolicyProfileResponse, DeletePolicyProfileResponses, DeletePolicyProfileStatus204, DeletePolicyProfileStatus400, DeletePolicyProfileStatus401, DeletePolicyProfileStatus403, DeletePolicyProfileStatus404, DeletePolicyProfileStatus409 } from "./types/DeletePolicyProfile";
 export type { DeleteProjectPathProjectId, DeleteProjectRequestConfig, DeleteProjectResponse, DeleteProjectResponses, DeleteProjectStatus204, DeleteProjectStatus400, DeleteProjectStatus401, DeleteProjectStatus403, DeleteProjectStatus404, DeleteProjectStatus429 } from "./types/DeleteProject";
 export type { DeleteReplicaPathDatabaseId, DeleteReplicaPathReplicaId, DeleteReplicaRequestConfig, DeleteReplicaResponse, DeleteReplicaResponses, DeleteReplicaStatus204, DeleteReplicaStatus400, DeleteReplicaStatus401, DeleteReplicaStatus403, DeleteReplicaStatus404, DeleteReplicaStatus429 } from "./types/DeleteReplica";
+export type { DeleteSchemaAnnotationPathProjectId, DeleteSchemaAnnotationQueryColumnName, DeleteSchemaAnnotationQuerySchemaName, DeleteSchemaAnnotationQueryTableName, DeleteSchemaAnnotationRequestConfig, DeleteSchemaAnnotationResponse, DeleteSchemaAnnotationResponses, DeleteSchemaAnnotationStatus204, DeleteSchemaAnnotationStatus400, DeleteSchemaAnnotationStatus401, DeleteSchemaAnnotationStatus403, DeleteSchemaAnnotationStatus404 } from "./types/DeleteSchemaAnnotation";
 export type { DeleteWebhookEndpointPathProjectId, DeleteWebhookEndpointPathWebhookId, DeleteWebhookEndpointRequestConfig, DeleteWebhookEndpointResponse, DeleteWebhookEndpointResponses, DeleteWebhookEndpointStatus204, DeleteWebhookEndpointStatus400, DeleteWebhookEndpointStatus401, DeleteWebhookEndpointStatus403, DeleteWebhookEndpointStatus404 } from "./types/DeleteWebhookEndpoint";
 export type { DiscardDatabaseBranchPathBranchId, DiscardDatabaseBranchPathProjectId, DiscardDatabaseBranchRequestConfig, DiscardDatabaseBranchResponse, DiscardDatabaseBranchResponses, DiscardDatabaseBranchStatus204, DiscardDatabaseBranchStatus400, DiscardDatabaseBranchStatus401, DiscardDatabaseBranchStatus403, DiscardDatabaseBranchStatus404 } from "./types/DiscardDatabaseBranch";
 export type { DnsInstructions } from "./types/DnsInstructions";
@@ -109,6 +110,8 @@ export type { ListRegionsRequestConfig, ListRegionsResponses, ListRegionsStatus2
 export type { ListRegionsResponse } from "./types/ListRegionsResponse";
 export type { ListReplicasPathDatabaseId, ListReplicasRequestConfig, ListReplicasResponses, ListReplicasStatus200, ListReplicasStatus400, ListReplicasStatus401, ListReplicasStatus403, ListReplicasStatus404, ListReplicasStatus429 } from "./types/ListReplicas";
 export type { ListReplicasResponse } from "./types/ListReplicasResponse";
+export type { ListSchemaAnnotationsPathProjectId, ListSchemaAnnotationsQueryPageSize, ListSchemaAnnotationsQueryPageToken, ListSchemaAnnotationsRequestConfig, ListSchemaAnnotationsResponses, ListSchemaAnnotationsStatus200, ListSchemaAnnotationsStatus400, ListSchemaAnnotationsStatus401, ListSchemaAnnotationsStatus403, ListSchemaAnnotationsStatus404, ListSchemaAnnotationsStatus429 } from "./types/ListSchemaAnnotations";
+export type { ListSchemaAnnotationsResponse } from "./types/ListSchemaAnnotationsResponse";
 export type { ListSelfHostEnrollmentsPathOrgId, ListSelfHostEnrollmentsRequestConfig, ListSelfHostEnrollmentsResponses, ListSelfHostEnrollmentsStatus200, ListSelfHostEnrollmentsStatus400, ListSelfHostEnrollmentsStatus401, ListSelfHostEnrollmentsStatus403 } from "./types/ListSelfHostEnrollments";
 export type { ListSelfHostEnrollmentsResponse } from "./types/ListSelfHostEnrollmentsResponse";
 export type { ListSupportCasesPathOrgId, ListSupportCasesQueryPage, ListSupportCasesQueryPageSize, ListSupportCasesQuerySearch, ListSupportCasesQueryStatus, ListSupportCasesRequestConfig, ListSupportCasesResponses, ListSupportCasesStatus200, ListSupportCasesStatus400, ListSupportCasesStatus401, ListSupportCasesStatus403 } from "./types/ListSupportCases";
@@ -145,6 +148,7 @@ export type { ProjectInsights } from "./types/ProjectInsights";
 export type { ProjectMetricsResponse } from "./types/ProjectMetricsResponse";
 export type { ProjectStatusKey } from "./types/ProjectStatus";
 export type { ProjectUsageResponse } from "./types/ProjectUsageResponse";
+export type { PutSchemaAnnotationData, PutSchemaAnnotationPathProjectId, PutSchemaAnnotationRequestConfig, PutSchemaAnnotationResponse, PutSchemaAnnotationResponses, PutSchemaAnnotationStatus200, PutSchemaAnnotationStatus400, PutSchemaAnnotationStatus401, PutSchemaAnnotationStatus403, PutSchemaAnnotationStatus404, PutSchemaAnnotationStatus429 } from "./types/PutSchemaAnnotation";
 export type { QueryInsight } from "./types/QueryInsight";
 export type { RecommendAgentPolicyData, RecommendAgentPolicyPathAgentId, RecommendAgentPolicyPathProjectId, RecommendAgentPolicyRequestConfig, RecommendAgentPolicyResponse, RecommendAgentPolicyResponses, RecommendAgentPolicyStatus200, RecommendAgentPolicyStatus400, RecommendAgentPolicyStatus401, RecommendAgentPolicyStatus403, RecommendAgentPolicyStatus404, RecommendAgentPolicyStatus429 } from "./types/RecommendAgentPolicy";
 export type { Region, RegionProviderEnumKey, RegionStatusEnumKey } from "./types/Region";
@@ -159,6 +163,8 @@ export type { RowFilter } from "./types/RowFilter";
 export type { SSLModeKey } from "./types/SSLMode";
 export type { ScanDatabaseForPiiPathDatabaseId, ScanDatabaseForPiiPathProjectId, ScanDatabaseForPiiRequestConfig, ScanDatabaseForPiiResponse, ScanDatabaseForPiiResponses, ScanDatabaseForPiiStatus200, ScanDatabaseForPiiStatus400, ScanDatabaseForPiiStatus401, ScanDatabaseForPiiStatus403, ScanDatabaseForPiiStatus404, ScanDatabaseForPiiStatus429 } from "./types/ScanDatabaseForPii";
 export type { ScanPiiResult } from "./types/ScanPiiResult";
+export type { SchemaAnnotation } from "./types/SchemaAnnotation";
+export type { SchemaAnnotationInput } from "./types/SchemaAnnotationInput";
 export type { SchemaCatalog } from "./types/SchemaCatalog";
 export type { SchemaCatalogColumn } from "./types/SchemaCatalogColumn";
 export type { SchemaCatalogRelation, SchemaCatalogRelationKindEnumKey } from "./types/SchemaCatalogRelation";

src/generated/operations-map.gen.ts

@@ -68,6 +68,9 @@ import type { ListRegionsStatus200 } from "./types/ListRegions";
 import type { ListReplicasRequestConfig, ListReplicasStatus200 } from "./types/ListReplicas";
 import type { CreateReplicaRequestConfig, CreateReplicaStatus201 } from "./types/CreateReplica";
 import type { DeleteReplicaRequestConfig } from "./types/DeleteReplica";
+import type { ListSchemaAnnotationsRequestConfig, ListSchemaAnnotationsStatus200 } from "./types/ListSchemaAnnotations";
+import type { PutSchemaAnnotationRequestConfig, PutSchemaAnnotationStatus200 } from "./types/PutSchemaAnnotation";
+import type { DeleteSchemaAnnotationRequestConfig } from "./types/DeleteSchemaAnnotation";
 import type { ListSelfHostEnrollmentsRequestConfig, ListSelfHostEnrollmentsStatus200 } from "./types/ListSelfHostEnrollments";
 import type { CreateSelfHostEnrollmentRequestConfig, CreateSelfHostEnrollmentStatus201 } from "./types/CreateSelfHostEnrollment";
 import type { RevokeSelfHostEnrollmentRequestConfig } from "./types/RevokeSelfHostEnrollment";
@@ -183,6 +186,11 @@ export const operationsByTag = {
   migrations: {
     lintMigration: { method: "POST", path: "/v1/projects/{project_id}/migrations:lint" },
   },
+  schemaAnnotations: {
+    listSchemaAnnotations: { method: "GET", path: "/v1/projects/{project_id}/schema-annotations" },
+    putSchemaAnnotation: { method: "PUT", path: "/v1/projects/{project_id}/schema-annotations" },
+    deleteSchemaAnnotation: { method: "DELETE", path: "/v1/projects/{project_id}/schema-annotations" },
+  },
   support: {
     listSupportCases: { method: "GET", path: "/v1/organizations/{org_id}/support/cases" },
     createSupportCase: { method: "POST", path: "/v1/organizations/{org_id}/support/cases" },
@@ -269,6 +277,9 @@ export const operationsByPath = {
   "GET /v1/databases/{database_id}/replicas": { method: "GET", path: "/v1/databases/{database_id}/replicas", operationId: "listReplicas" },
   "POST /v1/databases/{database_id}/replicas": { method: "POST", path: "/v1/databases/{database_id}/replicas", operationId: "createReplica" },
   "DELETE /v1/databases/{database_id}/replicas/{replica_id}": { method: "DELETE", path: "/v1/databases/{database_id}/replicas/{replica_id}", operationId: "deleteReplica" },
+  "GET /v1/projects/{project_id}/schema-annotations": { method: "GET", path: "/v1/projects/{project_id}/schema-annotations", operationId: "listSchemaAnnotations" },
+  "PUT /v1/projects/{project_id}/schema-annotations": { method: "PUT", path: "/v1/projects/{project_id}/schema-annotations", operationId: "putSchemaAnnotation" },
+  "DELETE /v1/projects/{project_id}/schema-annotations": { method: "DELETE", path: "/v1/projects/{project_id}/schema-annotations", operationId: "deleteSchemaAnnotation" },
   "GET /v1/organizations/{org_id}/self-host-enrollments": { method: "GET", path: "/v1/organizations/{org_id}/self-host-enrollments", operationId: "listSelfHostEnrollments" },
   "POST /v1/organizations/{org_id}/self-host-enrollments": { method: "POST", path: "/v1/organizations/{org_id}/self-host-enrollments", operationId: "createSelfHostEnrollment" },
   "DELETE /v1/organizations/{org_id}/self-host-enrollments/{enrollment_id}": { method: "DELETE", path: "/v1/organizations/{org_id}/self-host-enrollments/{enrollment_id}", operationId: "revokeSelfHostEnrollment" },
@@ -349,6 +360,9 @@ type GetProjectMetricsParams = { pathParams: NonNullable<GetProjectMetricsReques
 type ListReplicasParams = { pathParams: NonNullable<ListReplicasRequestConfig["pathParams"]> };
 type CreateReplicaParams = { pathParams: NonNullable<CreateReplicaRequestConfig["pathParams"]>; body: NonNullable<CreateReplicaRequestConfig["data"]> };
 type DeleteReplicaParams = { pathParams: NonNullable<DeleteReplicaRequestConfig["pathParams"]> };
+type ListSchemaAnnotationsParams = { pathParams: NonNullable<ListSchemaAnnotationsRequestConfig["pathParams"]>; queryParams?: NonNullable<ListSchemaAnnotationsRequestConfig["queryParams"]> };
+type PutSchemaAnnotationParams = { pathParams: NonNullable<PutSchemaAnnotationRequestConfig["pathParams"]>; body: NonNullable<PutSchemaAnnotationRequestConfig["data"]> };
+type DeleteSchemaAnnotationParams = { pathParams: NonNullable<DeleteSchemaAnnotationRequestConfig["pathParams"]>; queryParams: NonNullable<DeleteSchemaAnnotationRequestConfig["queryParams"]> };
 type ListSelfHostEnrollmentsParams = { pathParams: NonNullable<ListSelfHostEnrollmentsRequestConfig["pathParams"]> };
 type CreateSelfHostEnrollmentParams = { pathParams: NonNullable<CreateSelfHostEnrollmentRequestConfig["pathParams"]>; body: NonNullable<CreateSelfHostEnrollmentRequestConfig["data"]> };
 type RevokeSelfHostEnrollmentParams = { pathParams: NonNullable<RevokeSelfHostEnrollmentRequestConfig["pathParams"]> };
@@ -464,6 +478,11 @@ export interface ApiOperations {
   migrations: {
     lintMigration(params: LintMigrationParams): Promise<LintMigrationStatus200>;
   };
+  schemaAnnotations: {
+    listSchemaAnnotations(params: ListSchemaAnnotationsParams): Promise<ListSchemaAnnotationsStatus200>;
+    putSchemaAnnotation(params: PutSchemaAnnotationParams): Promise<PutSchemaAnnotationStatus200>;
+    deleteSchemaAnnotation(params: DeleteSchemaAnnotationParams): Promise<void>;
+  };
   support: {
     listSupportCases(params: ListSupportCasesParams): Promise<ListSupportCasesStatus200>;
     createSupportCase(params: CreateSupportCaseParams): Promise<CreateSupportCaseStatus201>;
@@ -550,6 +569,9 @@ export interface RequestMap {
   "GET /v1/databases/{database_id}/replicas": { params: ListReplicasParams; response: ListReplicasStatus200 };
   "POST /v1/databases/{database_id}/replicas": { params: CreateReplicaParams; response: CreateReplicaStatus201 };
   "DELETE /v1/databases/{database_id}/replicas/{replica_id}": { params: DeleteReplicaParams; response: void };
+  "GET /v1/projects/{project_id}/schema-annotations": { params: ListSchemaAnnotationsParams; response: ListSchemaAnnotationsStatus200 };
+  "PUT /v1/projects/{project_id}/schema-annotations": { params: PutSchemaAnnotationParams; response: PutSchemaAnnotationStatus200 };
+  "DELETE /v1/projects/{project_id}/schema-annotations": { params: DeleteSchemaAnnotationParams; response: void };
   "GET /v1/organizations/{org_id}/self-host-enrollments": { params: ListSelfHostEnrollmentsParams; response: ListSelfHostEnrollmentsStatus200 };
   "POST /v1/organizations/{org_id}/self-host-enrollments": { params: CreateSelfHostEnrollmentParams; response: CreateSelfHostEnrollmentStatus201 };
   "DELETE /v1/organizations/{org_id}/self-host-enrollments/{enrollment_id}": { params: RevokeSelfHostEnrollmentParams; response: void };