mcp: best-practices resources + workflow instructions

[ragnorc]

Summary

An LLM picking up `@modernrelay/omnigraph-mcp` cold has no idea about workflow norms — call schema first, parameterize queries, edge casing trap, verify writes, append-only retry-safety, etc. The OpenAPI surface doesn't communicate any of this. This PR fixes that with two affordances:

1. Server `instructions` field

~30 lines set on `McpServer` init. MCP hosts thread this into the LLM's system context at session start. Leads with:

ALWAYS read `omnigraph://schema` (or call `schema_get`) FIRST, before any query, mutation, or ingest.

Then enumerates the 8 workflow norms an LLM cannot afford to discover by failure: PascalCase/lowerCamelCase edge casing, no `mutation {}` wrapper, parameterize everything, the `commits_list` verify-after-write ritual, append-only-vs-pointer dedup table, branch-then-merge for risky writes, schema_apply destructiveness, date asymmetry, and the `sync_branch()` server-internal vs. tool distinction.

2. Five vendored cookbook references as MCP resources

```
omnigraph://best-practices/queries — before .gq queries (read/change)
omnigraph://best-practices/data — before ingest (mode selection, branch loop)
omnigraph://best-practices/schema — before schema_apply
omnigraph://best-practices/remote-ops — after any 504 or unexpected error
omnigraph://best-practices/search — before nearest/bm25/rrf queries
omnigraph://best-practices/index — what each of the above covers
```

Bodies stay out of session context until `resources/read` is called — the LLM only pays for what it needs.

Sync mechanics (hybrid auto-discover + curated descriptions)

• `scripts/sync-cookbook.ts` auto-discovers every `.md` under the upstream `references/` directory via the GitHub contents API.
• Validates against `packages/mcp/cookbook-descriptions.json`, which has two sections:
  • `exposed` — files surfaced as resources, with hand-written `title` + `description` (LLM reads these at `resources/list` time to decide whether to pull a body, so generic descriptions don't cut it).
  • `skipped` — files we intentionally don't expose, with a one-line reason (currently `aliases`, `commands`, `server-policy` — CLI/deployment-only concerns not actionable through the HTTP API).
• Every upstream file must be in exactly one section. Any drift fails the build with a clear message naming the file and pointing at the config. So if upstream cuts a new `tracing.md`, the next CI build fails until a maintainer decides whether to expose or skip it.
• The sync writes a generated TS module (`src/best-practices.gen.ts`, gitignored). Hooked via `prebuild`/`pretypecheck`/`pretest` so every workflow that touches MCP code regenerates it.
• The published npm tarball ships the bundled JS with the markdown inlined as string constants — no runtime network dependency for consumers.

Tarball impact

`@modernrelay/omnigraph-mcp` goes from 6.6 KB packed (0.4.0) to ~30 KB packed (0.4.1); unpacked 31 → 103 KB. All inlined cookbook content. SDK unchanged but ships in lockstep per the major.minor versioning policy.

Test plan

• `pnpm run check-drift` (still matches v0.4.2)
• `pnpm run check-coverage` (14/14)
• `pnpm run build` (SDK + MCP)
• `pnpm run typecheck`
• `pnpm run test` — 56 SDK + 12 MCP unit tests pass (2 new: `resources/list` membership, `instructions` content)
• `pnpm publish --dry-run` on MCP — 30.6 KB packed, 9 files, version 0.4.1
• Sync-script failure-path verified manually: when upstream has a file that's neither in `exposed` nor `skipped`, the script errors with a remediation message naming the missing entries and the config path.

After merge

```bash
git tag -a v0.4.1 -m "Release 0.4.1"
git push --follow-tags

approve the `release` environment in the Actions UI

```

🤖 Generated with Claude Code

---

Note

Medium Risk
Medium risk because it changes MCP server initialization (adds instructions) and introduces a build-time GitHub fetch/generation step that can fail builds or drift with upstream content.

Overview
The MCP server now provides an LLM-facing instructions block on initialize, emphasizing schema-first workflows and key safety norms for queries, ingest, retries, and schema changes.

It also exposes a set of omnigraph://best-practices/* markdown resources (plus an index) whose bodies are vendored from ModernRelay/omnigraph-cookbooks at build time via a new sync-cookbook script, with curated titles/descriptions enforced by cookbook-descriptions.json.

Build/test hooks run the sync automatically, the generated module is .gitignore’d/cleaned, tests assert the new resources/instructions, and package versions bump to 0.4.1 (including adding tsx as a dev dependency).

^{Reviewed by Cursor Bugbot for commit f9d0ca5. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Summary by cubic

Adds workflow instructions and ships best-practices docs as MCP resources in @modernrelay/omnigraph-mcp to guide safe, efficient use (read schema first, verify writes, parameterize, etc.). Content is vendored at build time and fetched on demand; both packages bump to 0.4.1.

• New Features

  • Server now returns an instructions brief on init covering: read omnigraph://schema first; parameterize queries; verify-after-write with commits_list; branch→ingest→verify→merge for risky writes; append-only vs pointer retry safety; .gq edge casing and no mutation {} wrapper; schema_apply is main-only and destructive; date formats; nearest/bm25/rrf require a trailing limit; sync_branch() is server-internal text.
  • Exposes vendored best-practices resources: omnigraph://best-practices/queries, data, schema, remote-ops, search, plus index. Bodies are returned only on resources/read.
  • Added tests for resources list/body and instructions presence.

• Dependencies

  • Build-time sync: packages/mcp/scripts/sync-cookbook.ts auto-discovers upstream markdown, validates against packages/mcp/cookbook-descriptions.json (now also fails if a key appears in both exposed and skipped), and generates src/best-practices.gen.ts (gitignored). Wired via prebuild/pretypecheck/pretest; no runtime network dependency.
  • Added dev dep tsx; version bumps to 0.4.1 for @modernrelay/omnigraph-mcp and @modernrelay/omnigraph. MCP tarball ~6.6 KB → ~30 KB due to inlined docs.

^{Written for commit f9d0ca5. Summary will update on new commits.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.