Expose Backscroll through a shared stateless MCP 2026-07-28 server

[pablontiv]

Description

Expose Backscroll through a reusable MCP server conforming to protocol revision 2026-07-28, so multiple agent tasks and conversations can query the perennial SQLite index through a standard interface without treating each conversation as the lifetime boundary of a separate Backscroll process.

The revision defines MCP as stateless: every request carries the metadata required to process it, servers should handle requests associated with multiple tasks, threads, or conversations, and clients should not use an individual conversation as the stdio-process lifetime boundary. Streamable HTTP accepts independent request-scoped POSTs and can serve multiple client connections.

References:

• https://modelcontextprotocol.io/specification/2026-07-28/basic
• https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http

Prerequisite

• Startup sync has quadratic session-text aggregation and can stall commands #46 defines Backscroll's core synchronization coordination and committed-snapshot behavior. The MCP server must consume that invariant; it must not replace or redefine Startup sync has quadratic session-text aggregation and can stall commands #46's lock design.

Goals

• Provide an MCP surface for Backscroll's database-backed read operations.
• Support reuse across multiple tasks and conversations.
• Keep SQLite as the only public query source.
• Keep protocol requests stateless and carry any application state through explicit identifiers.
• Define a deployment topology for local use that avoids binding an unauthenticated service to external interfaces.
• Preserve the CLI as a supported interface over the same application services.

Design Questions

• Which CLI operations map to MCP tools, resources, or both?
• Should the first transport be long-lived stdio, localhost Streamable HTTP, or both?
• How will separate Pi host processes discover and reuse one local server instance?
• How will protocol-version and extension capabilities be validated per request?
• What diagnostics and freshness metadata should accompany results while Startup sync has quadratic session-text aggregation and can stall commands #46's synchronizer is active?
• How should server lifecycle, upgrades, and crash recovery work without coupling them to a conversation?

Security Requirements

For Streamable HTTP, follow the specification requirements and recommendations:

• Validate the Origin header.
• Bind local deployments only to localhost by default.
• Require appropriate authentication and authorization.
• Do not expose arbitrary paths or query data beyond the user's configured Backscroll inputs.

Non-goals

• Reimplementing the O(n²), cross-process locking, or stale-read changes owned by Startup sync has quadratic session-text aggregation and can stall commands #46.
• Defining asynchronous sync jobs; track MCP Tasks separately.
• Replacing SQLite with an MCP-specific store.
• Removing the CLI.

Acceptance Criteria

• The server declares and validates MCP protocol revision 2026-07-28 capabilities per request.
• At least the agreed read-only Backscroll operations are available through documented MCP primitives.
• Multiple tasks or conversations can use the same server without conversation-local protocol state.
• CLI and MCP results share the same application/query semantics and committed SQLite source.
• The server integrates with Startup sync has quadratic session-text aggregation and can stall commands #46's synchronization coordinator rather than creating a second sync path.
• Local transport security follows the MCP specification.
• Integration tests cover concurrent clients, malformed protocol metadata, cancellation, and server restart behavior.