riverpod-knowledge-graph

Standalone TypeScript workspace for building and serving pinned Riverpod documentation snapshots, MCP read tools, and deterministic audit helpers for Flutter repos.

Current status

• public GitHub repo with a pinned Riverpod 3.2.1 fixture snapshot
• deterministic MCP server and audit CLI
• standalone local/stdin usage is supported today from a local checkout or package artifact
• remote hosting is not implemented yet; Cloudflare would need an HTTP transport adapter
• docs-only MCP is the secure default; local audit tools are opt-in

Why this exists (and how it compares to generic docs tools)

Generic documentation tools (Context7, raw upstream docs, ChatGPT training data) can tell you the correct Riverpod 3.0 migration patterns, codegen syntax, and ConsumerWidget usage. They answer "how does Riverpod work?" But they cannot answer "how does Riverpod work in MY project?" - and that is the question that matters when you are refactoring, auditing, or scorching code.

Real-world example

During a production onboarding/paywall rewrite of a Flutter app (Clueless Clothing), we needed to delete quiz_view_model.dart and rebuild from scratch. Context7 correctly told us the Riverpod 3.0 codegen patterns to use. But it could not tell us that:

• onboardingServiceProvider was defined INSIDE quiz_view_model.dart (not in its own file)
• That provider had 4 external consumers across 3 features (dashboard, auth, app loading gate)
• Deleting the file would silently kill the provider and break the app at runtime (not at compile time, since other files imported it transitively)
• The provider used @Riverpod(keepAlive: true) because it cached auth tokens that survived widget disposal

We had to manually grep the entire codebase to discover this. A project-aware tool would surface it immediately.

What this tool provides that docs tools don't

Capability	Generic docs (Context7, etc.)	riverpod-knowledge-graph
Riverpod API syntax and patterns	Yes	Yes (pinned snapshot)
Migration guides (StateNotifier to Notifier)	Yes	Yes
Provider dependency graph for YOUR project	No	Yes (audit_repo)
Cross-feature consumption map	No	Yes (which providers are read/watched outside their feature)
Stale pattern detection	No	Yes (finds legacy StateNotifier, missing codegen, etc.)
keepAlive vs autoDispose audit	No	Yes (flags mismatches between provider lifecycle and usage)
Code generation health check	No	Yes (detects stale .g.dart files)
Migration blast radius analysis	No	Yes ("if I delete this, what breaks?")
Custom local rules per project	No	Yes (overlay contract)

Generic docs tools answer "how does Riverpod work?" This tool answers "how does Riverpod work in your project?" - and those are different questions.

What it includes

• a normalized Riverpod corpus rooted in upstream docs snapshots
• read/query MCP tools for snapshots, topics, docs, and guidance lookups
• audit helpers for repo overlays and Riverpod authoring checks
• a pinned fixture snapshot for Riverpod 3.2.1

Current snapshot

• riverpod-3.2.1-fixture

MCP tools

• list_snapshots
• list_topics
• get_doc
• search_docs
• get_guidance_for_pattern
• audit_repo
• explain_finding
• compare_local_policy

Getting started

npm install
npm run build

Inspect the package CLI:

npm exec -- riverpod-knowledge-graph help

Print the Codex MCP config block for this checkout:

npm exec -- riverpod-knowledge-graph bootstrap-codex

Run the MCP server:

npm exec -- riverpod-knowledge-graph mcp

Run the MCP server with local audit tools enabled:

npm exec -- riverpod-knowledge-graph mcp-audit

Run the standalone audit CLI against a consuming Flutter repo. You can start from examples/clueless-flutter-overlay.json:

npm exec -- riverpod-knowledge-graph audit-repo \
  --repo-root /path/to/flutter/repo \
  --overlay /path/to/RIVERPOD_OVERLAY.json \
  --snapshot riverpod-3.2.1-fixture

Build a snapshot:

npm run build:snapshot -- \
  --docs-root /path/to/website/docs \
  --sidebar /path/to/website/sidebars.js \
  --snapshot riverpod-3.2.1-fixture \
  --ref <git-ref> \
  --repo-url https://github.com/rrousselGit/riverpod \
  --out-dir ./corpus/snapshots

Maintainer checks:

npm run check

Provision a Mac mini or other local workstation from a checkout:

npm run provision:mac-mini

Standalone modes

Supported today:

• local checkout on a workstation or Mac mini
• packaged artifact usage through the compiled dist/ entrypoint
• stdio MCP wiring from Codex, Claude Code, or any local MCP client
• docs-only MCP as the secure default surface

Not supported yet:

• direct remote MCP hosting on Cloudflare Workers
• HTTP/SSE or streamable MCP transport

The current server is stdio-only. A Cloudflare deployment would need a transport adapter, authentication, and a decision on how snapshots are bundled and updated remotely.

Recommended deployment path

The best supported path today is local-first:

• run this package from a Mac mini or workstation
• wire Codex to the local stdio MCP with bootstrap-codex
• treat Cloudflare or other remote hosting as a separate future rollout

That keeps the trust boundary honest. Codex bootstrap is concrete and testable today; remote hosting still needs transport, auth, and request-isolation work.

Security defaults

• mcp exposes the docs/read surface only
• mcp-audit enables local repo and overlay inspection tools
• public MCP read tools no longer accept caller-controlled corpus-root overrides
• do not expose mcp-audit in shared or remote environments without additional auth

See SECURITY.md for the trust boundary and residual risks.

Use with Codex

Docs-only default:

[mcp_servers.riverpod_knowledge_graph]
command = "node"
args = [
  "/absolute/path/to/riverpod-knowledge-graph/bin/riverpod-knowledge-graph.mjs",
  "mcp",
]

A ready-to-edit template lives at examples/codex-config.toml.

Or install the docs-only block directly into your local Codex config:

npm exec -- riverpod-knowledge-graph bootstrap-codex --write --backup

Audit-enabled local setup:

[mcp_servers.riverpod_knowledge_graph]
command = "node"
args = [
  "/absolute/path/to/riverpod-knowledge-graph/bin/riverpod-knowledge-graph.mjs",
  "mcp-audit",
]

An audit-enabled template lives at examples/codex-config-audit.toml.

Install the audit-enabled block into your local Codex config:

npm exec -- riverpod-knowledge-graph bootstrap-codex \
  --mode audit \
  --write \
  --backup

Mac mini provisioning

The repo ships an idempotent setup script for trusted local machines:

RKG_BOOTSTRAP_MODE=docs npm run provision:mac-mini

Set RKG_BOOTSTRAP_MODE=audit only when the machine should have local repo audit access. You can override the target config path with CODEX_CONFIG_PATH.

The script:

• verifies node and npm
• enforces Node 20+
• reuses an existing node_modules, or uses the pinned pnpm-lock.yaml through corepack on fresh installs
• falls back to npm install --package-lock=false only when no lockfile-managed path exists
• builds the compiled package
• runs npm run check
• writes or updates the Codex MCP block with a backup

Packaging notes

• published artifacts and npm pack include the compiled dist/ entrypoint
• source checkouts still fall back to tsx when dist/ has not been built yet
• a fresh machine sanity check is npm run check
• agents should start from AGENTS.md plus the example configs, not from ad hoc flags
• the best bootstrap surface for agents today is bootstrap-codex, not hand-edited TOML

Overlay contract

Consuming repos provide a thin overlay that pins one snapshot and lists their local rules. A concrete example lives at examples/clueless-flutter-overlay.json.

{
  "repo": "my-org/my-flutter-repo",
  "pinnedSnapshotId": "riverpod-3.2.1-fixture",
  "localRules": [
    {
      "id": "keep_alive_for_async_mutations",
      "description": "Async mutating notifiers should opt into keepAlive.",
      "severity": "warning"
    }
  ]
}