Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

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.md
deleted file mode 100644
index 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.md
deleted file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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": [
+ ]
+ }
+ ]
+ }
+})
+```
+
+**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.md
similarity index 98%
rename from backend/api/mcp/skills/execute-sql.md
rename to backend/api/mcp/skills/query.md
index 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: query
description: Run SQL queries on databases
---
diff --git a/backend/api/mcp/skills/schema-change.md b/backend/api/mcp/skills/schema-change.md
deleted file mode 100644
index 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.go
index 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.go
index 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).Text
require.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 skill
result, _, 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{