boris-mcp

A public MCP server about Boris Churzin (essl) — what he builds, how he decides, and the ops doctrine he runs on. Point an agent at it and interrogate the judgment instead of parsing a PDF.

uvx boris-mcp

Or in an MCP client config:

{
  "mcpServers": {
    "boris": { "command": "uvx", "args": ["boris-mcp"] }
  }
}

A taste

On always-on systems (design_decisions("dumb-evaluator")):

An always-on process is the one that runs when you are asleep and cannot supervise it. Every capability you give it is a capability that acts unsupervised. So the always-on half evaluates predicates and sends alerts; all judgment lives in the supervised half, which compiles rules for it.

On tracking work (doctrine("ack-is-not-answer")):

An acknowledgment is not an answer, and may be a disguised blocker. Auto-replies arrive in seconds and mean nothing happened.

That's the whole idea: ask the questions, get the reasoning. The rest is how the server serves it safely — which turns out to be the same discipline the answers are about.

Related MCP server: project-brain-mcp

Tools

Nine tools are public — no auth required, callable over stdio (uvx boris-mcp) or anonymously over HTTP:

Beyond these, eight more tools exist behind authentication and the circles-of-trust gate: a headhunter-tier pair (send_message, my_messages) for leaving the owner a message and checking for a reply, and an owner-tier set (inbox, reply, grant, revoke, access_requests, activity) for reading and answering the mailbox and managing who's let in. See Circles, auth, and the mailbox below.

Public tools are read-only over a public corpus. The consent-carrying set above mutates access or mailbox state — but only because the caller has already been proven to be the owner (or, for send_message, an authenticated non-anonymous caller) by a fail-closed gate: an unmapped or unauthenticated caller resolves to the public tier and nothing more, by construction, not by policy. Content above the commit boundary — the private corpus — lives off-repo on the operator's own disk and is served only through that same gate.

Circles, auth, and the mailbox

Access is a ladder of circles, outer to inner, each one trusted with strictly more than the last; a caller sees content gated at or below its own resolved circle and nothing above it — not even that a deeper circle exists.

flowchart LR
  A["agent / caller"] -->|"stdio (uvx): offline, no auth"| P["public tier"]
  A -->|"HTTP: OAuth via Authelia"| RC["resolve circle<br/>(a signed claim can only<br/>lower trust, never raise)"]
  P --> G{"circle gate<br/>fail-closed"}
  RC --> G
  G -->|"at / below your circle"| C["public corpus in-repo<br/>+ private corpus off-repo"]
  G -->|"above your circle"| D["honest denial<br/>(logged to activity)"]
  C --> M["mailbox &amp; event log<br/>pull + cursor, no push"]

public is the anonymous default; everything at or above the commit boundary lives only in a private corpus file on the operator's own disk, never in this repo. The stdio path (uvx boris-mcp) always resolves to public. Over HTTP, a caller authenticates via OAuth against an Authelia instance the operator runs, and the server clamps whatever circle the token claims to what an explicit grant actually gives it — a signed claim can lower your trust, never raise it. Forget to label a piece of content and it fails closed to owner (the top of the ladder), hidden from everyone but the operator.

Full picture: docs/ATP.md is the acceptance-test checklist behind every locked decision (published for transparency; it reads like internal QA scaffolding, because it is), and deploy/README.md runs the HTTP + Authelia stack yourself.

The message-passing here is the reference implementation of MCPP — the Model Context Peering Protocol (docs/MCPP.md), a formal MCP extension (SEP-style) for agent-to-agent messaging: MCP servers peer with each other the way SMTP MTAs do, with pull-based delivery and a trust ladder. MCPP is to MCP what SMTP is to TCP — an application protocol over a transport that already exists. The mailbox tools (send_message/inbox/reply/my_messages) are what's built and running today; docs/MESSAGES.md is the implementation-level walkthrough. The spec also defines a consent-gated ask operation — an agent drafts an answer only from what the asker is already cleared to see, and a human discloses it — which is specified but not yet implemented here.

Subscribing

There is no push, and that is deliberate. Call whats_new() at the start of a session; it returns everything after your cursor and hands you a fresh one. There's also an Atom feed for anything that isn't an agent.

Short version of why: MCP notifications are session-scoped and non-durable, a stdio server has no inbound network path, and the clients that matter don't implement subscriptions anyway — so push would drop any event fired while you had no session open, which is most of them. A cursor makes polling exact. The long version has the spec citations.

Using this for yourself

The reusable half lives in src/boris_mcp/_engine/ — the event log with cursor semantics, and Atom feed generation. It knows nothing about me: a test walks its import graph and scans its code for personal nouns, so it stays extractable (tests/test_engine_boundary.py).

The tool surface deliberately isn't abstracted. about() / projects() / design_decisions() is a good convention and a bad framework — a photographer wants a portfolio, a writer wants a bibliography. Abstract the plumbing, template the surface. Today that means: fork this, replace content.py and events.json, keep _engine/.

It'll be extracted as an installable package when someone actually wants that — see docs/GENERIC-SPLIT.md for the full split and why the repo keeps a personal name while the engine won't.

ops-lint

Two linter families for personal-ops text, both built and tested in _engine/opslint/. leak is a deterministic pre-publish check for anyone running a public server like this one — because the dangerous part of publishing a personal MCP isn't the code, it's the day you paraphrase something you shouldn't — and it's already wired in as scripts/leak_check.py, run by hand before every push. hygiene flags outbound items with no follow-up date, acknowledgments recorded as answers, statuses older than their own chase dates, and prepared-but-unsent work; the engine and its tests exist, but it isn't exposed as a callable MCP tool yet — that's what's coming.

Contributing

This repo is a personal instance, not a framework. The instance layer (content.py, events.json, the tool surface) is meant to be forked, not contributed to — see CONTRIBUTING.md. Genuine bug reports against the generic engine (_engine/) are welcome.

License

MIT