Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
feat(mcp): add and improve MCP skills (#18490)
p0nyb159672b70d9
diff --git a/backend/api/mcp/skills/create-instance.md b/backend/api/mcp/skills/create-instance.mddeleted file mode 100644index de7703460f..0000000000--- a/backend/api/mcp/skills/create-instance.md+++ /dev/null@@ -1,60 +0,0 @@-----name: create-instance-description: Add a database instance to Bytebase------# Create Instance--## Overview--Add a database instance (PostgreSQL, MySQL, etc.) to Bytebase for management.--## Prerequisites--- Have `bb.instances.create` permission-- Know the database engine type and connection details--## Workflow--1. **Get the schema**:- ```- search_api(operationId="InstanceService/CreateInstance")- ```--2. **List environments** (to get environment resource name):- ```- call_api(operationId="EnvironmentService/ListEnvironments", body={})- ```--3. **Create the instance**:- ```- call_api(operationId="InstanceService/CreateInstance", body={- "parent": "projects/{project-id}",- "instance": {- "title": "Production PostgreSQL",- "engine": "POSTGRES",- "environment": "environments/prod",- "activation": true,- "dataSources": [{- "type": "ADMIN",- "host": "localhost",- "port": "5432",- "username": "admin",- "password": "secret"- }]- },- "instanceId": "prod-pg"- })- ```--## Engine Types--POSTGRES, MYSQL, TIDB, CLICKHOUSE, SNOWFLAKE, SQLITE, MONGODB, REDIS, ORACLE, MSSQL, MARIADB, OCEANBASE--## Common Errors--| Error | Cause | Fix |-|-------|-------|-----|-| environment not found | Invalid environment name | List environments first |-| instance already exists | Duplicate instanceId | Choose different instanceId |-| connection failed | Wrong host/port/credentials | Verify connection details |diff --git a/backend/api/mcp/skills/create-project.md b/backend/api/mcp/skills/create-project.mddeleted file mode 100644index 5b57d9bec6..0000000000--- a/backend/api/mcp/skills/create-project.md+++ /dev/null@@ -1,44 +0,0 @@-----name: create-project-description: Set up a new Bytebase project------# Create Project--## Overview--Create a new project to organize databases and team members.--## Prerequisites--- Have `bb.projects.create` permission--## Workflow--1. **Get the schema**:- ```- search_api(operationId="ProjectService/CreateProject")- ```--2. **Create the project**:- ```- call_api(operationId="ProjectService/CreateProject", body={- "project": {- "title": "My Project",- "key": "MYPROJ"- },- "projectId": "my-project"- })- ```--3. **Add team members** (optional):- ```- search_api(operationId="ProjectService/SetProjectIamPolicy")- ```--## Common Errors--| Error | Cause | Fix |-|-------|-------|-----|-| project already exists | Duplicate projectId | Choose different projectId |-| invalid key | Key format wrong | Use uppercase letters, 2-10 chars |diff --git a/backend/api/mcp/skills/database-change.md b/backend/api/mcp/skills/database-change.mdnew file mode 100644index 0000000000..d7a2cdbc69--- /dev/null+++ b/backend/api/mcp/skills/database-change.md@@ -0,0 +1,151 @@+---+name: database-change+description: Create database change issues (single or batch) through review workflow+---++# Database Change++## Overview++Create database changes (DDL/DML) through Bytebase's review workflow. Supports single database or batch changes across multiple databases.++## Prerequisites++- Have `bb.plans.create`, `bb.issues.create`, `bb.rollouts.create` permissions+- Know the target database(s)++## Workflow++### Step 1: Create sheet(s) with SQL++SQL content must be **base64 encoded**. Engine field is **required**.++```+search_api(operationId="SheetService/CreateSheet")+```+```+call_api(operationId="SheetService/CreateSheet", body={+ "parent": "projects/{project-id}",+ "sheet": {+ "title": "Add users table",+ "engine": "POSTGRES",+ "content": "Q1JFQVRFIFRBQkxFIHVzZXJzIChpZCBJTlQgUFJJTUFSWSBLRVkpOw=="+ }+})+```++Note: `Q1JFQVRFIFRBQkxFIHVzZXJzIChpZCBJTlQgUFJJTUFSWSBLRVkpOw==` decodes to `CREATE TABLE users (id INT PRIMARY KEY);`++**Engine values:** `POSTGRES`, `MYSQL`, `TIDB`, `CLICKHOUSE`, `SNOWFLAKE`, `SQLITE`, `MONGODB`, `REDIS`, `ORACLE`, `MSSQL`, `MARIADB`, `OCEANBASE`++### Step 2: Create a plan++Plan contains `specs` directly (not wrapped in "steps").++**Single database:**+```+search_api(operationId="PlanService/CreatePlan")+```+```+call_api(operationId="PlanService/CreatePlan", body={+ "parent": "projects/{project-id}",+ "plan": {+ "title": "Add users table",+ "specs": [{+ "id": "spec-1",+ "changeDatabaseConfig": {+ "targets": ["instances/{instance-id}/databases/{database-name}"],+ "sheet": "projects/{project-id}/sheets/{sheet-id}",+ "type": "MIGRATE"+ }+ }]+ }+})+```++**Batch change (multiple databases):**+```+call_api(operationId="PlanService/CreatePlan", body={+ "parent": "projects/{project-id}",+ "plan": {+ "title": "Add users table to all databases",+ "specs": [+ {+ "id": "spec-dev",+ "changeDatabaseConfig": {+ "targets": ["instances/dev-pg/databases/mydb"],+ "sheet": "projects/{project-id}/sheets/{sheet-id}",+ "type": "MIGRATE"+ }+ },+ {+ "id": "spec-prod",+ "changeDatabaseConfig": {+ "targets": ["instances/prod-pg/databases/mydb"],+ "sheet": "projects/{project-id}/sheets/{sheet-id}",+ "type": "MIGRATE"+ }+ }+ ]+ }+})+```++**Key concepts:**+- `specs` is a flat array directly on the plan (no "steps" wrapper)+- Each `spec` has a unique `id` (any string, used for identification)+- `targets` is an **array** (even for single database)+- Specs are executed based on rollout policy (can be sequential or parallel)++**Using database groups:**+```+"targets": ["projects/{project-id}/databaseGroups/{group-name}"]+```++### Step 3: Create an issue++```+search_api(operationId="IssueService/CreateIssue")+```+```+call_api(operationId="IssueService/CreateIssue", body={+ "parent": "projects/{project-id}",+ "issue": {+ "title": "Add users table",+ "type": "DATABASE_CHANGE",+ "plan": "projects/{project-id}/plans/{plan-id}"+ }+})+```++### Step 4: Create a rollout++```+search_api(operationId="RolloutService/CreateRollout")+```+```+call_api(operationId="RolloutService/CreateRollout", body={+ "parent": "projects/{project-id}",+ "rollout": {+ "plan": "projects/{project-id}/plans/{plan-id}"+ }+})+```++## Change Types++| Type | Use Case |+|------|----------|+| `MIGRATE` | Imperative schema/data changes (DDL and DML) |+| `SDL` | State-based declarative schema migration |++## Common Errors++| Error | Cause | Fix |+|-------|-------|-----|+| database not found | Wrong database reference | Verify `instances/{id}/databases/{name}` format |+| sheet not found | Sheet doesn't exist | Create sheet first (Step 1) |+| missing engine | Sheet without engine field | Add `engine` field to sheet |+| plan not found | Plan doesn't exist | Create plan before issue |+| invalid base64 | SQL not encoded | Base64 encode the SQL content |+| targets must be array | Using string instead of array | Wrap target in array: `["..."]` |diff --git a/backend/api/mcp/skills/grant-permission.md b/backend/api/mcp/skills/grant-permission.mdnew file mode 100644index 0000000000..b9d30de62b--- /dev/null+++ b/backend/api/mcp/skills/grant-permission.md@@ -0,0 +1,174 @@+---+name: grant-permission+description: Grant roles and permissions to users at workspace or project level+---++# Grant Permission++## Overview++Grant roles to users or groups using Bytebase's RBAC system. Permissions can be set at workspace level (global) or project level (scoped).++## Prerequisites++- Have `bb.workspaces.setIamPolicy` for workspace-level grants+- Have `bb.projects.setIamPolicy` for project-level grants++## Permission Levels++| Level | Scope | Use Case |+|-------|-------|----------|+| **Workspace** | All projects | Admins, DBAs, global viewers |+| **Project** | Single project | Developers, project owners |++## Workflow++### Step 1: List Available Roles++```+search_api(operationId="RoleService/ListRoles")+```+```+call_api(operationId="RoleService/ListRoles", body={})+```++**Built-in roles:**++| Role | Description |+|------|-------------|+| `roles/workspaceAdmin` | Full workspace access |+| `roles/workspaceDBA` | Database administration |+| `roles/workspaceMember` | Basic workspace access |+| `roles/projectOwner` | Full project access |+| `roles/projectDeveloper` | Development access (create issues, plans) |+| `roles/projectReleaser` | Execute rollouts |+| `roles/sqlEditorUser` | SQL Editor access only |+| `roles/projectViewer` | Read-only access |+| `roles/gitopsServiceAgent` | GitOps automation |++### Step 2: Get Current IAM Policy++Always fetch current policy first to avoid overwriting existing bindings.++**Workspace level:**+```+search_api(operationId="WorkspaceService/GetIamPolicy")+```+```+call_api(operationId="WorkspaceService/GetIamPolicy", body={+ "resource": "workspaces/-"+})+```++**Project level:**+```+search_api(operationId="ProjectService/GetIamPolicy")+```+```+call_api(operationId="ProjectService/GetIamPolicy", body={+ "resource": "projects/{project-id}"+})+```++Save the returned `etag` for the update.++### Step 3: Set IAM Policy++Add new bindings while preserving existing ones.++**Workspace level:**+```+search_api(operationId="WorkspaceService/SetIamPolicy")+```+```+call_api(operationId="WorkspaceService/SetIamPolicy", body={+ "resource": "workspaces/-",+ "etag": "{etag-from-get}",+ "policy": {+ "bindings": [+ {+ "role": "roles/workspaceDBA",+ "members": ["user:[email protected]"]+ },+ {+ "role": "roles/workspaceMember",+ "members": [+ "user:[email protected]",+ "user:[email protected]",+ "group:[email protected]"+ ]+ }+ ]+ }+})+```++**Project level:**+```+call_api(operationId="ProjectService/SetIamPolicy", body={+ "resource": "projects/{project-id}",+ "etag": "{etag-from-get}",+ "policy": {+ "bindings": [+ {+ "role": "roles/projectOwner",+ "members": ["user:[email protected]"]+ },+ {+ "role": "roles/projectDeveloper",+ "members": ["group:[email protected]"]+ }+ ]+ }+})+```++## Member Format++| Type | Format | Example |+|------|--------|---------|+| User | `user:{email}` | `user:[email protected]` |+| Group | `group:{email}` | `group:[email protected]` |+| All users | `allUsers` | `allUsers` |++## Time-Limited Access (CEL Expressions)++Grant temporary access using CEL conditions.++```+call_api(operationId="ProjectService/SetIamPolicy", body={+ "resource": "projects/{project-id}",+ "etag": "{etag}",+ "policy": {+ "bindings": [{+ "role": "roles/projectDeveloper",+ "members": ["user:[email protected]"],+ "condition": {+ "expression": "request.time < timestamp('2024-12-31T23:59:59Z')",+ "title": "Temporary access",+ "description": "Access expires end of 2024"+ }+ }]+ }+})+```++**CEL variables for sqlEditorUser:**+- `resource.database`: Database name (`instances/{id}/databases/{name}`)+- `resource.schema_name`: Schema name+- `resource.table_name`: Table name+- `request.time`: For expiration++**CEL examples:**+- Expire at date: `request.time < timestamp('2024-12-31T23:59:59Z')`+- Limit to database: `resource.database == "instances/prod/databases/main"`++## Common Errors++| Error | Cause | Fix |+|-------|-------|-----|+| etag mismatch | Policy changed | Re-fetch policy and retry |+| role not found | Invalid role name | List roles first, use `roles/{name}` format |+| invalid member | Wrong format | Use `user:email` or `group:email` format |+| permission denied | Missing setIamPolicy | Check workspace/project admin access |+| invalid CEL | Bad expression syntax | Validate CEL expression format |diff --git a/backend/api/mcp/skills/execute-sql.md b/backend/api/mcp/skills/query.mdsimilarity index 98%rename from backend/api/mcp/skills/execute-sql.mdrename to backend/api/mcp/skills/query.mdindex 4a51d44f4b..0715e50cb0 100644--- a/backend/api/mcp/skills/execute-sql.md+++ b/backend/api/mcp/skills/query.md@@ -1,5 +1,5 @@----name: execute-sql+name: querydescription: Run SQL queries on databases---diff --git a/backend/api/mcp/skills/schema-change.md b/backend/api/mcp/skills/schema-change.mddeleted file mode 100644index aa48ea4a5b..0000000000--- a/backend/api/mcp/skills/schema-change.md+++ /dev/null@@ -1,92 +0,0 @@-----name: schema-change-description: Create schema migration issues------# Schema Change--## Overview--Create a schema change to modify database structure (DDL) through Bytebase's review workflow.--## Prerequisites--- Have `bb.plans.create`, `bb.issues.create`, `bb.rollouts.create` permissions-- Know the target database--## Workflow--1. **Create a sheet with the SQL** (content is base64 encoded):- ```- search_api(operationId="SheetService/CreateSheet")- ```- ```- call_api(operationId="SheetService/CreateSheet", body={- "parent": "projects/{project-id}",- "sheet": {- "title": "Add users table",- "content": "Q1JFQVRFIFRBQkxFIHVzZXJzIChpZCBJTlQgUFJJTUFSWSBLRVksIG5hbWUgVkFSQ0hBUigyNTUpKTs="- }- })- ```- Note: `content` is base64 encoded. The example above decodes to:- `CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(255));`--2. **Create a plan**:- ```- search_api(operationId="PlanService/CreatePlan")- ```- ```- call_api(operationId="PlanService/CreatePlan", body={- "parent": "projects/{project-id}",- "plan": {- "title": "Add users table",- "steps": [{- "specs": [{- "changeDatabaseConfig": {- "target": "instances/{instance-id}/databases/{database-name}",- "type": "MIGRATE",- "sheet": "projects/{project-id}/sheets/{sheet-id}"- }- }]- }]- }- })- ```--3. **Create an issue**:- ```- search_api(operationId="IssueService/CreateIssue")- ```- ```- call_api(operationId="IssueService/CreateIssue", body={- "parent": "projects/{project-id}",- "issue": {- "title": "Add users table",- "type": "DATABASE_CHANGE",- "plan": "projects/{project-id}/plans/{plan-id}"- }- })- ```--4. **Create a rollout** (to execute after approval):- ```- search_api(operationId="RolloutService/CreateRollout")- ```- ```- call_api(operationId="RolloutService/CreateRollout", body={- "parent": "projects/{project-id}",- "rollout": {- "plan": "projects/{project-id}/plans/{plan-id}"- }- })- ```--## Common Errors--| Error | Cause | Fix |-|-------|-------|-----|-| database not found | Wrong database reference | Verify database resource name |-| sheet not found | Sheet doesn't exist | Create sheet first |-| plan not found | Plan doesn't exist | Create plan before issue |-| issue not approved | Issue needs approval | Wait for approval before rollout |diff --git a/backend/api/mcp/tool_skill.go b/backend/api/mcp/tool_skill.goindex e0c776e6b7..4b241947c8 100644--- a/backend/api/mcp/tool_skill.go+++ b/backend/api/mcp/tool_skill.go@@ -32,7 +32,7 @@ const getSkillDescription = `Get step-by-step guides for Bytebase tasks.**Workflow:** get_skill("task") → search_api(operationId) → call_api(...)-Skills: execute-sql, create-instance, create-project, schema-change`+Skills: query, database-change, grant-permission`func (s *Server) registerSkillTool() {mcp.AddTool(s.mcpServer, &mcp.Tool{diff --git a/backend/api/mcp/tool_skill_test.go b/backend/api/mcp/tool_skill_test.goindex 478da44047..1a8e6271f4 100644--- a/backend/api/mcp/tool_skill_test.go+++ b/backend/api/mcp/tool_skill_test.go@@ -24,8 +24,8 @@ func TestGetSkillListSkills(t *testing.T) {text := result.Content[0].(*mcpsdk.TextContent).Textrequire.Contains(t, text, "Available Skills")- require.Contains(t, text, "execute-sql")- require.Contains(t, text, "create-instance")+ require.Contains(t, text, "query")+ require.Contains(t, text, "database-change")}func TestGetSkillSpecificSkill(t *testing.T) {@@ -33,9 +33,9 @@ func TestGetSkillSpecificSkill(t *testing.T) {s, err := NewServer(nil, profile, "test-secret")require.NoError(t, err)- // Test getting execute-sql skill+ // Test getting query skillresult, _, err := s.handleGetSkill(context.Background(), nil, SkillInput{- Skill: "execute-sql",+ Skill: "query",})require.NoError(t, err)require.NotNil(t, result)@@ -70,7 +70,7 @@ func TestGetSkillAllSkillsLoadable(t *testing.T) {s, err := NewServer(nil, profile, "test-secret")require.NoError(t, err)- skills := []string{"execute-sql", "create-instance", "create-project", "schema-change"}+ skills := []string{"query", "database-change", "grant-permission"}for _, skill := range skills {t.Run(skill, func(t *testing.T) {result, _, err := s.handleGetSkill(context.Background(), nil, SkillInput{