system-brain-mcp

Eleven read-only MCP tools for inspecting a software workspace and returning answers tied to observable evidence. Missing or degraded evidence produces a partial result or no recommendation, never invented certainty.

Start

npx -y -p system-brain-mcp system-brain-init /path/to/code

Or from source:

git clone https://github.com/QEbellavita/system-brain-mcp
cd system-brain-mcp
npm install
node bin/init.js /path/to/code

The initializer scans for repositories and deployment configuration, then writes a draft manifest. It leaves uncertain fields unresolved for human review.

Point an MCP client at the server:

{
  "mcpServers": {
    "system-brain": {
      "command": "npx",
      "args": ["-y", "system-brain-mcp"],
      "env": {
        "SYSTEM_BRAIN_DEPLOY_MANIFEST": "/path/to/deploy-targets.json",
        "SYSTEM_BRAIN_FABRICATION_DIRS": "/path/to/source"
      }
    }
  }
}

Tools

Tool	Purpose
brain_where_deploys	Compare declared and detected deployment evidence
brain_fabrication_audit	Flag narrow placeholder patterns for human verification
brain_backlog	Summarize accessible open work and local branches
brain_db_schema	Inspect configured local database structure
brain_analytics	Measure a configured outcome-labeling loop
brain_ml_models	Inventory configured local model artifacts
brain_architecture	Index configured architecture documents
brain_lenses	List available reasoning lenses
brain_roadmap	Find open checklist items in configured notes
brain_recommend	Produce evidence-linked candidate actions
brain_reframe	Apply a reasoning lens to one candidate action

All tools are read-only. They do not write to databases, repositories, or deployment targets.

Configuration

Variable	Purpose
SYSTEM_BRAIN_DEPLOY_MANIFEST	Path to a reviewed deployment manifest
SYSTEM_BRAIN_FABRICATION_DIRS	Directories eligible for static inspection
SYSTEM_BRAIN_DB	Local SQLite database path
SYSTEM_BRAIN_MODELS_DIRS	Directories containing model artifacts
SYSTEM_BRAIN_ARCH_DOCS	Architecture documents to index
SYSTEM_BRAIN_OBSIDIAN_VAULTS	Optional named vault paths
SYSTEM_BRAIN_ANALYTICS_CONFIG	Reviewed analytics configuration
SYSTEM_BRAIN_TAXONOMY_CONFIG	Reviewed work taxonomy

The files under config/ are neutral examples only. Copy them to user-specific files and replace every example table, label, taxonomy, and threshold before interpreting analytics. The project intentionally does not ship a production schema or recommended operating threshold.

brain_analytics measures labels within the configured outcome ledger. Other activity tables are reported separately so they cannot silently change that denominator. The tool reports incomplete evidence when a required query fails.

brain_fabrication_audit returns candidate locations, not verdicts. Read the surrounding implementation before classifying a capability.

Tests

npm test

Tests use temporary files and injected command behavior. Network access and a database are not required.

Public-data boundary

Public fixtures are synthetic. Do not add customer data, real internal identifiers, production table names, operating thresholds, incident details, or exact production-shaped examples to this repository or its release archives.

Licence

MIT. See LICENSE.