mkdir -p backend/api/mcp/skills

---
name: execute-sql
description: Run SQL queries on databases
---

# Execute SQL

## Overview

Run SQL queries against databases managed by Bytebase.

## Prerequisites

- Know the instance and database name
- Have `bb.databases.query` permission

## Workflow

1. **Get the schema**:

2. **List databases in project** (if needed):

3. **Execute SQL**:

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| database not found | Wrong instance/database name | List databases first |
| permission denied | Missing bb.databases.query | Check user permissions |
| syntax error | Invalid SQL | Check SQL syntax for the database engine |

cat backend/api/mcp/skills/execute-sql.md

---
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**:

2. **List environments** (to get environment resource name):

3. **Create the instance**:

## 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 |

---
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**:

2. **Create the project**:

3. **Add team members** (optional):

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| project already exists | Duplicate projectId | Choose different projectId |
| invalid key | Key format wrong | Use uppercase letters, 2-10 chars |

---
name: schema-change
description: Create schema migration issues
---

# Schema Change

## Overview

Create a schema change issue to modify database structure (DDL) through Bytebase's review workflow.

## Prerequisites

- Have `bb.issues.create` permission
- Know the target database

## Workflow

1. **Get the schema**:

2. **Get database info**:

3. **Create schema change issue**:

## Sheet Creation

Before creating an issue, you may need to create a sheet with the SQL:

## 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 |

package mcp

import (
	"context"
	"testing"

	mcpsdk "github.com/modelcontextprotocol/go-sdk/mcp"
	"github.com/stretchr/testify/require"

	"github.com/bytebase/bytebase/backend/common"
	"github.com/bytebase/bytebase/backend/component/config"
)

func TestGetSkillListSkills(t *testing.T) {
	profile := &config.Profile{Mode: common.ReleaseModeDev}
	s, err := NewServer(nil, profile, "test-secret")
	require.NoError(t, err)

	// Test listing all skills (no parameters)
	result, _, err := s.handleGetSkill(context.Background(), nil, SkillInput{})
	require.NoError(t, err)
	require.NotNil(t, result)
	require.Len(t, result.Content, 1)

	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")
}

func TestGetSkillSpecificSkill(t *testing.T) {
	profile := &config.Profile{Mode: common.ReleaseModeDev}
	s, err := NewServer(nil, profile, "test-secret")
	require.NoError(t, err)

	// Test getting execute-sql skill
	result, _, err := s.handleGetSkill(context.Background(), nil, SkillInput{
		Skill: "execute-sql",
	})
	require.NoError(t, err)
	require.NotNil(t, result)
	require.Len(t, result.Content, 1)

	text := result.Content[0].(*mcpsdk.TextContent).Text
	require.Contains(t, text, "Execute SQL")
	require.Contains(t, text, "SQLService/Query")
	require.Contains(t, text, "Workflow")
}

func TestGetSkillNotFound(t *testing.T) {
	profile := &config.Profile{Mode: common.ReleaseModeDev}
	s, err := NewServer(nil, profile, "test-secret")
	require.NoError(t, err)

	// Test getting non-existent skill
	result, _, err := s.handleGetSkill(context.Background(), nil, SkillInput{
		Skill: "non-existent",
	})
	require.NoError(t, err)
	require.NotNil(t, result)
	require.Len(t, result.Content, 1)

	text := result.Content[0].(*mcpsdk.TextContent).Text
	require.Contains(t, text, "not found")
	require.Contains(t, text, "get_skill()")
}

func TestGetSkillAllSkillsLoadable(t *testing.T) {
	profile := &config.Profile{Mode: common.ReleaseModeDev}
	s, err := NewServer(nil, profile, "test-secret")
	require.NoError(t, err)

	skills := []string{"execute-sql", "create-instance", "create-project", "schema-change"}
	for _, skill := range skills {
		t.Run(skill, func(t *testing.T) {
			result, _, err := s.handleGetSkill(context.Background(), nil, SkillInput{
				Skill: skill,
			})
			require.NoError(t, err)
			require.NotNil(t, result)
			require.Len(t, result.Content, 1)

			text := result.Content[0].(*mcpsdk.TextContent).Text
			require.NotContains(t, text, "not found", "skill %s should be loadable", skill)
			require.NotEmpty(t, text)
		})
	}
}

go test -v -count=1 github.com/bytebase/bytebase/backend/api/mcp -run ^TestGetSkill

package mcp

import (
	"context"
	"embed"
	"fmt"
	"path/filepath"
	"strings"

	"github.com/modelcontextprotocol/go-sdk/mcp"
	"gopkg.in/yaml.v3"
)

//go:embed skills/*.md
var skillFiles embed.FS

// SkillInput is the input for the get_skill tool.
type SkillInput struct {
	// Skill is the name of the skill to retrieve.
	// Leave empty to list all available skills.
	Skill string `json:"skill,omitempty"`
}

// skillMeta holds parsed skill metadata from frontmatter.
type skillMeta struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
}

// getSkillDescription is the description for the get_skill tool.
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`

func (s *Server) registerSkillTool() {
	mcp.AddTool(s.mcpServer, &mcp.Tool{
		Name:        "get_skill",
		Description: getSkillDescription,
	}, s.handleGetSkill)
}

func (s *Server) handleGetSkill(_ context.Context, _ *mcp.CallToolRequest, input SkillInput) (*mcp.CallToolResult, any, error) {
	if input.Skill == "" {
		// List all skills
		text := s.formatSkillList()
		return &mcp.CallToolResult{
			Content: []mcp.Content{&mcp.TextContent{Text: text}},
		}, nil, nil
	}

	// Get specific skill
	text, err := s.getSkillContent(input.Skill)
	if err != nil {
		return &mcp.CallToolResult{
			Content: []mcp.Content{&mcp.TextContent{Text: err.Error()}},
		}, nil, nil
	}

	return &mcp.CallToolResult{
		Content: []mcp.Content{&mcp.TextContent{Text: text}},
	}, nil, nil
}

func (*Server) formatSkillList() string {
	var sb strings.Builder
	sb.WriteString("## Available Skills\n\n")
	sb.WriteString("Use `get_skill(skill=\"name\")` to get the full guide.\n\n")
	sb.WriteString("| Skill | Description |\n")
	sb.WriteString("|-------|-------------|\n")

	entries, _ := skillFiles.ReadDir("skills")
	for _, entry := range entries {
		if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".md") {
			meta := parseSkillMeta(entry.Name())
			if meta != nil {
				sb.WriteString(fmt.Sprintf("| %s | %s |\n", meta.Name, meta.Description))
			}
		}
	}

	return sb.String()
}

func parseSkillMeta(filename string) *skillMeta {
	content, err := skillFiles.ReadFile(filepath.Join("skills", filename))
	if err != nil {
		return nil
	}

	// Parse YAML frontmatter
	str := string(content)
	if !strings.HasPrefix(str, "---") {
		return nil
	}

	end := strings.Index(str[3:], "---")
	if end == -1 {
		return nil
	}

	var meta skillMeta
	if err := yaml.Unmarshal([]byte(str[3:3+end]), &meta); err != nil {
		return nil
	}

	return &meta
}

func (*Server) getSkillContent(skillName string) (string, error) {
	filename := skillName + ".md"
	content, err := skillFiles.ReadFile(filepath.Join("skills", filename))
	if err != nil {
		return "", fmt.Errorf("skill %q not found. Use get_skill() to list available skills", skillName)
	}

	// Strip frontmatter for cleaner output
	str := string(content)
	if strings.HasPrefix(str, "---") {
		if end := strings.Index(str[3:], "---"); end != -1 {
			str = strings.TrimSpace(str[3+end+3:])
		}
	}

	return str, nil
}

go build ./backend/api/mcp/...

func (s *Server) registerTools() {
	s.registerSearchTool()
	s.registerCallTool()
}

func (s *Server) registerTools() {
	s.registerSearchTool()
	s.registerCallTool()
	s.registerSkillTool()
}

go test -v -count=1 github.com/bytebase/bytebase/backend/api/mcp -run ^TestGetSkill

go test -v -count=1 github.com/bytebase/bytebase/backend/api/mcp/...

go mod tidy

golangci-lint run --allow-parallel-runners ./backend/api/mcp/...

go build -ldflags "-w -s" -p=16 -o ./bytebase-build/bytebase ./backend/bin/server/main.go

git add backend/api/mcp/skills/ backend/api/mcp/tool_skill.go backend/api/mcp/tool_skill_test.go backend/api/mcp/server.go

git commit -m "feat(mcp): add get_skill tool for self-documenting guides

Add a get_skill tool that provides step-by-step guides for common
Bytebase tasks. Skills are embedded markdown files following the
Claude skill format with YAML frontmatter.

Initial skills:
- execute-sql: Run SQL queries
- create-instance: Add database instance
- create-project: Set up project
- schema-change: Create schema migrations"