NeuroDock Guardrail
Advisory detectors for rumination, hyperfocus, and sycophancy. Never silently blocks.
Open source Open in the app JSON README (API)
About
Advisory detectors for rumination, hyperfocus, and sycophancy. Never silently blocks.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- tlennon-ie
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.0.5
- Stars
- 11
- Forks
- 3
- Open pull requests
- 9
- Last push
- 2026-08-31T06:19:44Z
- Repository state
- ativo
- Language
- TypeScript
- License
- AGPL-3.0
- Added
- 2026-08-29 04:01:33
- Updated
- 2026-08-29 04:01:33
- Origin id
io.github.tlennon-ie/neurodock-mcp-guardrail
README
<p align="center">
<img src="./assets/icon-512.png" alt="NeuroDock" width="180">
</p>
<h1 align="center">NeuroDock</h1>
<p align="center"><em>A cognitive substrate that remembers, paces, and refuses. Built with neurodivergent professionals, not for them.</em></p>
<p align="center">
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0--or--later-1f1f1f.svg" alt="License AGPL-3.0-or-later"></a>
<img src="https://img.shields.io/badge/python-3.11%2B-1f1f1f.svg" alt="Python 3.11+">
<img src="https://img.shields.io/badge/node-22%2B-1f1f1f.svg" alt="Node 22+">
<a href="https://www.npmjs.com/package/@neurodock/cli"><img src="https://img.shields.io/npm/v/@neurodock/cli?label=%40neurodock%2Fcli&color=1f1f1f" alt="@neurodock/cli on npm"></a>
<a href="https://pypi.org/project/neurodock-mcp-chronometric/"><img src="https://img.shields.io/pypi/v/neurodock-mcp-chronometric?label=pypi%3A%20mcp-servers&color=1f1f1f" alt="neurodock-mcp-* on PyPI"></a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/cross--platform-macos%20%C2%B7%20linux%20%C2%B7%20windows-1f1f1f.svg" alt="Cross-platform">
<img src="https://img.shields.io/badge/MCP-native-1f1f1f.svg" alt="MCP-native">
<img src="https://img.shields.io/badge/local--first-default-1f1f1f.svg" alt="Local-first by default">
<img src="https://img.shields.io/badge/telemetry-none-1f1f1f.svg" alt="No telemetry">
<img src="https://img.shields.io/badge/self--ID-sufficient-1f1f1f.svg" alt="Self-ID sufficient">
</p>
## 5-second TL;DR
- **What it does:** gives Claude a memory of your work, a sense of time, a refuse-rumination guardrail, and a translator for corporate ambiguity.
- **Who it's for:** neurodivergent people — self-ID only, no diagnosis required, no gatekeeping.
- **How to install:** one command, below.
NeuroDock plugs into Claude Desktop / Claude Code / Cursor (any MCP-aware
client). Local-first by default. No telemetry. AGPL-3.0-or-later.
## How it fits together
You chat with Claude exactly like normal. Under the hood, Claude calls
NeuroDock's local MCP servers; they read and write your local store; the
result flows back into Claude's reply.
<p align="center">
<img src="./assets/branding/architecture-request-path.svg" alt="Request path: you talk to Claude; Claude calls five NeuroDock MCP servers (chronometric, cognitive-graph, task-fractionator, translation, guardrail) plus the evals harness; they read and write ~/.neurodock on your local machine; results flow back into Claude's reply. All local by default, no telemetry, your data stays your data." width="100%">
</p>
Everything runs on your laptop. Nothing leaves your machine unless you
explicitly turn on a cloud option.
<p align="center">
<img src="./assets/branding/onboarding-3-steps.svg" alt="Install NeuroDock in three steps: 1) Run npx @neurodock/cli@latest install-all (under 5 minutes). 2) Full-quit Claude with Cmd+Q or Ctrl+Q so it re-reads its MCP config (30 seconds). 3) Start talking to Claude — for example, ask 'What was I working on yesterday?'" width="100%">
</p>
## Install
```sh
npx --yes @neurodock/cli@latest install-all
```
One command. It pip-installs the five MCP servers (plus the `neurodock-evals`
harness), wires Claude Desktop / Claude Code / Cursor, and drops a starter
profile at `~/.neurodock/profile.yaml`.
Then, **in any conversation**, try one of:
```
What was I working on yesterday?
Plan my morning.
Decompose this goal into atomic tasks.
```
Claude calls the MCP tools under the hood; you just talk.
> ### 🛑 First-time gotcha: full-quit Claude before testing
>
> Claude only reads its MCP config at startup. **Closing the window is not
> enough.** This is the #1 silent failure people hit.
>
> - **macOS:** `Cmd + Q` (or Claude menu → Quit Claude).
> - **Windows:** right-click the Claude icon in the system tray → **Quit**.
> - **Linux:** kill the process (`pkill -f Claude` or quit from the tray).
>
> Then reopen Claude and try one of the prompts above.
Requires Python 3.11+ and Node 22+. Works on macOS, Linux, Windows.
> **Why `@latest`?** If you previously ran `npm install -g @neurodock/cli`,
> npx will silently reuse that older global install instead of fetching the
> current version — and old versions don't have `install-all`. The `@latest`
> tag forces npx to resolve against the npm registry every time. Same reason
> we use it on `update`.
<details>
<summary><strong>Want to install it step-by-step instead?</strong></summary>
NeuroDock ships across two registries: the Python **MCP servers** (MCP =
Model Context Protocol — the standard that lets Claude call local tools)
on PyPI, and the user-facing **CLI** on npm. The CLI wraps everything else.
**1. Install the six MCP servers**
```sh
pip install neurodock-mcp-chronometric neurodock-mcp-cognitive-graph neurodock-mcp-task-fractionator neurodock-mcp-translation neurodock-mcp-guardrail neurodock-evals
```
**2. Wire them into your MCP-aware client**
```sh
npx --yes @neurodock/cli@latest init
```
Detects Claude Desktop, Claude Code, or Cursor and writes the server
entries automatically.
**3. Restart Claude** (full quit, not close-window — see the callout above).
**About the `neurodock` command** — it lives on npm as `@neurodock/cli`,
**not** on PyPI. The `pip install` step gives you the MCP server binaries
that Claude calls over stdio; the CLI is separate. Two ways to run it:
```sh
# Option A — run via npx, no install
npx --yes @neurodock/cli@latest doctor
# Option B — install once, call 'neurodock' from anywhere
npm install -g @neurodock/cli
neurodock doctor
```
`@neurodock/cli` exposes: `init`, `doctor`, `validate`, `update`, `sync`,
`uninstall`, `host install`, `host uninstall`, `profile show`,
`profile validate`, `install-all`, `install-hooks`, `examples`,
`plugin add/remove/list/enable/disable/validate`.
### Proactive guardrails (optional, recommended)
By default NeuroDock waits for you to ask. That's the wrong shape — an
ND user in hyperfocus is the one least likely to remember to run a
break tool. One command flips it:
```sh
neurodock install-hooks --self-test
```
This wires a small Python script (bundled, stdlib-only — no extra
install needed) into Claude Code's hook system. It then runs silently
on every tool call and auto-fires the chronometric / rumination /
sycophancy heuristics when patterns trip. You get a one-line stderr
banner on the next prompt — never blocked, always dismissible.
For host-agnostic coverage (catches you working in the terminal at
02:00 too), add the standalone daemon:
```sh
neurodock install-hooks --install-daemon --self-test
```
That registers a per-user autostart entry (HKCU Run on Windows,
LaunchAgent on macOS, systemd `--user` on Linux). The daemon polls
every 5 min and surfaces OS-native notifications.
Opt out anytime:
```sh
neurodock install-hooks --uninstall # removes both
export NEURODOCK_GUARDRAILS=off # disables without removing
```
The browser extension carries its own equivalent (Phase 2 watchdog) —
it's enabled by default and toggleable from `chrome.storage.local` via
the popup Settings tab.
See [`docs/.../proactive-guardrails`](./docs/src/content/docs/concepts/proactive-guardrails.mdx) for the design behind this and the
opt-out matrix.
Want to see it work without installing from PyPI/npm at all?
`TESTING_LOCAL.md` walks through the from-clone path.
</details>
<details>
<summary><strong>Prefer a plugin, a one-click desktop extension, or the MCP Registry?</strong></summary>
The `install-all` command above is the recommended path. The same servers are
also distributed through three standard channels — all install the identical
local stdio servers, so you can pick whichever fits your client:
**Claude Code plugin** — bundles the five MCP servers _and_ a set of ND-aware
skills in one step. Requires [`uv`](https://docs.astral.sh/uv/) (the servers
run via `uvx`).
```
/plugin marketplace add tlennon-ie/neurodock
/plugin install neurodock@neurodock
```
**Claude Desktop extension (`.mcpb`)** — one-click install, no config editing.
One bundle per server under [`mcpb/`](./mcpb/); build with
`npx @anthropic-ai/mcpb pack mcpb/neurodock-mcp-translation` and drag the
`.mcpb` onto Claude Desktop → Settings → Extensions. Requires `uv`.
**Official MCP Registry** — each server ships a
[`server.json`](./packages/mcp-translation/server.json) and is published to
[registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)
under the `io.github.tlennon-ie/*` namespace, so MCP-aware clients can discover
them directly.
**Hosted remote server (no install)** — the stateless tools (translation,
guardrail, and `decompose`) are also served over OAuth at a hosted HTTPS
endpoint, so you can use them with no local install and no `uv`:
```
https://mcp.neurodock.org/mcp
```
In Claude (claude.ai or Desktop) → **Settings → Connectors → Add custom
connector** → paste that URL → complete the sign-in prompt. The eight stateless
tools appear immediately. An opt-in memory surface (`enable_hosted_storage`,
`connect_byos_storage`, `record_fact`, `recall_entity`, …) is also exposed but
does nothing until you explicitly enable storage for your signed-in account. The
personal cognitive graph and neurotype profile are **never** hosted — they stay
on the local install. Full walkthrough: [Hosted server](./docs/src/content/docs/getting-started/remote.mdx).
The hosted remote server is live at `mcp.neurodock.org`.
</details>
## Update
```sh
npx --yes @neurodock/cli@latest update
```
One command. Upgrades all six MCP servers (`pip install --upgrade` /
`uv tool install`), refreshes your wired client configs, and
re-registers the optional native-messaging host. Same flags as
`install-all` (`--client`, `--profile`, `--installer`, `--dry-run`,
`--no-native-host`, `--yes`).
The browser extension auto-updates through the Chrome / Firefox / Edge
store; sideloaded users `git pull` and rebuild.
> Full-quit Claude after updating so it re-reads its MCP config — same
> as first install.
Just want to re-shape client configs without touching package versions?
Use `neurodock sync`.
## See it in action
**The cognitive substrate in a real session** — you talk to Claude normally;
under the hood it calls NeuroDock's MCP tools to remember, pace, and decompose.
https://github.com/user-attachments/assets/bcbf65ce-88dd-4f83-8dc1-d56bdde01bed
**The browser extension** — translating corporate-speak inline on Gmail, Slack,
and the rest, right where you read it, without context-switching back to Claude.
https://github.com/user-attachments/assets/5fa25044-923e-4c25-95bd-f1bd63fb3d6e
> Prefer a written walkthrough? Try the [Claude Desktop walkthrough](./examples/claude-desktop/README.md).
## Browser extension (optional)
There's also a browser extension that translates corporate-speak inline on
Gmail, Slack, Linear, Notion, GitHub, Google Docs, and Outlook. It calls
the same translation tools the MCP server exposes, but surfaces them
where you'd actually use them — a floating Translate button plus a
right-click menu — so you don't have to context-switch back to Claude
just to decode "let's circle back on this."
You pick the LLM provider. Five options: Ollama (local, default), LM
Studio (local), OpenRouter (including its auto-router), Anthropic, OpenAI.
The API key, if you need one, stays in `chrome.storage.local` and never
leaves the device.
Store submission is still pending (the listing prep is done; the developer
accounts and screenshots aren't). Until then, load it manually:
1. Build it: `pnpm --filter @neurodock/extension-browser run build`
2. Chrome / Edge: go to `chrome://extensions`, turn Developer mode on,
click **Load unpacked**, and pick `packages/extension-browser/.output/chrome-mv3/`.
3. Firefox: go to `about:debugging`, click **This Firefox** → **Load
Temporary Add-on**, and pick `manifest.json` inside
`packages/extension-browser/.output/firefox-mv3/`.
Full per-provider setup walkthrough lives in
[`packages/extension-browser/README.md`](./packages/extension-browser/README.md).
## What's inside
NeuroDock is built around three pillars. Each pillar is made of small,
independent packages that you can use one at a time or all together.
```mermaid
flowchart TB
subgraph cognitive[Cognitive substrate]
chrono[mcp-chronometric<br/>time + sessions]
cgraph[mcp-cognitive-graph<br/>memory]
frac[mcp-task-fractionator<br/>decomposition]
end
subgraph comms[Communication layer]
trans[mcp-translation<br/>tone + meetings]
ext[extension-browser<br/>Gmail, Slack, ...]
end
subgraph safety[Clinical guardrails]
guard[mcp-guardrail<br/>rumination / hyperfocus / sycophancy]
clin[clinical<br/>heuristic library]
end
skills[skills/<br/>six markdown bundles] --> cognitive
skills --> comms
skills --> safety
cli[cli/<br/>install + manage] --> cognitive
cli --> comms
cli --> safety
```
<details>
<summary>Prefer the directory tree? Open this.</summary>
```
neurodock/
├── packages/
│ ├── mcp-chronometric/ Time + session + break management
│ ├── mcp-cognitive-graph/ Persistent memory + entity recall (SQLite)
│ ├── mcp-task-fractionator/ Decompose vague goals into atomic tasks
│ ├── mcp-translation/ Corporate-speak translator (MCP + browser ext)
│ ├── mcp-guardrail/ Rumination / hyperfocus / sycophancy detectors
│ ├── skills/ Six SKILL.md bundles activating on phrases
│ ├── extension-browser/ WXT-built Chrome / Firefox / Edge extension
│ ├── native-host/ Optional native messaging host (extension <-> profile.yaml)
│ ├── cli/ `npx neurodock init` and friends
│ ├── core/ Shared types, profile schema, plugin spec
│ ├── clinical/ Heuristic library for the guardrail server
│ └── evals/ Eval harness + corpus contribution pipeline
├── docs/ Astro Starlight site (deploys to docs.neurodock.org)
├── plugins/ Drop your own plugins here; auto-discovered
└── profiles/ Curated profile presets
```
</details>
## Status
**Public preview shipped.** All three substrate pillars (cognitive,
communication, guardrails) are built, on `main`, and installable from
npm + PyPI. Latest substrate tag: `v0.7.3`.
### MCP servers (PyPI)
- **`neurodock-mcp-chronometric`** — 5 tools, 22 tests, mypy `--strict`.
- **`neurodock-mcp-cognitive-graph`** — 4 tools, SQLite + sqlite-vec
- fastembed; 4-rung resolution cascade (exact → alias → fuzzy → embedding).
Latest patch ships friendlier `record_fact` errors so wrong-shape input
no longer leaks raw Pydantic traces.
- **`neurodock-mcp-task-fractionator`** — 2 tools, 32 tests; ISO 8601
duration spec.
- **`neurodock-mcp-translation`** — 4 tools, 29 tests; deterministic
baseline plus LLM refinement envelope.
- **`neurodock-mcp-guardrail`** — all three detectors live: rumination,
hyperfocus, sycophancy (48 tests, public heuristics).
- **`neurodock-evals`** — air-gapped harness, 10 seed corpus examples,
contribution pipeline.
- **`neurodock-clinical`** — reserved name; importable detector library
(currently a stub).
### CLI + browser surface (npm)
- **`@neurodock/cli`** — 19 verbs across 7 groups: `init`, `install-all`,
`examples`, `doctor`, `validate`, `update`, `sync`, `uninstall`,
`host install/uninstall`, `profile show/validate`, `install-hooks`,
`plugin add/remove/list/enable/disable/validate`. `install-hooks`
wires the proactive-guardrail hook into Claude Code and optionally
registers the standalone daemon.
- **`@neurodock/core`** — profile schema and plugin protocol manifests
(JSON Schema 2020-12).
- **`@neurodock/native-host`** — optional Chrome Native Messaging host
for the extension ↔ profile sync.
- **`@neurodock/extension-browser`** — WXT MV3 build for Chrome / Firefox
/ Edge. Seven sites wired. Five real LLM providers: Ollama, LM Studio,
Anthropic, OpenAI, OpenRouter. Includes the Phase 2 proactive watchdog
for hyperfocus / late-night / single-host rumination signals.
**Not yet store-published.**
### Skills + docs
- **Six launch skills** — `adhd-daily-planner`, `audhd-context-recovery`,
`ocd-decision-finalizer` (beta), `hyperfocus-formatter`, `visual-organizer`,
`asd-meeting-translator`.
- **Docs site** — builds clean (Astro Starlight), deploys to
[`docs.neurodock.org`](https://docs.neurodock.org).
### Still deferred
- **Browser-store submissions** — Chrome Web Store, Firefox Add-ons, Edge
Add-ons developer accounts + screenshots; manual step.
## How to actually test it right now
**`TESTING_LOCAL.md`** — step-by-step guide to running this against your
Claude Desktop, today, from a clone. Takes about 5 minutes.
## Documentation
The docs site lives at [`docs.neurodock.org`](https://docs.neurodock.org).
Source is at `docs/src/content/docs/`. To preview locally:
```bash
pnpm --filter @neurodock/docs run dev
# opens http://localhost:4321
```
## Architecture
The substrate splits into three pillars:
1. **Cognitive substrate** — externalises executive function (time,
memory, decomposition). MCP servers: chronometric, cognitive-graph,
task-fractionator.
2. **Communication layer** — translates corporate ambiguity; rewrites
outgoing messages for register-appropriate tone; structures meeting
transcripts. MCP server: translation. Browser extension surfaces the
same prompts in Gmail / Slack / Linear / Notion / GitHub / Docs / Outlook.
3. **Clinical guardrails** — detects and intervenes on rumination
(repeat-validation loops), hyperfocus (escalating session-length
nudges), and sycophancy (unconditional agreement). MCP server: guardrail.
Heuristics are public and auditable per `ETHICS.md`.
All three layers compose via the same MCP protocol the LLM client already
speaks. There's no "NeuroDock app" — the surface is your Claude client.
Design rationale lives in `docs/decisions/`:
- ADR 0001 — chronometric tool design
- ADR 0002 — cognitive-graph tool design
- ADR 0003 — task-fractionator tool design
- ADR 0004 — profile schema
- ADR 0005 — translation tool design
- ADR 0006 — guardrail tool design
- ADR 0007 — plugin protocol
- ADR 0008 — distribution & remote strategy
## Contributing
`CONTRIBUTING.md` has the welcome + on-ramp. Pick whichever lane matches
what you want to do:
**Smallest first PR (~15 min):**
- Add a test to an existing skill (`packages/skills/<name>/tests/`)
- Add a seed eval example (`packages/evals/corpora/translation/`)
- Improve a tool's parameter description (the LLM uses these — clearer
descriptions = better tool use)
**One-afternoon PR:**
- Write a new skill — markdown bundle activating on specific phrases.
Copy any `packages/skills/<name>/` as a template; see
`docs/src/content/docs/contribute/write-a-skill.mdx`.
- Sharpen the task-fractionator heuristics (regex / domain keyword maps).
- Add a new entity-resolution heuristic (e.g., phonetic) to
`mcp-cognitive-graph`.
**Multi-day PR:**
- Build an out-of-tree plugin (skill / mcp-server / profile / translation
pack / language pack / theme) per the ADR 0007 plugin protocol. See
`docs/src/content/docs/contribute/write-a-plugin.mdx`.
- Translation language pack (e.g., Hiberno-English, German directness norms,
Japanese keigo).
**No code:**
- Add an anonymised eval example from your own corporate inbox. The
contribution pipeline lives in `packages/evals/` and is the highest-
leverage non-code contribution.
All PRs run CI: `pnpm turbo run lint typecheck test build` + `uv run pytest`
- `uv run mypy --strict packages/...`. Every published package has its
own CHANGELOG. Use Conventional Commits in PR titles (`feat:`, `fix:`,
`docs:`, `test:`, `chore:`, `ci:`).
## Manifesto (short)
1. **Lower friction for users, and for contributors.**
2. **Local-first by default; cloud is opt-in.**
3. **The user is the authority.** Self-ID sufficient.
4. **Composable over monolithic.** No god-modules.
5. **Refuse where appropriate.** AI that fuels rumination, hyperfocus, or
anxiety is a regression, not a feature.
Full text in `MANIFESTO.md`. Ethics framework in `ETHICS.md`. Governance
in `GOVERNANCE.md`.
## License
[AGPL-3.0-or-later](LICENSE). Plugins must declare an AGPL-compatible license
to load — the SPDX whitelist is in ADR 0007.