convez.ai
MCP ServerBusca & PesquisaAvançado
ferre-z

Eyes-MCP

ferre-z/eyes-mcp

Servidor MCP de pesquisa distribuída com 10 adaptadores de fonte

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP de pesquisa para agentes de IA que executa buscas distribuídas em múltiplas fontes (SearXNG, Crawl4AI, GitHub, Reddit, YouTube, arXiv, etc). Empacotado em Docker, pronto para swarm e sem necessidade de chaves de API, sintetiza respostas com citações automaticamente.

Instalação

$npx convez-ai ferre-z/eyes-mcp

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

  • Pesquisa automatizada e síntese de múltiplas fontes para agentes IA
  • Busca em repositórios técnicos (GitHub, arXiv, Wikipedia) de forma estruturada
  • Augmentação de contexto para agents sem chamar APIs externas em paralelo
  • Serviço compartilhado de pesquisa em ambientes multi-tenant

Veredito

Ferramenta robusta e bem arquitetada para research distribuído em agents. Diferencia-se pela decomposição de tarefas em sub-agents sem LLM, parse em camadas e padrão de artefatos. Pronta para produção em Docker, mas exige Node.js ≥20 e compreensão da arquitetura MCP para customização efetiva.

README

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

Eyes-MCP

build license node mcp

Research MCP for AI agents. Docker-packaged. Swarm-ready. Zero required secrets.

A Model Context Protocol server that does the boring part of "go look this up on the internet" for any MCP-compatible agent. Callers send a question + a few parameters, Eyes-MCP fans out across SearXNG, Crawl4AI, GitHub, Reddit, YouTube, and more, and returns a synthesized answer with citations.


What we're building

flowchart TD
  Caller[Caller] -->|"prompt, depth, max_shards"| MainAgent
  subgraph MainAgent ["[main agent] - the only LLM"]
    MA1[1. Read available sources]
    MA2[2. Decompose prompt into N sub-tasks]
  end
  MainAgent -->|"N shards"| SubAgents
  subgraph SubAgents ["[N sub-agents] - async coroutines, no LLM"]
    SA1[search - SearXNG / GitHub / Reddit / YouTube / ...]
    SA2[fetch - Crawl4AI / API call]
    SA3[write raw output to disk - artifact pattern]
  end
  SubAgents -->|shard_id, path| Parse1
  subgraph Parse1 ["[parse layer 1] - bloat strip, depth-driven"]
    P1[strip HTML, nav, ads, boilerplate]
  end
  Parse1 --> Parse2
  subgraph Parse2 ["[parse layer 2] - chunk + per-shard dedup"]
    P2[chunk by structure then size cap 500 tokens]
    P3[simhash dedup within shard]
  end
  Parse2 -->|chunks grouped by shard_id| Review
  subgraph Review ["[main agent] - reviews and decides"]
    R1{synthesize or spawn more shards?}
  end
  Review -->|"synthesized answer"| Caller
  Review -->|"loop with gap-fill shards"| SubAgents

Decisions locked in:

  • Only the main agent is an LLM. Sub-agents = async coroutines.
  • Sub-agents write raw output to disk. Main agent sees pointers + chunks, not raw.
  • Parse layer 1 = bloat strip. Aggressiveness driven by the depth param.
  • No ranking. Every chunk goes to the main agent.
  • Themes = shards. Main agent's decomposition defines the themes. No re-clustering.
  • Crawl4AI's output is trusted for URL-fetched content — no re-stripping.

Why this is different

There are at least five "SearXNG + Crawl4AI + MCP" wrappers already (see 02-existing-landscape.md). What makes Eyes-MCP not the 6th me-too entry:

DifferentiatorWhat it means
Zero-friction installdocker compose up works with no API keys. LLM is optional.
Shared serviceStreamable HTTP, stateful sessions, multi-tenant. Designed to be a service, not a personal daemon.
Source-aware adaptersGitHub, Reddit, YouTube, academic — each has a dedicated adapter, not a generic search-then-scrape path.
Swarm-readyMain agent + sub-agents + two parse layers wired from day one (swarm flag-gated in v1).
Artifact patternSub-agents write to disk, main agent reads chunks. Token cost is bounded by EYES_TOKEN_BUDGET.

Install (laptop)

git clone https://github.com/ferre-z/eyes-mcp.git
cd eyes-mcp
npm install
npm run build
npm link                 # exposes `eyes` to your PATH
hash -r                  # ensure shell sees the new command
eyes --version           # should print 0.1.0

PATH note: npm link puts eyes in your global npm bin dir. If eyes --version says "command not found", add that dir to PATH. Usually ~/.nvm/versions/node/v*/bin, ~/.hermes/node/bin, or ~/.local/bin depending on your setup. npm config get prefix shows you where.

First-time setup

eyes models pick         # interactive: provider → model → paste API key
eyes doctor              # verify everything

This writes ~/.config/eyes/config.toml. Re-run any time to switch.

Run the server

docker compose up -d     # starts searxng + crawl4ai + redis + eyes-mcp
docker compose logs -f eyes-mcp

Service on http://localhost:8787 — health at /health, MCP at /mcp.

Important: before exposing SearXNG, replace the placeholder secret_key in searxng/settings.yml:

openssl rand -hex 32

Configure

The CLI uses ~/.config/eyes/config.toml (TOML, hand-rolled — no dep). The Docker server uses env vars only.


Configure (env vars — used by the Docker server)

All configuration is via environment variables. See .env.example for the full list with defaults. Highlights:

VariableDefaultPurpose
EYES_HTTP_PORT8787HTTP listen port
EYES_PROVIDERgoogle-ai-studiogoogle-ai-studio or openrouter
EYES_MODELgemma-4-31b-itModel id for the chosen provider
GOOGLE_AI_STUDIO_API_KEY(empty)Optional. If unset, server runs in heuristic-only mode.
OPENROUTER_API_KEY(empty)Optional. Used when EYES_PROVIDER=openrouter.
SEARXNG_URLhttp://searxng:8080Internal SearXNG endpoint
CRAWL4AI_URLhttp://crawl4ai:11235Internal Crawl4AI endpoint
GITHUB_TOKEN(empty)Bumps GitHub REST rate limit 60/hr → 5000/hr
REDDIT_CLIENT_ID / REDDIT_CLIENT_SECRET(empty)PRAW auth (optional)
EYES_MAX_SHARDS5Max shards per request (cap 20)
EYES_MAX_ITERATIONS2Max refinement iterations (cap 5)
EYES_TOKEN_BUDGET80000Token budget for the main agent's context
EYES_TIME_BUDGET_SEC120Wall-clock budget per request

CLI quick reference

eyes                              # open the chat REPL
eyes "your prompt"                # one-shot research
eyes chat "prompt" --depth deep   # one-shot with depth
eyes models list                  # show all free models across providers
eyes models pick                  # interactive: provider + model + key
eyes models current               # show active provider + model
eyes config                       # interactive config editor
eyes config get providers.model   # print a config value (secrets → ***)
eyes config set providers.model llama-3.3-70b
eyes config path                  # print the config file path
eyes init                         # create the config file with defaults
eyes doctor                       # check config + deps + LLM
eyes serve                        # start the MCP HTTP server

Usage

The server speaks the MCP streamable HTTP transport on /mcp and a plain health probe on /health.

curl http://localhost:8787/health
# {"status":"ok","version":"0.1.0","uptime":12,"dependencies":{...}}

MCP clients that work out of the box

  • Claude Desktop — add to claude_desktop_config.json:
    {
      "mcpServers": {
        "eyes": {
          "type": "http",
          "url": "http://localhost:8787/mcp"
        }
      }
    }
    
  • Cursor — same config under MCP servers.
  • MCP Inspector — point at http://localhost:8787/mcp to call tools interactively.
  • Any other MCP client supporting streamable HTTP.

Project layout

Eyes-MCP/
├── src/
│   ├── index.ts          ← HTTP server, /health, /mcp, signal handling (THIS SUBAGENT)
│   ├── health.ts         ← dependency probe (THIS SUBAGENT)
│   ├── util/logger.ts    ← winston logger (THIS SUBAGENT)
│   ├── tools/            ← MCP tool registration (subagent B)
│   ├── main-agent/       ← orchestrator + LLM client  (subagent B)
│   ├── llm/              ← Gemini/Gemma client         (subagent B)
│   ├── dispatcher/       ← shard fan-out + scheduling  (subagent B)
│   ├── adapters/         ← GitHub/Reddit/YouTube/etc.  (subagent C)
│   └── parse/            ← bloat strip + chunking      (subagent C)
├── searxng/              ← SearXNG config
├── data/                 ← runtime artifacts (gitignored)
├── docker-compose.yml
├── Dockerfile
├── package.json
├── tsconfig.json
├── .env.example
├── LICENSE               ← MIT
└── README.md             ← you are here

Status

✅ v0.1.0 — research MCP server, CLI, 10 source adapters, Google AI Studio + OpenRouter providers, full vitest suite (64/64 passing).

See 03-architecture-main-and-swarm.md for the design rationale and 00-brief.md for the one-liner.


License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados