foundation: Skill for Claude Code

Foundation MCP

This skill picks the vault call. It is not a tool list.

The user is the human who runs this vault on this machine. The vault MCP is on this machine (http://127.0.0.1:8787). Stay on localhost. Do not tell anyone to expose it.

Look up the live schema at call time (bootstrap, inspect_ontology, or the server tool list). bootstrap is lean (spine, types, relations, rules). Read foundation://guidance resources for how to extend. Starter bot recipes are MCP prompts. Input parameter docs on that list come from Zod .describe(). Do not trust a dump in this file.

Advertised tools (16): bootstrap, search, lookup, get, working_set, upsert, delete, merge, link, unlink, inspect_ontology, manage_type, manage_relation, list_activity, undo, job. Generated from the advertised inventory in @foundation/schema. Look up the live schema at call time. Parameter docs: docs/MCP_TOOLS.md.

Which call

• bootstrap — first attach / lean spine + live type and relation registry + compact rules. Read foundation://guidance for how to extend.
• lookup — a name, not a UUID yet
• get — already have a UUID, need the record (not activity)
• list_activity — already have a UUID, need the diary for that record (target). After a full page, send cursor. Read count. Omit fields and diff_only for the full snapshot. fields asks for a subset of activity keys. diff_only: true returns a lean before/after. Undo still uses the stored snapshot.
• working_set — already have a UUID, need the open work around it. Depth, hard cap, and the spine-root due window read the vault settings row.
• search — list or find without a bound id. After a full page, send cursor. Read count. search { url } finds a Gmail, Calendar, or Drive object. search { repo } finds a GitHub object. search { receipt } looks up a mail or calendar receipt, then get. Same tool, not a new verb. due accepts only today or overdue in the vault settings timezone. A specific day uses due_on_or_before and due_on_or_after on data.due. No settings tool.
• upsert — write or patch one record, or nodes[] (1–20) in one all-or-nothing call. Every node needs type and title on create and on update. A receipt-only update is still an update. A missing title returns { error: "Pass type and title for one node, or nodes (1 to 20) for several", suggestion: "Pass type and title. An update also needs id and base_updated_at from get. A receipt-only update is still an update." }. On a patch, pass the stored title unchanged. Updates also need id plus base_updated_at from the latest get (updated_at). Pass payload to replace the body. Omit payload on an update and the body stays. Pass data as an object. On update the server merges top-level keys. A key you omit stays. A top-level due returns { error: "Pass data.due, not due" }. Creates use an idempotency key. dry_run: true returns would-be snapshots and writes nothing. Missing type needed fields warn; strict: true refuses. A bot writes data.receipt after draft, send, book, move, or clear. The server does not invent it. When a live url and a live receipt both exist for the same gmail or calendar id, write both on that one record. Changing type revalidates live incident edges and refuses if one would no longer be allowed (unlink first).
• link — accept a suggested edge or hang a child. Pass from_id, to_id, relation_type, plus from_base_updated_at and to_base_updated_at from a fresh get on each endpoint (if-match), or edges[] (1–20). dry_run: true returns would-be receipts and writes nothing. Do not invent from_updated_at / to_updated_at. Suggestions and child_of placement read live kind, parent_types, and target_types, not a frozen slug list.
• manage_relation — create or update a relation. System relations may edit source_types and target_types. Slug, kind, label, and symmetry stay locked.
• delete — soft-delete a live node. Refuses when a live ref field still points at that id (clear the field first).
• merge — two live same-type duplicates. Pass keep, drop, keep_base_updated_at, drop_base_updated_at, and confirm set to true. Needs destructive scope. Rewrites edges and declared refs onto keep, unions aliases, moves unique identity when only drop holds it, then soft-deletes drop. Undo that activity row to restore the prior graph.
• job — claim a named instance routine before a pass (dream, vault-health, activity-prune, …). Keep the token. A second live claim fails. finish records last run. release opens without recording. read is who and last run. Not a graph write and not get_vault_health. Activity prune itself is the host script scripts/activity-prune.sh.