brains-mcp

Brains

A personal second-brain HTTP API and MCP (Model Context Protocol) server backed by Supabase Storage with Postgres full-text search. Designed for ChatGPT Actions, Claude integrations, and any MCP-compatible agent.

Quickstart: init a project

Run this once per project from any MCP-connected agent:

init_project({
  projectSlug: "my-project",
  projectName: "My Project",
  platform: "claude",
  execute: true
})

This single call idempotently:

• Creates projects/my-project/readme.md (project registry page).
• Generates and saves projects/my-project/instructions/claude.md (platform-specific instruction file).
• Seeds the three foundation pages (instructions/agent-instruction-schema-v1.md, instructions/agent-instruction-template-v1.md, instructions/brain-routing.md) if they are missing.
• Creates stub cross-project tracking pages at the brain root (active-open-loops.md, active-unanswered-questions.md, active-next-actions.md, decisions/core-decisions-log.md) if they are missing. Wikis that already carry the pre-#455 copies at projects/active-*.md keep using those — no duplicate is created.

The response includes two artifacts:

• instructionMarkdown — the full wiki instruction file saved to projects/my-project/instructions/claude.md. This is the canonical reference document an agent reads at session start.
• systemPromptMarkdown — a short pointer block to paste into your Claude Project system prompt (or CLAUDE.md). It contains the identity, brain-first rule, activation gate, and a single boot sequence that ends with "read projects/my-project/instructions/claude.md and follow it."

Paste systemPromptMarkdown into your system prompt. The instruction file handles all domain context and write-back rules — keep the system prompt short.

Preview before applying

init_project({
  projectSlug: "my-project",
  projectName: "My Project",
  execute: false
})

Returns the full operation plan with no writes.

Why not pull_wiki? It returns a base64-encoded ZIP inline in the tool response, which overflows MCP tool-result token caps at modest scale (~30 pages). pull_session_bundle returns plain text sized to fit in a single response and paginates via nextCursor. pull_wiki remains available for filesystem-equipped clients (e.g. Claude Desktop with filesystem access) and full-archive backup workflows.

Architecture

• HTTP server (src/httpServer.ts) — REST API with OAuth 2.0, designed for ChatGPT Actions and Claude integrations.
• MCP server (src/server.ts) — MCP tool registry over stdio or HTTP transport.
• Storage (src/storage/client.ts) — Local filesystem or Supabase Storage backend.
• Search (src/search/postgresIndex.ts) — Postgres full-text search index (Supabase) or local scan fallback.

See API-FIRST-ARCHITECTURE.md, STORAGE.md, and WIKI-SCHEMA.md for deeper documentation.

Observability

Every HTTP response carries an X-Response-Time header (e.g. X-Response-Time: 43ms) indicating server-side processing time. Every request also emits a single log line to stdout:

Plain format (default):

[req] GET /api/v1/search 200 43ms backend=sqlite-fts queryMs=12
[req] POST /api/v1/pages 200 11ms
[req] GET /api/v1/search 200 8ms zero-results=true

Structured JSON (LOG_FORMAT=json):

{"ts":"2026-04-17T10:00:00.000Z","method":"GET","path":"/api/v1/search","status":200,"durationMs":43,"backend":"sqlite-fts","queryMs":12}

Set LOG_FORMAT=json to enable structured logging for log-shipping (e.g. Datadog, Logtail). Search requests additionally log backend and queryMs when available, and zero-results=true when a search returns no results.

npm install
npm run build
npm start

Set BRAINS_TRANSPORT=stdio to run as an MCP stdio server.

Testing

npm test