feat: migrate SDK + MCP to omnigraph-server v0.8.0

[aaltshuler]

Catches the SDK up to the engine's v0.8.0 stable release (published 2026-07-01; npm was at 0.7.0 against a 0.8.0 server).

Follows the documented upgrade recipe (README → "when omnigraph cuts a release"):
serverVersion pin → sync-spec (from the v0.8.0 tag) → generate → package version bumps.

API delta (additive — no call-site changes):

• Same operation set; check-coverage green (17/17 bound, 3 intentionally unbound aliases).
• /healthz response gains required internal_schema_version (storage-format version the binary serves).
• Snapshot response gains required internal_schema_version (the graph branch's on-disk stamp).
• Both surface as internalSchemaVersion automatically via the Camelize<> DTOs; the health unit test now pins the camelization.

Operator note: server 0.8.0 is a breaking engine release (storage format v4 — pre-0.8.0 graphs are rebuilt via export/import), but the HTTP surface is additive, so existing SDK code keeps working; only the graph itself must be on v0.8.0 format.

Gate: check-drift ✓ (spec == upstream v0.8.0), check-versions ✓, check-coverage ✓, build ✓, typecheck ✓, tests 86+14 ✓.

After merge: tag v0.8.0 → release workflow publishes both packages to npm (provenance, latest) and creates the GitHub release.

🤖 Generated with Claude Code

https://claude.ai/code/session_011iy1zTac7zj73h3ESSVP6r

Greptile Summary

This PR syncs the TypeScript SDK and MCP server to omnigraph-server v0.8.0, adding the new required internal_schema_version field to HealthOutput and SnapshotOutput (surfaced as internalSchemaVersion via the Camelize<> DTOs) and updating all version pins.

• Schema / types: spec/openapi.json and the auto-generated types.gen.ts add internal_schema_version: number (required, int32) to both HealthOutput and SnapshotOutput, and update QueriesCatalogOutput's description to reflect that cluster-served graphs expose all stored queries rather than the mcp.expose subset.
• Test coverage (partial): The SDK health test is correctly updated to stub and assert on internal_schema_version: 4; however, the MCP fakeFetch /healthz stub and all snapshot stubs in both packages are not updated to include the new required field, leaving the MCP health round-trip and both snapshot camelization paths without coverage for the new field.

Confidence Score: 4/5

Safe to merge for existing callers — the HTTP surface change is additive and no call sites break. The only gap is incomplete test stubs that omit the new internal_schema_version field from snapshot and MCP health fakes.

The generated types, OpenAPI spec, and version pins are all consistent and correct. The SDK health test was properly extended to cover internalSchemaVersion. The snapshot stubs in both packages and the MCP fakeFetch /healthz stub were not updated to include the new required field, so those test paths give no confidence that internalSchemaVersion camelizes and round-trips correctly through the MCP layer or the snapshot path.

packages/mcp/test/server.test.ts and packages/sdk/test/client.test.ts — specifically the /healthz fakeFetch stub and all snapshot stubs, which are missing the new required field.

Important Files Changed

Filename	Overview
spec/openapi.json	Bumped to v0.8.0; adds required internal_schema_version (int32, min 0) to both HealthOutput and SnapshotOutput, and updates /queries description to reflect all-query catalog semantics.
packages/sdk/src/generated/types.gen.ts	Auto-generated from updated spec; correctly adds internal_schema_version: number as required on HealthOutput and SnapshotOutput, and updates doc strings for QueriesCatalogOutput.
packages/sdk/test/client.test.ts	Health stub correctly updated to include internal_schema_version: 4 with an assertion on h.internalSchemaVersion; snapshot stubs still omit the new required field and include a non-existent snapshot_id field.
packages/mcp/test/server.test.ts	Version assertions updated to 0.8.0; fakeFetch /healthz stub not updated to include internal_schema_version, leaving MCP health tool round-trip for the new field untested.
packages/mcp/src/server.ts	Logic is unchanged and correct; one inline comment still references omnigraph-server 0.7.0 (stale after the version bump).
packages/sdk/src/version.gen.ts	Single-line version bump from 0.7.0 to 0.8.0; correct.
packages/mcp/src/version.gen.ts	Single-line version bump from 0.7.0 to 0.8.0; correct.
package.json	Root omnigraph.serverVersion pin updated from 0.7.0 to 0.8.0 as required by the upgrade recipe.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client as SDK / MCP Client
    participant SDK as @modernrelay/omnigraph v0.8.0
    participant Server as omnigraph-server v0.8.0

    Client->>SDK: og.health()
    SDK->>Server: GET /healthz
    Server-->>SDK: "{ status, version, internal_schema_version: 4 }"
    SDK-->>Client: "Camelize → { status, version, internalSchemaVersion: 4 }"

    Client->>SDK: "og.snapshot({ branch })"
    SDK->>Server: "GET /graphs/{id}/snapshot?branch=..."
    Server-->>SDK: "{ branch, manifest_version, internal_schema_version: 4, tables }"
    SDK-->>Client: "Camelize → { branch, manifestVersion, internalSchemaVersion: 4, tables }"

    Client->>SDK: og.queries.list()
    SDK->>Server: "GET /graphs/{id}/queries"
    Note over Server: 0.8.0: returns ALL stored queries (not just mcp.expose subset)
    Server-->>SDK: "{ queries: [...all...] }"
    SDK-->>Client: "{ queries: [...all...] }"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client as SDK / MCP Client
    participant SDK as @modernrelay/omnigraph v0.8.0
    participant Server as omnigraph-server v0.8.0

    Client->>SDK: og.health()
    SDK->>Server: GET /healthz
    Server-->>SDK: "{ status, version, internal_schema_version: 4 }"
    SDK-->>Client: "Camelize → { status, version, internalSchemaVersion: 4 }"

    Client->>SDK: "og.snapshot({ branch })"
    SDK->>Server: "GET /graphs/{id}/snapshot?branch=..."
    Server-->>SDK: "{ branch, manifest_version, internal_schema_version: 4, tables }"
    SDK-->>Client: "Camelize → { branch, manifestVersion, internalSchemaVersion: 4, tables }"

    Client->>SDK: og.queries.list()
    SDK->>Server: "GET /graphs/{id}/queries"
    Note over Server: 0.8.0: returns ALL stored queries (not just mcp.expose subset)
    Server-->>SDK: "{ queries: [...all...] }"
    SDK-->>Client: "{ queries: [...all...] }"

Loading

Comments Outside Diff (2)

1. packages/mcp/test/server.test.ts, line 28-30 (link)

   Health stub not updated for new required field

   The fakeFetch() /healthz stub still returns { status: 'ok', version: '0.3.0' } without internal_schema_version, even though HealthOutput now declares it as a required field. The SDK test (client.test.ts) was correctly updated to include internal_schema_version: 4 and assert on h.internalSchemaVersion. But the MCP test's health-tool test ('calls the health tool and round-trips the SDK SERVER_VERSION') never checks whether internalSchemaVersion is present in the tool's JSON response — so the camelization round-trip through the MCP layer is not covered. When the real server returns the field, the tool will include it; the test just doesn't verify this.

   

2. packages/sdk/test/client.test.ts, line 21-29 (link)

   Snapshot stub missing new required internal_schema_version field

   Both snapshot test stubs ('snapshot encodes branch as a query param' and 'snapshot allows omitting branch') provide { branch, tables, snapshot_id }. After this PR, SnapshotOutput has two required numeric fields — manifest_version (pre-existing) and the newly added internal_schema_version — but neither appears in the stubs, and snapshot_id is not a real schema field. The PR added a internalSchemaVersion assertion only for the health path; the parallel coverage for snapshot is absent. Any code that reads s.internalSchemaVersion from a real server response will receive a number, but the test stubs leave it undefined.

   

_{Reviews (1): Last reviewed commit: "feat: migrate SDK + MCP to omnigraph-ser..." | Re-trigger Greptile}