# shadow-perception-mcp

Shadow's eye. Reads what a knowledge worker is looking at (Kaggle notebook / Power BI dashboard / R analysis / trading terminal) and feeds it to a deterministic 5-voice council. Sign-off on the observation with Ed25519 so the artifact is procurement-grade.

**Companion product to** [`alex-jb/shadow-mentor`](https://github.com/alex-jb/shadow-mentor) — Shadow's banking loan council. Same Ed25519 attestation primitive, same 5-voice architecture, different target audience.

- 中文 README: [README.zh-CN.md](./README.zh-CN.md)

## What it does

Point Shadow's eye at a Jupyter notebook, Power BI report, or R session. Five voices review it:

- **Leakage** — train/test contamination, target leakage, temporal leakage
- **Fairness** — protected-class proxies (ECOA §701 / GDPR Art. 9) in features
- **Reproducibility** — seed pinning, environment lock, deterministic ops
- **Compliance** — Kaggle competition rules, SR 11-7 model risk, EU AI Act Art. 22
- **Ops** — inference latency, memory, deploy footprint

Each voice returns SHIP / REWORK / BLOCK. Ed25519 signature over the verdict — attach to your Kaggle submission or share with a teammate as proof of pre-submit review.

## Install (as MCP server)

```jsonc
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "shadow-perception": {
      "command": "npx",
      "args": ["-y", "shadow-perception-mcp"]
    }
  }
}
```

Then in Claude Desktop: `/perception scan this notebook`.

## Install (as CLI, no MCP)

```bash
npm install -g shadow-perception-mcp
shadow-perception scan my-kaggle-notebook.ipynb
```

## Three MCP tools shipped

- `shadow_perception_scan` — read a Jupyter notebook, R script, or code file; return structured observations (imports / functions / cells / detected leakage patterns).
- `shadow_perception_council` — run the 5-voice council on structured observations; return verdict + per-voice rationale + adverse-action codes.
- `shadow_perception_attest` — Ed25519 sign the verdict; produces an attestation JSON that anyone with the public key can verify.

## Why fork perception from shadow-mentor?

- **Bank counsel review face** — Shadow banking edition sells to Raymond James, LPL, Stifel. Bank counsel does not want "watches employee screens" in the same procurement contract. Keeping perception in a separate repo shrinks their sign-off surface.
- **Different audience** — Kaggle competitors and data scientists want a mentor that sees their notebook. Bank counsel wants a mentor that never leaves the VPC. Same architecture, different distribution.
- **Same primitive** — Ed25519 attestation + 5-voice council + MCP server pattern is verbatim from shadow-mentor. Nothing new to invent; just a new vertical rubric.

## Why start with Kaggle first

- Cheapest to build: Python LSP is mature (`pyright`), `nbformat` parses `.ipynb` directly, Kaggle API exposes competition rules. Zero vision needed.
- Most differentiated: no OSS tool today runs a 5-voice pre-submit council on a Kaggle notebook with Ed25519 sign-off. Copilot / Cursor autocomplete; they don't audit.
- Biggest audience: ~15M Kaggle users as of 2026.

## Roadmap

- **v0.1** (this release) — Kaggle notebook scan + council + attestation
- **v0.2** — Power BI (XMLA endpoint parse, DAX measure council)
- **v0.3** — R (`languageserver` LSP, ggplot2 features council)
- **v0.4** — Trading terminal (Interactive Brokers `ib_insync`, pre-trade council)
- **v0.5** — Vision fallback (Claude Vision on charts / dashboards where LSP is blind)

Verticals ship as separate SKILL.md files on skills.sh so users install only what they need.

## Relationship to `shadow-mentor`

Shadow banking council + Shadow perception mcp = the full "compliance council + reality reader" story used in the IEEE VR 2027 paper "Ambient Council for Regulated AI Decisions." Both repos MIT, both authored by Alex Ji, both share the Ed25519 attestation primitive so decisions from either can be cross-verified with the same public key.

## License

MIT — see [LICENSE](./LICENSE).