Repository navigation
Description
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
Originheader. - 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-28capabilities 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
pablontiv commentedon Sep 6, 2026
[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.