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.

Tools

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

Tool	What it gives you
about()	Who, what, and the shape of the rest
guide()	What you can do here, and what to do next
whoami()	Who the server thinks you are, and what that gets you
whats_new(since)	What's shipped since a cursor you keep — poll this at session start
projects()	Systems built — and what's architecturally notable about each
design_decisions(topic)	How things were actually decided, and why
doctrine(rule)	Personal-ops rules, each with the failure it prevents
stack()	Languages, patterns, engineering discipline
contact()	How to reach him

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