Migrate MCP server to scala-mcp-sdk

[ingarabr]

Migrate MCP server from ch.linkyard.mcp to scala-mcp-sdk

Replaces the MCP protocol library with scala-mcp-sdk (com.github.ingarabr.mcp::server:0.2.0), adopting its async task model and resource subscription features.

Dependency change

- ch.linkyard.mcp::mcp-server:0.3.3
- ch.linkyard.mcp::jsonrpc2-stdio:0.3.3
+ com.github.ingarabr.mcp::server:0.2.0

Architecture changes

Server structure: Replaced class inheritance (class BleepMcpServer extends McpServer[IO] with initialize() returning a Session) with a factory pattern (object BleepMcpServer.create(): Resource[IO, McpServer[IO]]). Shared state extracted into a ToolState case class.

Async tasks: Long-running tools (compile, test, sourcegen, fmt, clean, run) use TaskMode.AsyncOnly. The client receives a task ID immediately and gets progress updates via ctx.reportProgress() and ctx.log(). The SDK manages the fiber — no manual fiber spawning.

Watch → resource: The bleep.watch tool (infinite compile/test loop) is replaced with two subscribable MCP resources:

• bleep://build/bleep.yaml — notifies subscribers when the build config changes and is reloaded
• bleep://watch — notifies subscribers when source files change

The client orchestrates: subscribe to bleep://watch, receive notification, call bleep.compile or bleep.test. This separates observation from action and gives the client control.

File watcher bridging: Callback-based BleepFileWatching watchers are bridged to fs2 streams via Queue[IO, Unit]. Watchers run on daemon threads, cleaned up via Resource.make.

Tool input schemas

Replaced com.melvinlow.json.schema.JsonSchemaEncoder + hand-crafted JSON with InputDef.raw from the SDK. Case classes with strict circe Decoders are preserved (reject unknown fields, fail on wrong types). Named tuples (InputDef[NamedTuple]) would be ideal but require -source 3.5+ and the project uses -source 3.4.

Tools

Tool	Mode	Change
bleep.compile	AsyncOnly	Unchanged behavior, now async
bleep.test	AsyncOnly	Unchanged behavior, now async
bleep.sourcegen	AsyncOnly	Unchanged behavior, now async
bleep.fmt	AsyncOnly	Unchanged behavior, now async
bleep.clean	AsyncOnly	Unchanged behavior, now async
bleep.run	AsyncOnly	Unchanged behavior, now async
bleep.test.suites	AsyncAllowed	Unchanged behavior, optionally async
bleep.status	Sync	Unchanged
bleep.build.effective	Sync	Unchanged
bleep.build.resolved	Sync	Unchanged
bleep.projects	Sync	Unchanged
bleep.programs	Sync	Unchanged
bleep.scripts	Sync	Unchanged
bleep.restart	Sync	Unchanged
bleep.watch	—	Removed (replaced by resource)
bleep.watch.stop	—	Removed (resource lifecycle)
bleep.sync	—	Removed (no longer needed)

New SDK features used

• McpServer.apply() with tasksEnabled = true and instructions parameter
• ToolDef.unstructured with TaskMode for async execution
• ResourceDef with updates: fs2.Stream[F, Unit] for subscribable resources
• ToolAnnotations with readOnlyHint, destructiveHint, openWorldHint
• InputDef.raw for case class input schemas
• ToolContext for logging (ctx.log) and progress (ctx.reportProgress)

Temporary workarounds

• InputSchema[Unit] given for no-argument tools (will be provided by SDK in next release)
• _root_.mcp.protocol / _root_.mcp.server imports needed because bleep.mcp package shadows mcp

What's preserved

• All 14 remaining tool descriptions, titles, and hint annotations
• Strict argument validation (reject unknown fields)
• BSP event routing by originId for concurrent tool calls
• Build history and diff-based response model
• Heartbeat progress reporting during builds
• Per-project error streaming via notifications

Test plan

• bleep compile bleep-cli passes
• Test with MCP Inspector (npx @anthropic/mcp-inspector)
• Test with Claude Code via .mcp.json
• Verify all 14 tools appear with correct schemas, descriptions, and annotations
• Verify resource subscriptions emit on file changes
• Verify async task progress streaming during compile/test

🤖 Generated with Claude Code

[ingarabr]

Claude Code MCP Limitations (as of April 2026)

While testing the bleep MCP server with Claude Code, we hit several gaps in Claude Code's MCP client implementation. Documenting here for context on the AsyncOnly → AsyncAllowed change.

1. No MCP Task-Augmented Execution (SEP-1686)

Claude Code calls MCP tools synchronously only. The task protocol (async task IDs, background execution, progress streaming) is not supported — even though the MCP TypeScript SDK bundled inside Claude Code already has the implementation (callToolStream(), getTask(), etc.). It's just not wired up.

Tools marked TaskMode.AsyncOnly fail with: "Tool 'bleep.compile' requires task-augmented execution"

Tracking: anthropics/claude-code#18617 (open, no assignee, marked stale)

2. No Progress or Log Notifications

notifications/progress and ctx.log() messages streamed by MCP servers during long-running operations are silently ignored by the client. No progress display, no streaming build output.

3. No MCP Resource Subscriptions

Claude Code can read resources via @ mentions (one-time fetch), but does not subscribe to notifications/resources/updated. Subscribable resources like bleep://watch (file change notifications) emit into the void.

Tracking: anthropics/claude-code#7252 (closed/stale, still requested by users)

4. No run_in_background for MCP Tools

The Bash tool supports run_in_background: true, but MCP tools have no equivalent. A community suggestion to inject a virtual run_in_background parameter client-side (no server changes needed) has not been acted on.

5. MCP Timeout Issues

Multiple reported bugs around MCP timeouts: connection timeout ignores MCP_TIMEOUT beyond 60s (#16837), and Claude Code kills healthy stdio MCP servers after 10-60s (#40207). The actual tool call execution timeout is unclear. These bugs make long-running MCP operations unreliable.

6. No Public Roadmap

No public timeline for when any of these features ship.

---

Workaround

Changed build tools from TaskMode.AsyncOnly to TaskMode.AsyncAllowed. This lets Claude Code call them synchronously for quick operations, while preserving async task support for capable clients. For long builds, bleep --no-color compile via Bash remains the reliable fallback.