[ENHANCEMENT] server Instructions support of MCP server config

[liHai001]

Problem (one or two sentences)

It seems Roo code mcp_settings.json does not support serverInstructions for each MCP server configuration?

like other chatbot MCP server:
type: streamable-http
url: xxx
serverInstructions: "xxx"

Context (who is affected and when)

i have configured serverInstructions param, and it does not work.

Desired behavior (conceptual, not technical)

support mcp server server Instructions param

Constraints / preferences (optional)

No response

Request checklist

• I've searched existing Issues and Discussions for duplicates
• This describes a specific problem with clear context and impact

Roo Code Task Links (optional)

No response

Acceptance criteria (optional)

No response

Proposed approach (optional)

No response

Trade-offs / risks (optional)

No response

[roomote]

I've analyzed this issue and here's my proposed implementation plan:

Current state: The McpServer type already has an instructions?: string field (in packages/types/src/mcp.ts), but it is only populated from the MCP protocol's server-provided instructions via client.getInstructions() (in src/services/mcp/McpHub.ts). There is no way for users to specify custom instructions per server in mcp_settings.json.

Proposed changes:

1. Add serverInstructions to the Zod config schema (src/services/mcp/McpHub.ts - BaseConfigSchema): Add an optional serverInstructions: z.string().optional() field so it is accepted during config validation.

2. Merge config instructions with protocol instructions (src/services/mcp/McpHub.ts - connectToServer method, around line 881): After connecting, combine the user-defined serverInstructions from config with the protocol-provided instructions from client.getInstructions(). The config-defined instructions would take precedence (or be appended), so users can override or supplement what the server itself provides.

3. Also set instructions on placeholder (disabled) connections (src/services/mcp/McpHub.ts - createPlaceholderConnection): Ensure the serverInstructions from config is visible even on disabled servers in the UI.

4. Update tests (src/services/mcp/__tests__/McpHub.spec.ts): Add test cases verifying that serverInstructions from config is correctly parsed, validated, and applied to the server connection.

Config example after this change:

{
  "mcpServers": {
    "my-server": {
      "type": "streamable-http",
      "url": "https://example.com/mcp",
      "serverInstructions": "Custom instructions for this server"
    }
  }
}

This approach keeps backward compatibility (the field is optional) and allows the user-defined instructions to supplement or override the protocol-provided server instructions.

Please mention @roomote in a comment saying that you approve this plan, and I'll proceed with the implementation.

[liHai001]

@roomote i think your proposed is good.
Because we want get same serverInstructions features in the Roo code mcp_settings.json configuration just as Librechat chatbot did: https://www.librechat.ai/docs/features/mcp

[roomote]

Thanks for the approval @liHai001! I've seen your comment and will proceed with the implementation. I'll open a draft PR shortly to share progress.

[roomote]

Opened a draft PR with my attempt at implementing this: #11826

The PR adds an optional serverInstructions field to the MCP server config schema. Config-defined instructions take precedence and are combined with protocol-provided instructions when both exist. Feedback welcome!

[liHai001]

@roomote hi, when do you release, so that i can test this feature by downloading new version of Roo code extension in the VS-code market?

[roomote]

Hi @liHai001, thanks for following up! The implementation PR (#11826) has all CI checks passing and is awaiting review from the maintainers. Once it gets reviewed and merged, it would be included in the next release of the Roo Code extension on the VS Code marketplace. I don't have control over the release schedule, but the PR is ready for review. You can subscribe to the PR to get notified when it's merged. In the meantime, if you'd like to test it early, you could build the extension from the PR branch locally.