Riferimento Strumenti MCP

VMark espone sette strumenti MCP compositi agli assistenti IA: session, workspace, document, workflow, selection, browser e coherence. Insieme coprono la spina dorsale dell'editor, il ciclo di vita di file/finestre, le modifiche CST-safe ai workflow, le modifiche mirate alla selezione, la navigazione delimitata del browser e una vista in sola lettura del livello di coerenza del workspace.

La precedente superficie di 12 strumenti / 76 azioni è stata ridotta perché gli strumenti di formattazione interni al documento (grassetto, intestazioni, tabelle, ecc.) duplicano un lavoro che gli agenti IA fanno già banalmente tramite il round-trip Markdown. Vedi il piano di riduzione MCP per la motivazione completa.

Flusso di Lavoro Consigliato

Chiama session.get_state una volta per vedere finestre aperte, schede e per ogni scheda {filePath, dirty, revision, kind}.
Per Markdown: document.read → ragionare → document.write (passando expected_revision per concorrenza sicura).
Per YAML di GitHub Actions (kind: "yaml-workflow"): workflow.apply_patch per modifiche CST-safe che preservano commenti e ancore; workflow.validate per la diagnostica actionlint.
Le operazioni sui file (apri, salva, chiudi, cambia scheda) si trovano in workspace.

Diagrammi Mermaid

Quando si usa l'IA per generare diagrammi Mermaid tramite MCP, considera l'installazione del server MCP mermaid-validator — rileva gli errori di sintassi usando gli stessi parser Mermaid v11 prima che i diagrammi raggiungano il tuo documento.

`session`

Orientamento one-shot. Scopri ogni finestra, ogni scheda e le capacità del server in una singola chiamata.

`get_state`

Nessun argomento.

Restituisce {windows, capabilities}:

json

{
  "windows": [
    {
      "label": "main",
      "focused": true,
      "tabs": [
        {
          "id": "tab-1",
          "filePath": "/path/to/notes.md",
          "title": "notes",
          "dirty": false,
          "revision": "rev-x7Q3aB1F",
          "kind": "markdown"
        },
        {
          "id": "tab-2",
          "filePath": "/repo/.github/workflows/ci.yml",
          "title": "ci",
          "dirty": true,
          "revision": "rev-x7Q3aB1F",
          "kind": "yaml-workflow"
        }
      ]
    }
  ],
  "capabilities": {
    "version": "<vmark-mcp-server version>",
    "supportedKinds": ["markdown", "yaml-workflow"],
    "mcpProtocol": "0.2.0"
  }
}

Il discriminatore kind ti dice se usare document.write (per markdown) o workflow.apply_patch (per yaml-workflow) su quella scheda.

`workspace`

Ciclo di vita di file e finestre. Niente all'interno del documento.

`new`

Crea una nuova scheda senza titolo.

Parametro	Tipo	Richiesto	Descrizione
`kind`	stringa	No	`"markdown"` (predefinito) o `"yaml-workflow"`
`windowLabel`	stringa	No	Finestra di destinazione; predefinita su quella in primo piano

Restituisce {tabId}.

`open`

Apri un file da disco.

Parametro	Tipo	Richiesto
`filePath`	stringa	Sì
`windowLabel`	stringa	No

Restituisce {tabId}.

`save`

Salva una scheda nel suo percorso esistente.

Parametro	Tipo	Richiesto
`tabId`	stringa	No (predefinito su quella in primo piano)

Restituisce {filePath, revision}.

`save_as`

Salva una scheda in un nuovo percorso.

Parametro	Tipo	Richiesto
`tabId`	stringa	No
`filePath`	stringa	Sì

Restituisce {revision}.

`close`

Chiude una scheda. Rifiuta di scartare lavoro non salvato senza force.

Parametro	Tipo	Richiesto
`tabId`	stringa	Sì
`force`	booleano	No

Restituisce {closed: true} in caso di successo, {closed: false, reason: "DIRTY"} se la scheda è modificata e force non è stato fornito.

`switch_tab`

Attiva una scheda.

Parametro	Tipo	Richiesto
`tabId`	stringa	Sì

`focus_window`

Porta in primo piano una finestra.

Parametro	Tipo	Richiesto
`windowLabel`	stringa	Sì

`document`

Leggere, scrivere, trasformare. La spina dorsale della superficie.

`read`

Parametro	Tipo	Richiesto
`tabId`	stringa	No (predefinito su quella in primo piano)

Restituisce {content, revision, filePath, kind, dirty}. Leggi sempre prima di scrivere — il token revision deve accompagnare il prossimo write.

`write`

Sostituisce il contenuto completo del documento.

Parametro	Tipo	Richiesto	Descrizione
`tabId`	stringa	No	Scheda di destinazione (predefinito su quella in primo piano)
`content`	stringa	Sì	Nuovo contenuto completo
`expected_revision`	stringa	No	Token di revisione dalla lettura più recente

Se viene fornito expected_revision e il documento è cambiato dopo quella lettura, la risposta è una busta di errore strutturato STALE con la revisione corrente; rileggi e riprova.

json

// successo
{ "revision": "rev-newAfterWrite" }

// stale
{ "error": "STALE", "message": "Document has changed since the last read", "current_revision": "rev-currentNow" }

`transform`

Applica una riscrittura deterministica. Attualmente supporta trasformazioni specifiche CJK (conversione punteggiatura larghezza intera ↔ ASCII, spaziatura CJK ↔ Latino).

Parametro	Tipo	Richiesto	Descrizione
`tabId`	stringa	No	Scheda di destinazione
`kind`	stringa	Sì	`"cjk-format"`, `"cjk-spacing"` o `"cjk-punctuation"`
`expected_revision`	stringa	No	Token di concorrenza

cjk-format applica le impostazioni di formattazione CJK dell'utente end-to-end. cjk-spacing inserisce singoli spazi tra caratteri CJK e Latini/cifre adiacenti. cjk-punctuation converte la punteggiatura ASCII che si trova accanto ai caratteri CJK nella sua forma a larghezza intera.

Restituisce {revision}.

`workflow`

Validazione actionlint e modifiche chirurgiche CST-safe per lo YAML dei workflow GitHub Actions. Disponibile solo per le schede il cui kind è "yaml-workflow".

document.read / document.write funzionano su ogni scheda — incluso lo YAML del workflow

Lo strumento workflow non è un sostituto della spina dorsale lettura/scrittura. Per una scheda di workflow, puoi:

document.read per ottenere il testo YAML grezzo (con tutti i commenti)
document.write per sostituirlo interamente (qualsiasi stringa invii viene memorizzata letteralmente — i commenti vengono preservati se li includi)
workflow.apply_patch quando vuoi che il server stesso garantisca che commenti, ancore e ordine delle chiavi sopravvivano a una modifica parziale

Usa apply_patch quando cambi un campo lasciando tutto il resto intatto (il server non può eliminare i commenti che non modifica). Usa document.write quando stai riscrivendo interamente o generando un nuovo workflow da zero.

`apply_patch`

Applica un array di oggetti IRPatch. Le patch sono inviate attraverso i mutatori CST-aware di VMark, che preservano commenti, ancore e ordine delle chiavi. Un document.write grezzo su un file YAML li perderebbe.

Parametro	Tipo	Richiesto
`tabId`	stringa	No
`patches`	IRPatch[]	Sì
`expected_revision`	stringa	No

IRPatch è un'unione discriminata (campo kind). Tipi supportati:

`kind`	Effetto
`workflow.set`	Imposta i campi top-level (`{path, value}`) — `name`, `env.X`, ecc.
`job.set`	Imposta un campo su un job (`{jobId, path, value}`)
`step.set`	Imposta un campo su uno step (`{jobId, stepIndex, path, value}`)
`with.set`	Imposta una chiave nel blocco `with:` di uno step (`{jobId, stepIndex, key, value}`)
`with.remove`	Rimuove una chiave dal blocco `with:` di uno step
`needs.add` / `needs.remove`	Aggiungi o rimuovi un ID job da `needs:`
`trigger.setFilters`	Sostituisci un array di filtri trigger — branches, paths, types, ecc. (`{event, filter, value: string[]}`)

Restituisce {revision} in caso di successo o una busta di errore strutturato STALE / INVALID_PATCH / NOT_WORKFLOW.

`validate`

Esegui actionlint sullo YAML del workflow.

Parametro	Tipo	Richiesto
`tabId`	stringa	No

Restituisce {ok, diagnostics, binaryAvailable}. Ogni diagnostica trasporta {line, col, message, severity}. binaryAvailable: false significa che actionlint non è installato localmente; installa tramite Homebrew o le release upstream.

`coherence`

Una vista in sola lettura del livello di coerenza del workspace — quali documenti derivati sono obsoleti rispetto alle sorgenti da cui sono stati generati. Nessuna delle due azioni modifica documenti, il registro (ledger) o alcuno stato dell'editor; entrambe sono servite interamente dal backend Rust a partire dal kernel per workspace, quindi funzionano anche quando nessuna finestra dell'editor è in primo piano.

Due ulteriori azioni in sola lettura espongono il livello semantico:

claims — le affermazioni canoniche correnti: {claim, entryId, statement, maturity, invalidAt, visible}. Solo le affermazioni established vincolano le verifiche semantiche; visible riflette il contesto default.
contexts — l'insieme dei contesti (il default implicito è sempre presente): {id, name, parent, enforcement, visibleClaims, errors}.

Un'azione di modifica, regolata dalla delega:

resolve — risolve un arco obsoleto attivo come agente esplicitamente delegato: {workspace_root, txf, input, resolution: "accept-newer" | "waive", reason? (required for waive)}. L'autorizzazione è fail-closed: il proprietario del workspace deve aver concesso alla tua identità di bridge autenticata una delega attiva e non scaduta che copra il tipo di risoluzione (concessa nell'app, dalla vista di dettaglio), e l'arco deve essere attivo. Ogni risoluzione delegata viene registrata nel log di audit a fronte della concessione. La mutazione di affermazioni e contesti non è mai esposta — il canone resta sotto controllo umano.

Tutte le azioni richiedono workspace_root: il percorso assoluto del workspace da interrogare. Ricavalo da session.get_state (il filePath delle schede aperte) o dallo strumento workspace. Un percorso mancante, non assoluto o che non è una directory viene rifiutato con un errore in forma di stringa semplice.

`status`

Contatori di stato del kernel per un workspace.

Parametro	Tipo	Richiesto	Descrizione
`workspace_root`	stringa	Sì	Percorso assoluto del workspace da interrogare

Restituisce:

json

{
  "initialized": true,
  "objects": 12,
  "open_items": 2,
  "quarantined": 0,
  "writer": "0198c0de-0000-7000-8000-000000000001"
}

Campo	Significato
`initialized`	`false` quando il workspace non ha ancora un registro di coerenza (nessuna directory `.vmark/`). In quel caso tutti i contatori tranne `objects` sono 0.
`objects`	Oggetti tracciati (file con un'identità di coerenza).
`open_items`	Archi vivi non freschi — la dimensione corrente del dettaglio.
`quarantined`	Righe malformate del registro messe in quarantena all'ultima lettura.
`writer`	L'ID writer (UUID) di questa installazione.

`edges`

Il dettaglio: ogni arco di dipendenza vivo la cui sorgente si è mossa. Esegue prima una riconciliazione con scansione, quindi la risposta riflette i file su disco al momento della chiamata.

Parametro	Tipo	Richiesto	Descrizione
`workspace_root`	stringa	Sì	Percorso assoluto del workspace da interrogare

Restituisce un array — vuoto quando tutto è coerente:

json

[
  {
    "txf": "0198c0de-0000-7000-8000-00000000000a",
    "input": 0,
    "upstream": "0198c0de-0000-7000-8000-00000000000b",
    "upstream_path": "characters/elena.md",
    "pinned": "rev-a1b2c3",
    "downstream": "0198c0de-0000-7000-8000-00000000000c",
    "downstream_path": "scenes/chapter-3.md",
    "downstream_rev": "rev-d4e5f6",
    "state": "version-stale"
  }
]

Campo	Significato
`txf` / `input`	La voce di trasformazione e lo slot di input che identificano questo arco (passali alle azioni di risoluzione nell'app).
`upstream` / `upstream_path`	L'oggetto da cui dipende il derivato, e il suo ultimo percorso noto.
`pinned`	La revisione della sorgente da cui è stato generato il derivato.
`downstream` / `downstream_path` / `downstream_rev`	L'oggetto derivato, il suo percorso e la sua revisione corrente.
`state`	`"version-stale"`, `"stale-valid"`, `"stale-contradicted"`, `"stale-unknown"`, `"waived"`, `"diverged"`, `"diverged-multi-head"` o `"unpinnable"`.

Risolvere un arco (accept-newer / waive) è un'azione umana eseguita nella vista di dettaglio di VMark — deliberatamente non è esposta via MCP.

Errori

Compaiono due forme di errore:

Errori di dominio — impostano success: false e restituiscono una busta codificata in JSON in error:

json

{ "error": "STALE", "message": "...", "current_revision": "rev-..." }

Errori sulla forma degli argomenti — per argomenti richiesti mancanti/non validi (ad es. document.write senza un campo content), error è una stringa semplice che descrive il problema. La busta strutturata è riservata alle condizioni a livello di dominio.

Codice	Mostrato come	Significato
`STALE`	busta	`expected_revision` non corrispondeva; rileggi e riprova
`INVALID_PATCH`	busta	`workflow.apply_patch` ha ricevuto un array `patches` malformato
`INVALID_TAB`	busta	`tabId` non poteva essere risolto
`INVALID_PATH`	busta	`workspace.open` ha ricevuto un `filePath` che non poteva essere letto
`NOT_WORKFLOW`	busta	`workflow.*` è stato chiamato su una scheda non YAML-workflow
`READ_ONLY`	busta	È stata tentata una mutazione su un documento di sola lettura
`INTERNAL`	busta	Errore inaspettato del gestore
(stringa semplice)	stringa	Argomento richiesto mancante o tipo errato

Riferimento Strumenti MCP ​

session ​

get_state ​

workspace ​

new ​

open ​

save ​

save_as ​

close ​

switch_tab ​

focus_window ​

document ​

read ​

write ​

transform ​

workflow ​

apply_patch ​

validate ​

coherence ​

status ​

edges ​

Errori ​

Riferimento Strumenti MCP

`session`

`get_state`

`workspace`

`new`

`open`

`save`

`save_as`

`close`

`switch_tab`

`focus_window`

`document`

`read`

`write`

`transform`

`workflow`

`apply_patch`

`validate`

`coherence`

`status`

`edges`

Errori