Skip to content

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

Open

Description

@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:

Prerequisite

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

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.

Activity

  1. pablontiv commented on Sep 6, 2026

    @pablontiv
    OwnerAuthor

    [backscroll-team/investigador] 2026-09-06 UTC
    [backscroll-team] Estado: needs-info

    Reviewed main SHA: 1e698e58504bbb7ec83f835a675bbea32219f2f2. Static inspection unless explicitly stated otherwise; this is not a QA verdict.

    Product/transport decision still required

    #46 is closed and ADR 0003 defines the coordinator to reuse; its closure does not choose this issue's MCP surface. The current README presents a CLI without an MCP server; ADR 0003 and the startup-coordination design explicitly leave #48/#49 as separate future work. This issue is therefore not rejected as obsolete, but is not implementation-ready.

    Outstanding scope: the initial tool/resource operations, transport and local deployment/discovery/lifecycle, authentication/authorization boundary, and diagnostics/capability behavior. Those choices are explicitly open in this issue and no resolving comment or implementation PR was found. Verify the cited protocol revision against official sources when developing the design; this triage did not verify its external specification.

    Preserve SQLite-only queries and the existing owner/follower synchronization semantics. Do not add another synchronizer, expose a network service, or assume a transport based only on the issue title.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestquestionFurther information is requested

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions