Executar localmente e conectar MCP¶
Escolha a configuração a partir da operação de que precisa — trocar um rascunho, conectar ferramentas à sua IA ou assinar uma declaração no terminal — e combine os caminhos conforme seu ambiente. Quem prepara no celular e quem verifica no desktop compartilham os contratos do protocolo, preservando os recursos e as condições de cada instalação.
Uma organização pode acrescentar busca interna e políticas próprias. Ao trocar contribuições entre ambientes, confira como cada lado exporta arquivos, concede acesso e autoriza o processamento.
Perfis de capacidade¶
Para participar de um espaço, identifique a apresentação, o acervo e as propostas acessíveis. Para abrir um espaço, combine esses recursos com instruções e condições de participação. A escolha abaixo descreve capacidades técnicas, não exige uma infraestrutura comum.
No celular, um chat como o Gemini pode trabalhar com os trechos ou anexos que você selecionar; a troca com o repositório pode continuar manual. Em hosts como Hermes, Codex ou Claude Code, ferramentas autorizadas de arquivos e Git podem reduzir essas transferências. Isso não constitui uma receita homologada para cada produto: confira versões, acessos, processamento e ações realmente testadas.
Preparar e trocar arquivos¶
Oferece: Legible Draft (campos técnicos Genealogy 0.1) e compartilhamento selecionado. Exige: editor ou chat cujo texto possa ser salvo e armazenamento escolhido pelos participantes. Não exige modelo, chave ou servidor Legible. Para usar IA, escolha o guia de primeiro uso ou o guia de participação. Cada um já contém as orientações e o formato; configuração MCP e bancada são avançadas.
Diagnóstico: anexe fontes quando a IA não puder abrir links; salve o Markdown manualmente quando não houver exportação de arquivos. Comece pelo exemplo entre participantes.
Usar as ferramentas MCP no desktop¶
Oferece: importação de pacotes de rascunhos, busca local por texto, preparação de declarações não assinadas e verificação estruturada. Exige: Python 3.10+, CLI Rust compilado e um host MCP stdio.
Diagnóstico: confira caminhos, inicialização, edição negociada e catálogo de tools. Configure a raiz e a identidade do participante; o MCP recusa caminhos fora desse escopo, mas não isola um agente com terminal irrestrito.
Formalizar pelo terminal¶
Oferece: preparação, revisão, assinatura suportada, validação e verificação,
com armazenamento privado antes de compartilhar.
Exige: Rust 1.88+ para o Cargo.lock atual, Python para helpers e OpenSSH com -Y e Ed25519 simples.
Diagnóstico: confira o conteúdo exato e o namespace de assinatura.
O caminho básico não aceita chaves FIDO ed25519-sk.
Aplicar políticas de processamento interno¶
Armazenamento e processamento internos podem combinar os caminhos acima. Uma organização escolhe modelos, controle de acesso e custódia de chaves; não há IAM corporativo ou modelo fornecido pelo protocolo.
O modelo é escolhido e pago por quem usa ou opera o ambiente. Arquivos não
exigem inferência. O servidor MCP de referência usa um stub em sua tool
draft; essa árvore provisória não é o formato de intercâmbio Legible Draft.
O modelo do host pode auxiliar a formulação, mas é outro componente.
Os perfis estão definidos em profiles/configurations.json no pacote.
Para conferir as dependências, execute python3 -m legible.doctor PERFIL, usando
mobile-files, desktop-mcp, private-terminal e internal-files.
O diagnóstico é offline: confere dependências locais. Conta de chat, aparelho,
host MCP e políticas precisam ser testados no ambiente em que serão usados.
Preparação local para terminal ou MCP¶
Para a primeira troca de rascunhos, basta Participar de um espaço. Os passos abaixo são para quem deseja executar os componentes de referência.
Obtenha uma cópia do repositório do protocolo, na edição que
pretende testar. Com Rust/Cargo e Python disponíveis, execute estes comandos
na raiz desse checkout, onde estão reference/ e profiles/:
cargo build --manifest-path reference/legible-core/Cargo.toml
export LEGIBLE_BIN="$PWD/reference/legible-core/target/debug/legible"
export PYTHONPATH="$PWD/reference/legible-py"
"$LEGIBLE_BIN" --help
python3 -m legible.doctor desktop-mcp
Os comandos usam os módulos e perfis desse checkout. A compilação pode precisar baixar dependências Rust. Esses passos preparam as ferramentas; assinatura e publicação são operações posteriores, separadas.
Edição MCP e inicialização¶
O servidor tem como alvo 2025-11-25 e negocia a edição solicitada quando suportada
(2025-06-18, 2025-03-26, 2024-11-05). Caso contrário, devolve sua edição-alvo;
o cliente decide se continua. Ensaios locais não certificam toda implementação
cliente. O piloto local acrescenta HTTP JSON para 2025-03-26,
2025-06-18 e 2025-11-25. OAuth e conexão nativa Gemini não são entregues.
Rascunhos sem chave ou DID¶
Crie primeiro uma pasta privada por participante, fora da pasta estática do site. Escolha e mantenha um URI de origem distinto por coleção/participante. Para gerar um identificador local uma única vez, execute:
python3 -c "import uuid; print('urn:uuid:' + str(uuid.uuid4()))"
Copie a saída para LEGIBLE_DRAFT_ORIGIN no template abaixo. Não use o
placeholder nem gere outra origem a cada sessão. Um nome como ana pode
existir em várias instalações; não identifica uma origem única. O URI não
prova identidade nem exige servidor. Cópias recebidas mantêm a origem de quem
as enviou. Origens já compartilhadas não devem ser renomeadas silenciosamente.
Sem terminal, o gerador local no guia de participação oferece a mesma escolha. Guarde o valor antes de sair da página; não gere uma segunda origem se a coleção já tem uma.
{
"mcpServers": {
"legible": {
"command": "/ABSOLUTE/PATH/TO/python3",
"args": ["-m", "legible_mcp.server"],
"env": {
"PYTHONPATH": "/YOUR/CHECKOUT/reference/legible-mcp",
"LEGIBLE_BIN": "/YOUR/CHECKOUT/reference/legible-core/target/debug/legible",
"LEGIBLE_REPO_ROOT": "/YOUR/PRIVATE/PARTICIPANT/REPOSITORY",
"LEGIBLE_PARTICIPANT": "YOUR_HANDLE",
"LEGIBLE_DRAFT_ORIGIN": "YOUR_STABLE_DISTINCT_ORIGIN_URI"
}
}
}
}
Preencha os caminhos absolutos, inclusive o do Python, e adapte o template
ao formato aceito pelo seu host. A raiz do participante é obrigatória.
O servidor recusa outros repositórios, arquivos fora da pasta de registros
e links simbólicos. Acesso a terminal irrestrito e custódia de chaves exigem
isolamento no host; a inicialização não autoriza assinatura ou publicação.
O host carrega esse JSON pelo mecanismo que disponibilizar; o template não
configura todos os produtos automaticamente. Confira a inicialização e
tools/list no host escolhido. save_draft exige origem explícita; sem ela,
recusa salvar em vez de usar o nome como origem. search_drafts e importação
preservam os arquivos recebidos. O diagnóstico legible.doctor desktop-mcp
informa se há URI configurado, mas não prova unicidade ou integração do host.
Exportar o rascunho escolhido¶
A busca MCP entrega drafts, complete e issues. Se houver falha em uma
entrada, confira o aviso de resultado parcial; arquivos íntegros continuam
legíveis e exportáveis por versão exata. Na biblioteca, search_report oferece
esse retorno; search mantém a lista estrita e falha se estiver incompleta.
Na CLI, python3 -m legible.drafts search --repo /CAMINHO/PRIVADO --report
devolve o relatório JSON: código 0 para consulta completa e 2 para parcial.
Sem --report, a busca conserva o contrato anterior de lista estrita.
Os caminhos e hashes do diagnóstico ajudam a localizar a falha. Preserve
os arquivos antes de qualquer recuperação; não há reparo ou exclusão automática.
Para a troca de rascunhos no MCP stdio, search_drafts e read_draft mostram
a origem, o identificador e bytes_sha256 da versão. Depois da seleção real,
chame export_draft_packet com esses três valores, um nome novo e simples em
package e selected: true. O pacote fica em exports/drafts/<package>/ da
raiz configurada, sem sobrescrita e sem cópia das evidências. Confira o
Markdown e o manifesto antes de escolher um envio. Não há publicação nem
assinatura nessa operação. Na outra instalação, coloque o pacote selecionado
em imports/ e use import_draft_packet; um reenvio idêntico não cria outro
rascunho. O MCP de rede do piloto não expõe essa exportação.
Preparação formal quando escolhida¶
Ao escolher a formalização, acrescente LEGIBLE_AUTHOR_DID ao mesmo objeto
env, com o DID público explícito do autor. A operação deve receber o mesmo
author_did; autoria incompatível é recusada. Não coloque chave privada ou
senha nessa configuração. Em sessão compartilhada, não atribua a declaração
ao dono da conta: use a identidade escolhida pelo próprio autor. A preparação
continua não assinada e não compartilhada.
Piloto Android + Gemini e MCP na rede local · Instruções para agentes · Downloads
Organize o repositório e a leitura¶
O README pode apresentar o espaço; CONTRIBUTING.md descreve o percurso de
envio, as licenças e a revisão. A convenção de armazenamento é .legible/;
os rascunhos seguem o perfil existente. Documentos de contexto
continuam documentos comuns: não precisam virar registros para poderem ser lidos.
Do rascunho privado ao acervo escolhido¶
A referência Python/MCP guarda cópias de trabalho em .ch/genealogy/.
Essa pasta é privada; não é o acervo que você deve colocar no Git. Exporte
apenas a contribuição selecionada, com o manifesto que conserva origem,
identificador e hash. O exemplo usa .legible/drafts/ para esses pacotes;
é uma organização de pastas para este percurso, não um novo formato obrigatório.
Na raiz do checkout do protocolo, configure PYTHONPATH conforme a
preparação local. Substitua os caminhos, a origem e o
identificador abaixo pelos valores reais mostrados na importação ou busca:
python3 -m legible.drafts export --repo /CAMINHO/RAIZ-PRIVADA --origin SUA_ORIGEM_URI --id ID_DO_RASCUNHO --path /CAMINHO/PACOTE-SELECIONADO --selected
No MCP local, export_draft_packet faz essa preparação sem sair da ferramenta.
Selecione a versão retornada por read_draft ou search_drafts: informe
origin, id, bytes_sha256, um nome simples em package e selected: true
somente após a escolha do participante. A saída fica em
exports/drafts/<package>/, dentro da sua raiz privada. O pacote contém apenas
o rascunho e o manifesto, não as evidências referenciadas. O comando recusa
sobrescritas e não envia arquivos, abre PRs ou assina. O piloto MCP de rede
mantém seu catálogo restrito; essa exportação pertence ao servidor local stdio.
A pasta de destino deve ser nova. Revise o Markdown e manifest.json, copie
somente esse pacote para o acervo compartilhável e confira git status e
git diff --cached antes do commit. Use uma subpasta por origem e contribuição,
para que nomes locais iguais não se sobrescrevam. Não copie o .gitignore
do repositório técnico como política do espaço: ele ignora toda a .legible/
local de propósito. O exemplo baixável permite os pacotes escolhidos em
.legible/drafts/, mantendo .ch/, contatos, evidências e credenciais fora.
Ignorar um arquivo evita inclusão comum no Git; não protege arquivos já
rastreados, o histórico nem o acesso pelo sistema operacional.
Sem biblioteca ou terminal, guarde o Markdown e a origem informada com ele, conforme o guia de participação. Não invente hashes ou um manifesto validado: o destinatário pode usar a referência para produzir a cópia de transporte.
Quando escolher compartilhar um registro assinado¶
Guardar um registro formal na sua raiz privada não o torna parte do espaço.
Depois da revisão e assinatura, valide o formato e verifique a assinatura com
legible validate --record ARQUIVO e legible verify --record ARQUIVO.
Confira também se o conteúdo e as referências podem ser compartilhados:
copiar o arquivo para um local público divulga seu conteúdo, mesmo que o
campo assinado continue marcado como visibility: private. Para declarar
outro escopo de visibilidade, prepare e assine um novo registro.
Para compartilhar a versão escolhida, copie somente o arquivo verificado
para a pasta correspondente no acervo autorizado, preservando nome, bytes,
ID e assinatura. Não copie a raiz privada, o CH, o perfil de contato ou as
evidências. Confira que o destino ainda não existe antes de copiar. Um Appoint,
por exemplo, fica em .legible/appoints/<ID>.appoint.
O modelo mantém registros formais ignorados por padrão. Para incluir apenas
o arquivo escolhido, use git add -f -- .legible/appoints/<ID>.appoint na
cópia compartilhável, substituindo <ID> pelo ID real. Confira git status
e git diff --cached, inclusive outros arquivos que já estejam preparados.
Não remova a proteção de toda a .legible/. A seleção desse arquivo não
autoriza commit, push ou envio: essas operações ainda dependem da sua escolha.
Se usar forks e PRs, explique como abrir e consultar uma proposta, inclusive quando ela não foi incorporada. A existência de um PR não garante preservação indefinida: quem desejar continuidade deve conservar os arquivos e as referências que tem direito de manter. Um repositório próprio pode cumprir essa função.
Um Git interno pode usar branches, referências ou intercâmbio de arquivos. Interfaces de PR dependem do software escolhido; não são um recurso do Git sozinho. Grupos com restrições de acesso precisam de um percurso compatível com suas políticas, sem incentivar cópias externas de material protegido.