Handle Glama startup without a local Ableton bridge

[Pantani]

Summary

• Keep the MCP server booting when the Ableton TCP bridge is unavailable.
• Add a small bridge-runtime helper that falls back to an offline bridge client instead of exiting during startup.
• Cover both offline and connected startup paths with a regression test.

Testing

• npm test -- tests/server-bridge-runtime.test.ts
• npm run typecheck
• npm run lint
• npm test
• npm run build
• npm run build:dxt:check
• Docker build and MCP smoke validation passed, including tools/list against the built image.

Summary by CodeRabbit

• New Features

  • Added offline mode support—the server now starts gracefully when the Ableton bridge is unavailable, allowing operation without a live connection.
  • Improved connection state monitoring and status reporting.

• Tests

  • Added tests for bridge connection and offline behavior scenarios.

[coderabbitai]

Warning

Review limit reached

@Pantani, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 37 minutes and 50 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f84019db-52e6-48fb-82e1-b02dc7c703d0

📥 Commits

Reviewing files that changed from the base of the PR and between a54dc63 and 4e300b5.

📒 Files selected for processing (2)

• src/server/bridge-runtime.ts
• tests/server-bridge-runtime.test.ts

📝 Walkthrough

Walkthrough

This PR introduces a bridge runtime abstraction layer to decouple TCP connection management from the main entrypoint. The new module handles connection lifecycle, gracefully falls back to offline mode on failure, and is integrated into startup with conditional forwarder attachment and improved shutdown handling.

Changes

Bridge Runtime Abstraction & Integration

Layer / File(s)	Summary
Bridge runtime abstraction and types src/server/bridge-runtime.ts	BridgeRuntime interface exposes bridge client, TCP client reference, connection state, status detail, and async close method. createBridgeRuntime() orchestrates TCP connection and configurable handshake; on failure it returns an offline runtime with throwing bridge and null client; on success it wires the bridge to the TCP client and sets connected flag. Internal closeIgnoringErrors() handles safe shutdown.
Bridge runtime tests tests/server-bridge-runtime.test.ts	Two test cases verify offline fallback (connection refused → offline mode, handshake not called, client closed once, bridge.call() rejects with offline error) and connected path (successful connection + handshake → connected runtime with proper status, bridge.call() succeeds, runtime.close() closes client).
Entrypoint refactoring and offline-mode support src/index.ts	Main startup now calls await createBridgeRuntime() and logs connection state. Server creation uses bridgeRuntime.bridge. Notification forwarder attachment is conditional on bridgeRuntime.client being non-null. Shutdown invokes await bridgeRuntime.close(). Documentation and imports updated to reflect offline-capable startup.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A bridge once built with care and grace,
Now gracefully falls back in place,
When Ableton hides beyond the wire,
The server still won't catch on fire—
Offline it goes, yet standing tall! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: enabling the MCP server to start without a local Ableton bridge connection.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/server/bridge-runtime.ts`:
- Around line 17-21: The offline bridge client currently throws a generic Error
in createOfflineBridgeClient's call method; change it to throw the
transport-specific JsonRpcTransportError (from your bridge transport contract)
so callers can classify transport failures properly—update the throw in
createOfflineBridgeClient (and ensure JsonRpcTransportError is
imported/available) to construct the JsonRpcTransportError with a descriptive
message including the detail string and any relevant metadata.

In `@tests/server-bridge-runtime.test.ts`:
- Around line 29-45: Add a test that covers the case where client.connect()
succeeds but handshake() throws: call createBridgeRuntime with a mock client
whose connect resolves and close is mocked, and a handshake mock that rejects;
assert the returned runtime.connected is false, runtime.detail indicates the
bridge is offline (e.g., "Ableton bridge offline"), runtime.client is still the
client, any runtime.bridge.call rejects or is not usable, and that
runtime.close() triggers client.close() exactly once; reference
createBridgeRuntime, client.connect, handshake, runtime.connected,
runtime.detail, runtime.bridge.call, client.close and runtime.close when adding
the test.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 77575b8f-c5c6-4d79-be50-f8c984f9260e

📥 Commits

Reviewing files that changed from the base of the PR and between 7010bad and a54dc63.

📒 Files selected for processing (3)

• src/index.ts
• src/server/bridge-runtime.ts
• tests/server-bridge-runtime.test.ts

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Docker build

🧰 Additional context used

📓 Path-based instructions (1)

src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

MCP server code must be written in TypeScript with Node 20+, using @modelcontextprotocol/sdk and Zod validation

src/**/*.{ts,tsx}: In TypeScript/Node MCP server code, use @modelcontextprotocol/sdk for implementing MCP protocol, Node 20+, and Zod for validation
TypeScript code must pass npm run typecheck, npm run lint, and npm test

Files:

• src/server/bridge-runtime.ts
• src/index.ts

🔇 Additional comments (2)

src/server/bridge-runtime.ts (1)

25-53: LGTM!

Also applies to: 55-61

src/index.ts (1)

56-67: LGTM!

Also applies to: 81-85, 102-103