MCP Protheus Expert

Servidor MCP especializado para desenvolvimento TOTVS Protheus — code review automatizado, analise de rotinas, consulta a normativa, documentacao TDN e integracao com versionadores.

Projetado para Claude Code (CLI da Anthropic), mas compativel com qualquer LLM que suporte o protocolo MCP. A integracao de versionador utiliza Bitbucket como referencia, mas a arquitetura e adaptavel para GitHub, GitLab, Azure DevOps ou qualquer outro provedor.

Sobre o Projeto

O MCP Protheus Expert e um servidor que implementa o Model Context Protocol (MCP) — um protocolo aberto que permite conectar modelos de IA a ferramentas externas via JSON-RPC sobre stdin/stdout.

Este projeto oferece 5 ferramentas especializadas para o dia a dia de quem desenvolve no ERP TOTVS Protheus:

Ferramenta	O que faz
RelatorioRotinaTool	Analisa rotinas Protheus, gera relatorios Markdown com diagramas Mermaid e busca rotinas por tabela
Code Review Protheus	Executa code review automatizado com 24 regras, gera relatorio HTML interativo
Normativa	Consulta o documento normativo de desenvolvimento (.docx)
Bitbucket Protheus	Lista PRs abertos e commits de PRs (Bitbucket Cloud — adaptavel para outros versionadores)
Consulta TDN	Busca documentacao oficial de funcoes e classes no TDN TOTVS

Stack tecnologica: TypeScript (servidor MCP) + Python (engine de code review)

Arquitetura

graph LR
    A["Claude Code / LLM"] -->|"stdin JSON-RPC"| B["server.ts"]
    B --> C["mcpRouter.ts"]
    C --> D["toolRegistry.ts"]
    D --> E["RelatorioRotinaTool"]
    D --> F["CodeReviewTool"]
    D --> G["NormativaTool"]
    D --> H["bitbucketTool"]
    D --> I["TotvsTdnTool"]

    E -->|"simple-git"| J[("Repos Locais<br/>HML / PRD")]
    F -->|"Python subprocess"| K["code_review_protheus.py"]
    K -->|"rules.json"| L["Relatorio HTML"]
    F -.->|"complementa"| G
    G -->|"mammoth"| M[("normativa.docx")]
    H -->|"axios"| N[("Bitbucket Cloud API")]
    I -->|"axios + cheerio"| O[("TDN TOTVS")]

Fluxo:

O Claude Code envia mensagens JSON-RPC via stdin
O server.ts recebe e repassa para o mcpRouter.ts
O roteador despacha para a ferramenta correta via toolRegistry.ts
A ferramenta executa e retorna o resultado via stdout

Pre-requisitos

Node.js 18 ou superior
npm (incluido com o Node.js)
Python 3.10 ou superior (para o code review)
Git instalado e configurado
Repositorios Protheus clonados localmente (HML e/ou PRD)
Credenciais do versionador (Bitbucket App Password por padrao) — opcional, apenas para a ferramenta de integracao com versionador
Documento normativo (.docx) — opcional, apenas para a ferramenta Normativa

Instalacao

# 1. Clonar o repositorio
git clone https://github.com/Brunostng/mcp-protheus-expert.git
cd mcp-protheus-expert

# 2. Instalar dependencias
npm install

# 3. Compilar o TypeScript
npm run build

# 4. Configurar variaveis de ambiente
cp .env.example .env
# Edite o arquivo .env com seus caminhos e credenciais (veja secao abaixo)

# 5. (Opcional) Colocar documento normativo
# Copie seu arquivo .docx para a pasta normative/

Configuracao (.env)

Copie o .env.example para .env e preencha conforme sua infraestrutura:

Variavel	Obrigatoria	Descricao
`REPO_HML`	Sim	Caminho local do repositorio de Homologacao
`REPO_PRD`	Sim	Caminho local do repositorio de Producao
`REPO_TOTVS_STANDARD`	Nao	Caminho do repositorio de fontes padrao TOTVS
`PYTHON_EXE`	Nao	Executavel Python (padrao: `python`)
`NORMATIVE_DOCX_PATH`	Nao	Caminho para o .docx da normativa (padrao: auto-detecta em `normative/`)
`BITBUCKET_USER`	*	Usuario do Bitbucket
`BITBUCKET_APP_PASSWORD`	*	App Password do Bitbucket
`BITBUCKET_WORKSPACE`	*	Workspace do Bitbucket
`BITBUCKET_REPO_HML`	*	Nome do repositorio HML no Bitbucket
`BITBUCKET_REPO_PRD`	*	Nome do repositorio PRD no Bitbucket
`ENABLE_FILE_CACHE`	Nao	Habilitar cache de arquivos (`true`/`false`)
`CACHE_TTL_SECONDS`	Nao	TTL do cache em segundos (padrao: `3600`)
`MCP_DEBUG`	Nao	`1` para ativar logs de debug via stderr

* Obrigatorio apenas se utilizar a ferramenta bitbucket_protheus.

Exemplo:

REPO_HML=C:\protheus\repositorio-hml
REPO_PRD=C:\protheus\repositorio-prd
REPO_TOTVS_STANDARD=C:\protheus\totvs-standard
PYTHON_EXE=python
NORMATIVE_DOCX_PATH=C:\protheus\docs\normativa_dev.docx
BITBUCKET_USER=meu.email@empresa.com
BITBUCKET_APP_PASSWORD=xxxxxxxxxxxxxxxxxxxx
BITBUCKET_WORKSPACE=minha-empresa
BITBUCKET_REPO_HML=protheus-hml
BITBUCKET_REPO_PRD=protheus-prd
MCP_DEBUG=1

Configuracao no Claude Code

Opcao 1: Via comando `claude mcp add` (recomendado)

claude mcp add mcp-protheus-expert \
  -e REPO_HML="C:\protheus\repositorio-hml" \
  -e REPO_PRD="C:\protheus\repositorio-prd" \
  -e PYTHON_EXE="python" \
  -e MCP_DEBUG="1" \
  -- node C:\caminho\para\mcp-protheus-expert\dist\server.js

Opcao 2: Configuracao manual (Claude Desktop)

Localize e edite o arquivo claude_desktop_config.json do seu Claude Desktop e adicione a configuracao do servidor MCP:

Onde encontrar o arquivo:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-protheus-expert": {
      "command": "node",
      "args": [
        "SEU CAMINHO DO EXECUTAVEL server.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "REPO_HML": "SEU CAMINHO DO REPOSITORIO DE HOMOLOGACAO",
        "REPO_PRD": "SEU CAMINHO DO REPOSITORIO DE PRODUCAO",
        "REPO_TOTVS_STANDARD": "SEU CAMINHO DO REPOSITORIO PADRAO TOTVS",
        "PYTHON_EXE": "SEU CAMINHO DO EXECUTAVEL python.exe",
        "BITBUCKET_USER": "SEU USUARIO DO BITBUCKET",
        "BITBUCKET_APP_PASSWORD": "SUA SENHA DE APLICATIVO DO BITBUCKET",
        "BITBUCKET_WORKSPACE": "SEU ESPACO DE TRABALHO DO BITBUCKET",
        "BITBUCKET_REPO_HML": "SEU NOME DE REPOSITORIO DE HOMOLOGACAO NO BITBUCKET",
        "BITBUCKET_REPO_PRD": "SEU NOME DE REPOSITORIO DE PRODUCAO NO BITBUCKET",
        "NORMATIVE_DOCX_PATH": "SEU CAMINHO DO DOCUMENTO NORMATIVO .docx",
        "ENABLE_FILE_CACHE": "true",
        "CACHE_TTL_SECONDS": "3600",
        "MCP_DEBUG": "1"
      }
    }
  }
}

Substitua os valores em maiusculo pelos caminhos e credenciais do seu ambiente. Apos salvar, reinicie o Claude Desktop para que as ferramentas fiquem disponiveis.

Verificando a conexao

Apos configurar, abra o Claude Code no diretorio do seu projeto Protheus. As ferramentas MCP ficam disponiveis automaticamente. Teste com:

"Liste as ferramentas MCP disponiveis"

Ferramentas Disponiveis

1. RelatorioRotina

Analisa rotinas Protheus nos repositorios locais — encontra arquivos fonte, extrai estrutura (funcoes, tabelas, includes), gera relatorios Markdown com diagramas Mermaid e busca rotinas por tabela.

Acoes disponiveis:

Action	Descricao
`renderReportMarkdown`	Gera relatorio completo em Markdown com diagrama Mermaid (padrao)
`analyzeRoutine`	Analise estrutural: funcoes, includes, tabelas utilizadas
`getSourceCode`	Retorna o codigo-fonte da rotina
`status`	Status Git da rotina (diff comparando com branch base)
`searchByTable`	Busca todas as rotinas que utilizam uma tabela especifica

Parametros:

Parametro	Tipo	Padrao	Descricao
`routine`	string	—	Nome da rotina (ex: `PCMCTF43`, `U_PCMACD05`)
`action`	string	`renderReportMarkdown`	Acao a executar
`env`	string	`AUTO`	Ambiente: `HML`, `PRD`, `TOTVS`, `STANDARD` ou `AUTO`
`baseBranch`	string	`origin/master`	Branch base para comparacao git
`includeSource`	boolean	`false`	Incluir codigo-fonte no relatorio Markdown
`mermaidMode`	string	`auto`	Modo Mermaid: `auto`, `confluence-safe` ou `off`
`sourceEncoding`	string	`latin1`	Encoding do fonte: `utf-8` ou `latin1`
`table`	string	—	Tabela para busca (action `searchByTable`)
`maxResults`	number	`50`	Limite de resultados na busca por tabela
`includeStandard`	boolean	`false`	Incluir rotinas padrao TOTVS na busca

Como usar no Claude Code:

"Gere um relatorio da rotina U_PCMCTF43 no ambiente HML"

"Busque todas as rotinas que usam a tabela PD3"

"Me mostre o codigo-fonte da rotina MATA010"

"Qual o status git da rotina U_PCMACD05 comparando com origin/master?"

"Analise a estrutura da rotina PCMCTF43 em HML com o codigo-fonte incluso"

2. Code Review Protheus

Executa code review automatizado em uma branch, comparando com origin/master. Gera um relatorio HTML interativo com as violacoes encontradas, diferencia codigo legado de novas violacoes e complementa automaticamente com trechos da normativa.

Parametros:

Parametro	Tipo	Obrigatorio	Padrao	Descricao
`branch`	string	Sim	—	Branch para validar (ex: `SPCD-1946`)
`ambiente`	`HML` / `PRD`	Sim	—	Ambiente do repositorio
`incluirNormativa`	boolean	Nao	`true`	Complementar com trechos da normativa

Funcionalidades:

24 regras configuraveis em python/rules.json
Deteccao de codigo legado (violacoes que ja existiam em origin/master nao sao contabilizadas)
Deteccao de conflitos de merge via git merge-tree
Relatorio HTML com filtros por severidade (ALTA / MEDIA / BAIXA)
Integracao automatica com a ferramenta Normativa para buscar explicacoes das regras violadas

Como usar no Claude Code:

"Faca o code review da branch SPCD-1946 no ambiente HML"

"Execute code review da branch feature/nova-tela em PRD"

"Code review da branch SPCD-2100 em HML sem normativa"

3. Normativa

Consulta o documento normativo de desenvolvimento (.docx), extraindo apenas as secoes 3 a 4.99 (regras de desenvolvimento). Utiliza score de relevancia para retornar os 5 trechos mais pertinentes a pergunta.

Parametros:

Parametro	Tipo	Obrigatorio	Descricao
`question`	string	Sim	Pergunta sobre a normativa de desenvolvimento

Como usar no Claude Code:

"O que a normativa diz sobre variaveis Private?"

"Qual a regra da normativa sobre nomes de funcoes?"

"O que diz a normativa sobre cabecalho Protheus.doc?"

"A normativa permite usar TcQuery?"

"Quais sao as regras de nomenclatura de variaveis?"

4. Bitbucket Protheus

Integra com a API do Bitbucket Cloud para listar PRs abertos e commits de PRs, selecionando o repositorio automaticamente pelo ambiente (HML ou PRD).

Adaptavel para outros versionadores: A implementacao atual utiliza a API do Bitbucket Cloud como referencia, mas a arquitetura modular do projeto permite adaptar facilmente para GitHub (API REST/GraphQL), GitLab (API REST), Azure DevOps (API REST) ou qualquer outro provedor de repositorios Git. Basta criar uma nova ferramenta seguindo a interface McpTool e ajustar as chamadas de API conforme a documentacao do provedor desejado.

Acoes:

Action	Descricao
`list_open_prs`	Lista todos os Pull Requests abertos
`list_pr_commits`	Lista os commits de um PR especifico

Parametros:

Parametro	Tipo	Obrigatorio	Descricao
`ambiente`	`HML` / `PRD`	Sim	Ambiente do repositorio
`action`	string	Sim	`list_open_prs` ou `list_pr_commits`
`sourceBranch`	string	Nao	Filtrar por branch de origem
`targetBranch`	string	Nao	Filtrar por branch de destino
`prId`	number	Nao	ID do PR (para `list_pr_commits`)

Como usar no Claude Code:

"Liste os PRs abertos no ambiente HML"

"Mostre os commits do PR 42 em PRD"

"Quais PRs abertos tem como destino a branch master em HML?"

"Liste os PRs da branch SPCD-1946 em HML"

5. Consulta TDN TOTVS

Consulta a documentacao oficial do TDN (TOTVS Developer Network) para funcoes, classes e metodos do framework Protheus. Retorna explicacao nao-tecnica, descricao tecnica e exemplos de codigo.

Parametros:

Parametro	Tipo	Obrigatorio	Descricao
`query`	string	Sim	Nome da funcao ou classe Protheus

Como usar no Claude Code:

"Consulte no TDN sobre FwTemporaryTable"

"O que diz a documentacao oficial sobre FWFormView?"

"Busque no TDN informacoes sobre FWAdapterBase"

"Me explique a classe FWFormBrowse segundo o TDN"

Regras do Code Review

O code review utiliza 24 regras definidas em python/rules.json. Cada regra possui severidade (ALTA, MEDIA ou BAIXA) e pode usar regex ou contains para deteccao:

ID	Severidade	Descricao
3.1	BAIXA	Cabecalho Protheus.doc obrigatorio nas rotinas
3.3	BAIXA	Nao deixar trechos de codigo comentado
3.4	BAIXA	Maximo 250 caracteres por linha
3.16	ALTA	Nao usar macro substituicao `&()` — usar FieldPut/FieldGet
3.17-1	ALTA	Nao utilizar `EVal()`
3.17-2	ALTA	Nao utilizar `aEval()`
3.17-3	ALTA	Nao utilizar `dbEval()`
3.19	MEDIA	Fonte com classes deve ter User Function dummy
3.20	MEDIA	Em classes, usar `self:Prop` ao inves de `::Prop`
3.21-1	ALTA	Nao usar variavel `Public`
3.21-2	ALTA	Nao usar variavel `Static` no escopo global
3.21-3	ALTA	Uso de `Private` deve ser justificado
3.23	ALTA	Nome de variavel com maximo 10 caracteres
3.25	ALTA	User Function com maximo 8 caracteres (sem contar `U_`)
3.27	ALTA	Static Function com maximo 10 caracteres
3.28	ALTA	Nao utilizar `StaticCall()`
3.32	ALTA	Nao acessar tabelas SX* diretamente (dicionario de dados)
3.42	ALTA	Funcoes obsoletas: AXCadastro, AXAltera, AXDelete, NewGetDados, CriaTrab, DbSetFilter
3.46	ALTA	Nao usar `TCSqlExec()` para Insert/Update/Delete
3.52	ALTA	Nao usar `SELECT *` em queries
3.59	ALTA	Nao usar `D_E_L_E_T_ = ''` (Oracle interpreta como NULL)
3.74	ALTA	Nao usar `TcQuery()` — usar DbUseArea + TcGenQry ou Embedded SQL
4.1	MEDIA	Paths Windows `\\` sem tratamento `IsSrvUnix()`

As regras sao configuraveis editando o arquivo python/rules.json. Cada regra suporta os tipos de match regex e contains.

Estrutura do Projeto

mcp-protheus-expert/
├── src/
│   ├── server.ts                    # Ponto de entrada MCP (stdin/stdout)
│   ├── mcpRouter.ts                 # Roteador JSON-RPC (initialize, tools/list, tools/call)
│   ├── toolRegistry.ts              # Registro central das 5 ferramentas
│   ├── types/
│   │   └── McpTool.ts               # Interface McpTool (name, description, run, inputSchema)
│   └── tools/
│       ├── RelatorioRotinaTool.ts    # Analise de rotinas e relatorios Markdown/Mermaid
│       ├── CodeReviewTool.ts         # Code review com integracao Python + normativa
│       ├── NormativaTool.ts          # Consulta normativa (.docx)
│       ├── bitbucketTool.ts          # Integracao Bitbucket Cloud API
│       └── TotvsTdnTool.ts           # Consulta TDN TOTVS (web scraping)
├── python/
│   ├── code_review_protheus.py      # Engine de code review (24 regras, relatorio HTML)
│   └── rules.json                   # Regras de validacao configuraveis
├── normative/
│   └── (seu_arquivo_normativa.docx)  # Documento normativo (nao versionado)
├── dist/                             # Build compilado (gerado por npm run build)
├── .env.example                      # Template de variaveis de ambiente
├── package.json                      # Dependencias e scripts npm
└── tsconfig.json                     # Configuracao TypeScript

Adaptando para Outros LLMs

O MCP e um protocolo aberto e universal. Qualquer cliente que implemente JSON-RPC sobre stdin/stdout pode utilizar este servidor. O Claude Code e o cliente principal, mas voce pode adaptar para qualquer LLM.

Testando manualmente via terminal

Inicie o servidor e envie mensagens JSON-RPC:

# Inicializar conexao
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/server.js

# Listar ferramentas disponiveis
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node dist/server.js

# Chamar uma ferramenta (exemplo: consulta TDN)
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"Totvs_Tdn_Consulta","arguments":{"query":"FwTemporaryTable"}}}' | node dist/server.js

Integrando com outros clientes MCP

O servidor utiliza o transporte stdio (stdin/stdout). Para integrar com qualquer outro LLM:

Inicie o processo: node dist/server.js
Envie initialize via stdin
Envie tools/list para descobrir as ferramentas
Envie tools/call com o nome da ferramenta e argumentos
Leia as respostas JSON-RPC via stdout

Consulte a especificacao MCP para detalhes do protocolo.

Debug e Troubleshooting

Ativando logs de debug

Defina MCP_DEBUG=1 no .env. Os logs sao enviados para stderr (nunca para stdout, que e reservado ao protocolo MCP).

Problemas comuns

Problema	Solucao
`Python not found`	Verifique se `PYTHON_EXE` aponta para o executavel correto
`Repository path not found`	Confira os caminhos `REPO_HML` e `REPO_PRD` no `.env`
`DOCX not found`	Coloque o .docx na pasta `normative/` ou defina `NORMATIVE_DOCX_PATH`
`Bitbucket 401 Unauthorized`	Gere um novo App Password em Bitbucket > Settings > App passwords
`Encoding errors`	Tente alterar `sourceEncoding` para `utf-8` ou `latin1`
Ferramenta nao aparece no Claude	Verifique se `npm run build` foi executado e o caminho no config esta correto

Contribuindo

Contribuicoes sao bem-vindas! Para adicionar funcionalidades:

Adicionando uma nova ferramenta MCP

Crie um arquivo em src/tools/SuaFerramenta.ts implementando a interface McpTool:

import { McpTool } from "../types/McpTool.js";

const suaFerramenta: McpTool = {
  name: "nome_da_ferramenta",
  description: "Descricao da ferramenta",
  inputSchema: {
    type: "object",
    properties: {
      parametro: { type: "string", description: "Descricao do parametro" }
    },
    required: ["parametro"]
  },
  async run(input) {
    // Sua logica aqui
    return { ok: true, resultado: "..." };
  }
};

export default suaFerramenta;

Registre em src/toolRegistry.ts:

import suaFerramenta from "./tools/SuaFerramenta.js";
// Adicione ao array de ferramentas

Compile com npm run build

Adaptando o versionador (GitHub, GitLab, Azure DevOps)

A ferramenta bitbucket_protheus foi construida para Bitbucket Cloud, mas voce pode criar uma versao para outro provedor. O fluxo e simples:

Duplique src/tools/bitbucketTool.ts como base (ex: githubTool.ts)
Substitua as chamadas da API do Bitbucket pelas do provedor desejado:
- GitHub: https://api.github.com/repos/{owner}/{repo}/pulls
- GitLab: https://gitlab.com/api/v4/projects/{id}/merge_requests
- Azure DevOps: https://dev.azure.com/{org}/{project}/_apis/git/repositories/{repo}/pullrequests
Ajuste a autenticacao (token Bearer, PAT, etc.)
Registre a nova ferramenta em src/toolRegistry.ts
Adicione as variaveis de ambiente correspondentes no .env

Adicionando regras de code review

Adicione um novo objeto ao array em python/rules.json:

{
  "id": "Normativa X.Y",
  "severidade": "ALTA",
  "descricao": "Descricao da regra",
  "linguagem": "advpl",
  "alvo": "added",
  "match": "regex",
  "padrao": "seu_pattern_aqui"
}

Autor

Desenvolvido por Bruno Santana Gomes — @Brunostng

Licenca

Este projeto esta licenciado sob a licenca MIT. Consulte o arquivo LICENSE para mais detalhes.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.claude		.claude
normative		normative
python		python
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

MCP Protheus Expert

Indice

Sobre o Projeto

Arquitetura

Pre-requisitos

Instalacao

Configuracao (.env)

Configuracao no Claude Code

Opcao 1: Via comando claude mcp add (recomendado)

Opcao 2: Configuracao manual (Claude Desktop)

Verificando a conexao

Ferramentas Disponiveis

1. RelatorioRotina

2. Code Review Protheus

3. Normativa

4. Bitbucket Protheus

5. Consulta TDN TOTVS

Regras do Code Review

Estrutura do Projeto

Adaptando para Outros LLMs

Testando manualmente via terminal

Integrando com outros clientes MCP

Debug e Troubleshooting

Ativando logs de debug

Problemas comuns

Contribuindo

Adicionando uma nova ferramenta MCP

Adaptando o versionador (GitHub, GitLab, Azure DevOps)

Adicionando regras de code review

Autor

Licenca

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Opcao 1: Via comando `claude mcp add` (recomendado)

Packages