Skip to main content
Glama

Cortex Browser MCP

Automazione browser per agenti AI: letture mirate e azioni in batch, usando Chromium tramite Playwright e il protocollo MCP su stdio.

Cortex punta a ridurre il contesto superfluo e i passaggi tra agente e browser: apri una pagina, leggi i controlli o i dati necessari, esegui più azioni e verifiche in una chiamata. Il profilo predefinito espone quattro tool.

Prima prova dell'autore con Codex: circa +70% di velocità stimata e 20% in meno di quota consumata nella finestra di 5 ore rispetto a Playwright MCP. L'autore ha dato lo stesso prompt a Codex una volta con Playwright MCP e una con Cortex, confrontando minutaggio e variazione della quota. È un risultato riferito dall'autore su quel confronto, non ancora riprodotto indipendentemente. La quota osservata non è un conteggio diretto dei token.

Stato: anteprima 0.2.0-dev.1. Funzioni e limiti in evolution.md. Codice source available: uso e modifiche consentiti, rivendita e servizi Cortex a pagamento vietati senza accordo separato. Vedere licenza, spiegazione e provenienza.

Cosa fa

Tool base

Uso

cortex_open

Apre un URL autorizzato, senza snapshot automatico.

cortex_peek

Cerca controlli, legge griglie o estrae campi selezionati con limiti e paginazione.

cortex_run

Esegue azioni e assert in batch, anche su record ripetuti con each.

cortex_debug

Restituisce diagnostica compatta, salva uno screenshot su richiesta e chiude sessioni isolate.

Esempi: compilare form, verificare flussi AJAX, leggere tabelle, espandere sezioni ripetute e controllare il risultato senza rileggere ogni volta tutta la pagina.

Profili opzionali aggiungono screenshot inline MCP, ispezione DOM/CSS/accessibilità, capture preventiva di rete/console e strumenti di sviluppo. JavaScript arbitrario, debugger e profiling richiedono permessi espliciti dell'host. Vedere funzioni e limiti.

Related MCP server: MCP Browser Bridge

Installazione da sorgente

Richiede Node >=24.22.1 <25 e npm >=11.19.1. La versione Node di riferimento è in .nvmrc. Serve anche il Chromium della versione Playwright fissata nel lockfile.

Dalla cartella del progetto:

npm ci --ignore-scripts
npm run browser:install

Su Linux, se mancano librerie di sistema, usare npx playwright install --with-deps chromium con le autorizzazioni necessarie. L'avvio MCP non scarica browser automaticamente.

Collegamento al client MCP

Adatta il percorso assoluto e gli origin autorizzati nell'esempio JSON:

{
  "mcpServers": {
    "cortex": {
      "command": "node",
      "args": ["C:/cortex/bin/cortex.mjs"],
      "env": {
        "CORTEX_ALLOWED_ORIGINS": "http://127.0.0.1:8080"
      }
    }
  }
}

Su Linux/macOS sostituisci il percorso con quello del checkout. Se il client non trova Node, usa il percorso assoluto del suo eseguibile. Il file va nella configurazione del tuo client: non è letto automaticamente da Cortex.

Gli origin sono esatti, inclusa la porta, senza slash finale. Autorizza anche API, asset o destinazioni di login esterni necessari alla pagina. Nessuna wildcard. Senza origin validi le chiamate browser sono rifiutate.

Per una prova manuale in PowerShell:

$env:CORTEX_ALLOWED_ORIGINS = 'http://127.0.0.1:8080'
node bin/cortex.mjs

Il processo attende un client MCP su stdio: non apre una pagina web e non stampa un banner. Il browser viene avviato alla prima chiamata valida, dopo initialize e tools/list.

Il .env del progetto viene letto solo passando --project <percorso-assoluto> oppure project_path al tool. Il solo fatto di avviare Cortex dalla cartella contenente .env non lo carica. Altri dettagli: configurazione.

Flusso di utilizzo

  1. Chiama cortex_open con url e newSession: true.

  2. Conserva il sessionId restituito e passalo alle chiamate successive.

  3. Usa cortex_peek per ottenere controlli e ref correnti.

  4. Esegui azioni e verifiche con cortex_run.

  5. Chiudi con cortex_debug e closeSession: true.

Esempio di argomenti per cortex_run, dopo aver verificato i target nella pagina:

{
  "sessionId": "ID_RESTITUITO_DA_CORTEX_OPEN",
  "operationId": "ricerca-1",
  "steps": [
    {"op": "fill", "target": "label:Nome", "value": "Mario"},
    {"op": "click", "target": "role:button|Cerca"},
    {"op": "expect_text", "target": "#status", "value": "Ricerca completata"}
  ]
}

Un batch ammette fino a 25 step e 200 operazioni atomiche, con budget di 60 secondi. Non è una transazione: gli effetti già prodotti rimangono anche se uno step fallisce. Dopo timeout o cancellazione verifica lo stato prima di riprovare. operationId consente di riconoscere duplicati nella stessa sessione, entro le quote del registro; non è una garanzia di esecuzione unica dell'applicazione remota.

Verifica e risoluzione problemi

npm test

Il gate esegue unit test, integrazione Chromium/stdio, lifecycle, profili estesi e installazione del tarball in un consumer temporaneo. Usa fixture locali; richiede Chromium installato e accesso al registry npm per il consumer.

Ultima verifica locale: Windows x64 con Node 24.22.1 e npm 11.20.0, 38 test unitari, 19 scenari MCP estesi e gate completo superati. La matrice GitHub Actions include Linux, Windows e macOS; questi risultati locali non certificano gli altri sistemi.

Problema

Controllo

EBADENGINE

Controlla node --version e npm --version, anche nel processo avviato dal client.

Chromium non installato

Esegui npm run browser:install nella cartella Cortex.

Origin non consentito

Controlla schema, host, porta e origin di redirect/API/asset.

Il terminale sembra fermo

È normale: stdio attende richieste MCP.

Un ref non è più valido

Esegui un nuovo peek mirato e riprendi dallo step fallito.

Efficienza e confronto

Le scelte concrete sono letture selettive, nessuno snapshot automatico all'apertura, catalogo base di quattro tool e batch di azioni/assert. Possono ridurre dati restituiti e chiamate MCP nei flussi adatti.

La prima prova dell'autore con Codex ha riportato il vantaggio indicato sopra; non è ancora disponibile un benchmark comparativo riproducibile che ne stabilisca la generalità o misuri il risparmio in token e costo. Il pilot incluso misura solo Cortex su una fixture sintetica, senza modello AI o conteggio token, ed è distinto dalla prova dell'autore. Playwright MCP offre a sua volta opzioni per ridurre gli snapshot.

Cortex usa Chromium, stdio locale e una coda globale: non offre esecuzione browser parallela, attach al browser personale, Firefox/WebKit o un servizio MCP remoto multiutente.

Documentazione

Il package resta private: true: la pubblicazione su npm è disabilitata. I rapporti interni, i file ambiente, i profili e gli artifact locali sono esclusi dal repository previsto tramite .gitignore; i file distribuibili via npm sono limitati anche dal campo files di package.json.

Available Tools

4 tools
cortex_debugC
Destructive

Diagnostica compatta senza contenuti console/rete; screenshot locale solo con screenshot=true.

Inputs: sessionId, screenshot, closeSession, project_path.

cortex_openC
Destructive

Apri URL autorizzato nella sessione condivisa; nessuno snapshot automatico.

Inputs: url (required), observe, sessionId, newSession, +1 more.

cortex_peekB
Read-onlyIdempotent

Controlli/griglie o estrazione mirata. Usa i ref restituiti; dopo navigazione o sostituzione AJAX aggiorna quelli necessari. scope opzionale: CSS di un solo contenitore verificato. items: CSS dei record ripetuti. fields maxLength 1..500 (default 300). Niente HTML o valori input.

Inputs: mode, frame, items, limit, +9 more.

cortex_runB
Destructive

Azioni/assert e piani each/expand/extract. Target: ref:s1-e1 o s1-e1; CSS; role:button|Nome, label:Nome. each/extract solo CSS; each limit max 50; fields maxLength 1..500. 25 step/200 azioni/60s. StaleRef/AmbiguousTarget: step non eseguito, max 5 candidati correnti; scegli il controllo e riprendi dallo step fallito senza ripetere quelli completati.

Inputs: steps (required), frame, sessionId, operationId, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 4 tools

    Disambiguation4/5

    The four tools map to distinct phases: open navigates, peek reads/extracts, run performs actions/asserts, and debug diagnoses. However, peek and run both support extraction, so an agent could reasonably hesitate between them when the task is only to extract data.

    Naming Consistency5/5

    All tools use the same cortex_ prefix followed by a short lowercase verb. The pattern is fully predictable across open, peek, run, and debug.

    Tool Count5/5

    Four tools is lean but appropriate for a focused browser automation server. Each tool covers a distinct interaction phase and none appears redundant.

    Completeness4/5

    The set covers the core browser loop: navigation, inspection/extraction, actions/assertions, and diagnostics. Minor gaps exist around explicit session close/history or standalone screenshot control, but they are workable through the provided tools.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Token-optimized Playwright MCP server that reduces context window usage by 73.8% by grouping 22 tools into 6 semantic operations, enabling AI assistants to control browsers with minimal token overhead.
      13 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to control, read, and verify a live Chrome browser through 46 schema-validated MCP tools, including DOM pruning, coordinate-aware interaction, and trusted CDP input events.
      77 npm
      41
      AGPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to drive a Chromium browser through MCP, with persistent sessions, compact page snapshots, guarded actions, batched operations, and explicit result verification.
      16
      MIT