feat(mcp): add readOnlyHint annotations to all MCP tools

[msukkari]

Summary

This PR adds readOnlyHint: true annotations to all MCP (Model Context Protocol) tools in Sourcebot. This enables compatibility with Cursor's Ask mode and other MCP clients that restrict tool usage based on whether tools modify their environment.

Problem

MCP tools in Sourcebot were not working in Cursor Ask mode because Cursor couldn't detect that our tools are read-only. According to the MCP specification, tools should include annotations to indicate their behavior characteristics.

Solution

Added readOnlyHint: true annotation to all 7 MCP tools in both implementations:

Built-in server (packages/web/src/features/mcp/server.ts):

• search_code
• list_commits
• list_repos
• read_file
• list_tree
• list_language_models
• ask_codebase

Standalone npm package (packages/mcp/src/index.ts):

• Same 7 tools

The readOnlyHint annotation is part of the MCP specification's ToolAnnotations interface and indicates that a tool does not modify its environment. All Sourcebot MCP tools are inherently read-only since they only query/read data.

Testing

• Verified both packages build successfully
• Confirmed all 7 tools in both implementations have the annotation
• Verified the annotations are properly exposed when tools are listed via the MCP protocol

Fixes #SOU-707

Linear Issue: SOU-707

  

Summary by CodeRabbit

• New Features

  • Added read-only annotations to MCP tools, enabling compatible clients to properly identify and handle read-only operations.

• Documentation

  • Updated changelog documenting read-only tool annotations for enhanced client compatibility.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: fc14dc5d-d617-4c96-b66a-11b4ab2ab7f3

📥 Commits

Reviewing files that changed from the base of the PR and between 71f0ffc and 9c063ce.

📒 Files selected for processing (3)

• CHANGELOG.md
• packages/mcp/src/index.ts
• packages/web/src/features/mcp/server.ts

---

Walkthrough

This PR adds read-only hint annotations to MCP tools across two implementation files and updates the changelog. Seven tools (search_code, list_commits, list_repos, read_file, list_tree, list_language_models, ask_codebase) are marked as read-only to support MCP clients that restrict tool usage based on behavior hints.

Changes

Cohort / File(s)	Summary
Documentation CHANGELOG.md	Added entry documenting the addition of readOnlyHint annotations to MCP tools for supporting Cursor Ask mode and other MCP clients.
MCP Server Tool Registration packages/mcp/src/index.ts	Added { readOnlyHint: true } parameter to 7 tool registrations: search_code, list_commits, list_repos, read_file, list_tree, list_language_models, and ask_codebase.
Web MCP Server Tool Registration packages/web/src/features/mcp/server.ts	Added annotations: { readOnlyHint: true } field to tool descriptors for the same 7 tools.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• feat(mcp): add list_tree tool #870: Directly modifies the same MCP tool declarations to add readOnlyHint annotations, including the newly introduced list_tree tool.
• fix(mcp): modify ask_codebase prompt to require explicit call out #995: Both PRs modify tool registrations in packages/web/src/features/mcp/server.ts, including ask_codebase tool definitions.

Suggested reviewers

• brendan-kellam

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/SOU-707-mcp-read-only-detection-ecd0

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

You can make CodeRabbit's review stricter and more nitpicky using the `assertive` profile, if that's what you prefer.

Change the reviews.profile setting to assertive to make CodeRabbit's nitpick more issues in your PRs.