---
fragment_peers:
  aplicar-politicas-de-processamento-interno: apply-internal-processing-policies
  do-rascunho-privado-ao-acervo-escolhido: from-private-draft-to-selected-collection
  edicao-mcp-e-inicializacao: mcp-edition-and-initialization
  executar-localmente-e-conectar-mcp: local-setup-and-mcp
  exportar-o-rascunho-escolhido: export-the-selected-draft
  formalizar-pelo-terminal: formalize-through-the-terminal
  organize-o-repositorio-e-a-leitura: organize-the-repository-and-its-reading
  perfis-de-capacidade: capability-profiles
  preparacao-formal-quando-escolhida: formal-preparation-when-chosen
  preparacao-local-para-terminal-ou-mcp: local-setup-for-terminal-or-mcp
  preparar-e-trocar-arquivos: prepare-and-exchange-files
  quando-escolher-compartilhar-um-registro-assinado: when-you-choose-to-share-a-signed-record
  rascunhos-sem-chave-ou-did: drafts-without-a-key-or-did
  usar-as-ferramentas-mcp-no-desktop: use-mcp-tools-on-desktop
lang: pt
peer: en/configurations/
shared_fragments: false
title: Executar localmente e conectar MCP
---

# 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](get-started.md), identifique a apresentação,
o acervo e as propostas acessíveis. Para [abrir um espaço](open-space.md),
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.

<div class="configuration-list" markdown="1">

### 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](downloads/legible-primeiro-uso-pt.txt){ download="legible-primeiro-uso-pt.txt" }
ou o [guia de participação](downloads/legible-participar-pt.txt){ download="legible-participar-pt.txt" }.
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](get-started.md).

### 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`.

</div>

## 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](get-started.md).
Os passos abaixo são para quem deseja executar os componentes de referência.

Obtenha uma cópia do [repositório do protocolo](https://github.com/LegibleProtocol/protocolDev), 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/`:

```sh
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](pilot.md) 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:

```sh
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](get-started.md#escolha-e-guarde-a-origem)
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.

```json
{
  "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](pilot.md) ·
[Instruções para agentes](agents.md) · [Downloads](downloads.md)


## Organize o repositório e a leitura

<aside class="technical-note" markdown="1">
**Caminhos técnicos opcionais.** As instruções abaixo servem a quem escolheu
usar Git, terminal ou MCP. Para a primeira troca manual, basta guardar o rascunho,
conservar sua origem e combinar como enviá-lo; você não precisa instalar essas ferramentas.
</aside>

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](drafts.md). 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](configurations.md). Substitua os caminhos, a origem e o
identificador abaixo pelos valores reais mostrados na importação ou busca:

```sh
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.