MCP Gdocs

MCP Google Docs Server

Servidor MCP (Model Context Protocol) profissional para operações com Google Docs, refatorado seguindo princípios SOLID e Dependency Injection.

🎯 Características

• ✅ Arquitetura SOLID: Separação de responsabilidades, interfaces bem definidas
• ✅ Dependency Injection: Container DI usando dependency-injector
• ✅ Protocolo MCP: Servidor MCP completo com tools registradas
• ✅ 100% Funcionalidades Originais: Todas as funções de gdocs_lib.py preservadas
• ✅ Configuração Centralizada: YAML + variáveis de ambiente
• ✅ Type Hints: Código totalmente tipado
• ✅ Error Handling: Exceptions customizadas

📁 Estrutura

mcp-gdocs/
├── src/
│   ├── mcp/              # Servidor MCP
│   │   ├── server.py      # Servidor principal
│   │   └── tools/         # Tools MCP organizadas
│   ├── services/          # Services (SOLID)
│   │   ├── auth/          # Autenticação OAuth
│   │   ├── document/      # CRUD documentos
│   │   ├── formatting/    # Formatação de texto
│   │   ├── markdown/      # Conversão Markdown
│   │   ├── table/         # Manipulação de tabelas
│   │   ├── drive/         # Operações Google Drive
│   │   └── header/        # Cabeçalhos
│   ├── models/            # Data models/DTOs
│   ├── interfaces/        # Interfaces/Protocols
│   ├── exceptions/        # Exceções customizadas
│   └── utils/             # Utilitários
├── config/                # Configurações (YAML)
├── tests/                 # Testes
├── container.py           # Container DI
└── main.py               # Entry point

🚀 Instalação

# Instalar dependências
pip install -r requirements.txt

# Configurar credenciais
# Copiar credentials.json para raiz do projeto

📝 Configuração

Configuração YAML

Edite config/settings.yaml:

scopes:
  - https://www.googleapis.com/auth/documents
  - https://www.googleapis.com/auth/drive.file

credentials_path: credentials.json
token_path: token.pickle

Variáveis de Ambiente

export GOOGLE_CREDENTIALS_PATH=/path/to/credentials.json
export GOOGLE_TOKEN_PATH=/path/to/token.pickle
export OPENROUTER_API_KEY=your_key

🎮 Uso

Como Servidor MCP

python main.py

O servidor roda em stdin/stdout seguindo o protocolo MCP.

Como Biblioteca Python

from container import Container

container = Container()
doc_service = container.document_service()

# Criar documento
doc_id = doc_service.create("Meu Documento")
print(f"Documento criado: {doc_id}")

# Inserir Markdown
markdown_service = container.markdown_converter_service()
markdown_service.insert_markdown(doc_id, "# Título\n\nConteúdo...")

# Aplicar formatação francesa
formatting_service = container.formatting_service()
formatting_service.apply_french_formatting(doc_id)

🛠️ Tools MCP Disponíveis

Document Operations

• create_document - Criar novo documento
• read_document - Ler conteúdo
• clear_document - Limpar conteúdo
• get_document_info - Obter informações
• get_document_structure - Obter estrutura
• list_headings - Listar títulos
• get_document_url - Obter URL

Formatting Operations

• format_text - Formatar texto (negrito/itálico)
• apply_heading_style - Aplicar estilo de título
• apply_french_formatting - Formatação acadêmica francesa

Markdown Operations

• insert_markdown - Inserir Markdown
• replace_markdown - Substituir com Markdown

Table Operations

• insert_table - Inserir tabela

Drive Operations

• list_files_in_folder - Listar arquivos
• create_folder - Criar pasta

Header Operations

• add_header_with_logo - Adicionar cabeçalho
• update_header - Atualizar cabeçalho

🧪 Testes

# Executar testes
pytest tests/

# Com cobertura
pytest --cov=src tests/

📚 Documentação

• README_REFACTORING.md - Detalhes da refatoração
• COMPLETION_GUIDE.md - Guia de conclusão
• STATUS_FINAL.md - Status do projeto

🔧 Extensão

Para adicionar nova funcionalidade:

1. Criar interface em src/interfaces/
2. Implementar service em src/services/
3. Registrar no container em container.py
4. Criar tool MCP em src/mcp/tools/
5. Adicionar testes em tests/

📊 Status

• ✅ Services: 7/7 (100%)
• ✅ DI Container: Completo
• ✅ MCP Server: Completo
• ✅ MCP Tools: Implementadas
• ⏳ Testes: Básicos criados (expandir)
• ⏳ Documentação: Básica (expandir)

📝 Notas

• Todas as funcionalidades originais foram preservadas
• Código segue princípios SOLID
• Dependências injetadas via construtor
• Configuração centralizada e extensível