ynfra / ybrain

Company knowledge MCP server (Bun + TypeScript): one HTTP endpoint an ordinary user adds to their MCP client to ask "what prompts do we have?", "who owns billing?", "where are the Grafana docs?", and "what skills exist and how do I install them?". Anyone can read and suggest; suggestions land as drafts that a supervisor publishes, and every change is a real Git commit in a single data repo.

MCP client ──HTTP──▶ ybrain (this server) ──git clone/pull/push──▶ github.com/<acct>/ybrain-data
   read + suggest = open                    (drafts/ → supervisor publishes → live)

Prerequisites

• Bun (or Docker with Compose v2).
• A Git data repo — fork data-repo-template/ — and a token with push access to it.

Usage

cp .env.example .env    # set YBRAIN_DATA_REPO_URL, YBRAIN_GIT_TOKEN; optional YBRAIN_SUPERVISOR_TOKENS
bun install
bun run dev             # or: docker compose up --build
curl localhost:8080/healthz

Then add the Streamable HTTP endpoint (POST /mcp) to an MCP client — read + suggest need no token:

{ "mcpServers": { "ybrain": { "url": "https://ybrain.example.com/mcp" } } }

A supervisor adds a named Bearer token to unlock publish/reject/register-source:

{ "mcpServers": { "ybrain": {
  "url": "https://ybrain.example.com/mcp",
  "headers": { "Authorization": "Bearer YOUR_SUPERVISOR_TOKEN" } } } }

Tools

Tool	Access	Description
list_prompts, get_prompt, search_prompts	open	Company prompts
who_owns, list_owners	open	Who owns what
list_docs, get_doc, search_docs	open	Docs / links to systems
list_skill_sources, list_skills, search_skills, get_skill	open	Skills index — internal + external, with per-source install commands
list_drafts, get_draft	open	Pending suggestions
suggest_prompt, suggest_owner, suggest_doc, suggest_skill	open	Propose content — committed under drafts/, never live
publish_draft, reject_draft	supervisor token	Promote / discard a draft
add_skill_source	supervisor token	Register an external skill repo to index

Notes

• Content lives in a separate data repo (YBRAIN_DATA_REPO_URL): prompts/, owners/, docs/, skills/, skill-sources.yaml, drafts/ — never in this code repo.
• A suggestion never goes live: the real access control is Git merge/publish rights — a supervisor promotes with publish_draft (or edits/merges directly on GitHub); ybrain implements no roles of its own.
• Supervisor tokens are named (YBRAIN_SUPERVISOR_TOKENS=alice=…,bob=…) so one can be revoked without rotating the rest; suggested_by is client-supplied, unverified metadata.
• Because reads and suggestions are open, the server caps request body size and rate-limits per IP.
• Skills are indexed, not vendored: ybrain reads each source's SKILL.md frontmatter via the GitHub API and prints the client-side install command per source kind (skills-cli, marketplace, folder, internal); external descriptions are labelled untrusted.
• Reads hit a local clone, not the GitHub API; a background fetch every YBRAIN_PULL_INTERVAL seconds — or an HMAC-verified POST /webhook — picks up edits made on GitHub.
• Run exactly one server instance: writes go through a single in-process queue, and two clones pushing will race.

See AGENTS.md for conventions, internals, and day-2 operations.