inception-mcp

Servidor MCP e CLI para gerenciar projetos, documentos e exportações do INCEpTION por meio da API REST AERO v1.

Documentação

inception-mcp

Um wrapper em torno da API REST AERO v1 do INCEpTION, expondo operações de gerenciamento de corpus como ferramentas MCP e comandos CLI.

As anotações são sempre realizadas por anotadores humanos dentro da interface do INCEpTION. Este pacote não anota: ele lida com tarefas de gerenciamento de corpus (upload, exportação, monitoramento, importação) que podem ser automatizadas ou delegadas a um 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."

Expõe a API REST AERO v1 do INCEpTION como:

Ferramentas MCP — chamáveis de qualquer agente compatível com MCP (Claude Code, Claude Desktop, etc.)
CLI — interface de terminal autônoma, sem necessidade de agente de IA

Ambos compartilham o mesmo InceptionClient subjacente.

Casos de uso

Cenário	Como
Upload de corpus em escala	Enviar em lote centenas de documentos para um projeto
Gerenciamento de pipeline	Encadear upload → monitorar progresso → exportar anotações concluídas
Monitoramento de progresso	Listar todos os documentos e seus estados de anotação por usuário
Exportação e pós-processamento	Exportar anotações ctsv3/XMI e canalizá-las para um script de análise
Gerenciamento de múltiplos projetos	Criar, inspecionar e arquivar projetos sem sair do terminal

Recursos

Recurso	Servidor MCP	CLI
Listar / criar / excluir projetos	✓	✓
Exportar / importar ZIP do projeto (esquema + documentos + anotações)	✓	✓
Status de progresso do projeto	✓	✓
Listar / enviar / excluir documentos	✓	✓
Enviar em lote uma pasta de documentos	✓	✓
Exportar fonte do documento	✓	✓
Listar anotações por usuário	✓	✓
Exportar / importar anotações (13 formatos)	✓	✓
Exportar todas as anotações de um projeto	✓	✓
Excluir anotações por usuário	✓	✓
Exportar / excluir camada de curadoria	✓	✓

Formatos de exportação suportados: ctsv3, xmi, xmi-struct, conllu, conll2003, conll2006, conll2009, conll2012, text, tcf, jsoncas, jsoncas-struct, nif.

Requisitos

Python ≥ 3.10
Uma instância do INCEpTION em execução (testada com INCEpTION 33+) com a API REST habilitada (veja abaixo)
uv (recomendado) ou pip

Habilitando a API REST do INCEpTION

A API REST AERO v1 deve ser habilitada antes de usar este pacote. Consulte a documentação oficial do INCEpTION para instruções.

Uma vez habilitada, a API é acessível em http://<host>:<port>/api/aero/v1. A interface Swagger está disponível em:

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

A autenticação usa HTTP Basic Auth com suas credenciais do INCEpTION.

Instalação

Com uv (recomendado)

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

Com pip

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

Configuração

Os parâmetros de conexão são lidos de variáveis de ambiente (ou de um arquivo .env na raiz do projeto):

Variável	Padrão	Descrição
`INCEPTION_URL`	`http://localhost:8080`	URL base da instância do INCEpTION
`INCEPTION_USER`	`admin`	Nome de usuário
`INCEPTION_PASSWORD`	(vazio)	Senha

Crie um arquivo .env:

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

Uso — servidor MCP

Claude Desktop

Adicione o seguinte bloco ao seu ~/.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 o Claude Desktop. As ferramentas do INCEpTION aparecerão automaticamente.

Claude Code (claude.ai/code)

Adicione o mesmo bloco em mcpServers no .claude/settings.json do seu projeto ou em ~/.claude/settings.json.

Ferramentas MCP disponíveis

Projetos

Ferramenta	Descrição
`list_projects`	Listar todos os projetos acessíveis
`create_project(name, description?)`	Criar um novo projeto
`delete_project(project_id)`	⚠️ Excluir um projeto e todos os seus documentos
`export_project_zip(project_id, output_path)`	Exportar projeto completo como ZIP
`import_project_zip(zip_path)`	Importar um projeto de ZIP
`project_status(project_id)`	Mostrar progresso de anotação por documento

Documentos

Ferramenta	Descrição
`list_documents(project_id)`	Listar documentos em um projeto
`upload_document(project_id, file_path, fmt?)`	Enviar um único arquivo
`batch_upload(project_id, folder_path, fmt?, glob?)`	Enviar todos os arquivos em uma pasta
`export_document_source(project_id, document_id, output_path, fmt?)`	Exportar fonte do documento
`delete_document(project_id, document_id)`	⚠️ Excluir um documento

Anotações

Ferramenta	Descrição
`list_annotations(project_id, document_id)`	Listar anotações por usuário
`export_annotations(project_id, document_id, user, fmt?, output_path?)`	Exportar anotações
`export_all_annotations(project_id, user, output_dir, fmt?)`	Exportar todos os documentos em um projeto
`import_annotations(project_id, document_id, user, file_path, fmt?, state?)`	Importar anotações
`delete_annotations(project_id, document_id, user)`	⚠️ Excluir as anotações de um usuário

Curadoria

Ferramenta	Descrição
`export_curation(project_id, document_id, fmt?, output_path?)`	Exportar anotações curadas
`delete_curation(project_id, document_id)`	⚠️ Excluir anotações curadas

Uso — CLI

# via uv
uv run inception-cli <command>

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

Opções globais

--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

Arquitetura

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 é a fonte única de verdade para todas as chamadas de API. Adicionar uma nova operação significa implementá-la uma vez em InceptionClient, depois expô-la em server.py (como um @mcp.tool()) e em cli.py (como um novo subcomando).

Execute os testes com:

pip install pytest
pytest tests/

Notas de segurança

Operações destrutivas são irreversíveis. delete_project, delete_document, delete_annotations e delete_curation não têm mecanismo de desfazer no INCEpTION. Sempre verifique os IDs antes de chamá-las.

O servidor é executado localmente e só é acessível a partir da máquina onde é iniciado. As credenciais são lidas de variáveis de ambiente — nunca as codifique diretamente em arquivos versionados. O .gitignore neste repositório exclui .env.

Referência da API do INCEpTION

A interface Swagger completa do AERO v1 está disponível em:

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

Licença

MIT — você é livre para usar, modificar e redistribuir este software em qualquer projeto, comercial ou não, desde que o aviso de direitos autorais original seja mantido.