C++ Excel Automation

Um servidor MCP baseado em C++ para automação inteligente do Excel usando a biblioteca OpenXLSX.

GitHub
78

Documentação

Idioma：中文 | English

C++ Excel Automation MCP Server

Este é um projeto de servidor MCP (Model Context Protocol) de Automação de Excel baseado em C++. Ele utiliza a biblioteca OpenXLSX para operações de arquivos Excel e tem como objetivo fornecer um conjunto inteligente de ferramentas de manipulação de Excel através do protocolo MCP, aproveitando as capacidades de LLM.

Índice

Recursos

  • Interface MCP Simples e Fácil de Usar: Fornece ferramentas MCP padronizadas, facilitando que clientes (como assistentes de IA) invoquem funções de automação do Excel.
  • Implantação em Arquivo Único: Compila em um único arquivo executável para fácil implantação e execução.
  • Suporte a Múltiplos Idiomas Personalizável: Adicione ou modifique facilmente os idiomas da interface via arquivos JSON.

Capacidades do Servidor

Este servidor MCP fornece as seguintes ferramentas, que podem ser invocadas por um LLM para interagir com arquivos de planilha xlsx:

  • open_excel_and_list_sheets:
    • Descrição: Abre um arquivo Excel e lista todos os nomes das planilhas. Esta ferramenta também define o caminho atual do arquivo Excel para operações subsequentes. RECOMENDA-SE EXECUTAR ESTA FERRAMENTA PRIMEIRO ANTES DE QUALQUER OPERAÇÃO OU SE QUISER MUDAR O ARQUIVO A SER MODIFICADO.
    • Parâmetros:
      • file_path (string): O caminho absoluto para o arquivo Excel.
  • get_sheet_range_content:
    • Descrição: Obtém e exibe o conteúdo da tabela dentro de um intervalo especificado em uma planilha específica. Abre e fecha automaticamente o arquivo Excel.
    • Parâmetros:
      • sheet_name (string): O nome da planilha da qual ler.
      • first_row (number): O número da linha inicial (baseado em 1).
      • first_column (number): O número da coluna inicial (baseado em 1).
      • last_row (number): O número da linha final (baseado em 1).
      • last_column (number): O número da coluna final (baseado em 1).
      • cell_with_coord (boolean, opcional): Exibe células não vazias com suas respectivas coordenadas, adequado para situações em que a área de saída contém um grande número de células vazias.
  • set_sheet_range_content:
    • Descrição: Define o conteúdo da tabela dentro de um intervalo especificado em uma planilha específica. Abre e fecha automaticamente o arquivo Excel.
    • Parâmetros:
      • sheet_name (string): O nome da planilha na qual escrever.
      • first_row (number): O número da linha inicial (baseado em 1).
      • first_column (number): O número da coluna inicial (baseado em 1).
      • values (array[array]): A matriz 2D de valores a serem escritos no intervalo (suporta tipos null, boolean, number, string).
  • create_xlsx_file_by_absolute_path: (Nota: O nome da ferramenta é definido assim no código, mas a chave no JSON é create_xlsx)
    • Descrição: Cria um novo arquivo xlsx com o caminho fornecido. Fecha automaticamente o arquivo Excel após a criação.
    • Parâmetros:
      • file_path (string): O caminho ABSOLUTO onde o arquivo deve ser criado.

(Nota: O comportamento automático de abrir/fechar mencionado nas descrições das ferramentas é um detalhe de implementação interna e não requer atenção do usuário.)

Compilando o Projeto

Este projeto usa CMake para compilação. Recomenda-se instalar o Ninja para velocidades de compilação mais rápidas.

Passos de Compilação:

  1. Prepare o Ambiente:
    • Certifique-se de ter um compilador C++17, CMake (>= 3.15) e Ninja instalados.
    • Clone o repositório: git clone https://github.com/smileFAace/MCP-ExcelAutoCpp.git
  2. Compile: 
    # Change to the project directory (if not already in the root)
# cd MCP-ExcelAutoCpp

# Generate build files (Ninja recommended)
cmake -G "Ninja" -S . -B build

# Perform compilation
cmake --build build
    O executável compilado geralmente está localizado no diretório bin/.

Uso

Após a compilação bem-sucedida, encontre o executável chamado ExcelAutoCpp (Linux/macOS) ou ExcelAutoCpp.exe (Windows) no diretório ./bin/.

Inicie o Servidor

Basta executar o executável para iniciar o servidor MCP.

# Example (adjust path as needed)
./bin/ExcelAutoCpp

Quando você vir uma saída semelhante à seguinte, o servidor foi iniciado com sucesso e está ouvindo em localhost:8888:


░█▀▀░█░█░█▀▀░█▀▀░█░░░█▀█░█░█░▀█▀░█▀█
░█▀▀░▄▀▄░█░░░█▀▀░█░░░█▀█░█░█░░█░░█░█
░▀▀▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀▀▀░░▀░░▀▀▀
v0.0.2                 By smileFAace

I(17:35:48) i18n: Successfully loaded language string for language code 'en'
I(17:35:48) i18n: Set current language to 'en'
W(17:35:48) lang.json not found at 'E:\prj\MCP-ExcelAutoCpp\bin\lang.json'. Using default language.
I(17:35:48) i18n: Set current language to 'en'
I(17:35:48) Current language set to: en
I(17:35:48) Starting MCP server at localhost:8888
I(17:35:48) Press Ctrl+C to stop the server

Conectando e Usando:

Este servidor segue o protocolo MCP. Você pode usar qualquer cliente compatível com MCP (como Roo, cline, claude, cherry studio, etc.) para conectar-se ao endpoint SSE do servidor (padrão: http://localhost:8888/sse) e invocar as ferramentas de automação do Excel fornecidas.

Por exemplo, para configurar este servidor MCP no cline, basta adicionar o seguinte conteúdo ao arquivo de configuração JSON do mcp fornecido pelo plugin após o servidor estar em execução com sucesso e, em seguida, atualizar:

{
  "mcpServers": {
    "excel-auto-cpp": {
      "url": "http://localhost:8888/sse"
    }
  }
}

Alterando e Personalizando o Idioma do Servidor:

O servidor usa o inglês (en) como idioma padrão da interface. Você pode alterar o idioma criando um arquivo de idioma personalizado:

  1. Localize o diretório que contém o executável do servidor (geralmente bin/).

  2. Crie um arquivo de texto chamado lang.json nesse diretório.

  3. Copie os pares chave-valor completos para o idioma desejado neste arquivo lang.json.

    • Você pode consultar os arquivos *.json no diretório lang/ do código-fonte do projeto como modelos (por exemplo, lang/zh-cn/lang.json contém as traduções em chinês).
    • O arquivo lang.json precisa conter todas as entradas de tradução necessárias para a interface e os logs do programa.

  4. Salve o arquivo lang.json e reinicie o servidor.

    • O servidor detectará e carregará automaticamente este arquivo na inicialização. Se carregado com sucesso, usará o idioma definido em lang.json.
    • Se o arquivo lang.json não existir, estiver formatado incorretamente ou estiver faltando entradas de tradução necessárias, o servidor usará o inglês padrão (en) como fallback.

Download

Você pode baixar a versão mais recente na página Releases.

🌟Histórico de Estrelas

Star History Chart