TypeScript packages for the Omnigraph graph database.
| Package | Purpose |
|---|---|
@modernrelay/omnigraph |
TypeScript SDK — instance-per-client, typed errors, camelCase types, streaming export. Read this if you're building against omnigraph-server. |
@modernrelay/omnigraph-mcp |
MCP server bridging Omnigraph to LLM hosts (Claude Desktop, …) over stdio. Wraps the SDK above. |
.
├── spec/openapi.json # committed copy of upstream OpenAPI at the pinned tag
├── scripts/ # spec sync, drift check, version-stamp generator
├── packages/
│ ├── sdk/ # @modernrelay/omnigraph
│ └── mcp/ # @modernrelay/omnigraph-mcp
└── .github/workflows/ # ci (build/typecheck/test/coverage), e2e (live server), release
The SDK is built against a specific omnigraph-server release. The pin lives in package.json#omnigraph.serverVersion at the repo root and is the single source of truth — scripts/sync-spec.ts reads it to fetch the matching OpenAPI spec, and scripts/gen-version.ts writes it into packages/sdk/src/version.gen.ts so consumers can import { SERVER_VERSION } from '@modernrelay/omnigraph'.
CI enforces drift in two ways: a structural check that the bundled spec matches the upstream tag exactly, and an end-to-end suite that runs against a live omnigraph-server of the pinned release.
@modernrelay/omnigraph matches omnigraph-server on major.minor; the patch is independent. A published @modernrelay/omnigraph@X.Y.* is built against omnigraph-server@X.Y.* and is expected to work against any >=X.Y.0, <X.(Y+1).0. The exact server version the SDK was generated from is always available at runtime as import { SERVER_VERSION } from '@modernrelay/omnigraph'.
In practice: server cuts 0.4.2, SDK ships 0.4.0 (and 0.4.1, 0.4.2, … as SDK-side fixes land independently). When server cuts 0.5.0, the SDK jumps to 0.5.0 regardless of where the 0.4.x patch line ended. This keeps SDK release cadence decoupled from the server while still making major.minor compatibility self-documenting.
- Bump
package.json#omnigraph.serverVersionto the new tag (e.g.,0.4.0). pnpm run sync-spec— fetches the matchingopenapi.jsonintospec/.pnpm run generate— regeneratespackages/sdk/src/generated/andpackages/sdk/src/version.gen.ts.- Commit
spec/openapi.json,packages/sdk/src/generated/,packages/sdk/src/version.gen.ts, and the bumpedpackage.json. The PR shows the full upstream change. - Bump
packages/sdk/package.json#version(andpackages/mcp/package.json#version) to match. - Tag
vX.Y.Z.release.ymlpublishes both packages to npm (see Releasing).
Pushing a v* tag triggers .github/workflows/release.yml, which runs the full gate (drift, coverage, build, typecheck, test) on the tag SHA and then publishes both @modernrelay/omnigraph and @modernrelay/omnigraph-mcp with npm provenance. The dist-tag is derived from the tag name: v1.2.3-alpha.1, -beta.x, -rc.x ship under next; everything else under latest.
pnpm --filter @modernrelay/omnigraph version 0.4.0-alpha.1
pnpm --filter @modernrelay/omnigraph-mcp version 0.4.0-alpha.1
git commit -am "Release 0.4.0-alpha.1"
git tag -a v0.4.0-alpha.1 -m "Release 0.4.0-alpha.1"
git push --follow-tags
# then approve the `release` environment in the Actions UI.One-time setup: add an npm NPM_TOKEN repo secret (use an Automation token to bypass 2FA in CI) and create a release GitHub Environment with required reviewers so a stray tag push cannot ship.
pnpm install
pnpm run check-drift # asserts spec matches the pinned server tag
pnpm run generate # regenerates types + version stamp
pnpm run check-coverage # asserts every spec op has an SDK binding
pnpm run build # builds all workspace packages (SDK first, then MCP)
pnpm run typecheck # runs after build so workspace types resolve
pnpm run test # mocked unit tests across all packages
# Live e2e against a real server (requires omnigraph-server v$(jq -r .omnigraph.serverVersion package.json) running):
OMNIGRAPH_E2E=1 OMNIGRAPH_BASE_URL=http://127.0.0.1:8080 OMNIGRAPH_TOKEN=$TOKEN pnpm --filter @modernrelay/omnigraph run testCI runs the same sequence (see .github/workflows/ci.yml and e2e.yml) and downloads the pinned omnigraph-server release binary for the e2e job.
MIT