Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

fix(mcp): preserve source evidence and clean up disconnected clients (#7553)

Louis Beaumontfd797a4607f7
diff --git a/crates/screenpipe-engine/src/lib.rs b/crates/screenpipe-engine/src/lib.rs
index 5ef78aadf..08847b30f 100644
--- a/crates/screenpipe-engine/src/lib.rs
+++ b/crates/screenpipe-engine/src/lib.rs
@@ -67,6 +67,7 @@ pub mod hot_frame_cache;
pub mod live_views;
pub mod local_chat;
pub mod logging;
+mod mcp_call;
pub mod mcp_servers_api;
pub mod meeting_export;
pub mod meeting_summary;
diff --git a/crates/screenpipe-engine/src/mcp_call.rs b/crates/screenpipe-engine/src/mcp_call.rs
new file mode 100644
index 000000000..2cc3b0488
--- /dev/null
+++ b/crates/screenpipe-engine/src/mcp_call.rs
@@ -0,0 +1,164 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+//! Allowlisted MCP diagnostics, never prompts, arguments, results or error text.
+use crate::qualified_value::AgentClient;
+use serde::Deserialize;
+use serde_json::{json, Value};
+
+#[derive(Debug, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub(crate) struct McpCall {
+ schema_version: u8,
+ request_id: String,
+ mcp_version: String,
+ client: AgentClient,
+ transport: Transport,
+ tool: String,
+ status: Status,
+ error_kind: ErrorKind,
+ duration_ms: u64,
+ response_bytes: u64,
+ result_count: Option<u64>,
+ truncated: Option<bool>,
+ dropped_reports: u64,
+}
+
+macro_rules! fixed_values {
+ ($name:ident { $($variant:ident),+ }) => {
+ #[derive(Debug, Deserialize, serde::Serialize)]
+ #[serde(rename_all = "snake_case")]
+ enum $name { $($variant),+ }
+ };
+}
+fixed_values!(Transport { Stdio, Http });
+fixed_values!(Status { Ok, Empty, Error });
+fixed_values!(ErrorKind {
+ None,
+ Auth,
+ InvalidRequest,
+ NotFound,
+ RateLimited,
+ Backend,
+ Unavailable,
+ Cancelled,
+ Unknown
+});
+
+const TOOLS: &[&str] = &[
+ "unknown",
+ "search-content",
+ "search_content",
+ "synced-devices",
+ "search-synced-content",
+ "list-meetings",
+ "activity-summary",
+ "search-elements",
+ "frame-context",
+ "export-video",
+ "update-memory",
+ "get-feedback",
+ "send-notification",
+ "health-check",
+ "list-audio-devices",
+ "list-monitors",
+ "add-tags",
+ "search-speakers",
+ "list-unnamed-speakers",
+ "update-speaker",
+ "merge-speakers",
+ "start-meeting",
+ "stop-meeting",
+ "get-meeting",
+ "update-meeting",
+ "keyword-search",
+ "get-frame-elements",
+ "control-recording",
+ "list-pipes",
+ "create-pipe",
+ "run-pipe",
+ "pipe-logs",
+ "team-search",
+ "team-devices",
+ "team-records",
+ "team-frame",
+ "list-workflows",
+ "get-workflow",
+ "screenpipe-skills",
+];
+
+impl McpCall {
+ pub(crate) fn into_properties(self) -> Option<Value> {
+ let version: Vec<_> = self.mcp_version.split('.').collect();
+ if self.schema_version != 1
+ || self.mcp_version.len() > 32
+ || version.len() != 3
+ || !version
+ .iter()
+ .all(|v| !v.is_empty() && v.bytes().all(|b| b.is_ascii_digit()))
+ || !TOOLS.contains(&self.tool.as_str())
+ || uuid::Uuid::parse_str(&self.request_id)
+ .map(|id| id.get_version_num() != 4)
+ .unwrap_or(true)
+ {
+ return None;
+ }
+ Some(json!({
+ "schema_version": 1, "request_id": self.request_id,
+ "mcp_version": self.mcp_version, "agent_client": self.client.as_str(),
+ "transport": self.transport, "tool": self.tool, "status": self.status,
+ "error_kind": self.error_kind, "duration_ms": self.duration_ms,
+ "response_bytes": self.response_bytes, "result_count": self.result_count,
+ "truncated": self.truncated, "dropped_reports": self.dropped_reports,
+ }))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ fn valid() -> Value {
+ json!({"schema_version":1,"request_id":"12345678-1234-4234-8234-123456789abc",
+ "mcp_version":"0.20.2","client":"claude","transport":"stdio",
+ "tool":"search-content","status":"empty","error_kind":"none",
+ "duration_ms":42,"response_bytes":30,"result_count":0,"truncated":false,"dropped_reports":0})
+ }
+ #[test]
+ fn keeps_empty_and_unknown_outcomes_distinct() {
+ let properties = serde_json::from_value::<McpCall>(valid())
+ .unwrap()
+ .into_properties()
+ .unwrap();
+ assert_eq!(properties["status"], "empty");
+ assert_eq!(properties["result_count"], 0);
+ assert!(properties.get("success").is_none());
+ let mut v = valid();
+ v.as_object_mut().unwrap().remove("result_count");
+ assert!(serde_json::from_value::<McpCall>(v)
+ .unwrap()
+ .into_properties()
+ .unwrap()["result_count"]
+ .is_null());
+ }
+ #[test]
+ fn rejects_free_text_and_unknown_schema_values() {
+ for key in ["query", "result", "error", "arguments"] {
+ let mut v = valid();
+ v[key] = json!("private content");
+ assert!(serde_json::from_value::<McpCall>(v).is_err());
+ }
+ for key in ["client", "transport", "status", "error_kind"] {
+ let mut v = valid();
+ v[key] = json!("private content");
+ assert!(serde_json::from_value::<McpCall>(v).is_err());
+ }
+ for key in ["tool", "mcp_version", "request_id"] {
+ let mut v = valid();
+ v[key] = json!("private content");
+ assert!(serde_json::from_value::<McpCall>(v)
+ .unwrap()
+ .into_properties()
+ .is_none());
+ }
+ }
+}
diff --git a/crates/screenpipe-engine/src/routes/internal_telemetry.rs b/crates/screenpipe-engine/src/routes/internal_telemetry.rs
index 31387bb07..4d788ec40 100644
--- a/crates/screenpipe-engine/src/routes/internal_telemetry.rs
+++ b/crates/screenpipe-engine/src/routes/internal_telemetry.rs
@@ -11,3 +11,12 @@ pub(crate) async fn record_mcp_value(Json(outcome): Json<McpOutcome>) -> StatusC
analytics::capture_event_nonblocking("qualified_value_event", outcome.into_properties());
StatusCode::ACCEPTED
}
+
+/// Uses the engine's existing telemetry consent and authenticated API boundary.
+pub(crate) async fn record_mcp_call(Json(call): Json<crate::mcp_call::McpCall>) -> StatusCode {
+ let Some(properties) = call.into_properties() else {
+ return StatusCode::UNPROCESSABLE_ENTITY;
+ };
+ analytics::capture_event_nonblocking("mcp_tool_call_completed", properties);
+ StatusCode::ACCEPTED
+}
diff --git a/crates/screenpipe-engine/src/server.rs b/crates/screenpipe-engine/src/server.rs
index 77577683c..8bbab339a 100644
--- a/crates/screenpipe-engine/src/server.rs
+++ b/crates/screenpipe-engine/src/server.rs
@@ -1135,6 +1135,10 @@ impl SCServer {
"/internal/telemetry/mcp-value",
axum::routing::post(crate::routes::internal_telemetry::record_mcp_value),
)
+ .route(
+ "/internal/telemetry/mcp-call",
+ axum::routing::post(crate::routes::internal_telemetry::record_mcp_call),
+ )
.route(
"/outputs/targets",
get(crate::routes::structured_outputs::assigned_targets_handler),
diff --git a/crates/screenpipe-engine/tests/router_contract_test.rs b/crates/screenpipe-engine/tests/router_contract_test.rs
index dd4ec3a27..0fd624b8c 100644
--- a/crates/screenpipe-engine/tests/router_contract_test.rs
+++ b/crates/screenpipe-engine/tests/router_contract_test.rs
@@ -63,16 +63,22 @@ async fn full_router_exposes_openapi_and_private_axum_routes() {
// This intentionally plain Axum handler caused v2.5.143's oasgen panic
// when it was accidentally registered inside the OpenAPI route builder.
// A malformed request may be rejected, but the route must still exist.
- let private_route = router
- .oneshot(
- Request::builder()
- .method("POST")
- .uri("/internal/telemetry/mcp-value")
- .body(Body::empty())
- .unwrap(),
- )
- .await
- .expect("request private Axum route");
- assert_ne!(private_route.status(), StatusCode::NOT_FOUND);
- assert_ne!(private_route.status(), StatusCode::METHOD_NOT_ALLOWED);
+ for path in [
+ "/internal/telemetry/mcp-value",
+ "/internal/telemetry/mcp-call",
+ ] {
+ let private_route = router
+ .clone()
+ .oneshot(
+ Request::builder()
+ .method("POST")
+ .uri(path)
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .expect("request private Axum route");
+ assert_ne!(private_route.status(), StatusCode::NOT_FOUND);
+ assert_ne!(private_route.status(), StatusCode::METHOD_NOT_ALLOWED);
+ }
}
diff --git a/docs/COVERAGE.md b/docs/COVERAGE.md
index 13f7528e5..fed885b37 100644
--- a/docs/COVERAGE.md
+++ b/docs/COVERAGE.md
@@ -37,16 +37,16 @@ results and `cargo llvm-cov` data on top when judging release confidence.
### Core Engine
- Mapped suites: 36
-- Mapped Rust files: 388
-- Active test blocks: 3827
+- Mapped Rust files: 389
+- Active test blocks: 3829
- Ignored/manual test blocks: 177
-- Weighted coverage points: 3162.7
+- Weighted coverage points: 3164.1
| Platform | Suites | Active tests | Ignored tests | Weighted points | Layers | Flows | Critical score |
| --- | --- | --- | --- | --- | --- | --- | --- |
-| windows | 32 | 3681 | 163 | 3096.4 | 21 | 11 | 100% |
-| macos | 31 | 3707 | 138 | 3084.9 | 22 | 11 | 100% |
-| linux | 28 | 3264 | 138 | 2719.8 | 20 | 11 | 100% |
+| windows | 32 | 3683 | 163 | 3097.8 | 21 | 11 | 100% |
+| macos | 31 | 3709 | 138 | 3086.3 | 22 | 11 | 100% |
+| linux | 28 | 3266 | 138 | 2721.2 | 20 | 11 | 100% |
## Refresh
diff --git a/docs/coverage/CORE.md b/docs/coverage/CORE.md
index 990d764f0..ac960a203 100644
--- a/docs/coverage/CORE.md
+++ b/docs/coverage/CORE.md
@@ -8,11 +8,11 @@ confidence, and criticality.
- Manifest: `docs/coverage/core-engine-map.json`
- Tracked crates: screenpipe-engine, screenpipe-db, screenpipe-sqlite-coordinator, screenpipe-audio, screenpipe-screen, screenpipe-a11y, screenpipe-fs
- Mapped suites: 36
-- Mapped Rust files: 388
-- Active test blocks: 3827
+- Mapped Rust files: 389
+- Active test blocks: 3829
- Ignored/manual test blocks: 177
-- Declared test blocks: 4004
-- Weighted coverage points: 3162.7
+- Declared test blocks: 4006
+- Weighted coverage points: 3164.1
Confidence weights: strong=1.0, partial=0.7, conditional=0.4, smoke=0.3.
Criticality weights: high=1.0, medium=0.7, low=0.4.
@@ -23,15 +23,15 @@ are explicitly enabled in a runtime lane.
| Platform | Suites | Active tests | Ignored tests | Weighted points | Layers | Flows | Critical score |
| --- | --- | --- | --- | --- | --- | --- | --- |
-| windows | 32 | 3681 | 163 | 3096.4 | 21 | 11 | 100% |
-| macos | 31 | 3707 | 138 | 3084.9 | 22 | 11 | 100% |
-| linux | 28 | 3264 | 138 | 2719.8 | 20 | 11 | 100% |
+| windows | 32 | 3683 | 163 | 3097.8 | 21 | 11 | 100% |
+| macos | 31 | 3709 | 138 | 3086.3 | 22 | 11 | 100% |
+| linux | 28 | 3266 | 138 | 2721.2 | 20 | 11 | 100% |
## Crate Summary
| Crate | Suites | Integration files | Source unit files | Active tests | Ignored tests | Weighted points | Flows |
| --- | --- | --- | --- | --- | --- | --- | --- |
-| screenpipe-engine | 12 | 21 | 127 | 1834 | 52 | 1412.7 | 10 |
+| screenpipe-engine | 12 | 21 | 128 | 1836 | 52 | 1414.1 | 10 |
| screenpipe-db | 5 | 67 | 27 | 617 | 29 | 588.6 | 9 |
| screenpipe-sqlite-coordinator | 1 | 0 | 3 | 27 | 0 | 27.0 | 2 |
| screenpipe-audio | 7 | 28 | 53 | 686 | 53 | 601.3 | 5 |
@@ -70,19 +70,19 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| db-search | 2 suites / 118 active / 9 ignored / 118.0 pts | 2 suites / 118 active / 9 ignored / 118.0 pts | 2 suites / 118 active / 9 ignored / 118.0 pts |
| engine-lifecycle | 6 suites / 265 active / 1 ignored / 238.5 pts | 6 suites / 265 active / 1 ignored / 238.5 pts | 6 suites / 261 active / 9 ignored / 237.6 pts |
| local-api | 3 suites / 478 active / 11 ignored / 338.2 pts | 3 suites / 478 active / 11 ignored / 338.2 pts | 3 suites / 478 active / 11 ignored / 338.2 pts |
-| meeting | 6 suites / 1734 active / 31 ignored / 1419.3 pts | 6 suites / 1734 active / 31 ignored / 1419.3 pts | 4 suites / 1385 active / 27 ignored / 1094.0 pts |
+| meeting | 6 suites / 1736 active / 31 ignored / 1420.7 pts | 6 suites / 1736 active / 31 ignored / 1420.7 pts | 4 suites / 1387 active / 27 ignored / 1095.4 pts |
| ocr | 4 suites / 140 active / 7 ignored / 129.8 pts | 4 suites / 133 active / 7 ignored / 127.6 pts | 3 suites / 124 active / 6 ignored / 118.6 pts |
| os-integration | 1 suites / 6 active / 0 ignored / 1.7 pts | 1 suites / 6 active / 0 ignored / 1.7 pts | - |
| performance | 13 suites / 1661 active / 80 ignored / 1469.6 pts | 14 suites / 1769 active / 84 ignored / 1512.8 pts | 13 suites / 1661 active / 80 ignored / 1469.6 pts |
-| pipes | 1 suites / 540 active / 3 ignored / 378.0 pts | 1 suites / 540 active / 3 ignored / 378.0 pts | 1 suites / 540 active / 3 ignored / 378.0 pts |
-| privacy | 5 suites / 1002 active / 42 ignored / 809.1 pts | 5 suites / 1041 active / 17 ignored / 804.0 pts | 5 suites / 960 active / 14 ignored / 774.0 pts |
+| pipes | 1 suites / 542 active / 3 ignored / 379.4 pts | 1 suites / 542 active / 3 ignored / 379.4 pts | 1 suites / 542 active / 3 ignored / 379.4 pts |
+| privacy | 5 suites / 1004 active / 42 ignored / 810.5 pts | 5 suites / 1043 active / 17 ignored / 805.4 pts | 5 suites / 962 active / 14 ignored / 775.4 pts |
| real-app | - | 1 suites / 108 active / 4 ignored / 43.2 pts | - |
| speaker | 2 suites / 415 active / 18 ignored / 415.0 pts | 2 suites / 415 active / 18 ignored / 415.0 pts | 2 suites / 415 active / 18 ignored / 415.0 pts |
| storage | 4 suites / 682 active / 39 ignored / 567.7 pts | 4 suites / 682 active / 39 ignored / 567.7 pts | 4 suites / 682 active / 39 ignored / 567.7 pts |
-| sync | 1 suites / 540 active / 3 ignored / 378.0 pts | 1 suites / 540 active / 3 ignored / 378.0 pts | 1 suites / 540 active / 3 ignored / 378.0 pts |
+| sync | 1 suites / 542 active / 3 ignored / 379.4 pts | 1 suites / 542 active / 3 ignored / 379.4 pts | 1 suites / 542 active / 3 ignored / 379.4 pts |
| timeline | 4 suites / 1230 active / 45 ignored / 1009.2 pts | 4 suites / 1230 active / 45 ignored / 1009.2 pts | 4 suites / 1230 active / 45 ignored / 1009.2 pts |
| transcription | 6 suites / 882 active / 52 ignored / 691.9 pts | 5 suites / 876 active / 52 ignored / 687.8 pts | 5 suites / 876 active / 52 ignored / 687.8 pts |
-| ui-events | 4 suites / 817 active / 34 ignored / 620.0 pts | 3 suites / 748 active / 5 ignored / 571.7 pts | 3 suites / 748 active / 5 ignored / 571.7 pts |
+| ui-events | 4 suites / 819 active / 34 ignored / 621.4 pts | 3 suites / 750 active / 5 ignored / 573.1 pts | 3 suites / 750 active / 5 ignored / 573.1 pts |
| vision-capture | 6 suites / 576 active / 32 ignored / 453.6 pts | 6 suites / 569 active / 32 ignored / 451.4 pts | 5 suites / 560 active / 31 ignored / 442.4 pts |
## Critical Flow Matrix
@@ -142,7 +142,7 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| engine-focus-os | screenpipe-engine | windows, macos | engine-lifecycle, os-integration | engine-health-lifecycle, performance-liveness | medium | conditional | unit | 3 | 6 | 0 | Platform focus-tracker parsing/helpers. These files are cfg-gated and only execute on their target OS. |
| engine-linux-keep-awake | screenpipe-engine | linux | engine-lifecycle | engine-health-lifecycle | high | conditional | mixed | 1 | 2 | 8 | Existing isolated-process missing/stalled bus regressions plus ignored live logind inhibitor tests. Live tests require logind and explicit execution. |
| engine-local-api-search-integration | screenpipe-engine | windows, macos, linux | local-api, db-search | local-api-search | high | strong | integration | 1 | 12 | 5 | Active /search route test builds an audio-disabled router, seeds captured-screen-shaped OCR data into an in-memory DB, and asserts the HTTP response and pagination. |
-| engine-meeting-privacy-sync | screenpipe-engine | windows, macos, linux | meeting, privacy, ui-events, pipes, sync | meeting-live-notes, privacy-and-redaction, accessibility-ui-events, performance-liveness | medium | strong | unit | 32 | 540 | 3 | Unit-heavy coverage for privacy filter policy, capture exclusions, UI recorder safety, pipes/live-view/structured-output helpers, sync helpers, and CLI parsing. Meeting detection moved to the engine-meeting-watcher suite. |
+| engine-meeting-privacy-sync | screenpipe-engine | windows, macos, linux | meeting, privacy, ui-events, pipes, sync | meeting-live-notes, privacy-and-redaction, accessibility-ui-events, performance-liveness | medium | strong | unit | 33 | 542 | 3 | Unit-heavy coverage for privacy filter policy, capture exclusions, UI recorder safety, pipes/live-view/structured-output helpers, sync helpers, and CLI parsing. Meeting detection moved to the engine-meeting-watcher suite. |
| engine-meeting-watcher | screenpipe-engine | windows, macos | meeting | meeting-live-notes | high | strong | mixed | 10 | 270 | 3 | Successor of src/meeting_detector.rs and src/meeting_telemetry.rs. Audio-process and UI-scan backend state machines, candidate resolution, shared telemetry, and a scored trajectory eval. ui_scan/macos.rs and ui_scan/windows.rs are cfg-gated and only execute on their target OS; both backends are null on Linux. |
| engine-retention-storage | screenpipe-engine | windows, macos, linux | storage, engine-lifecycle, performance | engine-health-lifecycle, performance-liveness | medium | strong | mixed | 5 | 39 | 0 | Local retention deletion (including lean-mode heavy-text stripping), cloud archive watermarking, atomic state-file replacement, and the low-disk capture monitor. |
| engine-telemetry-observability | screenpipe-engine | windows, macos, linux | engine-lifecycle, performance | engine-health-lifecycle, performance-liveness | medium | strong | unit | 6 | 35 | 0 | PostHog capture gating, telemetry context shaping, piggyback telemetry forwarding, crash-log helpers, resource monitoring, and the recording-coverage reliability metric. |
@@ -414,6 +414,7 @@ bun run coverage:core -- --llvm-cov-summary ../../docs/coverage/core-llvm-cov-su
| engine-meeting-privacy-sync | screenpipe-engine | src/live_views.rs | source | 17 | 0 | 17 |
| engine-api-routes | screenpipe-engine | src/local_chat.rs | source | 5 | 0 | 5 |
| engine-config-lifecycle | screenpipe-engine | src/logging.rs | source | 18 | 0 | 18 |
+| engine-meeting-privacy-sync | screenpipe-engine | src/mcp_call.rs | source | 2 | 0 | 2 |
| engine-meeting-privacy-sync | screenpipe-engine | src/mcp_servers_api.rs | source | 19 | 0 | 19 |
| engine-meeting-privacy-sync | screenpipe-engine | src/meeting_export.rs | source | 7 | 1 | 8 |
| engine-api-routes | screenpipe-engine | src/meeting_summary/extract.rs | source | 7 | 0 | 7 |
diff --git a/docs/coverage/core-engine-map.json b/docs/coverage/core-engine-map.json
index 76f9917bd..26e5fbe09 100644
--- a/docs/coverage/core-engine-map.json
+++ b/docs/coverage/core-engine-map.json
@@ -475,6 +475,7 @@
"src/drm_detector.rs",
"src/external_memory_sync.rs",
"src/live_views.rs",
+ "src/mcp_call.rs",
"src/mcp_servers_api.rs",
"src/meeting_export.rs",
"src/pipe_store.rs",
diff --git a/packages/screenpipe-mcp/README.md b/packages/screenpipe-mcp/README.md
index 210188f42..8e46a6b14 100644
--- a/packages/screenpipe-mcp/README.md
+++ b/packages/screenpipe-mcp/README.md
@@ -55,6 +55,55 @@ client names. HTTP MCP now reports successful searches through the same
best-effort local telemetry endpoint as stdio MCP; empty/failed searches do not
produce qualified-value events.
+## Call diagnostics and source references
+
+New engine builds accept `POST /internal/telemetry/mcp-call` through the same
+local API authentication and analytics consent boundary as other private MCP
+telemetry. `mcp_tool_call_completed` records one best-effort observation per
+completed dispatcher call: schema version, random request ID, package version,
+fixed client/tool/transport names, `ok`/`empty`/`error`, normalized error category,
+duration, content bytes, optional search count/truncation and known report loss.
+No arguments, result text, error strings or raw client names are included.
+The existing `qualified_value_event` definition is unchanged.
+
+`ok` means the dispatcher returned without a protocol/tool error. It does not
+mean the answer was correct or the user completed their task. Search alone sets
+`result_count` and `truncated`; absent fields on other tools remain unknown.
+`response_bytes` counts UTF-8 text and base64 content bytes, not total serialized
+JSON or model tokens. Duration includes tool execution, excluding report delivery.
+
+The request ID is returned in `_meta["screenpipe/request_id"]` and forwarded to
+the local API as `x-screenpipe-request-id`. It is one call's correlation key, not
+a user, session or task ID. This change does not add engine log persistence for
+that header. Local helpers report to the engine, which applies its telemetry
+opt-out. `SCREENPIPE_DISABLE_TELEMETRY` and `SCREENPIPE_TELEMETRY_DISABLED` also
+suppress call reporting; CI suppresses it by default. Delivery is capped at eight
+pending requests per reporter and expires after one second. Old engines, opt-out,
+backend outages and process exit can lose reports. `dropped_reports` reports
+known local losses on a later delivery, not complete observation coverage.
+
+Screen/audio/input search results preserve backend source identifiers and deep
+links. Both package transports cap text at 1,000 characters per hit by default;
+`max_content_length=0` requests full text for a scoped read. The cap excludes
+metadata, tags and images, so callers should also limit result count. Final pages
+do not suggest another offset. In stdio, pass a returned `frame_id` to
+`frame-context` or `get-frame-elements` to inspect evidence beyond the snippet.
+HTTP clients can open the returned Screenpipe link or make a narrower search.
+A missing source ID stays missing.
+
+| Package capability | stdio | HTTP |
+|---|---|---|
+| Search with source references and text caps | `search-content` | `search_content` |
+| Bundled guides | `screenpipe-skills` | `screenpipe-skills` |
+| Frame inspection and saved workflows | Available | Not exposed |
+| Enterprise team tools | With team configuration | Not exposed |
+| Call diagnostics | Best effort | Best effort, per session |
+
+This describes this package, not the separate hosted personal or enterprise MCP
+services. A hung backend read no longer keeps a stdio helper alive after stdin
+EOF: shutdown is bounded to 500 ms and affects only that client's process.
+This does not diagnose desktop recording health or reap another client's process.
+
## Installable plugins
Build the local Claude Desktop extension and the cloud plugin from source:
@@ -490,7 +539,8 @@ Questions or concerns: open an issue at
`list-workflows` searches the desktop Workflows catalog; `get-workflow` returns
ordered steps, gaps and historical accessibility evidence through the same
-authenticated API. Both tools are available in stdio and HTTP modes. The running
+authenticated API. Both tools are available in stdio mode. The package HTTP mode exposes
+`search_content` and `screenpipe-skills`; it does not expose workflow tools. The running
desktop engine must support `/workflows`; an older engine returns an error.
Connected clients can use this context to plan automation, but retrieval neither
authorizes nor executes actions. Captured bounds/IDs must be resolved again in
diff --git a/packages/screenpipe-mcp/src/call-observation.test.ts b/packages/screenpipe-mcp/src/call-observation.test.ts
new file mode 100644
index 000000000..067334166
--- /dev/null
+++ b/packages/screenpipe-mcp/src/call-observation.test.ts
@@ -0,0 +1,49 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+import { afterEach, expect, it, vi } from "vitest";
+import { createCallObserver, currentMcpRequestId, observeSearchResult, observeMcpError, type CallObservation } from "./call-observation";
+const tick = () => new Promise(resolve => setImmediate(resolve));
+afterEach(() => vi.useRealTimers());
+function fixture(send?: (p: CallObservation, s: AbortSignal) => Promise<unknown>, enabled = true) {
+ const sent: CallObservation[] = [];
+ const observe = createCallObserver({ tools: ["search-content"], transport: "stdio", client: () => "codex", enabled: () => enabled,
+ send: send || (async p => { sent.push(p); }) });
+ return { sent, observe };
+}
+it("isolates concurrent calls and keeps raw content out of diagnostics", async () => {
+ const { sent, observe } = fixture();
+ const results = await Promise.all([0, 2].map(count => observe("search-content", async () => {
+ const id = currentMcpRequestId(); await tick(); expect(currentMcpRequestId()).toBe(id);
+ observeSearchResult(count, count > 0); return {content:[{type:"text",text:"private query and answer"}]};
+ })));
+ await tick();
+ expect(new Set(sent.map(p => p.request_id)).size).toBe(2);
+ expect(sent.map(p => p.status)).toEqual(["empty", "ok"]);
+ expect(results.map(r => r._meta?.["screenpipe/request_id"])).toEqual(sent.map(p => p.request_id));
+ expect(JSON.stringify(sent)).not.toContain("private"); expect(currentMcpRequestId()).toBeUndefined();
+});
+it("records returned and thrown errors without their text or unknown tool names", async () => {
+ const { sent, observe } = fixture();
+ await observe("private-tool-name", async () => { observeMcpError({status:401}); return {isError:true,content:[]}; });
+ await expect(observe("search-content", async () => { throw Object.assign(new Error("private"), {status:503}); })).rejects.toThrow("private");
+ await tick();
+ expect(sent.map(p => [p.tool, p.status, p.error_kind])).toEqual([["unknown","error","auth"],["search-content","error","backend"]]);
+ expect(sent[0].result_count).toBeUndefined(); expect(JSON.stringify(sent)).not.toContain("private");
+});
+it("does no reporting when disabled and retains the tool result if reporting throws", async () => {
+ const send = vi.fn().mockRejectedValue(new Error("offline"));
+ await fixture(send, false).observe("search-content", async () => ({content:[]}));
+ expect(send).not.toHaveBeenCalled();
+ const result = await fixture(send).observe("search-content", async () => ({content:[{text:"answer"}]}));
+ await tick(); expect(result.content[0].text).toBe("answer");
+});
+it("bounds outstanding reports, expires hung adapters, and reports the loss later", async () => {
+ vi.useFakeTimers(); const sent: CallObservation[] = [];
+ let hang = true;
+ const {observe} = fixture(async p => {sent.push(p); if(hang) await new Promise(() => {});});
+ for(let i=0;i<12;i++) await observe("search-content",async()=>({content:[]}));
+ expect(sent).toHaveLength(8);
+ await vi.advanceTimersByTimeAsync(1001); hang = false;
+ await observe("search-content",async()=>({content:[]})); await vi.advanceTimersByTimeAsync(1);
+ expect(sent).toHaveLength(9); expect(sent[8].dropped_reports).toBe(12);
+});
diff --git a/packages/screenpipe-mcp/src/call-observation.ts b/packages/screenpipe-mcp/src/call-observation.ts
new file mode 100644
index 000000000..16f5737e5
--- /dev/null
+++ b/packages/screenpipe-mcp/src/call-observation.ts
@@ -0,0 +1,109 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { PKG_VERSION } from "./version";
+import { safeMcpClient, type McpClient } from "./qualified-value";
+
+export type ErrorKind = "none" | "auth" | "invalid_request" | "not_found" | "rate_limited" | "backend" | "unavailable" | "cancelled" | "unknown";
+type Observation = {
+ request_id: string;
+ error_kind: ErrorKind;
+ result_count?: number;
+ truncated?: boolean;
+};
+const context = new AsyncLocalStorage<Observation>();
+export const currentMcpRequestId = () => context.getStore()?.request_id;
+
+export function observeSearchResult(count: number, truncated: boolean): void {
+ const state = context.getStore();
+ if (state) { state.result_count = Math.max(0, Math.floor(count)); state.truncated = truncated; }
+}
+
+export function observeMcpError(error: unknown): void {
+ const state = context.getStore();
+ if (!state) return;
+ const e = error as { status?: number; name?: string } | null;
+ state.error_kind = e?.name === "AbortError" ? "cancelled"
+ : e?.name === "BackendDownError" ? "unavailable"
+ : e?.status === 401 || e?.status === 403 ? "auth"
+ : e?.status === 400 || e?.status === 422 ? "invalid_request"
+ : e?.status === 404 ? "not_found"
+ : e?.status === 429 ? "rate_limited"
+ : e?.status && e.status >= 500 ? "backend" : "unknown";
+}
+
+export type CallObservation = {
+ schema_version: 1;
+ request_id: string;
+ mcp_version: string;
+ client: McpClient;
+ transport: "stdio" | "http";
+ tool: string;
+ status: "ok" | "empty" | "error";
+ error_kind: ErrorKind;
+ duration_ms: number;
+ response_bytes: number;
+ result_count?: number;
+ truncated?: boolean;
+ dropped_reports: number;
+};
+
+const disabled = () => ["SCREENPIPE_DISABLE_TELEMETRY", "SCREENPIPE_TELEMETRY_DISABLED", "CI", "GITHUB_ACTIONS"]
+ .some(key => /^(1|true|yes|on)$/i.test(process.env[key] || ""));
+
+/** A bounded best-effort reporter. It never records arguments, results or errors. */
+export function createCallObserver(options: {
+ tools: readonly string[];
+ transport: "stdio" | "http";
+ client: () => McpClient;
+ send: (payload: CallObservation, signal: AbortSignal) => Promise<unknown>;
+ enabled?: () => boolean;
+}) {
+ const knownTools = new Set(options.tools);
+ let pending = 0, dropped = 0;
+ function report(payload: Omit<CallObservation, "dropped_reports">) {
+ if (!(options.enabled?.() ?? !disabled())) return;
+ if (pending >= 8) { dropped++; return; }
+ pending++;
+ const previousDrops = dropped;
+ dropped = 0;
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), 1000);
+ timer.unref();
+ // Resolve on timeout even if an adapter ignores its signal.
+ const timeout = new Promise<never>((_, reject) => controller.signal.addEventListener("abort", () => reject(new Error("telemetry timeout")), { once: true }));
+ void Promise.race([Promise.resolve().then(() => options.send({ ...payload, dropped_reports: previousDrops }, controller.signal)), timeout])
+ .catch(() => { dropped += previousDrops + 1; })
+ .finally(() => { clearTimeout(timer); pending--; });
+ }
+ return async function observe<T extends { content?: unknown; isError?: boolean; _meta?: Record<string, unknown> }>(name: string, run: () => Promise<T>): Promise<T & { _meta: Record<string, unknown> }> {
+ const state: Observation = { request_id: randomUUID(), error_kind: "none" };
+ const start = performance.now();
+ return context.run(state, async () => {
+ let result: T | undefined;
+ try {
+ result = await run();
+ return { ...result, _meta: { ...result._meta, "screenpipe/request_id": state.request_id } };
+ } catch (error) {
+ observeMcpError(error);
+ throw error;
+ } finally {
+ const failed = !result || result.isError === true;
+ // Count content size without serializing or retaining a second copy.
+ const bytes = Array.isArray(result?.content) ? result.content.reduce((sum, item) =>
+ sum + (typeof item?.text === "string" ? Buffer.byteLength(item.text) : typeof item?.data === "string" ? Buffer.byteLength(item.data) : 0), 0) : 0;
+ try { report({ schema_version: 1, request_id: state.request_id, mcp_version: PKG_VERSION,
+ client: safeMcpClient(options.client()), transport: options.transport,
+ tool: knownTools.has(name) ? name : "unknown",
+ status: failed ? "error" : state.result_count === 0 ? "empty" : "ok",
+ error_kind: failed ? state.error_kind === "none" ? "unknown" : state.error_kind : "none",
+ duration_ms: Math.max(0, Math.round(performance.now() - start)), response_bytes: bytes,
+ ...(state.result_count === undefined ? {} : { result_count: state.result_count }),
+ ...(state.truncated === undefined ? {} : { truncated: state.truncated }),
+ }); } catch { /* Diagnostics must never change the tool result. */ }
+ }
+ });
+ };
+}
diff --git a/packages/screenpipe-mcp/src/http-server.ts b/packages/screenpipe-mcp/src/http-server.ts
index c8c529b14..cb72151a6 100644
--- a/packages/screenpipe-mcp/src/http-server.ts
+++ b/packages/screenpipe-mcp/src/http-server.ts
@@ -30,6 +30,8 @@ import {
flushMcpTelemetry,
initMcpTelemetry,
} from "./telemetry";
+import { createCallObserver, currentMcpRequestId, observeSearchResult } from "./call-observation";
+import { formatSearchHit, searchContentCap, searchResultHeader } from "./search-result";
import { PKG_VERSION } from "./version";
import { BUNDLED_SKILLS_TOOL, readBundledSkills } from "./bundled-skills";
import { normalizeTimeFields } from "./time-normalization";
@@ -172,6 +174,7 @@ const TOOLS = [
default: "all",
},
limit: { type: "integer", description: "Max results. Default: 10" },
+ max_content_length: { type: "integer", minimum: 0, description: "Text characters per result; default 1000. Use 0 only for an explicitly scoped full-text read." },
offset: { type: "integer", description: "Skip N results for pagination. Default: 0" },
start_time: {
type: "string",
@@ -211,6 +214,7 @@ function makeFetchAPI(screenpipePort: number, client: () => McpClient) {
headers: {
"Content-Type": "application/json",
...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+ ...(currentMcpRequestId() ? { "x-screenpipe-request-id": currentMcpRequestId()! } : {}),
"x-screenpipe-client": "mcp",
"x-screenpipe-agent": client(),
...options.headers,
@@ -234,12 +238,13 @@ async function handleSearchContent(
if (!response.ok) {
const body = await response.json().catch(() => ({}));
const detail = typeof body?.error === "string" ? `: ${body.error.slice(0, 500)}` : "";
- throw new Error(`HTTP error: ${response.status}${detail}`);
+ throw Object.assign(new Error(`HTTP error: ${response.status}${detail}`), { status: response.status });
}
const data = await response.json();
const results = data.data || [];
const pagination = data.pagination || {};
+ observeSearchResult(results.length, false);
if (results.length === 0) {
return {
@@ -252,44 +257,12 @@ async function handleSearchContent(
};
}
- const formattedResults: string[] = [];
- for (const result of results) {
- const content = result.content;
- if (!content) continue;
- if (result.starred) formattedResults.push("[Starred moment]");
-
- if (result.type === "OCR") {
- formattedResults.push(
- `[OCR] ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
- `${content.timestamp || ""}\n` +
- `${content.text || ""}`
- );
- } else if (result.type === "Audio") {
- formattedResults.push(
- `[Audio] ${content.device_name || "?"}\n` +
- `${content.timestamp || ""}\n` +
- `${content.transcription || ""}`
- );
- } else if (result.type === "UI" || result.type === "Accessibility") {
- formattedResults.push(
- `[Accessibility] ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
- `${content.timestamp || ""}\n` +
- `${content.text || ""}`
- );
- } else if (result.type === "Parsed") {
- formattedResults.push(
- `[Parsed] ${content.app_name || "?"} | ${content.window_name || "?"} | frame ${content.frame_id || "?"}\n` +
- `${content.timestamp || ""}\n` +
- `${content.text || ""}`
- );
- }
- }
-
- const header =
- `Results: ${results.length}/${pagination.total || "?"}` +
- (pagination.total > results.length
- ? ` (use offset=${(pagination.offset || 0) + results.length} for more)`
- : "");
+ const cap = searchContentCap(args.max_content_length);
+ const hits = results.map((result: unknown) => formatSearchHit(result, cap))
+ .filter((hit: ReturnType<typeof formatSearchHit>) => hit !== null);
+ observeSearchResult(results.length, hits.some((hit: NonNullable<ReturnType<typeof formatSearchHit>>) => hit.truncated));
+ const formattedResults = hits.map((hit: NonNullable<ReturnType<typeof formatSearchHit>>) => hit.text);
+ const header = searchResultHeader(results.length, pagination);
if (formattedResults.length > 0) qualifiedValue.searchResult();
@@ -327,13 +300,20 @@ function createMcpServer(screenpipePort: number): Server {
s.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...TOOLS, BUNDLED_SKILLS_TOOL] }));
- s.setRequestHandler(CallToolRequestSchema, async (request) => {
+ const observeCall = createCallObserver({
+ tools: [...TOOLS.map(tool => tool.name), BUNDLED_SKILLS_TOOL.name], transport: "http", client,
+ send: async (payload, signal) => {
+ const response = await fetchAPI("/internal/telemetry/mcp-call", { method: "POST", body: JSON.stringify(payload), signal });
+ if (!response.ok) throw new Error("Telemetry unavailable");
+ },
+ });
+ s.setRequestHandler(CallToolRequestSchema, async (request) => observeCall(request.params.name, async () => {
const { name, arguments: args } = request.params;
if (name === BUNDLED_SKILLS_TOOL.name) return readBundledSkills(args);
- if (!args) throw new Error("Missing arguments");
+ if (!args) throw Object.assign(new Error("Missing arguments"), { status: 400 });
if (name === "search_content") return handleSearchContent(fetchAPI, args, qualifiedValue);
- throw new Error(`Unknown tool: ${name}`);
- });
+ throw Object.assign(new Error(`Unknown tool: ${name}`), { status: 400 });
+ }));
return s;
}
diff --git a/packages/screenpipe-mcp/src/index.ts b/packages/screenpipe-mcp/src/index.ts
index 9527e6510..0f5fc61c5 100644
--- a/packages/screenpipe-mcp/src/index.ts
+++ b/packages/screenpipe-mcp/src/index.ts
@@ -32,7 +32,7 @@ import {
} from "./qualified-value";
import { discoverTeamConfig } from "./team-config";
import { teamFrameContent, teamFramePath } from "./team-frame";
-import { WORKFLOW_TOOLS, readWorkflowTool, frameAutomationContent, inputEventContent } from "./workflow-tools";
+import { WORKFLOW_TOOLS, readWorkflowTool, frameAutomationContent } from "./workflow-tools";
import { PKG_VERSION } from "./version";
import { BUNDLED_SKILLS_TOOL, readBundledSkills } from "./bundled-skills";
import { formatForElementPurpose } from "./element-format";
@@ -42,6 +42,8 @@ import {
normalizeTime,
normalizeTimeFields,
} from "./time-normalization";
+import { createCallObserver, currentMcpRequestId, observeMcpError, observeSearchResult } from "./call-observation";
+import { formatSearchHit, searchContentCap, searchResultHeader } from "./search-result";
import { resolveScreenpipeApiBase } from "./api-base";
initMcpTelemetry({ transport: "stdio" });
@@ -1324,6 +1326,7 @@ async function fetchAPI(
headers: {
"Content-Type": "application/json",
...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+ ...(currentMcpRequestId() ? { "x-screenpipe-request-id": currentMcpRequestId()! } : {}),
"x-screenpipe-client": "mcp",
"x-screenpipe-agent": currentMcpClient(),
...options.headers,
@@ -1405,13 +1408,18 @@ function screenTag(textSource: unknown): string {
// ---------------------------------------------------------------------------
// Tool handlers
// ---------------------------------------------------------------------------
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+const observeCall = createCallObserver({
+ tools: [...TOOLS.map(tool => tool.name), ...TEAM_TOOLS.map(tool => tool.name), ...WORKFLOW_TOOLS.map(tool => tool.name), BUNDLED_SKILLS_TOOL.name],
+ transport: "stdio", client: currentMcpClient,
+ send: (payload, signal) => callAPI("/internal/telemetry/mcp-call", { method: "POST", body: JSON.stringify(payload), signal }),
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => observeCall(request.params.name, async () => {
const { name, arguments: args } = request.params;
if (name === BUNDLED_SKILLS_TOOL.name) return readBundledSkills(args);
if (!args) {
- throw new Error("Missing arguments");
+ throw Object.assign(new Error("Missing arguments"), { status: 400 });
}
try {
@@ -1608,12 +1616,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
// Default text cap if the caller didn't pass max_content_length.
// Keeps single calls under Claude Code's per-tool output limit.
const userCap = normalized.max_content_length;
- const effectiveCap =
- typeof userCap === "number"
- ? userCap
- : userCap === undefined
- ? DEFAULT_SEARCH_CONTENT_TRUNCATE
- : Number(userCap);
+ const effectiveCap = searchContentCap(userCap);
const params = new URLSearchParams();
for (const [key, value] of Object.entries(normalized)) {
if (value !== null && value !== undefined) {
@@ -1625,6 +1628,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
const data = await response.json();
const results = data.data || [];
const pagination = data.pagination || {};
+ observeSearchResult(results.length, false);
if (results.length === 0) {
return {
@@ -1646,72 +1650,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
const formattedResults: string[] = [];
const images: Array<{ data: string; context: string }> = [];
+ let truncated = false;
for (const result of results) {
const content = result.content;
if (!content) continue;
- if (result.starred) formattedResults.push("[Starred moment]");
-
- if (result.type === "OCR") {
- const tagsStr = content.tags?.length ? `\nTags: ${content.tags.join(", ")}` : "";
- // result.type is "OCR" by historical naming, but content.text_source
- // tells us if the text actually came from the accessibility tree
- // (primary path) or OCR (fallback). Use it to label honestly.
- const tag = screenTag(content.text_source);
- formattedResults.push(
- `${tag} ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
- `${content.timestamp || ""}\n` +
- `${truncateMiddle(content.text || "", effectiveCap)}` +
- tagsStr
- );
- if (includeFrames && content.frame) {
- images.push({
- data: content.frame,
- context: `${content.app_name} at ${content.timestamp}`,
- });
- }
- } else if (result.type === "Audio") {
- const tagsStr = content.tags?.length ? `\nTags: ${content.tags.join(", ")}` : "";
- formattedResults.push(
- `[Audio] ${content.device_name || "?"}\n` +
- `${content.timestamp || ""}\n` +
- `${truncateMiddle(content.transcription || "", effectiveCap)}` +
- tagsStr
- );
- } else if (result.type === "UI" || result.type === "Accessibility") {
- formattedResults.push(
- `[Accessibility] ${content.app_name || "?"} | ${content.window_name || "?"}\n` +
- `${content.timestamp || ""}\n` +
- `${truncateMiddle(content.text || "", effectiveCap)}`
- );
- } else if (result.type === "Input") {
- formattedResults.push(inputEventContent(content, effectiveCap));
- } else if (result.type === "Memory") {
- const tagsStr = content.tags?.length ? ` [${content.tags.join(", ")}]` : "";
- const importance =
- content.importance != null ? ` (importance: ${content.importance})` : "";
- // frame_id links a memory back to the exact moment — jump there with
- // frame-context / get-frame-elements (frame_id=N).
- const frameRef = content.frame_id != null ? ` frame:${content.frame_id}` : "";
- formattedResults.push(
- `[Memory #${content.id}]${tagsStr}${importance}${frameRef}\n` +
- `${content.created_at || ""}\n` +
- `${truncateMiddle(content.content || "", effectiveCap)}`
- );
- } else if (result.type === "Parsed") {
- formattedResults.push(
- `[Parsed] ${content.app_name || "?"} | ${content.window_name || "?"} | frame ${content.frame_id || "?"}\n` +
- `${content.timestamp || ""}\n` +
- `${truncateMiddle(content.text || "", effectiveCap)}`
- );
+ const hit = formatSearchHit(result, effectiveCap);
+ if (hit) { formattedResults.push(hit.text); truncated ||= hit.truncated; }
+ if (includeFrames && result.type === "OCR" && content.frame) {
+ images.push({ data: content.frame, context: `${content.app_name} at ${content.timestamp}` });
}
}
- const header =
- `Results: ${results.length}/${pagination.total || "?"}` +
- (pagination.total > results.length
- ? ` (use offset=${(pagination.offset || 0) + results.length} for more)`
- : "");
+ observeSearchResult(results.length, truncated);
+ const header = searchResultHeader(results.length, pagination);
// Co-occurring tags (only present when include_related=true + tags set).
// Compact one-liner per namespace so it's cheap to read.
@@ -2441,6 +2393,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
throw new Error(`Unknown tool: ${name}`);
}
} catch (error) {
+ observeMcpError(error);
const errorMessage = error instanceof Error ? error.message : "Unknown error";
if (!(error instanceof BackendDownError) && !(error instanceof BackendHttpError)) {
captureMcpMessage("tool call failed", "error", { phase: "tool_call", tool: name });
@@ -2452,7 +2405,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
content: [{ type: "text", text: `Error executing ${name}: ${errorMessage}` }],
};
}
-});
+}));
// Run the server
async function main() {
@@ -2462,6 +2415,16 @@ async function main() {
console.error(`[screenpipe-mcp] v${PKG_VERSION} phase=connect target=${SCREENPIPE_API}`);
const transport = new StdioServerTransport();
await server.connect(transport);
+ // The SDK does not close its transport on stdin EOF. An outstanding fetch
+ // can otherwise keep an abandoned helper alive indefinitely after its host
+ // exits. This process belongs to this one stdio client only.
+ process.stdin.once("end", () => {
+ const deadline = setTimeout(() => process.exit(0), 500);
+ void server.close()
+ .then(() => flushMcpTelemetry(250))
+ .catch(() => {})
+ .finally(() => { clearTimeout(deadline); process.exit(0); });
+ });
console.error("[screenpipe-mcp] phase=connected transport=stdio");
// Warm the API key in the background so the first tool call doesn't pay the
// discovery latency. Never awaited here — key discovery must not gate attach.
diff --git a/packages/screenpipe-mcp/src/search-result.test.ts b/packages/screenpipe-mcp/src/search-result.test.ts
new file mode 100644
index 000000000..c366eaf54
--- /dev/null
+++ b/packages/screenpipe-mcp/src/search-result.test.ts
@@ -0,0 +1,22 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+import { expect, it } from "vitest";
+import { formatSearchHit, searchContentCap, searchResultHeader } from "./search-result";
+it("preserves real references through truncation, without inventing missing IDs", () => {
+ const hit = formatSearchHit({type:"OCR",content:{frame_id:72,text:"HEAD"+"x".repeat(3000)+"TAIL",text_source:"accessibility"}},10)!;
+ expect(hit.truncated).toBe(true); expect(hit.text).toContain("frame_id=72"); expect(hit.text).toContain("screenpipe://frame/72");
+ expect(hit.text).toContain("HEAD"); expect(hit.text).toContain("TAIL"); expect(hit.text.length).toBeLessThan(250);
+ expect(formatSearchHit({type:"OCR",content:{text:"no source"}},100)!.text).not.toContain("Source:");
+});
+it("keeps audio references and input text, including explicit unlimited reads", () => {
+ expect(formatSearchHit({type:"Audio",content:{chunk_id:31,timestamp:"2026-10-01T00:00:00Z",transcription:"speech"}},100)!.text).toContain("chunk_id=31");
+ const input={type:"Input",content:{frame_id:72,text_content:"long input"}};
+ expect(formatSearchHit(input,3)!.truncated).toBe(true);
+ expect(formatSearchHit(input,0)!.text).toContain("long input"); expect(formatSearchHit(input,0)!.truncated).toBe(false);
+});
+it("only suggests an offset when a next page exists", () => {
+ expect(searchResultHeader(5,{total:10,offset:5})).not.toContain("offset=");
+ expect(searchResultHeader(5,{total:10,offset:0})).toContain("offset=5");
+ expect(searchResultHeader(0,{total:10,offset:0})).not.toContain("offset=");
+ expect(searchContentCap(undefined)).toBe(1000); expect(searchContentCap(-1)).toBe(1000);
+});
diff --git a/packages/screenpipe-mcp/src/search-result.ts b/packages/screenpipe-mcp/src/search-result.ts
new file mode 100644
index 000000000..bfed0aa66
--- /dev/null
+++ b/packages/screenpipe-mcp/src/search-result.ts
@@ -0,0 +1,75 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+
+import { inputEventContent } from "./workflow-tools";
+
+export const DEFAULT_SEARCH_CONTENT_TRUNCATE = 1000;
+
+export function searchContentCap(value: unknown): number {
+ const cap = typeof value === "number" ? value : Number(value);
+ return value !== undefined && Number.isFinite(cap) && cap >= 0
+ ? Math.floor(cap) : DEFAULT_SEARCH_CONTENT_TRUNCATE;
+}
+
+export function truncateSearchText(text: string, cap: number): string {
+ if (cap === 0 || text.length <= cap) return text;
+ const left = Math.floor(cap / 2);
+ return text.slice(0, left) + `…[${text.length - cap} chars truncated; inspect the source or narrow the search]…` + text.slice(text.length - (cap - left));
+}
+
+function numericId(value: unknown): number | undefined {
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+/** Source identifiers come from the backend, never from result position or text. */
+export function formatSearchHit(result: any, cap: number): { text: string; truncated: boolean } | null {
+ const c = result.content;
+ if (!c || typeof c !== "object") return null;
+ const frame = numericId(c.frame_id);
+ const chunk = numericId(c.chunk_id);
+ const frameRef = frame === undefined ? "" : `\nSource: frame_id=${frame}; screenpipe://frame/${frame}`;
+ const tags = Array.isArray(c.tags) && c.tags.length ? `\nTags: ${c.tags.join(", ")}` : "";
+ let label: string, body: string, source = frameRef;
+ switch (result.type) {
+ case "OCR":
+ label = c.text_source === "accessibility" ? "[Screen·a11y]" : c.text_source === "ocr" ? "[Screen·ocr]" : "[Screen]";
+ label += ` ${c.app_name || "?"} | ${c.window_name || "?"}`;
+ body = c.text || "";
+ break;
+ case "UI": case "Accessibility":
+ label = `[Accessibility] ${c.app_name || "?"} | ${c.window_name || "?"}`;
+ body = c.text || "";
+ break;
+ case "Audio":
+ label = `[Audio] ${c.device_name || "?"}`;
+ body = c.transcription || "";
+ source = chunk === undefined ? "" : `\nSource: chunk_id=${chunk}`;
+ if (typeof c.timestamp === "string" && Number.isFinite(Date.parse(c.timestamp))) {
+ source += `${source ? "; " : "\nSource: "}screenpipe://timeline?timestamp=${encodeURIComponent(c.timestamp)}`;
+ }
+ break;
+ case "Parsed":
+ label = `[Parsed] ${c.app_name || "?"} | ${c.window_name || "?"} | frame ${frame ?? "?"}`;
+ body = c.text || "";
+ break;
+ case "Memory":
+ label = `[Memory #${c.id}]${c.importance != null ? ` (importance: ${c.importance})` : ""}`;
+ body = c.content || "";
+ break;
+ case "Input":
+ return { text: `${result.starred ? "[Starred moment]\n" : ""}${inputEventContent(c, cap === 0 ? Number.MAX_SAFE_INTEGER : cap)}${source}`, truncated: cap > 0 && typeof c.text_content === "string" && c.text_content.length > cap };
+ default: return null;
+ }
+ body = String(body);
+ return {
+ text: `${result.starred ? "[Starred moment]\n" : ""}${label}\n${c.timestamp || c.created_at || ""}${source}\n${truncateSearchText(body, cap)}${tags}`,
+ truncated: cap > 0 && body.length > cap,
+ };
+}
+
+export function searchResultHeader(count: number, pagination: any): string {
+ const total = typeof pagination.total === "number" ? pagination.total : undefined;
+ const offset = typeof pagination.offset === "number" ? pagination.offset : 0;
+ return `Results: ${count}/${total ?? "?"}` +
+ (count > 0 && total !== undefined && offset + count < total ? ` (use offset=${offset + count} for more)` : "");
+}
diff --git a/packages/screenpipe-mcp/src/stdio-lifecycle.test.ts b/packages/screenpipe-mcp/src/stdio-lifecycle.test.ts
new file mode 100644
index 000000000..723b2a49d
--- /dev/null
+++ b/packages/screenpipe-mcp/src/stdio-lifecycle.test.ts
@@ -0,0 +1,48 @@
+// screenpipe — AI that knows everything you've seen, said, or heard
+// https://screenpipe.com
+import { it, expect } from "vitest";
+import { spawn, execFileSync, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { createServer } from "node:http";
+import { once } from "node:events";
+import path from "node:path";
+const sleep=(ms:number)=>new Promise(resolve=>setTimeout(resolve,ms));
+async function until(predicate:()=>boolean, timeout=2000) {
+ const end=Date.now()+timeout;
+ while(!predicate() && Date.now()<end) await sleep(10);
+ expect(predicate()).toBe(true);
+}
+it("reaps a helper on EOF during a hung read while another client remains usable",async()=>{
+ const root=path.resolve(__dirname,"..");
+ execFileSync("bun",["run","build"],{cwd:root,stdio:"pipe",timeout:120000});
+ let hanging=false;
+ const api=createServer((req,res)=>{
+ if(req.url?.includes("q=hang")){hanging=true;return;}
+ res.setHeader("Content-Type","application/json");res.end(JSON.stringify({data:[],pagination:{total:0}}));
+ });
+ await new Promise<void>(resolve=>api.listen(0,"127.0.0.1",resolve));
+ const address=api.address();if(!address||typeof address==='string')throw new Error('fixture unavailable');
+ const port=address.port;
+ const children:ChildProcessWithoutNullStreams[]=[];
+ async function start(){
+ const child=spawn(process.execPath,[path.join(root,'dist/cli.js')],{env:{PATH:process.env.PATH||'',SCREENPIPE_LOCAL_API_KEY:'fixture',SCREENPIPE_LOCAL_API_URL:`http://127.0.0.1:${port}`,SCREENPIPE_DISABLE_TELEMETRY:'1'},stdio:'pipe'});
+ children.push(child);let output='';child.stdout.on('data',part=>output+=part);child.stderr.resume();
+ const send=(value:unknown)=>child.stdin.write(JSON.stringify(value)+'\n');
+ send({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1'}}});
+ await until(()=>output.includes('"id":1'));
+ send({jsonrpc:'2.0',method:'notifications/initialized'});
+ return {child,send,output:()=>output};
+ }
+ try{
+ const abandoned=await start(), live=await start();
+ abandoned.send({jsonrpc:'2.0',id:2,method:'tools/call',params:{name:'search-content',arguments:{q:'hang'}}});
+ await until(()=>hanging);abandoned.child.stdin.end();
+ await until(()=>abandoned.child.exitCode!==null);
+ expect(live.child.exitCode).toBeNull();
+ live.send({jsonrpc:'2.0',id:2,method:'tools/call',params:{name:'search-content',arguments:{}}});
+ await until(()=>live.output().includes('No results'));
+ live.child.stdin.end();await until(()=>live.child.exitCode!==null);
+ } finally {
+ for(const child of children)if(child.exitCode===null&&child.signalCode===null){child.kill('SIGKILL');await once(child,'exit');}
+ api.closeAllConnections();await new Promise<void>(resolve=>api.close(()=>resolve()));
+ }
+},15000);