MCP Jupyter Complete

MCP Jupyter Complete

Um servidor abrangente do Model Context Protocol (MCP) para manipulação de notebooks Jupyter com operações baseadas em posição e integração com VS Code.

Recursos

🎯 Operações Baseadas em Posição

• list_cells - Lista todas as células com índices e informações de tipo
• get_cell_source - Obtém o código-fonte de células específicas por índice
• edit_cell_source - Edita o conteúdo da célula por índice
• insert_cell - Insere novas células em posições específicas
• delete_cell - Exclui células por índice com reindexação automática

🚀 Operações Avançadas

• move_cell - Move células entre posições
• convert_cell_type - Converte entre células de código/markdown/raw
• bulk_edit_cells - Executa múltiplas operações em uma única chamada

🔧 Integração com VS Code

• trigger_vscode_reload - Força o VS Code a recarregar arquivos de notebook
• Suporte a observador de arquivos para recarga automática
• Geração de workspace e configurações do VS Code
• Recomendações de extensões para experiência Jupyter ideal

Instalação

1. Clone o repositório:

   git clone https://github.com/tofunori/mcp-jupyter-complete.git
   cd mcp-jupyter-complete
   

2. Instale as dependências:

   npm install
   

3. Torne executável (opcional):

   npm link
   

Configuração

Adicione à sua configuração ~/.claude.json:

{
  "mcpServers": {
    "jupyter-complete": {
      "command": "node",
      "args": ["/path/to/mcp-jupyter-complete/src/index.js"]
    }
  }
}

Ou se instalado globalmente via npm:

{
  "mcpServers": {
    "jupyter-complete": {
      "command": "mcp-jupyter-complete"
    }
  }
}

Exemplos de Uso

Operações Básicas com Células

// List all cells
await mcp.call("list_cells", {
  notebook_path: "/path/to/notebook.ipynb"
});

// Get cell content
await mcp.call("get_cell_source", {
  notebook_path: "/path/to/notebook.ipynb",
  cell_index: 0
});

// Edit a cell
await mcp.call("edit_cell_source", {
  notebook_path: "/path/to/notebook.ipynb",
  cell_index: 1,
  new_source: "print('Hello World!')"
});

Operações Avançadas

// Insert a new markdown cell
await mcp.call("insert_cell", {
  notebook_path: "/path/to/notebook.ipynb",
  position: 2,
  cell_type: "markdown",
  source: "# New Section\\n\\nThis is a new markdown cell."
});

// Move a cell
await mcp.call("move_cell", {
  notebook_path: "/path/to/notebook.ipynb",
  from_index: 3,
  to_index: 1
});

// Bulk operations
await mcp.call("bulk_edit_cells", {
  notebook_path: "/path/to/notebook.ipynb",
  operations: [
    {
      type: "edit",
      cell_index: 0,
      new_source: "# Updated title"
    },
    {
      type: "convert",
      cell_index: 1,
      new_type: "markdown"
    }
  ]
});

Integração com VS Code

// Trigger VS Code reload
await mcp.call("trigger_vscode_reload", {
  notebook_path: "/path/to/notebook.ipynb"
});

Configuração do VS Code

Para integração ideal com VS Code:

1. Instale as extensões recomendadas:

   • Python
   • Jupyter
   • Jupyter Keymap
   • Jupyter Renderers

2. Configure a recarga automática: Adicione às configurações do VS Code:

   {
     "files.watcherExclude": {
       "**/.ipynb_checkpoints/**": true
     },
     "notebook.diffEditor.ignoreTrimWhitespace": false
   }
   

3. Use com Claude Code: Ao usar com Claude Code, alterações no notebook feitas via MCP acionarão automaticamente o VS Code para solicitar recarga.

Referência da API

Funções Principais

Função	Parâmetros	Descrição
list_cells	notebook_path	Lista todas as células com índices
get_cell_source	notebook_path, cell_index	Obtém o código-fonte da célula
edit_cell_source	notebook_path, cell_index, new_source	Edita o conteúdo da célula
insert_cell	notebook_path, position, cell_type?, source?	Insere nova célula
delete_cell	notebook_path, cell_index	Exclui célula

Funções Avançadas

Função	Parâmetros	Descrição
move_cell	notebook_path, from_index, to_index	Move a posição da célula
convert_cell_type	notebook_path, cell_index, new_type	Converte o tipo da célula
bulk_edit_cells	notebook_path, operations[]	Operações em lote

Funções do VS Code

Função	Parâmetros	Descrição
trigger_vscode_reload	notebook_path	Força recarga do VS Code

Tipos de Células

Tipos de células suportados:

• code - Células de código Python/executável
• markdown - Células de texto Markdown
• raw - Células de texto bruto

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para:

• Índices de células inválidos
• Permissões de leitura/escrita de arquivos
• JSON de notebook malformado
• Conversões inválidas de tipo de célula

Desenvolvimento

Testes

npm test

Lint

npm run lint

Modo de Desenvolvimento

npm run dev

Contribuindo

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Faça suas alterações
4. Adicione testes se aplicável
5. Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Changelog

v1.0.0

• Lançamento inicial
• Operações de células baseadas em posição
• Integração com VS Code
• Suporte a operações em lote
• Tratamento abrangente de erros