inception-mcp

Servidor MCP y CLI para gestionar proyectos, documentos y exportaciones de INCEpTION a través de la API REST AERO v1.

Documentación

inception-mcp

Un envoltorio alrededor de la API REST AERO v1 de INCEpTION, que expone operaciones de gestión de corpus como herramientas MCP y comandos CLI.

Las anotaciones siempre las realizan anotadores humanos dentro de la interfaz de INCEpTION. Este paquete no anota: maneja tareas de gestión de corpus (subida, exportación, monitoreo, importación) que pueden automatizarse o delegarse a un agente.

"Upload all .txt files in gutenberg/processed/ to project 1."
"Export annotations for document 42 by user admin in ctsv3 format to data/annot.tsv."

Expone la API REST AERO v1 de INCEpTION como:

Herramientas MCP — invocables desde cualquier agente compatible con MCP (Claude Code, Claude Desktop, etc.)
CLI — interfaz de terminal independiente, sin necesidad de agente de IA

Ambos comparten el mismo InceptionClient subyacente.

Casos de uso

Escenario	Cómo
Subida de corpus a escala	Subir por lotes cientos de documentos a un proyecto
Gestión de pipelines	Encadenar subida → monitorear progreso → exportar anotaciones completadas
Monitoreo de progreso	Listar todos los documentos y sus estados de anotación por usuario
Exportación y post-procesamiento	Exportar anotaciones ctsv3/XMI y pasarlas a un script de análisis
Gestión multi-proyecto	Crear, inspeccionar y archivar proyectos sin salir de la terminal

Características

Característica	Servidor MCP	CLI
Listar / crear / eliminar proyectos	✓	✓
Exportar / importar ZIP de proyecto (esquema + documentos + anotaciones)	✓	✓
Estado de progreso del proyecto	✓	✓
Listar / subir / eliminar documentos	✓	✓
Subida por lotes de una carpeta de documentos	✓	✓
Exportar fuente del documento	✓	✓
Listar anotaciones por usuario	✓	✓
Exportar / importar anotaciones (13 formatos)	✓	✓
Exportar todas las anotaciones de un proyecto	✓	✓
Eliminar anotaciones por usuario	✓	✓
Exportar / eliminar capa de curación	✓	✓

Formatos de exportación admitidos: ctsv3, xmi, xmi-struct, conllu, conll2003, conll2006, conll2009, conll2012, text, tcf, jsoncas, jsoncas-struct, nif.

Requisitos

Python ≥ 3.10
Una instancia de INCEpTION en ejecución (probada con INCEpTION 33+) con la API REST habilitada (ver más abajo)
uv (recomendado) o pip

Habilitación de la API REST de INCEpTION

La API REST AERO v1 debe estar habilitada antes de usar este paquete. Consulte la documentación oficial de INCEpTION para obtener instrucciones.

Una vez habilitada, la API es accesible en http://<host>:<port>/api/aero/v1. La interfaz Swagger UI está disponible en:

http://<host>:<port>/swagger-ui.html

La autenticación utiliza autenticación básica HTTP con sus credenciales de INCEpTION.

Instalación

Con uv (recomendado)

git clone https://github.com/RaphFaure/inception-mcp
cd inception-mcp
uv sync

Con pip

git clone https://github.com/RaphFaure/inception-mcp
cd inception-mcp
pip install -e .

Configuración

Los parámetros de conexión se leen de variables de entorno (o de un archivo .env en la raíz del proyecto):

Variable	Predeterminado	Descripción
`INCEPTION_URL`	`http://localhost:8080`	URL base de la instancia de INCEpTION
`INCEPTION_USER`	`admin`	Nombre de usuario
`INCEPTION_PASSWORD`	(vacío)	Contraseña

Cree un archivo .env:

cp .env.example .env
# then edit .env with your credentials

Uso — servidor MCP

Claude Desktop

Agregue el siguiente bloque a su ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "inception": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/inception-mcp", "inception-mcp"],
      "env": {
        "INCEPTION_URL": "http://localhost:8080",
        "INCEPTION_USER": "admin",
        "INCEPTION_PASSWORD": "your_password"
      }
    }
  }
}

Reinicie Claude Desktop. Las herramientas de INCEpTION aparecerán automáticamente.

Claude Code (claude.ai/code)

Agregue el mismo bloque bajo mcpServers en el .claude/settings.json de su proyecto o en ~/.claude/settings.json.

Herramientas MCP disponibles

Proyectos

Herramienta	Descripción
`list_projects`	Listar todos los proyectos accesibles
`create_project(name, description?)`	Crear un nuevo proyecto
`delete_project(project_id)`	⚠️ Eliminar un proyecto y todos sus documentos
`export_project_zip(project_id, output_path)`	Exportar el proyecto completo como ZIP
`import_project_zip(zip_path)`	Importar un proyecto desde ZIP
`project_status(project_id)`	Mostrar el progreso de anotación por documento

Documentos

Herramienta	Descripción
`list_documents(project_id)`	Listar documentos en un proyecto
`upload_document(project_id, file_path, fmt?)`	Subir un solo archivo
`batch_upload(project_id, folder_path, fmt?, glob?)`	Subir todos los archivos de una carpeta
`export_document_source(project_id, document_id, output_path, fmt?)`	Exportar la fuente del documento
`delete_document(project_id, document_id)`	⚠️ Eliminar un documento

Anotaciones

Herramienta	Descripción
`list_annotations(project_id, document_id)`	Listar anotaciones por usuario
`export_annotations(project_id, document_id, user, fmt?, output_path?)`	Exportar anotaciones
`export_all_annotations(project_id, user, output_dir, fmt?)`	Exportar todos los documentos de un proyecto
`import_annotations(project_id, document_id, user, file_path, fmt?, state?)`	Importar anotaciones
`delete_annotations(project_id, document_id, user)`	⚠️ Eliminar las anotaciones de un usuario

Curación

Herramienta	Descripción
`export_curation(project_id, document_id, fmt?, output_path?)`	Exportar anotaciones curadas
`delete_curation(project_id, document_id)`	⚠️ Eliminar anotaciones curadas

Uso — CLI

# via uv
uv run inception-cli <command>

# or, if installed via pip
inception-cli <command>

Opciones globales

--url       URL INCEpTION  (overrides $INCEPTION_URL)
--user      Username        (overrides $INCEPTION_USER)
--password  Password        (overrides $INCEPTION_PASSWORD)

Comandos

# Projects
inception-cli list-projects
inception-cli create-project --name my_project
inception-cli status --project 1
inception-cli export-project --project 1 --out backup.zip
inception-cli import-project --zip backup.zip
inception-cli delete-project --project 1

# Documents
inception-cli list-documents --project 1
inception-cli upload --project 1 --file doc.txt --format text
inception-cli batch-upload --project 1 --folder ./texts --glob "*.txt"
inception-cli export-doc-source --project 1 --doc 42 --out source.txt
inception-cli delete-doc --project 1 --doc 42

# Annotations
inception-cli list-annotations --project 1 --doc 42
inception-cli export --project 1 --doc 42 --user admin --format ctsv3 --out annot.tsv
inception-cli export-all --project 1 --user admin --out-dir ./annotations
inception-cli import-annotations --project 1 --doc 42 --user admin --file annot.tsv
inception-cli delete-annotations --project 1 --doc 42 --user admin

# Curation
inception-cli export-curation --project 1 --doc 42 --format ctsv3 --out curation.tsv
inception-cli delete-curation --project 1 --doc 42

Arquitectura

inception_mcp/
├── __init__.py      # Public exports: InceptionClient, InceptionError
├── client.py        # InceptionClient — HTTP layer over AERO v1 REST API
├── server.py        # FastMCP server — wraps client as MCP tools
└── cli.py           # argparse CLI — wraps client as shell commands
tests/
└── test_client.py   # Unit tests (22 tests, no INCEpTION instance required)

client.py es la única fuente de verdad para todas las llamadas a la API. Agregar una nueva operación significa implementarla una vez en InceptionClient, luego exponerla en server.py (como un @mcp.tool()) y en cli.py (como un nuevo subcomando).

Ejecute las pruebas con:

pip install pytest
pytest tests/

Notas de seguridad

Las operaciones destructivas son irreversibles. delete_project, delete_document, delete_annotations y delete_curation no tienen mecanismo de deshacer en INCEpTION. Siempre verifique los IDs antes de llamarlas.

El servidor se ejecuta localmente y solo es accesible desde la máquina donde se inicia. Las credenciales se leen de variables de entorno — nunca las codifique en archivos comprometidos con el control de versiones. El .gitignore en este repositorio excluye .env.

Referencia de la API de INCEpTION

La interfaz Swagger UI completa de AERO v1 está disponible en:

http://<your-inception-host>:<port>/swagger-ui.html

Licencia

MIT — usted es libre de usar, modificar y redistribuir este software en cualquier proyecto, comercial o no, siempre que se conserve el aviso de copyright original.