fix(mcp)!: replace the stale skills with server instructions - #21552

Ships in the same release as #21551, which makes query_database, get_schema and propose_database_change work for users whose access comes only from project roles. The query skill removed here was their only path until then.

This removes the MCP server's two embedded skills, query and database-change, and the get_skill tool that served them. It adds static server instructions that route an agent to the right tool.

The skills taught the wrong path:

• query.md:30 lists databases across the whole workspace, and the skill never mentions query_database. It also says dataSourceId is required (query.md:54). SQLService/Query picks a data source when the request has none.
• database-change.md:119 tells the agent to create the rollout itself, right after it creates the issue.
• database-change.md:143 tells the agent to add an engine field to the sheet. Sheet has only name, content and content_size.

get_skill served only these two skills, so it goes too. The package's AGENTS.md documented only how to write skills, so it goes with its CLAUDE.md import.

Server instructions

The server sent no instructions before. Now initialize returns a short, static text. It says:

• which tool to use: query_database for reads, get_schema for schemas, propose_database_change for changes, and search_api then call_api for anything else;
• that propose_database_change changes one database per call;
• that under a Read-write policy, query_database can also run DML and DDL, which take effect at once, without an issue or approval;
• that on an instance with a read-only data source, query_database runs every statement through that data source, so changes there go through propose_database_change;
• that a refused call states its reason, and a person acts on it in the Bytebase console.

One server serves every workspace, and an admin can change a workspace's policy at any time. So the text names no workspace and assumes no mode.

The read-only data source sentence is there because query_database always sends the data source selectDataSource picks, and it prefers a read-only one. SQLService/Query keeps an explicit data source, so the write never reaches the admin data source. On PostgreSQL the session is read-only, and an INSERT fails with "cannot execute INSERT in a read-only transaction". Routing writes to the admin data source would change what the tool can do, so it isn't part of this PR.

The single-database note

propose_database_change's description sent multi-database changes to get_skill("database-change"). It now states the single-database limit, and points a change to several databases in one plan to the console or GitOps. The description and the server instructions take that sentence from one constant, so they can't drift apart. This changes guidance, not capability: an agent can still build a multi-database plan through call_api, under the same server checks.

Breaking Changes

• The get_skill MCP tool is removed. A client that calls it gets an unknown-tool error.

Release note: "The MCP get_skill tool is removed. At session start, the MCP server now sends instructions that route agents to query_database, get_schema, propose_database_change, search_api and call_api."

Docs

bytebase.com has no reference to get_skill, the query skill or the database-change skill, on main or on any branch (git grep, 2026-10-02). docs/integrations/mcp.mdx describes the tools without skills, so this PR needs no docs change.

For a later docs PR: docs/integrations/mcp.mdx:118 says the query tool runs INSERT, UPDATE, DELETE, CREATE, ALTER and DROP "within your permissions". It has the same read-only data source gap.

Not in this change

• The page agent has its own get_skill tool and its own skill copies (frontend/src/modules/agent/logic/skills/). They are a separate tool, unchanged here.
• Multi-database support in propose_database_change.

Tests

• TestInitializeServesInstructions opens a session on the real /mcp route. initialize returns the instructions, they name the five routed tools, and tools/list has no get_skill. With the instructions option removed, it fails.
• TestToolGuidanceNamesOnlyRegisteredTools checks the server instructions and every tool description. Each snake_case name outside a quoted example must be a registered tool. With the old propose_database_change note put back, it fails: propose_database_change description names "get_skill", which is not a registered tool.
• TestSkillsOnlyInstructServableCalls checked a different rule: every operation a skill named is one the MCP gate serves. That rule goes with the skills, its only subject.
• Deleted with the tool: TestGetSkillListSkills, TestGetSkillSpecificSkill, TestGetSkillNotFound, TestGetSkillAllSkillsLoadable and TestSkillsOnlyInstructServableCalls.

Receipts

🤖 Generated with Claude Code