Local setup and MCP¶
Choose a configuration for the operation you need — exchanging a draft, connecting tools to your AI or signing a declaration in the terminal — and combine paths to suit your environment. Someone preparing on a phone and someone verifying on a desktop share the protocol's contracts while retaining the resources and conditions of their own installations.
An organization can add internal search and its own policies. When exchanging contributions across environments, check how each side exports files, grants access and authorizes processing.
Capability profiles¶
To participate in a space, identify its introduction, collection and accessible proposals. To open a space, combine these resources with participation instructions and conditions. The choices below describe technical capabilities without requiring shared infrastructure.
On mobile, a chat such as Gemini can work with excerpts or attachments you select; repository exchange may remain manual. In hosts such as Hermes, Codex or Claude Code, authorized file and Git tools may reduce those transfers. This is not a validated recipe for each product: check versions, access, processing and actions actually tested.
Prepare and exchange files¶
Offers: Legible Draft (technical Genealogy 0.1 fields) and selected sharing. Requires: an editor or chat whose text can be saved and storage selected by participants. No model, key or Legible server is required. For AI assistance, choose the first-use guide or participation guide. Each already contains guidance and the format; MCP setup and the bench are advanced.
Diagnostics: attach sources when AI cannot open links; save Markdown manually when file export is unavailable. Start with the example between participants.
Use MCP tools on desktop¶
Offers: draft packet import, local text search, unsigned declaration preparation and structured verification. Requires: Python 3.10+, a Rust-built CLI and a stdio MCP host.
Diagnostics: check paths, initialization, negotiated edition and tool catalogue. Configure participant root and identity; MCP refuses paths outside that scope but does not isolate an unrestricted terminal agent.
Formalize through the terminal¶
Offers: preparation, review, supported signing, validation and verification,
with private storage before sharing.
Requires: Rust 1.88+ for the current Cargo.lock, Python helpers and OpenSSH with -Y and plain Ed25519.
Diagnostics: check the exact content and signature namespace.
The baseline path does not accept FIDO ed25519-sk keys.
Apply internal-processing policies¶
Internal storage and processing can combine the paths above. An organization chooses models, access control and key custody; the protocol supplies neither enterprise IAM nor a model.
The model is selected and paid for by whoever uses or operates the environment.
Files need no inference. The reference MCP server uses a stub in its
draft tool; that provisional tree is not the Legible Draft interchange format.
The host's model may help formulation but is a separate component.
Profiles are defined in profiles/configurations.json in the package.
To check dependencies, run python3 -m legible.doctor PROFILE, using
mobile-files, desktop-mcp, private-terminal and internal-files.
The diagnosis is offline: it checks local dependencies. Chat accounts, devices,
MCP hosts and policies need testing in the environment where they will be used.
Local setup for terminal or MCP¶
For the first draft exchange, follow Participate in a space. The steps below are for running the reference components.
Obtain a checkout of the protocol repository at the edition
you intend to test. With Rust/Cargo and Python available, run these commands
from its root, which contains reference/ and 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
The commands use the modules and profiles in that checkout. Compilation may need to download Rust dependencies. These steps prepare the tools; signing and publication are separate, later operations.
MCP edition and initialization¶
The server targets 2025-11-25 and negotiates the client's requested edition when
supported (2025-06-18, 2025-03-26, 2024-11-05). Otherwise it returns its target
edition; the client must decide whether to continue. Local transport tests do not
certify every client's implementation. The local pilot adds HTTP
JSON for 2025-03-26, 2025-06-18 and 2025-11-25. OAuth and native Gemini
integration are not delivered.
Drafts without a key or DID¶
First create a private directory per participant, outside the static site root. Choose and keep a distinct origin URI per collection/participant. To generate a local identifier once, run:
python3 -c "import uuid; print('urn:uuid:' + str(uuid.uuid4()))"
Copy the output into LEGIBLE_DRAFT_ORIGIN in the template below. Do not use
the placeholder or generate a new origin every session. A name like ana
may exist in many installations; it identifies no unique origin. The URI
proves no identity and requires no server. Received copies retain their
sender's origin. Never silently relabel already shared origins.
Without a terminal, the local generator in the participation guide offers the same choice. Save the value before leaving the page; do not generate a second origin for a collection that already has one.
{
"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"
}
}
}
}
Fill in the absolute paths, including Python's, and adapt the template to the
format your host accepts. The participant root is required. The server refuses
other repositories, files outside the record store and symlinks.
Unrestricted terminal access and key custody require host isolation;
initialization does not authorize signing or publication.
The host loads this JSON through its own mechanism; the template does not
automatically configure every product. Check initialization and tools/list
in the chosen host. save_draft requires an explicit origin; without it,
it refuses saving rather than use a name as origin. search_drafts and import
preserve received files. legible.doctor desktop-mcp reports whether a URI
is configured, but proves neither uniqueness nor host integration.
Export the selected draft¶
MCP search returns drafts, complete and issues. If an entry fails, inspect
the partial-result warning; healthy files remain readable and exportable by
exact version. In the library, search_report provides that response; search
retains its strict list and fails when incomplete. In the CLI,
python3 -m legible.drafts search --repo /PATH/PRIVATE --report returns JSON:
exit 0 for a complete query and 2 for a partial one. Without --report, search
preserves its previous strict-list contract. Diagnostic paths and hashes help
locate the failure. Preserve files before any recovery; nothing is automatically
repaired or deleted.
For draft exchange in stdio MCP, search_drafts and read_draft return the
origin, handle and bytes_sha256 of the version. After actual selection, call
export_draft_packet with these three values, a new simple label in package
and selected: true. The packet goes to exports/drafts/<package>/ under the
configured root, with no overwrite or evidence copying. Review the Markdown
and manifest before choosing to send. This operation neither publishes nor
signs. In the other installation, place the selected packet in imports/ and
use import_draft_packet; an identical resend creates no new draft. The network
pilot MCP does not expose this export.
Formal preparation when chosen¶
When choosing formalization, add LEGIBLE_AUTHOR_DID to the same env
object with the author's explicit public DID. The operation must supply the
same author_did; mismatching authorship is refused. Put no private key or
password in that configuration. In a shared session, do not attribute the
declaration to the account owner; use the identity chosen by its author.
Preparation remains unsigned and unshared.
Android + Gemini and LAN MCP pilot · Agent instructions · Downloads
Organize the repository and its reading¶
The README can introduce the space; CONTRIBUTING.md describes submission,
licenses and review. The storage convention is .legible/; drafts use the
existing profile. Context documents remain ordinary documents:
they need not become records to be read.
From private draft to selected collection¶
The Python/MCP reference keeps working copies in .ch/genealogy/. This is
private storage, not the collection to commit to Git. Export only the selected
contribution with the manifest preserving origin, handle and hash. The example
uses .legible/drafts/ for these packets; this directory layout is one operating
choice, not a new mandatory format.
From the protocol checkout root, configure PYTHONPATH as described in
local setup. Replace the paths, origin and handle below
with real values returned by import or search:
python3 -m legible.drafts export --repo /PATH/PRIVATE-ROOT --origin YOUR_ORIGIN_URI --id DRAFT_ID --path /PATH/SELECTED-PACKET --selected
In the local MCP server, export_draft_packet prepares this packet without
leaving the tool. Select the version returned by read_draft or search_drafts:
supply origin, id, bytes_sha256, a simple label in package and
selected: true only after the participant's choice. Output goes to
exports/drafts/<package>/ within the private root. The packet contains only
the draft and manifest, not referenced evidence. The tool refuses overwrites
and neither sends files, opens PRs nor signs. The network MCP pilot retains
its restricted catalogue; this export belongs to the local stdio server.
The destination must be new. Review the Markdown and manifest.json, copy
only that packet into the shareable collection and check git status and
git diff --cached before committing. Use a subdirectory per origin and
contribution so equal local names do not overwrite each other. Do not copy
the technical repository's .gitignore as your space policy: it deliberately
ignores the whole local .legible/ tree. The downloadable example allows
selected packets in .legible/drafts/, leaving .ch/, contacts, evidence
and credentials out. Ignoring prevents ordinary Git inclusion; it protects
neither tracked files, history nor operating-system access.
Without a library or terminal, save the Markdown and the origin supplied with it as described in the participation guide. Do not invent hashes or a validated manifest: the recipient can use the reference to produce a transport copy.
When you choose to share a signed record¶
Saving a formal record in your private root does not make it part of the space.
After review and signing, validate its format and verify its signature with
legible validate --record FILE and legible verify --record FILE.
Also check whether the content and references may be shared: copying a file to a
public location discloses its content even if its signed field remains marked
visibility: private. To declare a different visibility scope, prepare
and sign a new record.
To share the selected version, copy only the verified file to its corresponding
directory in the authorized collection, preserving its name, bytes, ID and
signature. Do not copy the private root, CH, contact profile or evidence.
Check that the destination does not exist before copying. An Appoint, for example,
belongs at .legible/appoints/<ID>.appoint.
The template ignores formal records by default. To include only the selected
file, use git add -f -- .legible/appoints/<ID>.appoint in the shareable copy,
replacing <ID> with the real ID. Check git status and git diff --cached,
including any other staged files. Do not remove protection from the entire
.legible/ tree. Selecting this file does not authorize a commit, push or
submission: those operations still require your choice.
If using forks and PRs, explain how to open and consult a proposal, including one not incorporated. A PR's existence does not guarantee indefinite preservation: people wishing to continue should retain the files and references they are entitled to keep. Their own repository can serve that purpose.
Internal Git can use branches, references or file exchange. PR interfaces depend on the chosen software; they are not a feature of Git alone. Groups with access restrictions need a path consistent with their policies, without encouraging external copies of protected material.