Free MCP tools reference

Auto-generated from the real MCP tool registry — the exact tools/list response a free-tier client receives (silex-archaeology 0.11.36). 10 tools. Drift between this page and the registry fails the site build (--check).

create_workspace

Create a workspace and trigger the ingestion scan in background.

Quando usar: primeiro passo pra analisar um repositório novo (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: get_workspace_stats (poll até scan_status=completed); se não souber o workspace_id, list_workspaces primeiro.

Two modes, both returning immediately after the workspace is registered (BEFORE scan completes). In both cases the scan (chunking, Neo4j/SQLite mirror, Qdrant, communities, semantic labeling) runs in a daemon thread — check progress with get_workspace_stats(workspace_id).

Mode git (default) — multi-repo CLONE: Clones each repo (reusing existing clones for the same URL+branch) and registers one Repo per spec. Wraps the same engine as POST /api/workspaces.

Mode local (EXT-ZEROCONF-2 #1040) — attach IN-PLACE, no clone/copy: Registers local_path as the workspace source via create_workspace_with_source and scans the directory WHERE IT IS (zero clone, zero copy). This is the Jornada B path: the "Analisar este repositório" button in the Extension analyses the repo the user already has open. repos is IGNORED in this mode.

Parameter Type Default Required
name string — yes
repos array | null None no
description null | string None no
source_type string 'git' no
local_path null | string None no

Example call:

{
  "tool": "create_workspace",
  "arguments": {
    "name": "<name>"
  }
}

generate_domain_report

Generate a human-readable Markdown domain report for sharing with QA, functional analysts and tech leads.

Quando usar: fechamento do fluxo de exploração — consolidar entidades/rules/FSMs/workflows num relatório compartilhável (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: nenhum obrigatório; para enriquecer com LLM primeiro, confira silex.llm_provider.status e rode de novo com enrich_with_llm=True.

Runs the full extraction pipeline, then renders a report with: - Summary (entities, rules, state machines, workflows) - Entity table with fields, relationships, PKs - State machine diagrams with transitions - Business rules table (with 🔧 heuristic / 🤖 llm badges) - Enums table - Workflow summaries - Gap analysis with severity emojis - Recommended next steps

Parameter Type Default Required
workspace_id string — yes
domain_id string 'auto' no
output_dir string '' no
enrich_with_llm boolean False no
llm_provider string 'azure' no
language string 'en' no
force_inline boolean False no

Example call:

{
  "tool": "generate_domain_report",
  "arguments": {
    "workspace_id": "<workspace_id>"
  }
}

get_code_communities

Hierarchical code communities (Leiden) with members + labels — tier-aware.

Quando usar: ver o mapa navegável do codebase (comunidades hierárquicas com labels) depois do scan completo (kit de onboarding — MCP-KIT-1

1136). Próximo passo: get_structural_findings (achados sem LLM) ou

silex.community.code_pack pra ler o código de uma comunidade específica.

J1-MAPA-1 (#1077): fonte do MAPA navegável do Domain Explorer no free-tier. Delega ao leitor canônico único fetch_communities_with_members (DOGFOOD-2

678), que resolve o tier: no free lê .silex/workspace.db (SQLite), no

pro/enterprise lê Postgres — SHAPE IDÊNTICO nos dois. Ao contrário de get_communities (Postgres-only, shape achatado), devolve a hierarquia completa com a MESMA forma anexada por generate_domain_jsons no campo communities: id, label, level, parent_id, algorithm, cohesion, bridge_nodes, members. Ordem estável (supers por size desc; cada sub logo após o pai). Lista vazia quando o workspace não tem community detection rodada — o consumidor trata como "sem mapa" (orientação #1058), nunca mapa fantasma.

Parameter Type Default Required
workspace_id string — yes

Example call:

{
  "tool": "get_code_communities",
  "arguments": {
    "workspace_id": "<workspace_id>"
  }
}

get_rules_by_ids

Batch-fetch rules from the materialized business_logic.json.

Quando usar: resolver linked_rule_ids (de um step de workflow ou de silex.business_logic.submit) em rule dicts completos, num round-trip (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: generate_domain_report pra visão consolidada do domínio.

Sprint 2026-04-17. Used by the Workflow Viewer to resolve step.linked_rule_ids into full rule dicts in a single round-trip (avoids N calls to get_operation_detail per workflow).

Parameter Type Default Required
workspace_id string — yes
rule_ids array — yes

Example call:

{
  "tool": "get_rules_by_ids",
  "arguments": {
    "workspace_id": "<workspace_id>",
    "rule_ids": []
  }
}

get_structural_findings

Structural findings — pontes, hubs e áreas órfãs do grafo local (sem LLM).

Quando usar: depois do mapa (get_code_communities), pra achados estruturais objetivos (pontes/hubs/órfãos) sem gastar LLM (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: silex.community.code_pack pra aprofundar numa comunidade específica.

ACHADOS-1 (#1114): a fonte da seção Achados do Domain Explorer (irmã do mapa J1-MAPA-1 #1077). Fina por cima do service compute_structural_findings, que deriva os três achados dos MESMOS dados do mapa (comunidades de código + arestas code_references) via os leitores canônicos tier-aware — free lê o espelho SQLite, pro/enterprise Postgres/ Neo4j. NÃO recomputa comunidades nem escreve no grafo.

Shape: {workspace_id, bridges, hubs, orphan_areas, hardcoded_secrets, shared_literals, clone_families, clone_families_total, clone_families_capped, dead_code_candidates, risk_markers, config_usage, state_contradictions}. hardcoded_secrets (SENSOR-SECRET-1 #1200) é aditivo: connection string Password=/Pwd= ou api key/token/secret literal em código de aplicação, com âncora file/line e valor SEMPRE mascarado (masked_value, nunca o segredo em claro). shared_literals (SENSOR-LIT-1 #1201) é aditivo: literal distintivo (≥6 chars, não-rota/SQL/path/formato) compartilhado entre arquivos de ≥2 comunidades ou 2 linguagens vira achado shared_literal com âncoras de TODOS os arquivos envolvidos (padrão golden: FP_events PHP×JS do SuiteCRM) — literal trivial/único/de alta frequência nunca vira achado. clone_families (SENSOR-CLONE-1 #1202) é aditivo: bloco de código idêntico (normalizado, janela de ≥5 linhas significativas) repetido em ≥2 arquivos de aplicação vira UMA família clone_family com TODOS os membros ancorados (file/line_start/line_end por membro) — nunca N achados soltos pro mesmo clone. Cap de 100 famílias (as maiores primeiro) declarado via clone_families_total/clone_families_capped — nunca truncamento silencioso. dead_code_candidates (SENSOR-DEAD-1 #1203) é aditivo: símbolo de aplicação (chunk com method) sem referência textual fora da própria definição vira candidato dead_code_candidate com âncora e confidence (alta privado/interno, baixa público/protegido — reflection/DI podem chamar sem referência estática, NUNCA um veredito). Exclusões estruturadas (entry point, handler DOM *_handler_L<linha>, action de *Controller, override/interface, teste/vendor) nunca viram achado — controller action pública NUNCA é flagada (anti-aceite: falso-positivo mata a confiança no achado). risk_markers (SENSOR-MARK-1 #1204) é aditivo: {markers, total, by_community, top_files, top_files_total, top_files_capped} — marcador TODO/HACK/FIXME em contexto de comentário (//, #, /*, <!--, ' só em VB) vira achado marker_kind/file/line/text ancorado, agregado por comunidade e por top arquivos (cap declarado, nunca truncamento silencioso). Marcador dentro de STRING literal (sem delimitador de comentário na linha) nunca conta. age_days sai SEMPRE None aqui — a leitura tier-aware não expõe root de disco resolvível pra git blame; só o extractor de business_logic.rules (pipeline real, com context.workspace_path) calcula a idade, best-effort, nunca quebra sem git. config_usage (SENSOR-CONF-1 #1205) é aditivo: {declared_unused, used_undeclared, diagnostics} — chave declarada em appsettings*.json/web.config sem NENHUMA leitura no código vira declared_unused (âncora na declaração, severidade baixa); chave lida (Configuration["K"]/AppSettings["K"]/GetValue<T>("K")/ GetSection("K")/GetConnectionString("K")) e ausente de TODA config do repo vira used_undeclared (âncora na leitura, severidade média — risco de runtime); declarada E lida não vira achado. Chave passada como variável/concatenação (não literal) nunca vira candidato — sai como diagnóstico dynamic_key (nunca silêncio). Limitação: este consumidor só lê chunks tier-aware (sem disco) — web.config não é chunkeado pelo ingestor hoje, então só surge aqui se presente como chunk; o extractor real (business_logic.rules, com context.workspace_path) lê ambos direto do disco, sem essa limitação. state_contradictions (CONTRA-1 #1221) é aditivo: literal de estado numa condition de regra (ex.: status != 11) cujo campo resolve pra um enum do domínio (ex.: Situacao {1..9}) mas NÃO está entre os valores válidos vira achado state_not_in_domain com âncora dos DOIS lados (client_anchor da condition + domain_anchor da declaração do enum) e mensagem legível. Reusa o parser de enum de numeric_state_catalog (não re-parseia) — enum [Flags]/aberto tem domínio aberto e nunca contradiz; campo que não resolve pra enum conhecido não vira achado (conservador, zero falso positivo); literal dentro dos valores válidos não vira achado. Grafo/chunks sem dado → os grupos vêm vazios (o consumidor renderiza o estado honesto, nunca achado inventado).

Parameter Type Default Required
workspace_id string — yes

Example call:

{
  "tool": "get_structural_findings",
  "arguments": {
    "workspace_id": "<workspace_id>"
  }
}

get_workspace_stats

Get overview stats for a workspace: classes, edges, communities, languages.

language (SCAN-IGNORE-1 #1329, mesmo contrato stateless de generate_domain_report): idioma da linha honesta vendor_generated — "en" (default) ou "pt-br". Idioma desconhecido devolve erro estruturado (normalize_language), nunca fallback silencioso.

Quando usar: poll depois de create_workspace até scan_status virar completed (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: get_code_communities (mapa) quando o scan terminar.

Tier-aware (STATS-TIER-1 #1057). Este é o elo do poll do botão de 1 clique: o free-tier não tem Neo4j instalado, então o ramo pago (que consulta o grafo) importava neo4j incondicionalmente e o poll morria com No module named 'neo4j' mesmo com o scan já completo.

O shape de resposta é IDÊNTICO entre tiers: {workspace_id, classes, edges, communities, languages, scan_status, heartbeat_age_seconds, vendor_generated_excluded, next_action}.

J1-DONE-1 (#1069): scan_status (registry de workspaces, mesma coluna nos dois tiers — scanning/completed/error/pending) é o sinal de "pipeline COMPLETO" que o poll do botão de 1 clique passou a exigir; ``classes

0`` só prova o fim do chunking (existe minutos antes de linking/Leiden/ comunidades). Campo aditivo — leitor antigo ignora.

J1-RESCAN-1 (#1071): heartbeat_age_seconds (segundos desde o updated_at do registry, null quando indisponível) expõe a idade do heartbeat da #1072. É a fonte que o botão usa pra distinguir scanning vivo (idade pequena) de scanning zumbi (idade estagnada — só sobra em kill -9), sem hardcodar heurística sem lastro no registry. Campo aditivo.

Parameter Type Default Required
workspace_id string — yes
language string 'en' no

Example call:

{
  "tool": "get_workspace_stats",
  "arguments": {
    "workspace_id": "<workspace_id>"
  }
}

list_workspaces

List all registered workspaces, most recently updated first.

Quando usar: descobrir workspaces já existentes antes de repetir create_workspace (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: get_workspace_stats(workspace_id) com o id escolhido.

Reads the local registry in-process (same tier-aware path as create_workspace — no HTTP, no running API required). Read-only — no side effects. Use this before create_workspace or any workspace-scoped tool to let the caller pick an existing workspace by name instead of requiring a raw UUID.

No parameters.

Example call:

{
  "tool": "list_workspaces",
  "arguments": {}
}

silex.business_logic.submit

Persiste rules extraídas pelo LLM do cliente (com provenance) (#675).

Quando usar: depois de silex.community.code_pack — submeter as rules que o LLM do cliente extraiu do código lido (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: silex.contract.fact.generate pra consolidar o escopo, ou generate_domain_report pra visão completa do domínio.

Fecha o loop da arqueologia client-orchestrated (ONBOARD-6): recebe as rules que o LLM do cliente extraiu do code_pack, valida a evidência e as persiste no business_logic.json materializado — shape consumido por silex.contract.fact.generate (passa a montar o fact_contract com rules reais, não fixture).

Trava não-negociável: rule sem evidência é alucinação. Cada rule exige provenance — class_name (símbolo), source_file (arquivo) e line_start ou evidence (localização/trecho). Rule sem isso é rejeitada (erro estruturado) e nada é persistido (atômico). As rules entram como proposed (camada 1.5 — fato candidato, nunca ground-truth silencioso); promover é review humano. Merge idempotente: re-submeter a mesma rule não duplica.

Parameter Type Default Required
workspace_id string — yes
rules_json string — yes
artifact_root string '' no

Example call:

{
  "tool": "silex.business_logic.submit",
  "arguments": {
    "workspace_id": "<workspace_id>",
    "rules_json": "<rules_json>"
  }
}

silex.community.code_pack

Devolve o pack de leitura de uma comunidade — código + evidência (#675).

Quando usar: depois de escolher uma comunidade (via get_code_communities/get_structural_findings) pra ler o código-fonte e extrair rules com o LLM do cliente (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: silex.business_logic.submit com as rules extraídas.

Substrato da arqueologia client-orchestrated (ONBOARD-6): o server não roda LLM. Dado um escopo coeso (comunidade/package), esta tool resolve os membros (Postgres) e devolve o código dos chunks (do .silex/workspace.db free-tier, ONBOARD-2) + evidência estrutural (arquivo/classe/método/linhas/labels + arestas :REFERENCES intra-escopo), num formato enxuto pro LLM do cliente (claude-code) interpretar e extrair as rules — que voltam por silex.business_logic.submit.

Camada 1 (fato, fiel ao código). Read-only — não muta nada. Happy path free-tier: zero chave, zero GPU.

Orçamento por default (PACK-BUDGET-1 #1325): comece SEM parâmetros — o pack já respeita um orçamento default (~40k chars) que cabe no teto de resultado do seu cliente MCP. Se houver mais código do que cabe, o retorno vem truncated: true com um next_cursor opaco e uma continuation_hint textual: chame de novo com cursor=<next_cursor> (mesmos parâmetros) pra pegar a próxima página. Pagine até o retorno vir sem next_cursor — a concatenação reconstrói o pack inteiro, byte a byte, sem perda. Corte é SEMPRE em fronteira de chunk (nunca código pela metade). Poder avançado: max_total_chars=0 devolve tudo de uma vez (ilimitado); max_chunk_chars/max_chunks_per_member são knobs finos ortogonais ao orçamento.

Truncamento consciente de chunk (PACK-CHUNK-TRUNC-1 #1338): quando max_chunk_chars corta o código de um chunk, o corte recua pra a última quebra de linha completa dentro do limite — nunca no meio de uma linha/método. O chunk truncado vem com truncated: true + chunk_handle opaco + continuation_hint: chame de novo só com chunk_handle=<handle> (mesmos workspace_id/db_path; não precisa repetir package_id/community_id) pra receber o RESTO do código desse chunk, byte a byte, numa resposta chunk_continuation.

Parameter Type Default Required
workspace_id string — yes
package_id string '' no
community_id string '' no
db_path string '' no
max_chunk_chars integer 0 no
max_chunks_per_member integer 0 no
max_total_chars integer 40000 no
cursor string '' no
chunk_handle string '' no

Example call:

{
  "tool": "silex.community.code_pack",
  "arguments": {
    "workspace_id": "<workspace_id>"
  }
}

silex.contract.fact.generate

Gera o contrato de fato (fact_contract/v1) de um escopo coeso.

Quando usar: depois de silex.business_logic.submit (ou de rules heurísticas já materializadas), pra consolidar o escopo num contrato versionado (kit de onboarding — MCP-KIT-1 #1136). Próximo passo: nenhum obrigatório — o fact_contract é o artefato de saída deste ramo do fluxo.

Coleta as rules já extraídas (com provenance de símbolo) de uma comunidade/package materializada e as serializa num artefato versionado com status: proposed. É agregação/serialização sobre o business_logic.json materializado — não nova extração.

Camada 1 (fato, fiel ao código). Propor ledger candidato é MH-3; review/promoção proposed→active é MH-4 — fora desta tool.

Parameter Type Default Required
workspace_id string — yes
package_id string '' no
community_id string '' no
artifact_root string '' no
use_cache boolean True no

Example call:

{
  "tool": "silex.contract.fact.generate",
  "arguments": {
    "workspace_id": "<workspace_id>"
  }
}