MCP Beta
Usa DocAI direttamente dal tuo agente di coding
DocAI MCP collega gli agenti di coding all'intelligenza documentale di DocAI tramite il Model Context Protocol. Testato con Codex, Claude Code e Gemini CLI, e compatibile con altri client MCP stdio.
npx -y @synairo/docai-mcp@next install
npx -y @synairo/docai-mcp@next doctor
Avvio rapido
-
Passo 1
Installa
npx -y @synairo/docai-mcp@next install
Il programma di installazione configura gli host MCP supportati utilizzando il loro normale meccanismo di configurazione. Le voci esistenti per altri server non vengono mai modificate.
-
Passo 2
Verifica
npx -y @synairo/docai-mcp@next doctor
doctor verifica la configurazione e la connettività con l'API di DocAI. Non stampa mai la tua chiave API.
-
Passo 3
Chiedi al tuo agente
Esempio di richiesta a un agente di coding:
Integra l'estrazione di documenti DocAI in questo progetto. Usa l'architettura e le convenzioni esistenti del progetto. Mantieni le credenziali DocAI lato server. Gestisci gli errori di API e di elaborazione. Usa risultati di estrazione strutturati. Aggiungi test adeguati. Verifica l'integrazione con un documento di esempio anonimizzato.
Qui non c'è nulla di magico. L'agente legge tramite MCP le funzionalità di DocAI e la guida all'integrazione, esamina il tuo progetto e scrive lui stesso l'integrazione. Tu rivedi il diff come sempre.
Cosa fa realmente l'agente
- Scopre DocAI MCP
- Legge le funzionalità
- Legge la guida all'integrazione
- Ispeziona il progetto
- Implementa l'integrazione
- Esegue test con input sanificati
MCP aiuta l'agente di coding a comprendere e utilizzare DocAI. Non sposta l'intelligenza documentale nell'agente di coding.
Strumenti
docai_get_capabilities
Scopri i formati supportati, i limiti e il versionamento dell'API prima che l'agente scriva codice di integrazione.
docai_get_integration_guide
Recupera la guida all'integrazione mantenuta che l'agente dovrebbe seguire per questo progetto.
docai_extract_file
Invia un documento all'interno dell'area di lavoro corrente e restituisce risultati di estrazione compatti e strutturati. Sono accessibili solo i file all'interno dell'area di lavoro.
docai_get_result
Recupera il risultato di un job ancora in elaborazione nel momento in cui docai_extract_file ha restituito la risposta.
Architettura
Il pacchetto MCP non implementa una pipeline di elaborazione documentale separata. Utilizza la stessa API di DocAI e lo stesso motore di elaborazione delle integrazioni dirette tramite API.
API per gli sviluppatori. MCP per gli agenti di coding.
Usa MCP quando
- lavori da un agente di coding compatibile con MCP
- vuoi che l'agente scopra la guida all'integrazione DocAI
- desideri un'integrazione del progetto assistita dall'agente
- vuoi testare i documenti dell'area di lavoro locale tramite l'interfaccia MCP
Usa l'API REST quando
- stai realizzando un'integrazione diretta in produzione
- richiami DocAI dal codice applicativo
- stai implementando un tuo client
- stai integrando da un'infrastruttura priva di MCP
Entrambi i percorsi utilizzano lo stesso backend DocAI.
Confini di sicurezza
- Accesso ai file limitato all'area di lavoro
- L'elaborazione dei file locali è limitata all'area di lavoro configurata. I tentativi di path traversal e di escape tramite symlink al di fuori dell'area di lavoro vengono rifiutati.
- Nessuna shell generica
- DocAI MCP non espone l'esecuzione di comandi shell arbitrari.
- Nessun browser del filesystem arbitrario
- Non esiste un'interfaccia generica di esplorazione del filesystem, ma solo lo strumento di estrazione limitato all'area di lavoro.
- Nessun URL di documento arbitrario
- L'interfaccia MCP non espone un'ingestione generica di documenti tramite URL arbitrari.
- Confine contro il prompt injection
- Il testo presente nei documenti viene trattato come dati del documento, non come istruzioni per l'agente di coding.
- Credenziali
- La chiave API viene fornita tramite meccanismi di configurazione e variabili d'ambiente. Non deve mai essere incorporata nei prompt né inclusa nel controllo di versione.
- Output strutturato
- I risultati di estrazione strutturati sono l'interfaccia predefinita.
- OCR grezzo
- L'OCR grezzo è disattivato per impostazione predefinita.
Client testati
| Client | Stato | Note |
|---|---|---|
| Codex CLI 0.147.0 | Testato | MCP stdio |
| Claude Code 2.1.231 | Testato | MCP stdio |
| Gemini CLI 0.53.0 | Testato | MCP stdio |
| Altri client MCP stdio | Compatibile con il protocollo | Non certificato individualmente |
Le versioni indicate sopra sono le versioni dei client con cui l'integrazione è stata verificata. Altri client MCP stdio dovrebbero funzionare perché il protocollo è lo stesso, ma non li certifichiamo singolarmente. DocAI non è affiliato ai fornitori di questi client, non è approvato da loro e non ha partnership con loro.
DocAI MCP Beta
Cosa include la prima beta pubblica:
- Un server MCP stdio locale, distribuito su npm.
- Un installer che configura gli host MCP supportati e un comando doctor che verifica il risultato.
- Verificato con Codex, Claude Code e Gemini CLI.
- Accesso ai file locali limitato all'area di lavoro.
- Risultati di estrazione strutturati e compatti.
- Invio dei job idempotente, così un nuovo tentativo non elabora due volte lo stesso documento.
- I confini di sicurezza descritti sopra.
Beta significa che l'insieme degli strumenti può ancora cambiare tra le versioni. Fissa una versione nelle configurazioni di lunga durata.
Pacchetto
| Pacchetto | @synairo/docai-mcp |
|---|---|
| Editore | Synairo, l'organizzazione npm gestita da SYNAIRO sp. z o.o., che pubblica DocAI. |
| Beta attuale | 0.1.0-beta.1 |
| Canale di onboarding | next |
| Richiede | Node.js 18.17 o successivo |
| npm | https://www.npmjs.com/package/@synairo/docai-mcp |
La configurazione host duratura generata dal programma di installazione fissa la versione esatta, ad esempio npx -y @synairo/docai-mcp@0.1.0-beta.1 serve, mai il tag di canale next.
I documenti elaborati tramite MCP attingono allo stesso saldo di pagine dell'API REST, perché passano dallo stesso backend DocAI.