Core Tool Reference

eye ships five MCP tools.

get_project_structure

Returns a bounded read-only tree and skips generated paths such as build, dist, out, .eye, and similar defaults.

Configured sourceRoots are ordered before sibling directories so source folders stay visible in bounded results.

Use it first when the repository is unfamiliar. It does not create .eye runtime state.

read_source_range

Reads a file around a requested 1-based line with numbered output.

Use it when the file is already known and you need exact local context instead of full-file reads. filePath is relative to projectRoot.

query_symbol

Offers one symbol-query surface for definition, references, and context.

• the easiest first call is target: "Name" with action: "definition"
• canonical target.by can be anchor, symbolId, or symbol
• { "name": "Name" } and { "by": "name", "name": "Name" } are accepted as symbol-name shorthands
• the response always returns matches
• action: "context" also returns a bounded context block for the best definition
• anchor definitions, anchor references, and symbolId references try semantic navigation first, then fall back to indexed or ripgrep-backed results when needed

The fastest sequence is to resolve by name first, then reuse the returned symbolId.

{
  "name": "query_symbol",
  "arguments": {
    "target": "helper",
    "action": "definition"
  }
}

Then follow up with the returned symbolId:

{
  "name": "query_symbol",
  "arguments": {
    "target": {
      "by": "symbolId",
      "symbolId": "sym:typescript:src/utils/helper.ts:helper:1"
    },
    "action": "references"
  }
}

refresh_index

Creates or refreshes the .eye cache for the whole root or a narrowed scope.

Use it after repository changes or when you want a deterministic indexing pass before deeper navigation.

get_index_status

Reports generation, counts, and cache state.

This path is read-only and returns an idle zero-value summary when no cache exists yet.

Scope limits

• single project root only
• lazy .eye/ initialization under the target repository
• persistent cache in .eye/cache.db
• content-addressed sidecar blobs in .eye/blobs/
• generated .eye/.gitignore keeps runtime cache files local while .eye/config.json remains visible
• Universal Ctags for index-backed symbol extraction

Next step: frequently asked questions.