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

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

Mark all MCP tools as read-only using the MCP specification's
readOnlyHint annotation. This enables compatibility with Cursor's
Ask mode and other MCP clients that restrict tool usage based on
whether tools modify their environment.

All 7 tools (search_code, list_commits, list_repos, read_file,
list_tree, list_language_models, ask_codebase) are now annotated
with readOnlyHint: true in both the built-in web server and the
standalone npm package.

Fixes #SOU-707

Co-authored-by: Michael Sukkarieh <msukkari@users.noreply.github.com>

* docs: add CHANGELOG entry for MCP read-only annotations

Co-authored-by: Michael Sukkarieh <msukkari@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Michael Sukkarieh <msukkari@users.noreply.github.com>

Author: msukkari

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Added read-only annotations to MCP tools for compatibility with Cursor Ask mode and other MCP clients that restrict tool usage based on behavior hints. [#1013](https://github.com/sourcebot-dev/sourcebot/pull/1013)
+
 ## [4.15.8] - 2026-03-17
 
 ### Added

packages/mcp/src/index.ts

@@ -69,6 +69,7 @@ server.tool(
             .transform((val) => (val < env.DEFAULT_MINIMUM_TOKENS ? env.DEFAULT_MINIMUM_TOKENS : val))
             .optional(),
     },
+    { readOnlyHint: true },
     async ({
         query,
         filterByRepos: repos = [],
@@ -186,6 +187,7 @@ server.tool(
     "list_commits",
     dedent`Get a list of commits for a given repository.`,
     listCommitsQueryParamsSchema.shape,
+    { readOnlyHint: true },
     async (request: ListCommitsQueryParamsSchema) => {
         const result = await listCommits(request);
 
@@ -201,6 +203,7 @@ server.tool(
     "list_repos",
     dedent`Lists repositories in the organization with optional filtering and pagination.`,
     listReposQueryParamsSchema.shape,
+    { readOnlyHint: true },
     async (request: ListReposQueryParams) => {
         const result = await listRepos(request);
 
@@ -226,6 +229,7 @@ server.tool(
     "read_file",
     dedent`Reads the source code for a given file.`,
     fileSourceRequestSchema.shape,
+    { readOnlyHint: true },
     async (request: FileSourceRequest) => {
         const response = await getFileSource(request);
 
@@ -249,6 +253,7 @@ server.tool(
     Returns a flat list of entries with path metadata and depth relative to the requested path.
     `,
     listTreeRequestSchema.shape,
+    { readOnlyHint: true },
     async ({
         repo,
         path = '',
@@ -395,6 +400,7 @@ server.tool(
     "list_language_models",
     dedent`Lists the available language models configured on the Sourcebot instance. Use this to discover which models can be specified when calling ask_codebase.`,
     {},
+    { readOnlyHint: true },
     async () => {
         const models = await listLanguageModels();
 
@@ -424,6 +430,7 @@ server.tool(
     This is a blocking operation that may take 30-60+ seconds for complex questions as the agent researches the codebase.
     `,
     askCodebaseRequestSchema.shape,
+    { readOnlyHint: true },
     async (request: AskCodebaseRequest) => {
         const response = await askCodebase(request);
 

packages/web/src/features/mcp/server.ts

@@ -76,6 +76,7 @@ export function createMcpServer(): McpServer {
         "search_code",
         {
             description: TOOL_DESCRIPTIONS.search_code,
+            annotations: { readOnlyHint: true },
             inputSchema: {
                 query: z
                     .string()
@@ -230,6 +231,7 @@ export function createMcpServer(): McpServer {
         "list_commits",
         {
             description: TOOL_DESCRIPTIONS.list_commits,
+            annotations: { readOnlyHint: true },
             inputSchema: z.object({
                 repo: z.string().describe("The name of the repository to list commits for."),
                 query: z.string().describe("Search query to filter commits by message content (case-insensitive).").optional(),
@@ -268,6 +270,7 @@ export function createMcpServer(): McpServer {
         "list_repos",
         {
             description: TOOL_DESCRIPTIONS.list_repos,
+            annotations: { readOnlyHint: true },
             inputSchema: z.object({
                 query: z.string().describe("Filter repositories by name (case-insensitive)").optional(),
                 page: z.number().int().positive().describe("Page number for pagination (min 1). Default: 1").optional().default(1),
@@ -308,6 +311,7 @@ export function createMcpServer(): McpServer {
         "read_file",
         {
             description: TOOL_DESCRIPTIONS.read_file,
+            annotations: { readOnlyHint: true },
             inputSchema: {
                 repo: z.string().describe("The repository name."),
                 path: z.string().describe("The path to the file."),
@@ -341,6 +345,7 @@ export function createMcpServer(): McpServer {
         "list_tree",
         {
             description: TOOL_DESCRIPTIONS.list_tree,
+            annotations: { readOnlyHint: true },
             inputSchema: {
                 repo: z.string().describe("The name of the repository to list files from."),
                 path: z.string().describe("Directory path (relative to repo root). If omitted, the repo root is used.").optional().default(''),
@@ -480,6 +485,7 @@ export function createMcpServer(): McpServer {
         "list_language_models",
         {
             description: TOOL_DESCRIPTIONS.list_language_models,
+            annotations: { readOnlyHint: true },
         },
         async () => {
             const models = await getConfiguredLanguageModelsInfo();
@@ -491,6 +497,7 @@ export function createMcpServer(): McpServer {
         "ask_codebase",
         {
             description: TOOL_DESCRIPTIONS.ask_codebase,
+            annotations: { readOnlyHint: true },
             inputSchema: z.object({
                 query: z.string().describe("The query to ask about the codebase."),
                 repos: z.array(z.string()).optional().describe("The repositories accessible to the agent. If not provided, all repositories are accessible."),