tds-mcp connects an AI assistant to a TOTVS Protheus server via the TDS language server, letting it compile AdvPL/TLPP sources, generate/deploy patches, and inspect the RPO.
Servers & session — tds_list_servers lists servers/environments/includes from servers.json and shows the active session; tds_use_server connects and authenticates (TDS saved token, or credentials from ~/.tds-mcp/config.json) to a server/environment for all other tools.
Compilation — tds_compile compiles sources or folders into the RPO (force with recompile; accepts sources and resources like .tres/.png); tds_syntax_check validates syntax without writing to the RPO; tds_generate_ppo returns the preprocessed source to debug #include/#define.
RPO inspection — tds_rpo_objects lists RPO objects with source-file mtime semantics, tds_rpo_functions lists functions with source and line, tds_rpo_info returns RPO version, generation date and applied-patch history.
Patch workflow — tds_patch_generate builds a PTM with manifest and traceability from already-compiled sources; tds_patch_validate checks a patch against the RPO without applying; tds_patch_info lists a patch's contents; tds_patch_apply deploys a patch to the RPO (destructive, optionally forcing older sources).
Diagnostics — tds_server_log shows the latest advpls messages for troubleshooting connection or compilation issues.
Safety notes — compile, patch generation and patch apply modify the real RPO (apply is destructive), so confirmation prompts are recommended; sources must be CP1252-encoded, and only the boolean sucesso/sintaxeOk should be trusted as proof of success.
Integrates with TOTVS Protheus servers to compile AdvPL/TLPP sources, generate and apply patches, and inspect the RPO (Remote Program Object) repository.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tds-mcp compile the AdvPL source clientes.prw"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor MCP que dá a um assistente de IA (Claude Code, Claude Desktop, ou qualquer cliente MCP) a capacidade de compilar fontes AdvPL/TLPP, gerar e aplicar patches e inspecionar o RPO de servidores TOTVS Protheus.
Por baixo usa o advpls — o mesmo TDS Language Server que a extensão
tds-vscode utiliza — falando JSON-RPC via stdio.
Reaproveita a configuração que você já tem no TDS: servidores, ambientes, includes e tokens.
Não distribui binários da TOTVS. O
advplsé localizado na extensão tds-vscode já instalada na sua máquina. Você precisa ter o TDS instalado e um servidor configurado.
Windows (veja Limitações)
Node.js 18+
Extensão totvs.tds-vscode instalada, com pelo menos um servidor configurado e já conectado uma vez pelo VS Code
AppServer Protheus acessível (build 7.00.x)
Related MCP server: vibing-steampunk
git clone https://github.com/Guipegoraro/tds-mcp.git
cd tds-mcp
npm install # o script "prepare" já compila o TypeScriptRegistre no Claude Code:
claude mcp add --scope user tds node "<caminho-do-clone>/dist/index.js"Ou, em qualquer cliente MCP, via configuração JSON:
{
"mcpServers": {
"tds": {
"command": "node",
"args": ["C:\\caminho\\para\\tds-mcp\\dist\\index.js"]
}
}
}O MCP lê ~/.totvsls/servers.json — o arquivo global onde o TDS guarda seus servidores.
Você não precisa cadastrar nada duas vezes:
Cliente MCP (Claude)
└── tds-mcp (Node, stdio)
├── lê ~/.totvsls/servers.json (servidores, ambientes, includes, tokens)
├── spawn advpls.exe language-server
└── JSON-RPC: $totvsserver/connect, compilation, patchGenerate, patchApply, ...O arquivo é procurado na mesma ordem que o TDS usa: TDS_MCP_SERVERS_JSON (override) →
.vscode/servers.json do workspace (opção Workspace server config) → ~/.totvsls/servers.json.
tds_list_servers mostra em arquivoConfig qual está em uso.
Autenticação, em ordem:
Token de reconexão salvo pelo TDS — funciona sem senha nenhuma. Se expirar, basta conectar no servidor pelo VS Code uma vez para renovar.
Credenciais em ~/.tds-mcp/config.json — fallback opcional (veja
Configuração). O arquivo é relido a cada tds_use_server: credencial gravada
com o MCP aberto vale sem reconectar.
A conexão do MCP é independente da do VS Code: ambos podem estar conectados ao mesmo tempo.
Tool | Descrição | Efeito |
| Servidores do servers.json, ambientes, sessão ativa e binário advpls em uso | read-only |
| Conecta/autentica em servidor + ambiente (token do TDS, ou | sessão |
| Compila fontes/pastas no RPO; | grava no RPO |
| Verifica sintaxe com o linter do TDS (erros e avisos com linha); não usa o AppServer | nenhum |
| Fonte pré-processado (debug de | nenhum |
| Lista objetos do RPO (filtro + datas) | read-only |
| Lista os fontes compilados com | read-only |
| Remove do RPO os temporários registrados; outro fonte só com | remove do RPO |
| Lista funções do RPO (fonte + linha) | read-only |
| Versão do RPO + histórico de patches aplicados | read-only |
| Gera PTM com manifesto e rastreabilidade | read-only no RPO |
| Valida patch contra o RPO sem aplicar | read-only |
| Lista o conteúdo de um | read-only |
| Aplica patch no RPO (deploy) | destrutivo |
| Últimas mensagens do advpls + caminho e versões do tds-ls/extensão | read-only |
| Pastas e arquivos de uma pasta do AppServer | read-only |
| Operações que o usuário pode executar no AppServer | read-only |
| Sessões (threads) conectadas: usuário, ambiente, programa, memória | read-only |
| Envia mensagem ao usuário de uma sessão | afeta usuário |
| Pede à aplicação da sessão que se encerre | destrutivo |
| Derruba a sessão imediatamente | destrutivo |
| Executa uma função num SmartClient HTML invisível: concluído, erro (fonte/linha + pilha com variáveis) ou tempo esgotado (texto da tela); arquivos enviados ao navegador (PDF, CpyS2TW) em | executa código |
| Inicia depuração (modos headless, navegador para operar telas pelo chrome-devtools, job para StartJob/REST); | executa código |
| Espera parada / continua, próxima, entrar, sair; devolve local, pilha, Local/Private/Static, watches e o que mudou | depuração |
| Troca os breakpoints de um fonte (também com o programa rodando); condição, contagem, logpoint e rastro | depuração |
| Variáveis por escopo (Local, Private, Public, Static, Table) e frame; expande array/JSON/tabela | read-only |
| Avalia expressão no ponto de parada; | executa código |
| Expressões observadas a cada parada / encerra a sessão (a thread parada num breakpoint é encerrada ali) e o WebAgent dela; no modo navegador devolve | depuração |
tds_compile, tds_patch_generate, tds_patch_apply e tds_rpo_delete alteram o RPO de um servidor real, e as
tools de ação do monitor (tds_monitor_*) afetam usuários conectados, e
tds_run, tds_debug_start e tds_debug_evaluate executam código no servidor.
Recomendação forte: configure seu cliente MCP para sempre pedir confirmação nelas.
No Claude Code, em ~/.claude/settings.json:
{
"permissions": {
"ask": [
"mcp__tds__tds_compile",
"mcp__tds__tds_patch_generate",
"mcp__tds__tds_patch_apply",
"mcp__tds__tds_rpo_delete",
"mcp__tds__tds_monitor_send_message",
"mcp__tds__tds_monitor_kill_user",
"mcp__tds__tds_monitor_app_kill_user",
"mcp__tds__tds_run",
"mcp__tds__tds_debug_start",
"mcp__tds__tds_debug_evaluate"
]
}
}As ações do monitor identificam a sessão pela thread e conferem na lista atual do monitor antes
de agir.
Uma thread parada num breakpoint fica presa no AppServer até o depurador sair: tds_debug_stop
libera, e a sessão também encerra sozinha por inatividade (debugIdleMinutes) e quando o tds-mcp fecha.
As demais tools são read-only e podem ser liberadas sem risco.
Usa o debugAdapter da TOTVS (@totvs/tds-da, o mesmo do VS Code, localizado ao lado do advpls) e
o SmartClient HTML (webapp) do AppServer, num Chromium/Chrome/Edge headless controlado pelo
tds-mcp. O processo para o agente (pedir licença, alinhar fonte e RPO, escolher o modo,
inspecionar, encerrar) está na skill skills/debugar-advpl deste repositório.
Para o Claude Code enxergá-la, ligue a pasta nas skills do usuário (Windows, sem admin):
mklink /J "%USERPROFILE%\.claude\skills\debugar-advpl" "<repo>\skills\debugar-advpl"No modo navegador o tds-mcp devolve abrirCom (url, isolatedContext e, com o WebAgent,
initScript) e proximoPasso com as chamadas do chrome-devtools: new_page em about:blank no
contexto isolado e navigate_page com a url e o initScript. O contexto isolado é necessário:
o perfil normal do navegador guarda o último programa, e o webapp então descarta os parâmetros da
URL e roda o programa fora do depurador. O initScript grava a porta do agente no localStorage
antes de o webapp carregar: o webapp informa essa porta ao AppServer ao abrir a conexão, antes de o
agente conectar, e sem ela o AppServer trata a sessão como sem agente (ExecInClient, como a porta
serial, volta vazio). O Chromium headless do tds-mcp faz o mesmo sozinho. tds_debug_wait informa
conectado enquanto nenhum webapp abriu a sessão e o estado do agente. Ao terminar,
tds_debug_stop devolve fecharAba com a aba a fechar (close_page): aberta, ela mantém no
AppServer o programa que não estava parado num breakpoint. O agente da sessão encerra quando a
página sai do programa ou a aba fecha.
Com modulo (código ou nome, ex.: 04 ou SIGAEST) a rotina roda pelo SIGABPM dentro do módulo,
com o ambiente que o usuário tem no menu (empresa, filial, data base, variáveis do módulo). A tela
pede login e confirma os diálogos de entrada do módulo; a rotina roda sem argumentos. Sem modulo,
a função é o programa inicial e roda sem empresa aberta.
Nos modos headless e job, o arquivo que o programa manda ao navegador (PDF do FWMSPrinter sem
WebAgent, CpyS2TW) é gravado em pastaDownloads (padrão %TEMP%\tds-mcp\downloads\<data_hora>,
guardada por 24 h) e listado em arquivosBaixados; nome repetido ganha sufixo (2) em vez de
sobrescrever. O fim do programa espera até 2 s pelo início de um download.
O WebAgent é o agente local da TOTVS que dá ao webapp o comportamento do SmartClient desktop:
GetRemoteType() 1, arquivo local, Excel, impressão, porta serial (MsOpenPort) e PDF abrindo no
visualizador da máquina. Ele roda na máquina do tds-mcp: arquivos, impressoras e portas COM são os
dela. O tds-mcp sobe uma instância própria do agente em cada execução, numa porta livre, sem mexer
no agente que o usuário tiver aberto, e a encerra no fim (no modo navegador, quando a página sai do
programa ou a aba fecha, no máximo 2 h depois do stop: agente encerrado com a página ligada faria o
webapp abrir outro pelo protocolo web-agent: do Windows).
Ligado por padrão no modo navegador (alguém acompanha a tela); desligado em tds_run, headless
e job, que seguem recebendo o arquivo gerado como download. webAgent: true/false muda numa execução.
O agente vem de webAgentPath no config (executável ou pasta), de TDS_MCP_WEBAGENT ou do
WebAgent instalado (%LOCALAPPDATA%\Programs\web-agent).
A versão do agente precisa ser a que o webapp do servidor aceita: a TOTVS amarra as versões de
WebApp e WebAgent (TDN "2. WebApp - WebAgent"), e o Protheus traz os instaladores em
bin\web-agent. O tds-mcp não escolhe pela versão: confere no log da instância se o handshake
fechou. Se o webapp recusar o agente ou não conectar, o headless recomeça sem agente; o modo
navegador avisa no tds_debug_wait para iniciar de novo com webAgent: false. O retorno traz
webAgent com ativo ou o motivo de seguir sem ele.
Agente que fala TLS com certificado não confiável no Windows não é usado, e o motivo traz o
comando Import-Certificate para confiar no certificado da TOTVS (o tds-mcp não instala certificado).
Com o agente, o PDF do FWMSPrinter é aberto no visualizador padrão da máquina e não vem em
arquivosBaixados.
Limitações do depurador TOTVS que as tools contornam: evaluate só no frame do topo (outros
frames via tds_debug_variables), sem setVariable (use x := v), pause não interrompe thread
em Sleep (inclua breakpoint), logpoint só interpola nome de variável numérica (use rastro),
erro de execução não para o depurador (a tela de erro é capturada e devolvida).
Uma compilação pode falhar em dois níveis independentes — e olhar só um deles faz erro parecer sucesso:
Nível | Onde aparece | Exemplo |
Build |
|
|
Fonte |
| erro de sintaxe ( |
Uma falha de build acontece antes/fora da compilação individual: resultados pode vir
vazio ou só com SUCCESS, e ainda assim nada foi gravado no RPO (o build é revertido).
Sempre use o booleano
sucesso(ousintaxeOk) — ele já combina os dois níveis. Nunca conclua sucesso apenas porque não há itensERRORemresultados.
Quando falha, a resposta também vem marcada como erro no protocolo MCP (isError) e inclui
logDoServidor com as mensagens do AppServer — é lá que aparece, por exemplo, a dica
BuildKillUsers = 1 do COMPILEERROR-300.
Sucesso sem gravação: fontes já atualizados no RPO voltam com status SKIPPED (quando
recompile=false). Isso conta como sucesso, mas nada foi escrito — se todos forem
ignorados, a resposta traz o campo aviso dizendo isso. Confira ignorados antes de
afirmar que algo foi compilado.
Valores de returnCode medidos em AppServer 7.00.240223P: 0 sucesso, -1 erro de fonte
(sintaxe / arquivo inexistente), -300 sem acesso exclusivo ao RPO, 40840 token expirado.
O compilador Protheus só aceita Windows-1252. Um fonte em UTF-8 com acentos vai para o
RPO com caracteres corrompidos — às vezes sem erro de compilação, o que é pior que falhar.
Como agentes de IA gravam em UTF-8 por padrão, tds_compile e tds_syntax_check
verificam antes de enviar e recusam o que não estiver em CP1252:
arquivo 100% ASCII → passa (é idêntico nos dois encodings)
bytes altos que não formam UTF-8 válido → assume CP1252 → passa
UTF-8 válido com acentos, ou BOM UTF-8 → bloqueia, dizendo qual arquivo e como converter
CP1252 com trechos em UTF-8 (agente editou parte de um fonte CP1252) → bloqueia e aponta
as linhas; converter o arquivo inteiro corromperia os acentos que já estavam certos. Linha que
também tem acento CP1252 (ex.: StrTran(cTxt, "ç", "ç")) não conta. Quando a sequência é
intencional (tabela de conversão de UTF-8), o usuário confirma as linhas e o agente repete com
aceitarMisto: true; tds_compile e tds_syntax_check listam o que foi liberado em
encodingMistoAceito
UTF-16 (BOM FF FE/FE FF ou bytes nulos, saída padrão do Out-File do PowerShell 5) → bloqueia
O arquivo nunca é alterado pelo MCP — a conversão é decisão sua (convert_encoding do
MCP file-tools, ou Save with Encoding → Windows 1252 no VS Code). Recursos binários
(.png, .bmp, .res) não passam pela checagem.
O campo de data que o RPO expõe por objeto (dataFonte em tds_rpo_objects, date em
tds_patch_info, rpoDate no manifesto, dataPatch/dataRPO em tds_patch_validate)
é o mtime do arquivo-fonte registrado no momento da compilação — não o instante
em que a compilação ocorreu.
dataFonte == mtime do arquivo em disco (±2s) → o RPO contém o conteúdo atual.
mtime do disco > dataFonte → fonte alterado depois da última compilação → recompilar.
Nunca compare com data de commit git: commit posterior ao mtime é normal (editou num dia, commitou no outro) e não significa RPO desatualizado.
Exceção: tds_rpo_info.dataGeracao e as datas do histórico de patches (geradoEm,
aplicadoEm) são datas de evento reais.
Cada tds_patch_generate produz em <patchesRoot>/<cliente>/<ticket>/:
DDMMAA_HHMM_<ticket>_<customizacao>.ptm — data/hora (padrão brasileiro) lideram o nome,
seguidas do ticket e do identificador da customização, ex.
011026_1706_00018662_balanca_refugo_req_op.ptm. Colisão no mesmo minuto ganha segundos
(DDMMAA_HHMMSS). customizacao é obrigatório: snake_case minúsculo, sem acento, até 40
caracteres.
DDMMAA_HHMM_<ticket>_<customizacao>.manifest.json — título do tcloud, título e descrição
recomendados, sha256, fontes com data do RPO, servidor/ambiente/build de origem, autor, commit
git (opcional)
historico.jsonl — append-only por ticket (gerações, validações, aplicações)
<patchesRoot>/historico-global.jsonl — histórico consolidado
Título recomendado (data e hora primeiro): 19/07/2026 20:37 — Cliente ticket — FONTE.PRW
Título do tcloud (tituloTcloud, obrigatório, até 60 caracteres, validado na entrada e devolvido
no retorno e no manifesto): ticket + o que muda, ex. 18662 Balança refugo: regras, data e requisição na OP.
Opcional. Copie config.example.json para ~/.tds-mcp/config.json:
{
"patchesRoot": "C:\\TOTVS\\patches",
"advplsPath": "",
"credentials": {
"NomeDoServidorNoTDS": { "user": "usuario", "password": "senha" }
},
"webappUrls": { "NomeDoServidorNoTDS": "http://servidor:8080/webapp/" },
"debugIdleMinutes": 10
}patchesRoot — raiz da árvore de patches (padrão C:\TOTVS\patches)
advplsPath — só se o advpls não estiver na extensão instalada (sem ele, usa a extensão
tds-vscode de maior versão; tds_server_log mostra qual binário está em uso). Também aceita a variável
de ambiente TDS_MCP_ADVPLS
credentials — senhas em texto plano. Prefira deixar vazio e usar o token do TDS.
O arquivo fica fora do repositório; nunca o versione.
webappUrls — URL do webapp por servidor, quando não for http(s)://<endereço>:<porta>/webapp/
(porta multiprotocolo)
debugIdleMinutes — minutos sem uso até a sessão de depuração encerrar (padrão 10; no modo
navegador vale o triplo, porque o uso das telas pelo chrome-devtools não passa pelo tds-mcp)
debugAdapterPath, chromiumPath — só se o debugAdapter ou o navegador não forem
encontrados (também TDS_MCP_DEBUG_ADAPTER e TDS_MCP_CHROMIUM)
webAgentPath — WebAgent compatível com o webapp dos servidores, quando não for o instalado
(também TDS_MCP_WEBAGENT)
Um caminho informado (advplsPath, debugAdapterPath, chromiumPath, webAgentPath ou as variáveis de
ambiente) que não existe é erro: o tds-mcp não troca por outro binário sem avisar. Campo com
tipo errado ou JSON inválido no config é ignorado com aviso em avisosConfig do tds_server_log (e no
erro do tds_use_server que depender dele). O config é relido a cada tds_use_server;
debugIdleMinutes e advplsPath só mudam ao reconectar o MCP.
npm run build # compila TypeScript
npm test # testes de lógica e do linter local (não precisa de AppServer;
# o do linter usa o advpls da extensão TDS e é pulado sem ela)
node test/smoke.mjs <servidor> [ambiente] # read-only: conecta e inspeciona o RPO
node test/debug-protocol.mjs [host] [porta] # JSON-RPC cru (diagnóstico de protocolo)
node test/debug-returncode.mjs <srv> [amb] # read-only: returnCode em cada cenário
node test/e2e-readonly.mjs <servidor> [amb] # read-only: E2E pelo servidor MCP
node test/e2e-admin-readonly.mjs <srv> [amb] # read-only: binário, privilégios, pastas e monitor
node test/e2e-debug.mjs <servidor> [amb] # COMPILA test/zTstDbg1.prw e executa/depura as funções dele
node test/e2e-debug-bordas.mjs <srv> [amb] # inatividade no navegador, download no modo job, parâmetros inválidos (depois do e2e-debug)
node test/e2e-webagent.mjs <srv> [amb] # WebAgent no navegador e no headless (GetTempPath(.T.) da máquina), recusa e ausência do agente (depois do e2e-debug)
node test/e2e-monitor-acoes.mjs <srv> [amb] # COMPILA test/zTstDbg1.prw; mensagem, app kill e kill na thread do teste
node test/e2e-rpo-delete.mjs <srv> [amb] # COMPILA e REMOVE do RPO dois fontes de teste; registro de temporários
node test/e2e-mcp.mjs <servidor> [ambiente] # E2E: COMPILA um fonte de teste no RPO
node test/cleanup.mjs <servidor> [ambiente] # remove o fonte de teste do RPOOs E2E aceitam TDS_MCP_TEST_USER e TDS_MCP_TEST_PASSWORD para autenticar com usuário e senha
quando o token salvo pelo TDS expirou.
O E2E compila test/zTstMcp1.prw (User Function inofensiva) e gera um patch. Use apenas
em ambiente de desenvolvimento descartável e rode o cleanup depois.
Verificação de sintaxe: no tds-ls 2.2.x o modo syntaxOnly da compilação não passa pelo
AppServer (é o linter local, que só reporta para arquivo aberto num workspace LSP). Por isso
tds_syntax_check sobe um language server próprio, abre os fontes e colhe os diagnósticos do
linter, com as pastas de include do servidor (sem elas o linter não acha nem o PRTOPDEF.CH
implícito; pasta que não existe na máquina sai em includesAusentes). O linter é mais rigoroso
que o compilador em alguns casos (ex.: For com variável não Local vira aviso W0004 na
compilação; o tds-mcp rebaixa esse caso); na dúvida, compile num ambiente de desenvolvimento.
Windows apenas por enquanto: a resolução do binário procura
bin/windows/advpls.exe na extensão tds-vscode. O advpls existe para Linux e macOS
(@totvs/tds-ls), então o suporte é uma mudança pequena em resolveAdvplsPath() —
PRs bem-vindos.
Prazos do advpls: compilação e patch (gerar, aplicar, validar, ler) têm 30 min para
responder; os demais pedidos, 5 min. O prazo não cancela nada no servidor: depois de um
timeout de compilação o build pode continuar e gravar no RPO, então confira com
tds_rpo_objects antes de repetir.
O protocolo $totvsserver/* não é um contrato público da TOTVS. Ao atualizar a
extensão TDS, o binário muda junto; se algo quebrar, tds_server_log ajuda a
diagnosticar. A especificação viva é
src/protocolMessages.ts.
O advpls não aceita o handshake LSP initialize com params mínimos (derruba o
processo com 0xC0000409). Os requests $totvsserver/* são enviados diretamente — é o
que o @totvs/tds-languageclient oficial também faz.
Fora do escopo (mas mapeados no protocolo): defragRPO, rpoCheckIntegrity,
deletePrograms, wsdlGenerate.
Se você precisa de CI/CD em vez de um assistente:
advpls cli <script.ini> — modo CLI oficial do TDS Language Server (script INI em CP1252)
appserver.exe -compile — compilação/patch direto pelo AppServer, usado nos pipelines
oficiais da TOTVS (totvs/protheus-ci-universo)
Este projeto não é afiliado à TOTVS. O protocolo foi derivado do código-fonte público do
tds-vscode (Apache-2.0) e da documentação do
tds-ls. As regras de encoding CP1252, a lista de
extensões compiláveis e parte do troubleshooting seguem a skill oficial
advpl-tlpp-compile (Engenharia Protheus, MIT). Protheus, AdvPL, TLPP e TOTVS são marcas de
seus respectivos proprietários.
MIT — veja LICENSE.
Retorna o fonte após o pré-processador (resolução de #include/#define). Útil para depurar problemas de defines e includes.
| Name | Required | Description | Default |
|---|---|---|---|
| arquivo | Yes | Caminho do fonte |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
As anotações já declaram readOnlyHint=true, indicando operação somente leitura. A descrição adiciona valor ao especificar que o retorno é o fonte pré-processado, contextualizando o comportamento além das anotações.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A descrição é composta por apenas duas frases, sem palavras desnecessárias. A primeira frase já informa a função principal, e a segunda fornece o caso de uso. Perfeitamente concisa e bem estruturada.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Dada a baixa complexidade da ferramenta (1 parâmetro obrigatório, sem esquema de saída), a descrição cobre completamente o que o agente precisa saber: o que a ferramenta retorna e por que é útil. Não há lacunas significativas.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
A cobertura de descrição do esquema é de 100%; o único parâmetro 'arquivo' já está descrito no esquema como 'Caminho do fonte'. A descrição da ferramenta não adiciona informações extras sobre o parâmetro, então a pontuação permanece no patamar 3 (linha de base para cobertura alta).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A descrição afirma claramente que a ferramenta retorna o fonte após o pré-processador (resolução de #include/#define) e especifica sua utilidade para depurar defines e includes. O nome 'Gerar PPO (fonte pré-processado)' reforça o propósito. Diferencia-se bem de ferramentas irmãs como tds_syntax_check e tds_rpo_objects, que têm finalidades distintas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
A descrição indica explicitamente quando usar a ferramenta: 'Útil para depurar problemas de defines e includes'. Embora não mencione quando não usar ou alternativas, o contexto é claro o suficiente para um agente IA escolher corretamente entre as ferramentas irmãs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
APLICA um patch no RPO do ambiente conectado (operação de deploy — altera o ambiente). Por padrão aplica somente fontes mais novos; use aplicarAntigos=true para forçar. Recomenda-se tds_patch_validate antes.
| Name | Required | Description | Default |
|---|---|---|---|
| arquivoPatch | Yes | Caminho local do .ptm/.upd/.pak | |
| aplicarAntigos | No | Aplicar mesmo fontes mais antigos que os do RPO |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description matches the destructiveHint annotation by noting it's a deploy operation that changes the environment. It adds useful behavioral context about default newer-only application and the optional override.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences, each adding essential information. It is front-loaded with the core action and context, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, destructive annotation, and parameter count, the description covers the core purpose, default behavior, and prerequisite validation. It provides sufficient information for an AI agent, though error conditions are not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the baseline is 3. The description adds value by explaining the default behavior for aplicarAntigos and the file types for arquivoPatch, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies a patch to the RPO as a deploy operation that alters the environment. It distinguishes itself from sibling tools like tds_patch_validate by recommending validation beforehand.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the default behavior (only newer fonts) and how to force old fonts with aplicarAntigos=true. It recommends using tds_patch_validate first, providing clear context for usage, though it does not explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gera um patch PTM a partir de fontes já compilados no RPO, com organização padrão (///DDMMAA_HHMM_.ptm, datas no padrão brasileiro), manifesto JSON (sha256, fontes, datas do RPO, servidor, autor, git) e histórico. Retorna também título e descrição recomendados — o título começa com data e hora. No manifesto/retorno, rpoDate de cada fonte é o mtime do arquivo-fonte na compilação (semântica de tds_rpo_objects), não o instante da compilação.
| Name | Required | Description | Default |
|---|---|---|---|
| fontes | Yes | Nomes dos objetos no RPO (ex.: TEC10R06.PRW). Devem já estar compilados. | |
| ticket | Yes | Ticket/slug da demanda (vira pasta) | |
| cliente | Yes | Nome do cliente (vira pasta) | |
| descricao | No | Motivo/resumo da alteração | |
| pastaFontesLocais | No | Pasta local dos fontes (para registrar commit git no manifesto) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the rpoDate semantics (mtime not compilation time), output file naming, and manifest content. Adequate behavioral coverage for a generation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is dense but efficient, front-loading the action and then detailing specifics. No irrelevant sentences; every line adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains return values (title, description, manifest) and input constraints. Could mention error conditions, but overall sufficient for a file generation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds context: fontes must be compiled, ticket becomes folder, etc., which adds meaning beyond parameter names and schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a PTM patch from compiled sources, with specific output structure and metadata. It distinguishes from siblings like tds_patch_validate or tds_patch_info by focusing on generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (sources must be compiled) and output specifics, but does not explicitly compare to alternatives or state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista o conteúdo (fontes, datas, tamanhos) de um arquivo de patch sem aplicá-lo. Auditoria de patch recebido de terceiros. O campo date de cada objeto é o mtime do arquivo-fonte registrado na compilação (mesma semântica de tds_rpo_objects).
| Name | Required | Description | Default |
|---|---|---|---|
| arquivoPatch | Yes | Caminho local do .ptm/.upd/.pak |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint: true, and the description reinforces 'sem aplicá-lo' (without applying). Additionally, it explains the semantics of the 'date' field, referencing tds_rpo_objects, adding useful behavioral context beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the core purpose and add a relevant usage context and field semantics note. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter input and no output schema, the description adequately explains what the tool does (lists sources, dates, sizes) and provides enough context (audit use case, date field meaning) for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; the parameter description in the schema already documents 'Caminho local do .ptm/.upd/.pak'. The tool description does not add further parameter-level detail beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists contents (sources, dates, sizes) of a patch file without applying it, with a specific use case for auditing third-party patches. It distinguishes from siblings like tds_patch_apply.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the tool is for auditing patches received from third parties, implying inspection rather than application or validation. While it doesn't explicitly list when-not-to-use, the context of sibling tools provides implicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Valida um arquivo de patch contra o RPO do ambiente conectado, sem aplicar. Aponta fontes do patch mais antigos que o RPO. Gate recomendado antes de tds_patch_apply. As datas comparadas (dataPatch/dataRPO) seguem a semântica de mtime do arquivo-fonte na compilação, não do instante de compilação.
| Name | Required | Description | Default |
|---|---|---|---|
| arquivoPatch | Yes | Caminho local do .ptm/.upd/.pak |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, and description confirms 'sem aplicar'. Adds detail about checking source ages and mtime semantics, providing value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core purpose. Every sentence adds value: validation without apply, gate recommendation, and date semantics clarification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, and clear annotations, the description is sufficient. It explains what, when, and the date semantics, leaving no major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter, fully described in schema. Description adds no extra meaning beyond what schema already provides. Schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates a patch against the RPO without applying it, and highlights it flags source files older than the RPO. This distinguishes it from siblings like tds_patch_apply and tds_patch_generate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends as a gate before tds_patch_apply, providing clear context for when to use. No explicit exclusions, but the purpose implies when not to use (e.g., when applying is needed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista funções do RPO com fonte e linha onde estão definidas. Use filtro para procurar uma função específica (ex.: 'U_TEC10R06').
| Name | Required | Description | Default |
|---|---|---|---|
| filtro | No | Substring case-insensitive do nome da função | |
| limite | No | Máximo de itens retornados | |
| apenasPublicas | No | Omitir funções privadas/estáticas |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and the description adds behavioral context by stating the output includes source and line. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two purposeful sentences, front-loading the tool's purpose and providing a clear usage example without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the output (functions with source and line) but omits details like return format or pagination behavior for the 'limite' parameter. Adequate for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for all three parameters. The description adds little beyond what the schema provides, earning a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists RPO functions with source and line, using the verb 'Lista'. It distinguishes from siblings like tds_rpo_objects and tds_rpo_info, though not explicitly mentioning them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage example with the filter parameter but does not offer guidance on when to avoid this tool or mention alternative tools for different scopes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Versão do RPO, data de geração e histórico de patches aplicados no ambiente conectado. Auditoria pré/pós-deploy.
| Name | Required | Description | Default |
|---|---|---|---|
| ultimosPatches | No | Quantos patches do histórico retornar |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint: true. Description adds 'Auditoria pré/pós-deploy' indicating historical tracking, and specifies it operates on the connected environment. No contradictory behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, clear sentences directly describing the tool's output. No unnecessary words or repetition. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with one optional parameter and no output schema, the description adequately explains what is returned. Could mention output format or typical use case but not required for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'ultimosPatches' is fully described in the schema (100% coverage). The description adds no extra meaning beyond the schema's 'How many patches from history to return', so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides RPO version, generation date, and patch history. It distinguishes itself from siblings like tds_rpo_objects and tds_patch_info by focusing on overall RPO info and audit trail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Given the many sibling tools (e.g., tds_patch_info for specific patches, tds_rpo_objects for objects), a recommendation would help the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lista fontes/recursos do RPO do ambiente conectado. Use filtro para limitar (ex.: 'TEC10'). ATENÇÃO à semântica de dataFonte: é o mtime (data de modificação) do ARQUIVO-FONTE registrado no momento da compilação — NÃO é o instante em que a compilação ocorreu. Uso correto: comparar com o mtime do arquivo em disco — igual (±2s) significa que o RPO contém o conteúdo atual do arquivo; disco mais novo significa fonte alterado depois da última compilação. NÃO compare com data de commit git (commit posterior ao mtime é normal). Sem filtro retorna contagem + primeiros 100.
| Name | Required | Description | Default |
|---|---|---|---|
| filtro | No | Substring case-insensitive do nome | |
| limite | No | Máximo de itens retornados | |
| incluirRecursos | No | Incluir recursos não-fonte (tres) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds critical behavioral context beyond the readOnlyHint annotation by explaining the semantics of dataFonte and warning about common pitfalls. This helps agents use the tool correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph. While it includes valuable information, it could be more structured (e.g., bullet points) for easier scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description adequately explains the critical dataFonte semantics and default behavior. However, it does not detail all output fields, which might be necessary for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. The description reinforces the filter example and default behavior (no filter returns count + first 100) but does not add significant new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists sources/resources from the RPO using a filter. However, it does not distinguish itself from sibling tools like tds_rpo_info or tds_rpo_functions that might also list RPO objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an example filter and warns about misinterpreting the dataFonte field (not to compare with git commit). Does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Últimas mensagens emitidas pelo advpls nesta sessão (diagnóstico de conexão/compilação).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by specifying that it shows only the last messages from the current session for diagnostics. This provides useful behavioral context about scope and purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that captures the essential purpose without any wasted words. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is largely complete. It explains what the tool does and its scope. It could mention whether the output is a list or text, but it is sufficient for a simple log tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema, and the description does not need to add parameter details. The baseline is 4 for zero parameters, and the description is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool shows the last messages from advpls in the session for connection/compilation diagnostics. It uses a specific verb and resource, and distinguishes from sibling tools like syntax check or RPO functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for diagnostics, but does not explicitly state when to use it versus alternatives or provide any exclusion criteria. With no parameters, it is straightforward, but guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compila com syntaxOnly: valida os fontes no servidor SEM commitar no RPO. Sem efeito colateral — pode ser usada livremente antes de tds_compile. Confie no campo sintaxeOk: ele considera tanto returnCode (falha de build) quanto os status por fonte. Lista resultados vazia NÃO significa sucesso.
| Name | Required | Description | Default |
|---|---|---|---|
| arquivos | Yes | Caminhos de fontes ou pastas |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true; description adds that it has no side effects, explains the sintaxeOk field interpretation, and warns that an empty resultados list does not indicate success. There is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core purpose, and every sentence adds value. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (one parameter, no output schema), the description is fully complete: it explains behavior, usage, output interpretation, and side-effect profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the single parameter 'arquivos' with a clear description. The tool description does not add new parameter details beyond what the schema provides, justifying the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compiles with syntaxOnly, validating sources without committing to RPO. It distinguishes itself from siblings by noting it is safe to use before tds_compile, which likely commits changes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool before tds_compile and notes it has no side effects. It does not list specific when-not-to-use scenarios but provides adequate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0tds_generate_ppotds_patch_applytds_patch_generatetds_patch_infotds_patch_validatetds_rpo_functionstds_rpo_infotds_rpo_objectstds_server_logtds_syntax_checkScored across 10 tools
Each tool serves a distinct purpose (syntax check, listing RPO objects/functions, preprocessor, server log, RPO info, patch operations). No two tools overlap in functionality; descriptions clearly differentiate them.
All tools follow a consistent 'tds_verb_noun' pattern with snake_case (e.g., tds_syntax_check, tds_rpo_objects). Naming is predictable and uniform across the set.
10 tools cover the full workflow of TDS/ADVPL development: syntax checking, RPO exploration, preprocessor, logging, and patch lifecycle. The count is appropriate for the domain without redundancy.
The tools cover core operations: syntax validation, object/function listing, preprocessor output, server diagnostics, and patch management. Minor gap: no direct tool to fetch raw source file content (though generate_ppo provides preprocessed source).
Plan Salesforce deploys, open pull requests and trigger pipelines from your AI client.
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
