<p align="center">
  <img src="./assets/header.svg" alt="system-brain-mcp" width="100%">
</p>

# 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

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

Or from source:

```bash
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:

```json
{
  "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

```bash
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](LICENSE).