klypix-mcp

Overview Schema Source Related Servers Discussions Admin

KLYPIX Context Gateway — synchronize task, peers, conflicts, and relevant memory

brain_sync

Idempotent

Coordinate coding tasks over an authorized MCP connection by declaring intent and expected files, then receiving shared brain context, active peers, messages, and exact-file conflict alerts.

Instructions

APPROVAL-FREE task gateway over the authorized MCP connection. Call FIRST with a concise intent and expected files, again when scope changes, and with phase:"complete" before the final response. One bounded response returns compact task-relevant brain context, active TASK peers (idle connections hidden), one-time messages, structured exact-file conflicts, and late-arrival overlap alerts. A completion that supplies machine-checkable result manifests is fail-closed: invalid, conflicting, or incomparable evidence returns needs-reconciliation and retains task scope. results is ONLY for such manifests, never a summary of the work: with nothing machine-checkable to claim, complete without it. Works on any MCP host — it needs only the authorized MCP connection, so native lifecycle hooks are optional. LIMITS: blocking overlap is EXACT-PATH over the declared files of each session plus the edits its host observed; sessions on different branches are also test-merged with git merge-tree (committed work only); a same-folder overlap is an advisory notice; coordination/result reconciliation is machine-local and OS-user-local; a teammate on another computer appears only when KLYPIX network is installed on both computers (presence, intent, files and brain_message, no result reconciliation), and file overlap remains ADVISORY.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "brain_sync"
  }
}

Input Schema

Name	Required	Description
`role`	No	Optional free-text label for this session, such as "reviewer". Peers see it, and a handoff addressed to that role (brain_handoff for) is offered first to a session that declares it. It is a label only: no history, reputation or authority comes with it, and it lasts for this session. An empty string clears it.
`agent`	No	Only for a subagent: the child id KLYPIX gave it when it started (for example "sub-1a2b3c"). Its intent and files are then recorded under that child id, under its parent session, instead of replacing what the parent declared. KLYPIX accepts only an id the host reported (Claude Code reports subagents); any other id is ignored and the call is recorded under the parent session.
`files`	No	Project-relative files you expect to touch or have touched. Exact overlaps with peers are flagged.
`phase`	No	start replaces prior task scope; checkpoint merges changed scope; complete clears task intent/files. Default: checkpoint.
`intent`	No	One sentence describing the current task. Supply for start/checkpoint; completion clears it.
`project`	No	Nonempty absolute current project root that directly contains brain.klypix or brain.any. Supply it on phase "start" so routing stays correct even when the MCP host launches from its own install directory.
`results`	No	On phase complete, 1-8 result manifests for stable claim keys. The in-handler versioned validator rejects malformed, empty, unknown-field, or incomparable evidence and retains task scope.
`releaseClaim`	No	Stake a durable claim that specific commits ride the NEXT release — the promise "you'll see it in the next build" made machine-readable. Unlike presence rows (which age out ~10min after a session ends), a claim persists until fulfilled (the release ref contains the shas — auto-retired with a courtesy note), withdrawn, or expired (14d). A release that would drop claimed shas is REFUSED until they are acknowledged BY NAME, and acknowledging them away notifies the owner. Use exactly one of shas (stake/extend) or withdraw.
`releaseIntent`	No	Declare EXCLUSIVE intent to prepare a release of this project. The first declarer takes a ~2h lease (refreshed by checkpoints, freed by phase "complete", by expiry, or when the holder session ends); a second declarer gets a structured hard conflict naming the holder, version, and ref. While any lease is active every peer's sync gains a "release in preparation" footer line. A NEW declaration is also checked against what the release would LEAVE BEHIND: if the ref is missing commits that are on trunk or on a branch a live peer session is working on, OR commits any session STAKED a releaseClaim on (even one that has since ended), the lease is REFUSED (nothing is changed) and the response lists them — report those commits to the user, then re-declare with acknowledge:[...] naming each sha if the release should go ahead without them. Acknowledging away a claimed or live-owned commit queues its owner a notification automatically.
`include_context`	No	Include fast task-relevant brain cards and offer queued coordination notes in the same response. Defaults true; false also defers note delivery so internal supervisor probes cannot consume model-visible messages.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.110.0Oct 31, 2026

addedInput schema / properties / agent

Added value: +{
+  "description": "Only for a subagent: the child id KLYPIX gave it when it started (for example \"sub-1a2b3c\"). Its intent and files are then recorded under that child id, under its parent session, instead of replacing what the parent declared. KLYPIX accepts only an id the host reported (Claude Code reports subagents); any other id is ignored and the call is recorded under the parent session.",
+  "maxLength": 200,
+  "type": "string"
+}

addedInput schema / properties / role

Added value: +{
+  "description": "Optional free-text label for this session, such as \"reviewer\". Peers see it, and a handoff addressed to that role (brain_handoff for) is offered first to a session that declares it. It is a label only: no history, reputation or authority comes with it, and it lasts for this session. An empty string clears it.",
+  "maxLength": 40,
+  "type": "string"
+}

First observedv0.1.0Sep 8, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover openWorld/idempotent/destructive hints; the description adds far more: fail-closed validation returning needs-reconciliation while retaining task scope, an explicit LIMITS block (exact-path overlap, git merge-tree test-merge on differing branches, same-folder overlaps are advisory only), and the machine-local/OS-user-local boundary with network presence as the only cross-machine path.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded correctly — the approval-free gateway framing and call cadence come before the limits. It is dense and occasionally repetitive ('over the authorized MCP connection' is restated as 'needs only the authorized MCP connection'), and the all-caps emphasis is heavy, but almost every clause carries distinct operational information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with nested objects and no output schema, the description still explains the response payload, the failure mode, and the coordination boundaries. An agent has enough to call it correctly at start, checkpoint, and complete without opening anything else.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already carries most parameter meaning and the baseline is 3. The description still adds real semantic value the schema does not: it clarifies that `results` must not substitute for a work summary, and that `phase` drives start/replace versus checkpoint/merge versus complete/clear behavior in the call flow.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb-plus-resource ('task gateway' that synchronizes) and enumerates exactly what one bounded response returns: brain context, active TASK peers, one-time messages, exact-file conflicts, and overlap alerts. An agent can tell this apart from brain_message or brain_handoff because those are narrow channels while this is the aggregate sync gateway.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit call timing — FIRST with intent and expected files, again on scope change, and with phase:'complete' before the final response. It also gives an explicit when-NOT: '`results` is ONLY for such manifests, never a summary of the work: with nothing machine-checkable to claim, complete without it.' That is about as prescriptive as a usage section gets.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.