convez.ai
MCP Server
JEM-Fizbit

brain-mcp-server

JEM-Fizbit/brain-mcp-server

Ver no GitHub
InicialPluginScore · de 0 a 100

Generic MCP server for Markdown-based AI Brain context systems

Instalação

$npx convez-ai JEM-Fizbit/brain-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 4 dias
Versão
v1.14.2
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

brain-mcp-server

A generic MCP server that serves Markdown-based AI Brain files to any MCP-compatible client.

What It Does

Gives MCP clients persistent, context-aware access to a collection of Markdown files (an "AI Brain") via the Model Context Protocol. Supports reading, writing, searching, git-backed versioning, local stdio transport, and hosted HTTP transport with GitHub OAuth.

Tools

ToolDescription
brain_load_contextEntry point — returns the loader + NOW.md, plus lint, issue, and inbox nudges
brain_read_fileRead a specific file. Accepts scope = brain (default) or sources to read from the sources/ archive
brain_update_fileUpdate a Brain file (replace, append, or patch)
brain_commitGit commit changes, optionally push
brain_list_filesList all Brain files with staleness metadata
brain_list_sourcesList files in the sources/ archive, with optional category filter
brain_searchSearch for keywords. Accepts scope = brain (default), sources, or all
brain_logAppend an entry to the Brain change log
brain_read_logRead recent change log entries
brain_lintRun a health check (bloat, staleness, orphan backlinks, drift, missing cross-references)
brain_ingestProcess a new source — dry-run analysis or save to sources/
brain_ingest_completeRecord provenance after ingest (updates SOURCES.md + LOG.md, optionally deletes inbox file)
brain_scan_inboxList files pending in the inbox/ drop-folder for processing

The scope parameter on brain_read_file and brain_search separates the Brain vault (curated summaries, default) from the sources/ archive (original ingested documents: bios, assessments, meeting notes, writing samples, analysis, correspondence, etc.). Claude escalates scope automatically when a query implicates original material rather than a Brain summary.

Requirements

  • Node.js 18+
  • A directory of Markdown files (your "Brain") with at least 00_loader.md and NOW.md
  • Git initialised in the Brain directory (for commit/push features)

Quick Start

# 1. Clone and build
git clone <your-fork-or-clone-url> ~/Projects/brain-mcp-server
cd ~/Projects/brain-mcp-server
npm install
npm run build

# 2. Verify the build produced dist/index.js
ls dist/index.js

# 3. Test with MCP Inspector (optional but recommended)
npx @modelcontextprotocol/inspector node dist/index.js

Configuration

VariableDescriptionDefault
BRAIN_DIRAbsolute path to your Brain markdown files directory~/Projects/ai-brain-jem/brain
BRAIN_SOURCES_DIRAbsolute path to your source archive directorysibling sources/ next to BRAIN_DIR
TRANSPORTstdio by default, or http for hosted/HTTP modeunset / stdio
HOST or MCP_HTTP_HOSTHTTP bind host when TRANSPORT=http127.0.0.1
PORTHTTP bind port and local OAuth base fallback3000
MCP_OAUTH_PUBLIC_BASEPublic HTTPS base URL for hosted OAuth and MCP metadatahttp://127.0.0.1:$PORT
MCP_OAUTH_SIGNING_SECRETRequired in HTTP mode. HS256 access-token signing secretunset
GITHUB_OAUTH_CLIENT_IDRequired in HTTP mode. GitHub OAuth app client IDunset
GITHUB_OAUTH_CLIENT_SECRETRequired in HTTP mode. GitHub OAuth app client secretunset
GITHUB_ALLOWED_LOGINSComma-separated GitHub login allowlist for fallback owner accessunset
GITHUB_ALLOWED_EMAILSComma-separated email allowlist for fallback owner accessunset
BRAIN_PLATFORM_CONFIGRegistry JSON path for hosted/multi-Brain mode~/.config/brain-platform/registry.json
BRAIN_PLATFORM_STATE_ROOTFile-backed OAuth state root~/.config/brain-platform/state
BRAIN_AUTO_SYNCFilesystem/git mode only. When true, successful mutating Brain tools automatically commit changes. Do not enable for Supabase-backed hosted runtimeunset / false
BRAIN_AUTO_PUSHFilesystem/git mode only. When auto-sync is enabled, push commits to origin unless set false. Do not enable for Supabase-backed hosted runtimetrue
BRAIN_DATE_TIME_ZONEIANA timezone used for Brain log/source datesTZ or UTC

Hosted HTTP Deployment

Remote-only clients need a public HTTPS MCP endpoint; 127.0.0.1 only works for clients running on the same laptop. The current hosted rebuild targets a Node runtime that serves OAuth and MCP over HTTPS while storing Brain revisions in Supabase Postgres and source artifacts in private Supabase Storage. The local Markdown Brain remains the baseline and is mirrored through the sync contract rather than by a hosted git checkout.

This repo includes:

  • Dockerfile for the hosted Node runtime
  • fly.toml for the first Supabase-backed Fly.io target, jem-brain-mcp
  • docs/deploy-fly.md for the deployment runbook
  • docs/ROADMAP.md for the staged JEM cutover, ERS migration, and multi-tenant roadmap

Hosted endpoint shape:

https://jem-brain-mcp.fly.dev/mcp

Client Setup

Claude Code

Add to ~/.claude/settings.json (user-level) or .claude/settings.json (project-level):

{
  "mcpServers": {
    "brain": {
      "command": "node",
      "args": ["/absolute/path/to/brain-mcp-server/dist/index.js"],
      "env": {
        "BRAIN_DIR": "/absolute/path/to/your/brain/files"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (same format as above).

Claude Cowork

Add via the MCP server configuration in Cowork settings (same command, args, and env values).

Post-Install Configuration

After the MCP server is connected, three additional steps make it fully automatic.

Step 1: Pre-authorise tool calls (Claude Code)

Add mcp__brain to your permissions allow-list so Claude doesn't prompt for approval on every Brain tool call.

In ~/.claude/settings.json, add to the permissions.allow array:

{
  "permissions": {
    "allow": [
      "mcp__brain"
    ]
  }
}

This matches all thirteen Brain tools. You can verify with /permissions in Claude Code.

Step 2: Conditional auto-load directive (Claude Code / Cowork)

Add the following to ~/.claude/CLAUDE.md so Claude loads Brain context when relevant — not on every conversation:

## AI Brain (Conditional Auto-Load)

An AI Brain (personal knowledge system) is connected via MCP. Load it when the conversation
benefits from personal context — skip it for generic tasks.

Load Brain context proactively (don't wait to be asked) when:
- Writing on the user's behalf, career/professional tasks, work context, personal projects,
  strategy/advice requiring background, anything needing voice/preferences/expertise,
  user references "my Brain" / "my context", or user attaches a document or asks to ingest.

Skip when:
- Generic technical questions, general knowledge/research, pure coding help,
  or user explicitly says not to load.

Load sequence (when loading):
1. Fetch tools (if deferred): ToolSearch(query="select:mcp__brain__brain_load_context,mcp__brain__brain_read_file,mcp__brain__brain_search,mcp__brain__brain_list_files,mcp__brain__brain_list_sources,mcp__brain__brain_update_file,mcp__brain__brain_commit,mcp__brain__brain_log,mcp__brain__brain_read_log,mcp__brain__brain_lint,mcp__brain__brain_ingest,mcp__brain__brain_ingest_complete,mcp__brain__brain_scan_inbox")
2. Call brain_load_context — returns the loader navigation table, current priorities, and nudges (lint overdue, inbox pending). The loader contains the full ingestion protocol, source categories, and file-editing rules; follow it.
3. Call brain_read_file for task-relevant files per the navigation table.
4. If brain_load_context flags a lint nudge, run brain_lint before accuracy-sensitive work.

Reading source archives:
- brain_read_file and brain_search accept scope = "brain" (default, vault only), "sources", or "all" (search only). Escalate scope automatically when a query implicates original ingested material rather than a Brain summary.
- Use brain_list_sources (optional category filter) to discover source files.

Inbox: files dropped into the inbox/ folder are pending sources. Use brain_scan_inbox when asked, then process each using the ingestion protocol in the loader. The inbox_file parameter on brain_ingest_complete handles cleanup.

This works for both Claude Code and Cowork (both read ~/.claude/CLAUDE.md).

Step 3: User preferences (Claude Desktop / claude.ai — manual)

Claude Desktop and claude.ai do not read CLAUDE.md. For these clients, add the conditional auto-load directive to your user preferences (Settings → Profile → User preferences).

See MANUAL_SETUP.md for the exact text to paste, verification tests, and a troubleshooting checklist.

Note: This step requires manual entry in each client's preferences UI. It cannot be automated.

How It Works

  1. Claude calls brain_load_context at session start (automatically, if configured per above)
  2. The response includes the loader, NOW.md, and nudges (lint overdue, open maintenance issues, pending inbox files)
  3. Claude reads the navigation table and requests specific files via brain_read_file
  4. Edits are written via brain_update_file, then committed via brain_commit
  5. New information is processed via brain_ingest (dry-run analysis, then guided updates)
  6. Changes are tracked via brain_log; health is checked via brain_lint

The routing logic lives in the loader (a Markdown file you maintain), not in code. The server is content-agnostic — it knows nothing about your specific Brain content, only how to serve Markdown files.

Brain files use [[backlinks]] (Obsidian-style wikilinks) to cross-reference each other. During ingest, the LLM maintains these links across all affected files. The lint process checks for orphan content files (zero inbound backlinks). The Brain directory can be opened as an Obsidian vault for graph view and backlink navigation.

Recommended Workflow

The MCP server works from any Claude client, but different tasks suit different clients:

ActivityBest clientWhy
Using Brain in conversationChat (any client with MCP)All read/write tools work over stdio — no uploads needed
Small updates (NOW.md, tasks, journal)Chatbrain_update_file + brain_commit handle it directly
Large document ingestionCowork or CodeMulti-step workflow needs filesystem access to sources/
Drop-folder ingestionAny (via scheduled task)Drop files into inbox/, daily task processes them automatically
Server code maintenanceCodeIterative build-test-commit cycle
Brain repo git operationsCodeShell access for rebasing, conflict resolution, pushing
Graph view & knowledge mappingObsidianOpen brain/ as a vault for graph visualization, backlink navigation, and orphan detection

Chat is the primary interface for day-to-day Brain usage — loading context, searching, editing files, committing. Cowork or Code are needed when the workflow requires direct filesystem access (e.g., saving source documents) or agentic multi-step operations. Code is the right tool for maintaining the server codebase itself.

For the full methodology, see the AI Brain Primer.

Related Projects

  • ai-brain-primer — Framework and methodology for building an AI Brain
  • ai-brain-jem — Example private Brain implementation (private repo)

License

MIT

Ver o original no GitHub

Bom para

Relacionados