GUIA DO MCP

Do problema à decisão,
com as fontes à vista.

Conecte seu assistente de IA ao Knowledge para investigar bugs, planejar PJs e avaliar o impacto de uma mudança, sem sair do editor.

01 / CONECTAR

Conecte em dois passos

O endereço do servidor é https://yz-knowledge.discloud.dev/mcp. Use uma das opções abaixo.

Claude Code, com OAuth

Adicione o servidor e autorize pelo navegador. Não há token para guardar.

claude mcp add --transport http yzidro-knowledge https://yz-knowledge.discloud.dev/mcp

Depois, rode /mcp no Claude Code, escolha o servidor e aprove os escopos.

Codex, com token pessoal

Crie o token no Hub de Desenvolvimento, em Minha conta → MCP, e guarde-o na variável YZIDRO_KNOWLEDGE_MCP_TOKEN. No config.toml:

[mcp_servers.yzidro_knowledge_mvp]
url = "https://yz-knowledge.discloud.dev/mcp"
bearer_token_env_var = "YZIDRO_KNOWLEDGE_MCP_TOKEN"
tool_timeout_sec = 60
Aprove todos os escopos

Sem os seis escopos de fonte e conteúdo, você vê apenas a consulta ao conhecimento oficial. Bugs, planejamento, código e Wiki exigem todos eles.

Nunca coloque o token no código nem no chat

Trate-o como uma senha. Se ele vazar, revogue em Minha conta → MCP.

02 / POR ONDE COMEÇAR

Peça em linguagem natural

Você não precisa decorar ferramentas: descreva o que precisa e o assistente escolhe. A tabela mostra por onde ele começa em cada situação.

Você querExemplo de pedidoFerramenta inicial
Saber o que o MCP faz por você"O que você consegue fazer? Me dê exemplos."about
Investigar um bug"O total da nota sai com um centavo a menos ao aplicar desconto. Onde pode estar o problema?"diagnose_issue
Planejar um PJ"Prepare o planejamento do PJ-007848."plan_project
Entender um PJ"O que o PJ-007848 pede e em que estado ele está?"get_project_brief
Saber o que uma mudança afeta"Se eu alterar TfrmNFEEmissao.FormCreate, o que pode quebrar?"analyze_change_impact
Saber por que o código é assim"Quem mexeu em Comum/untNFEEmissao.pas e por quê?"get_file_history
Responder um chamado do suporte"O banco pediu os JSONs das requisições do Itaú. Como o suporte gera isso?"search_knowledge_and_code
Seguir os padrões do time"Quais padrões devo seguir para criar um cadastro herdado do CadBase?"get_development_guides
Achar código em outro sistema"Onde o ACBr monta o XML da NF-e?" ou "Procure TfrmPrincipal no YzCommerce."search_repository_code
Revisar um PR"Revise o PR 351 contra os requisitos do PJ."read_pr_diff
Ver se o time N3 já resolveu"Erro 000944.TD.000071 ao atualizar o cliente. O N3 já resolveu isso?"search_support_cases
Achar precedentes"Já tivemos hotfix de arredondamento na nota?"search_projects
Consultar uma regra"Qual é a regra de bloqueio de crédito?"search_business_knowledge
Ver como uma regra mudou"Como essa regra evoluiu?"get_item_history
Respostas no formato do seu perfil

São dois perfis: Suporte (N1 e N2) / Implantação (linguagem simples, passos pela interface, o que conferir e quando escalar) e Desenvolvimento / N3 (repositório, arquivos, rotinas, linhas e impacto). Se você ainda não tem perfil, o assistente pergunta antes de responder e salva a sua resposta; nas próximas conversas ele já vem definido. Também dá para escolher ou trocar no Hub, em Minha conta → MCP (o administrador também pode definir), ou pedindo na conversa ("troque meu perfil para desenvolvimento"). Em qualquer perfil, a opção na tela vem antes de config.ini, SQL ou código, e você pode pedir outro formato só naquela resposta ("me responde como dev"). O perfil não muda os escopos. Quando o administrador liga o guard rail, só o perfil Desenvolvimento / N3 recebe código-fonte, e esse perfil passa a ser definido pelo administrador.

Dê pistas e a resposta melhora

03 / FLUXOS PRONTOS

Roteiros para tarefas comuns

O MCP oferece seis prompts que conduzem o assistente passo a passo e definem o formato da resposta. Cada cliente os mostra de um jeito; no Claude Code, eles aparecem entre os comandos com prefixo /mcp__.

investigar-bug

Do sintoma à causa provável: pistas, histórico, regra esperada e código.

planejar-pj

Escopo, etapas, arquivos, riscos, dúvidas abertas e plano de testes.

avaliar-impacto

O que muda, o que pode quebrar, o que testar e o que não foi avaliado.

revisar-pr

Requisitos atendidos e pendentes, desvios dos padrões, defeitos prováveis e testes faltantes.

atender-suporte

Para qualquer chamado (como fazer, erro, configuração, regra, pedido de banco ou parceiro, integração parada): caminho na interface, o que conferir e quando escalar, no formato do seu perfil.

implementar-com-padroes

Checklist dos padrões da Wiki com links, plano de implementação, divergências com o código, riscos e passos de commit.

PADRÕES DO DESENVOLVIMENTO

Implemente do jeito do time

O MCP lê ao vivo as páginas de manuais do setor na Wiki e monta um catálogo pesquisável. Quando a Wiki muda, o MCP acompanha, sem novo deploy.

Manuais

Delphi, boas práticas de IA, debug remoto, processo de commit, merge, CompiladorXE, AtualizaBD, PDV Offline e Jenkins.

Time de Evolução

Onboarding com Clean Code e Padrões Yzidro, Git Flow, CadBase/PsqBase, Frames, BI/DTCharts, DTScript, parâmetros e banco de dados.

Time de Sustentação

Diretrizes de ocorrências, atendimento e reclassificação, criação de FAQ e uso do portal.

Como a busca funciona

Procura no título, na seção, no resumo e no conteúdo das páginas, entende sinônimos do setor (ex.: cadastro → CadBase, git → Git Flow) e devolve trechos. Itens riscados na Wiki ficam de fora.

Como usar

Manual é referência, não prova

Se o padrão da Wiki divergir do código existente, o assistente deve mostrar a divergência e não escolher sozinho qual vale.

04 / COMO LER AS RESPOSTAS

Nem toda informação vale o mesmo

Antes de decidir, confira de onde veio cada informação.

OrigemO que significaComo usar
Conhecimento oficialRevisado e publicado. Aparece como official ou KNOWLEDGE_CONFIRMED.Base mais confiável, mas compare com o código atual.
EvidênciaWiki, commits, código e varredura. Aparece como evidence ou SOURCE_EVIDENCE_NOT_REVIEWED.Leia a fonte antes de concluir.
ProvisórioDados da última coleta do PJ, ainda sem publicação. Aparece como PROVISIONAL_UNREVIEWED.Confira a data em collectedAt: não é o ERP em tempo real.
Candidatov0 escrita por um autor ou assistente. Aparece como CANDIDATE_NOT_OFFICIAL.Ponto de partida, nunca regra confirmada.

Campos que ajudam a decidir

gaps
O que não foi possível avaliar. Leia sempre: uma lacuna pode mudar a decisão.
coverage
Estado de cada fonte consultada, como found, not_found ou unavailable.
risks
Alertas por regras fixas, como invariante vinculada ou requisito impeditivo. Não é uma avaliação completa.
openQuestions
Dúvidas que dependem de uma decisão sua antes de implementar.
leads
Pistas de um diagnóstico. Não são a causa confirmada.
nextCalls
Próximas consultas sugeridas, prontas para o assistente executar.
matchedTerms
Quantos termos da busca o item cobre. Quanto menor, mais fraca a relação.
Vários repositórios

A busca de código cobre os repositórios dos projetos Bitbucket liberados: Delphi (Yzidro, DTUtils), Delphi-Legacy (YzFood, YzCommerce, YzServices, YzidroXML) e Delphi - Componentes (Componentes, ACBr), na branch principal de cada um. Cada resultado traz repository; as leituras, o histórico e os PRs desse repositório usam o mesmo campo. Sem ele, vale o repositório principal (Yzidro).

Você não precisa dizer onde procurar: pelo assunto da pergunta o MCP sugere o repositório (boleto e CNAB → ACBr; cobrança por API, extrato, Open Finance, Mercado Livre, TrackCash, iMendes → YzCommerce; XML para contador, Demander, WMS → YzidroXML; PDV Offline, BI, BStrac → YzServices; cardápio e iFood → YzFood; Fortes, Chromium, TecnoSpeed → Componentes), busca primeiro nele e mostra os demais. Código de serviço descontinuado, como a Tribox, vem marcado.

Não encontrar não significa não existir

As buscas têm limites e nem tudo está mapeado. Um arquivo sem vínculo oficial pode, sim, afetar regras de negócio. Da mesma forma, citar um PJ em um commit é uma pista, não prova do motivo da alteração.

05 / FERRAMENTAS

O que está disponível

As ferramentas aparecem conforme os escopos da sua conta e da credencial. As de varredura dependem da integração habilitada.

Começar

about
O que o MCP faz para a sua conta, a versão em execução (com build e data) e exemplos prontos para escolher. Respeita seu perfil e acesso.

Decidir

diagnose_issue
Pistas para investigar um defeito.
plan_project
Insumos para planejar um PJ.
analyze_change_impact
O que pode ser afetado por uma mudança.

Projetos

get_project_brief
Requisitos, checklists, análise e estado do PJ.
search_projects
PJs por texto, hotfix, área, erro e complexidade.
find_projects_by_code
PJs publicados que citam um arquivo ou símbolo.
get_working_project_context
Wiki, PRs e arquivos de um PJ em andamento.
read_working_project_code
Código do PR de um PJ em andamento.
publish_working_candidate
Grava uma v0 candidata, quando pedido.
get_working_candidate
Recupera a v0 candidata.

Casos do time N3

search_support_cases
Atendimentos do time N3 (Desenvolvimento), por erro, código ou problema, com status de solução avaliado pela IA.
read_support_case
Problema, causa, solução e passos de um caso; conversa higienizada sob pedido.

Código e histórico

list_code_repositories
Repositórios liberados, o que cada um contém e a branch usada.
search_repository_code
Busca lexical nos repositórios liberados, com filtro por repositório ou projeto.
read_repository_code
Lê código por rotina, linhas ou bytes.
get_file_history
Commits, autores e PJs de um arquivo.
read_pr_diff
Arquivos e diff de um pull request.

Conhecimento oficial

search_business_knowledge
Busca regras, decisões, invariantes e mais.
search_knowledge_and_code
Busca em conhecimento, Wiki, código e varredura.
list_domains
Domínios e subdomínios para filtrar.
get_knowledge_item
Entidade completa, com relações e origens.
get_item_history
Versões e campos alterados.
get_process_context
Processo e suas relações.
get_code_context
CodeMappings oficiais.
build_context_pack
Pacote de contexto para uma tarefa.

Wiki e evidências

search_wiki_references
Busca por título, descrição e caminho.
read_wiki_reference
Lê uma página da Wiki.
get_development_guides
Busca nos manuais e padrões do Desenvolvimento, com trechos e links.
list_evidence_collections
Coletas de uma entidade publicada.
get_evidence_index
Fontes e arquivos de uma coleta.
read_evidence_source
Lê uma fonte da coleta.
read_evidence_code
Lê código no commit da coleta.

Varredura do ERP

discover_scan_candidates
Telas e relatórios a partir de uma pergunta.
get_integrated_context
Parâmetros, permissões e acessos de uma tela.
get_call_graph
Quem chama um método e o que ele chama.
trace_scan_event
Liga um componente a uma tela ou relatório.
query_scan_evidence
Consulta paginada da varredura.
get_scan_analysis
Última análise concluída.

06 / PROBLEMAS COMUNS

Se algo não funcionar

O que apareceCausaO que fazer
Ferramenta não apareceFaltam escopos ou o cliente guardou a lista antiga.Reconecte o cliente e confira os escopos em Minha conta → MCP.
MCP_INVALID_TOKENCredencial inválida, revogada ou expirada.Gere outro token ou autorize de novo.
FORBIDDENSua conta ou credencial não tem os escopos exigidos.Peça a liberação ao administrador.
MCP_RATE_LIMITMais de 120 chamadas por minuto na credencial.Aguarde um minuto e tente de novo.
MCP_RESULT_TOO_LARGEA resposta passou do limite.Peça menos itens ou use detail=summary.
FILE_TOO_LARGE ou DIFF_TOO_LARGEO arquivo passa de 2 MiB ou o diff passa de 8 MiB.Consulte trechos pela busca ou compare commits.
SYMBOL_AMBIGUOUSHá mais de uma rotina com esse nome.Use o nome qualificado ou leia pelas linhas indicadas.
SCAN_CHANGED, CODE_CHANGED ou CANDIDATE_SOURCES_CHANGEDA fonte mudou durante a consulta.Refaça a consulta desde o início.
not_collectedO PJ não tem coleta.Solicite a coleta na aplicação. O MCP não inicia coletas.
index_unavailableO índice de projetos não está disponível.Avise o responsável pelo Knowledge. As demais ferramentas seguem funcionando.