convez.ai
MCP ServerDesenvolvimento WebIntermediário
mym0404

Eye MCP - Navegador de Código para Agentes

mym0404/eye

Navegação semântica de código-fonte para agentes em repositórios grandes

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que fornece navegação semântica em repositórios locais para agentes de IA. Oferece tools para explorar estrutura de projetos, ler código fonte, resolver símbolos e manter índice atualizado usando Universal Ctags e ripgrep.

Instalação

$npx convez-ai mym0404/eye

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Explorar estrutura de repositórios desconhecidos
  • Resolver definições e referências de símbolos em TypeScript/JavaScript
  • Ler trechos de código com contexto de linha numerada
  • Indexar projetos para navegação determinística e rápida

Veredito

MCP server robusto e bem-documentado para agentes navegarem código em larga escala. Requer dependências externas (ctags, ripgrep) mas oferece semântica superior ao text search puro, ideal para automação de refatoração e análise de código.

README

A tradução para o português deste README ainda está na fila.

eye-mcp

codecov

eye-mcp is a source-browsing MCP server for coding agents working in large local repositories.

Public docs: mym0404.github.io/eye

What It Does

ToolWhat it does
get_project_structureStart here on unfamiliar repositories. Returns a bounded read-only tree and does not create .eye.
read_source_rangeReads project-root-relative source around a 1-based line with numbered output.
query_symbolResolves definition, references, and context from a symbol-name shorthand, anchor, symbolId, or canonical symbol target.
refresh_indexCreates or refreshes the local .eye cache for the whole project or a narrowed scope.
get_index_statusReports cache generation, counts, and readiness without creating .eye.

Quick Start

Requirements:

  • Node.js 20+
  • Universal Ctags on PATH as ctags
  • ripgrep on PATH as rg

Install prerequisites:

  • macOS: brew install universal-ctags ripgrep
  • Ubuntu 24.04: sudo apt-get update && sudo apt-get install --yes universal-ctags ripgrep

Run the published package:

npx -y eye-mcp

Add It To Your Agent

Codex

codex mcp add eye -- npx -y eye-mcp

Claude Code

claude mcp add --scope project eye -- npx -y eye-mcp

Generic .mcp.json

{
  "mcpServers": {
    "eye": {
      "command": "npx",
      "args": ["-y", "eye-mcp"]
    }
  }
}

How query_symbol Works

query_symbol always returns matches. When action is context, it also returns one bounded context block for the first match.

Current behavior:

  • anchor definitions, anchor references, and symbolId references try semantic navigation first
  • if semantic resolution throws or returns nothing useful, the query falls back to indexed rows and then lower-confidence text search when needed
  • semantic reference results do not infer symbolId from usage-site proximity
  • when a symbolId target resolved successfully, semantic reference matches reuse that requested symbolId and indexed symbol name
  • merged reference candidates are deduped by filePath:line:column before truncation

Typical flow:

  1. get_project_structure
  2. read_source_range
  3. query_symbol with target: "Name" and action: "definition"
  4. reuse the returned symbolId for references or context
  5. refresh_index when the repository changed or you want a deterministic refresh

Quick symbol-name lookup:

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

Anchor lookup is still available when the agent already has a source location:

{
  "name": "query_symbol",
  "arguments": {
    "target": {
      "by": "anchor",
      "filePath": "src/main.ts",
      "line": 42,
      "column": 17
    },
    "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",
    "includeDeclaration": false
  }
}

Project Root And Cache

eye works on one project root at a time.

Root detection order:

  1. explicit projectRoot
  2. nearest ancestor with .eye/config.json
  3. nearest workspace root such as .git, pnpm-workspace.yaml, or turbo.json
  4. nearest project root such as package.json, tsconfig.json, jsconfig.json, pyproject.toml, or setup.py
  5. server process cwd

On the first index-backed operation, eye creates .eye/config.json and fills sourceRoots with inferred relative paths such as src, app, or packages/web/src.

sourceRoots controls indexing and helps get_project_structure show source roots before sibling directories. Structure and source reads still work across the whole resolved project root.

Runtime init also creates .eye/.gitignore, which keeps local cache files out of Git while leaving .eye/config.json visible.

Limitations

  • indexing is lazy and query-triggered; there is no watch mode
  • name-based lookups can still be ambiguous
  • context is bounded for navigation, not whole-file dumping
  • the persisted index is ctags-backed, so some queries can still fall back to lower-confidence text search
Ver o original no GitHub

Bom para

Relacionados