[Bug]: indexCheck reports false COLLSCAN on sharded (Mongo) clusters — usesIndex() doesn't handle SINGLE_SHARD explain shape

[jdesilvio]

Version

2.1.1

App

• Cursor
• Windsurf
• VSCode
• VSCode Insiders
• Claude Desktop
• Other

Affected Models (if applicable)

• Claude 3.5 Sonnet
• Claude 3.7 Sonnet
• GPT-4a
• o4-mini
• Other

Bug Description

Summary

MDB_MCP_INDEX_CHECK=true rejects find queries with ForbiddenCollscan
even when the winning plan is a clean IXSCAN, whenever the server is
connected to a sharded Atlas cluster (mongos). The check is a false
positive — the underlying query is indexed.

Root cause

usesIndex() in src/helpers/indexCheck.ts only walks a flat
winningPlan.stage → winningPlan.inputStage.stage → ... chain. It has
no handling for the SINGLE_SHARD (mongos) explain shape, where the real
plan is nested under winningPlan.shards[i].winningPlan instead of
winningPlan.inputStage:

{
  "queryPlanner": {
    "winningPlan": {
      "stage": "SINGLE_SHARD",
      "shards": [{
        "winningPlan": {
          "stage": "LIMIT",
          "inputStage": {
            "stage": "FETCH",
            "inputStage": { "stage": "IXSCAN", "indexName": "..." }
          }
        }
      }]
    }
  }
}

Since winningPlan.stage is "SINGLE_SHARD" (not in indexScanStages,
not "COLLSCAN") and winningPlan.inputStage is undefined, the
function falls through every branch to return false — reporting a real
IXSCAN as "no index used."

Steps to reproduce

1. Connect the MCP server to a sharded Atlas cluster with
   MDB_MCP_INDEX_CHECK=true.
2. Run find with a filter that has a matching single- or compound-field
   index, e.g. { "product.productId": "X" } with an index on
   product.productId.
3. Confirm via the explain tool that the winning plan is IXSCAN.
4. find still throws:
   Index check failed: ... performs a collection scan (COLLSCAN) ...

Expected behavior

usesIndex() should recognize SINGLE_SHARD/MULTI_SHARD winning
plans and recurse into winningPlan.shards[i].winningPlan (checking all
shards) instead of only winningPlan.inputStage.

Environment

• MongoDB Atlas, sharded cluster (mongos), server version 8.0.30
• Reproduced identically on two independent clusters/environments
• Confirmed NOT collection- or query-specific: reproduced across
  multiple databases, collections, and indexes (single-field and
  compound) on the same clusters
• A non-sharded replica-set connection did not show the issue

Workaround

Setting MDB_MCP_INDEX_CHECK=false unblocks all queries (expected,
since it disables the check).

[github-actions]

Thanks for opening this issue. The ticket MCP-647 was created for internal tracking.