简体中文 · English · Architecture · Operations · MCP contract

Sightglass

Read WeChat where it lives. Bring only the requested context to your reader.

Sightglass is an experimental, read-only WeChat reading service with a native macOS source and a portable core. It gives an authorized MCP client a structured view of conversations, participants, messages and local attachments, with explicit coverage and source receipts. The daemon does not generate summaries. Optional semantic recall uses Cloudflare Workers AI and Vectorize only after explicit operator configuration and external-data authorization; it is disabled by default.

Use it when a reader needs to inspect the original conversation, follow one participant, open a referenced file, or continue from an acknowledged reading position. The WeChat database and its keys remain on your Mac. In local mode, admitted state and processing remain there too. An explicitly configured Linux core receives the approved Sightglass state and bounded captured pages/resources; returned tool content reaches the connected client and is subject to that client's data handling.

Development preview · 0.1.0.dev1. Native access supports the exact WeChat 4.1.13 / build 269602 / arm64 and 4.1.15 / build 270115 / arm64 profiles and requires operator-supplied, verified database keys. Sightglass does not extract those keys. The 4.1.15 profile has no verified sticker-decryption offset; those local stickers report unavailable while ordinary messages remain readable. Try the synthetic example before configuring an account. Publication and licensing status is recorded in Current state and Notices.

Everyday reading

Start with wechat_read_inbox(). Its default mode="recent" lists recent authorized contacts and groups from the observed conversation catalog, including conversations with no cached message bodies. kinds=["direct"] selects direct contacts. Choose an item and follow its read_action to wechat_read_messages(mode="recent"). Continue new replies with mode="updates"; the reader acknowledges a delivered page only after consuming it. Retrying without an ACK returns that exact pending payload.

A new ordinary remote recent or updates read uses the connected Mac edge automatically. It does not require a history job, retained archive or semantic index. Offline reads return only available resident messages with explicit bounded freshness. A missing preview is marked latest_state="not_resident"; it does not mean the contact has no messages. mode="resident" on the inbox selects the cached-message activity view. include_latest="text" adds only available resident previews, with their own time; an older cached preview is labelled older_resident.

Related MCP server: yan

Optional Mac edge and Linux core

The optional remote core is part of the development preview. Installation and production cutover require the VPS migration procedure. It uses the same thirteen tools and schema-v10 state. A thin Mac edge owns native read-only sessions and one 64 MiB ordered spool; the Linux core alone owns window.db, reader ACK, immutable deliveries, CAS, processing and MCP. The edge initiates a fixed SSH stdio connection; there is no public Sightglass listener or arbitrary provider-method RPC.

The edge keeps one bounded private connection snapshot for operator diagnosis, including control-stage failures without chat content, request IDs or source paths. This observed state does not certify a live connection or fresh messages.

Remote capture is limited to its enrolled conversation set. A reader's all_except_denylist policy does not extend that independent source-egress grant; new conversations need operator enrollment before remote discovery/reading.

Native direct messages use same-shard sender identity before status hints. A mapped peer is not relabeled as self because of its message status; other unverified native sender mappings remain unresolved while the message stays readable. Independent native self-username binding, including reliable self-dialog attribution, remains an open limitation; see source identity.

An optional macOS source-access helper provides persistent, read-only access to the single configured account directory. It uses an explicit system picker and authenticated bookmark handoff, reusing the existing Edge credential without sending that credential to the helper. Preparation writes a new shadow config; real directory authorization and restart acceptance are separate operator steps. It is not enabled by default or installed by a normal package upgrade.

When the encrypted Core volume uses a Mac-held key, an explicitly installed Mac recovery task can restore the existing vault after a VPS restart. It first probes the fixed SSH capability, reads the existing Keychain item only while the vault is locked, and leaves an intentionally stopped service alone on a mounted volume. The Mac and noninteractive Keychain access must be available. Setup, maintenance inhibition and manual recovery are documented in the vault recovery procedure.

On macOS, access to another app's protected data container may require the owner to confirm an App Data prompt for each new edge process, including a managed restart. Verify the actual handshake and fresh read after confirmation; see the operating procedure.

Remote configurations default to view="replica": cached messages, search, links, retrieval, resource catalog and cached bytes use admitted state while the Mac is offline. Results report partial resident coverage and bounded freshness; a zero-hit replica result cannot prove source absence. wechat_list_resources lists the owning message's current resident bindings; an expired or released body returns SOURCE_INCOMPLETE, and an inactive historical resolver is never restored. Use view="fresh" on tools that expose it for bounded source verification. New ordinary mode="recent" and mode="updates" requests select fresh source evidence with a connected edge and no explicit view. Recent cursors keep their selected plane; pending updates and committed request retries replay locally before any source work. view="replica" remains explicitly local. Cursor-free non-update reads can use refresh=true to require source evidence even when offline; updates use explicit view="fresh" for new work. Failure after selecting fresh never falls back to cache. New remote recent-inbox and conversation-discovery requests also refresh catalog metadata when connected, using the existing catalog capture rather than collecting message history. Their signed continuations retain the original plane and snapshot; offline, explicit replica and resident inbox reads stay local. A fresh catalog receipt confirms activity metadata; cached body previews remain bounded-stale. Native catalog fact time may stay unchanged across successful confirmations when source files do not change. See the reading contract. Read longer spans through the returned cursor and next_actions; clear refresh on continuation. A signed source cursor retains its fresh view even on hosts that expose refresh without view. Each page is independently validated. Exact supported app upgrades use the stopped, verified same-account edge-rebind procedure; the existing keys, identities and stream state remain in place. wechat_status distinguishes transport from confirmation in view="replica": read_plane.capture_transport reports whether the capture edge is currently connected (transport evidence only, without probing the source); read_plane.live_refresh_available reports whether a fresh request can be started now (connected transport or a confirmed capture, never while paused) while read_plane.live_refresh_confirmed reports whether a current capture actually confirmed source facts, and readiness.live_refresh/resource_acquisition report awaiting_confirmation until a current capture actually confirms source facts, and degraded only when that transport is disconnected or unobserved. An empty mode="resident" inbox means no resident body, not a missing observed catalog: its next_actions point at wechat_find_conversations (enumerating the observed catalog under the caller's account/kind scope) and then an explicit bounded wechat_read_messages fresh read of one chosen conversation_id. The guidance is caller instruction only and never executes or bulk-fills history. Fresh updates reconcile independently of the ACK position, eventually restarting a completed scan to find old-position arrivals/corrections; pages never claim one global change snapshot. Missing source prefixes fail closed. A scoped request_id retains an exact completed update response for 30 days, subject to current policy and pause. Local-source updates use the same bounded verification/reconciliation path: at most 200 message candidates or source-page messages per step, without hydrating the whole conversation. ACK consumes the frozen delivery position even after an interpretation upgrade or an admitted sort correction. Current authorization still applies, and revoking then restoring a scope does not revive its expired deliveries.

Native source support still means the exact macOS profile above. remote-capture is an offline core binding, not a Linux WeChat adapter. Linux processing prerequisites and platform evidence are in Linux processing; ownership, loss recovery and wire limits are in Capture protocol.

What you can read

The thirteen MCP tools are wechat_status, wechat_find_conversations, wechat_read_inbox, wechat_find_participants, wechat_read_messages, wechat_read_transcripts, wechat_search_messages, wechat_find_links, wechat_retrieve, wechat_find_resources, wechat_list_resources, wechat_read_resource, and wechat_search_resource_text. Arguments, schemas and error semantics live in the MCP contract. wechat_find_links/wechat_retrieve are the only tools that return the full observed raw/normalized URL; the ordinary message link projection stays redacted, and no tool ever fetches a URL.

MCP responses default to response_profile="brief" (sightglass.mcp.brief.v1), retaining content, coverage, freshness and continuation while omitting implementation diagnostics. Compact rows still use fields and people. New compact recent pages default to 30 messages, search/link pages to 20 hits, and retrieval to 3 contexts; bounded pages target about 16 KiB for reading/retrieval and 8 KiB for search/links. Follow next_actions for polling, result pagination or further source scanning; each action identifies its own token field. Preparation continuations reuse their original scope and effective limit. Request response_profile="diagnostic" for full receipts or the explicit recovery of truncated message text. Updates retain exact pending-delivery replay and ACK semantics.

A successfully admitted native recent page records its observed window for local rereading; it never advances the background continuous sync frontier over a gap. Known current-epoch messages and their indexed context remain readable without waiting for background tail completion; missing history stays explicit. Local auto and offline/explicit replica pages can lag the source; a new ordinary remote recent read uses the connected edge. Use read_messages(refresh=true) without a cursor to require current source messages, fill a partial context or explicitly reread source content; the same policy and bounded source checks apply. Storage-blocked voice preparation reports not_scheduled while preserving the text page. Materialized reader progress can use bounded maintenance space, but required writes still respect the filesystem free floor.

With a local source, ordinary daemon search first returns preparing with a signed reading_token. Repeat identical arguments with that token (or the existing cursor parameter) to obtain canonically validated results; preparing is never an empty result. The bounded private job survives restart, re-scanning an interrupted conversation under fresh source evidence once an identical token poll supplies the query again. Query text stays in memory. Final result next_cursor keeps normal search pagination. See the search lifecycle.

With a local source, cold find_links/retrieve also return preparing, then usable bounded results, including when cached bodies and indexes were released. Only matches and bounded context are cached. A partial result supplies a separate continuation reading_token to scan older rows; the original token only polls, and page.next_cursor only paginates prepared results. Traversal across multiple read leases never claims one complete current snapshot. See the cold discovery lifecycle.

Remote-core search, links and retrieval currently recall from admitted resident candidates. A fresh check validates those bounded candidates; it does not discover arbitrary never-admitted or released source history through the edge. An explicit selected-conversation history job can admit that history under the current residency and access policy. Empty results never prove source-wide absence.

Retention is an independent operator setting. New configurations and conversations default to on_demand: idle polling opens no message bodies, and foreground search retains matching candidates rather than every scanned source row. keep collects future messages continuously; historical backfill must be explicitly selected with keep --keep-backfill and a bounded job. This also works through the configured remote capture path; single-conversation setup distinguishes retained history from optional semantic indexing and its separate egress consent. recent defaults to 30 days and 512 MiB per conversation. On-demand reads cache bounded pages/context for 24 hours and at most 256 MiB per conversation; the shared temporary-body cap is 1 GiB. These caps cover resident body copies, while the outer storage budget covers the whole installation. Legacy admitted stock remains protected until an exact operator preview/apply releases its disposable copies. Expiry preserves identity, observed traversal state, corrections and exact pending replay; it never refills history automatically. Operator commands and the stopped-only schema-v10 candidate/paired rollback path are in residency operations.

New admissions store ordinary body text once; card search fields retain their independent meaning. Legacy schema-v10 rows remain readable; explicit stopped-only compaction normalizes exact duplicate current fields while preserving frozen recovery, identities and observation episodes. Startup performs no bulk rewrite.

Local link/lexical reconciliation uses eligible resident bodies; releasing a body also removes its local derivatives, and idle/restarted/rebuilding workers cannot recreate empty records from durable history. Derivative sweeps select a bounded resident-position page before testing receipts, commit progress with publication and resume after restart. Completed large warm sweeps recheck hourly, with immediate rebuild/unfinished work; ordinary admissions publish directly. A warm verification pass preserves published-index readiness. This repairs admitted content without collecting more source history. Resource, voice and derived workers wake on new work, retry or lease deadlines, with a 30-second fallback. Settled on-demand metadata uses the same slower cadence; keep/recent collection retains its live-tail cadence. Native catalog handles are reused, with at most 16 idle handles and a 60-second age threshold; active reads and narrow-session handles retain their own lifetime. These are local work bounds, not a measured production memory or latency guarantee.

For an explicitly authorized release of all existing body copies, the stopped-only compact workflow accepts storage compact preview --all-stock: a snapshot-bound plan with streaming membership, while retaining pending deliveries and active job inputs. An already-current schema can move to another verified private volume with storage compact prepare-pair --copy-current, preserving an independent rollback namespace without repeating conversion. Both operations require a stopped daemon.

Try it with synthetic data

With Python 3.11+ (Python 3.12 on Linux with voice), SQLite 3.43+ built with FTS5 trigram and contentless_delete support, and uv installed:

Clone the repository below for the interface and example documented here:

git clone https://github.com/IndelibleVivi/sightglass.git
cd sightglass
uv sync --extra dev
uv run python examples/synthetic_read.py

The example creates a disposable source and read model, lists two recent conversations before any body is cached, discovers a synthetic group and reads three messages. It does not inspect WeChat, access Keychain, start a daemon or alter an installed configuration. The temporary files are removed when it exits.

{
  "source": "generated synthetic fixture",
  "inbox_schema": "sightglass.inbox-page.v2",
  "recent_conversations": 2,
  "contacts_without_cached_bodies": 2,
  "schema": "sightglass.message-page.v1",
  "returned_messages": 3,
  "source_page_complete": true,
  "message_kinds": ["file", "unknown", "text"]
}

source_page_complete describes that source page; it is not a claim that an entire account or history has been indexed.

The separately authorized semantic benchmarks can send generated synthetic text only to Cloudflare Workers AI and store its vectors in a dedicated Vectorize experiment index. They use no configured account or daemon, download no model weights, and do not enable production semantic retrieval. The active benchmark now uses BGE-M3 only; the two-model artifact is retained historical evidence. Running that experiment consumes the operator's Cloudflare services; ordinary installation and CI never run it.

Optional account-backed semantic retrieval has a separate operator setup: one dedicated index, exact conversation scope, explicit external-data consent and a token in the platform secret store. Background indexing and query failures report their coverage; disabling the lane retains local/remote derivatives and does not erase previously uploaded data. Semantic recipe v2 deduplicates identical canonical text/card fields and excludes empty inputs and unknown-message placeholders; those messages remain available through context neighbors. Upgrading a v1 sidecar requires the stopped-only derivative replacement procedure in the operator guide.

Pending semantic publication reads back the exact stored intent first. An absent remote object may be retried after durable backoff using the same vector bytes; a present conflicting object is never overwritten. Canonical version and current consent still gate every publication; deterministic reading remains available.

Semantic complete requires a finished pass proved against the current canonical revision, not just zero pending uploads. Appends, corrections and renewed resident availability invalidate that proof; the bounded worker continues building while preserving remote readback backoff. Source/history coverage, resident availability, index coverage and semantic relevance remain separate claims.

MCP calls yield the stdio event loop while IPC work runs. Caller cancellation and disconnect propagate into the daemon; an in-flight capture still settles through its durable terminal/ACK path. An IPC timeout can leave an unknown outcome: retry the same update request without advancing ACK. See the caller lifecycle. Legacy internal CAS hardlinks have an explicit stopped-only preview and repair; ordinary reads and startup never repair an unproved hardlink.

Connect a local account

The native runtime requires macOS on Apple Silicon, the exact supported WeChat profile, and a complete key map for the selected account. Optional voice recognition additionally needs macOS 26, a Swift toolchain and installed speech assets for the selected language.

brew install poppler sqlcipher
uv sync --extra dev --extra macos-wechat

Follow Operations for initialization, verified key import, policy selection, daemon lifecycle and recovery. Native initialization selects one readable conversation by default. Account-wide access is a separate operator decision, with a denylist enforced on the server. New installations use a neutral Reader profile; existing saved reader identities remain unchanged.

For a production installation, use the isolated wheel promotion and rollback procedure. Keep its environment separate from the editable development checkout; restart the existing bridge/tunnel after promotion.

Once a development daemon is configured and running, launch the stdio bridge from the checkout:

uv run sightglass-mcp

For a client's command configuration, use the absolute path to the installed .venv/bin/sightglass-mcp; do not depend on the client's working directory. Stdout carries MCP only. A remote client needs a separately configured transport; Sightglass itself opens no HTTP listener. External tunnel/host acceptance is installation-specific.

Optional local transcription:

uv sync --extra dev --extra macos-wechat --extra voice
bash scripts/compile-voice-helper.sh

The helper build only compiles a local executable. It does not start a service, enroll keys or download speech assets. Its default destination belongs to the default data directory. For a paired production installation, pass the active configuration's helper path, or <data_dir>/voice/sightglass-transcribe when that setting is empty; a helper in another pair does not make the active pair ready. Missing decoder, helper or language assets produce explicit readiness/blocking states; ordinary reads remain available. See the voice setup procedure.

Architecture

The core owns admitted state; local mode owns source access, while remote mode delegates only finite capture to the Mac edge. Providers return evidence; the reader service decides admission and policy. Message bodies in window.db are source-derived projections and supply the local read plane for admitted message pages and resident inbox previews. Catalog recents remain visible without bodies, while new ordinary remote recent message reads use the connected edge. Materialized responses identify themselves as bounded-stale rather than claiming a new live-source observation. The same database also owns reader ACK/cursor state, correction history and resource/voice bindings; deleting it loses those local states. Local reads, source reads, resource derivation, the single database writer and transcript waits have independent bounded runtime lanes, so slow source or processor work cannot consume local-read capacity. Long PDF derivations use durable jobs introduced in schema v6, with lease/fencing recovery, and return a polling token instead of occupying a synchronous request indefinitely. Slow source reads run outside the database writer transaction. Catalog work uses a full validated snapshot; known conversation/message fallbacks and cold resources use typed dependency-scoped sessions that pin and revalidate only the SQLCipher databases/files they actually read. Cold resource processors run after that source lease closes, and a short transaction rechecks both the resolver revision and any worker fence before binding derived objects. Authorized CAS hits and transcript reads stay local while rechecking the owning conversation's current policy.

See the component/evidence map and editable topology.

Boundaries and limits

• Read-only at the source. No sending, recalling, marking as read, app re-signing, injection or WeChat writes. Sightglass writes its own private projection, cache, delivery and transcript state.

• Explicit local authorization. Reader identity is injected by the daemon, never supplied in tool arguments. Operator mutations use a separate credential.

• Bounded disclosure. Raw database keys, source paths and transport envelopes stay private. Message-bound resource IDs are reauthorized before content is returned.

• Selective residency. keep, recent and on_demand do not grant access. Changing a mode does not release legacy stock. Temporary-body expiry can stale a local cursor; repeat the bounded read or explicitly rebaseline updates. Active resource/voice dependencies and pending replay stay protected. Releasing copies does not immediately shrink SQLite's file; physical compaction is an explicit stopped-only operation, and normal startup refuses older schemas.

• Full observed URLs in discovery. wechat_find_links and wechat_retrieve can return credentials, ports, query strings and fragments present in an observed URL. That content reaches the connected MCP client. Ordinary structured message links stay redacted; neither discovery tool visits the URL.

• No implicit network retrieval. Missing local attachments stay missing. Transcript recognition stays on device; speech-asset installation is a separate operator action. A connected MCP client can receive requested content.

• Storage backpressure, explanation and recovery. The daemon defaults to a 4 GiB soft budget, 6 GiB hard budget, 2 GiB filesystem free floor and an additional 256 MiB maintenance reserve. Soft pressure pauses backfill and new voice work; hard pressure rejects new admission with STORAGE_PRESSURE. Filesystem headroom also reflects other applications and macOS; daemon ready=true and a healthy tunnel do not establish reader admission. Check storage.admission_allowed in sightglassctl status and an actual host read when accepting an installation. Pending deliveries still replay, and validated ACKs can use the reserve. New observation payloads use lossless compression; legacy admitted stock remains protected until exact operator release; temporary body copies follow their explicit expiry/cap lifecycle. The read-only operator command sightglassctl storage explain returns a quick tracked-file/capacity summary and exact 7/30-day growth when those daily baselines exist. Explicit --deep phases inspect exact counts and SQLite physical usage under a 10-second default deadline (25-second maximum), cancel on client disconnect, and retain completed results when interrupted, without exposing content or performing cleanup. Stopped-only storage backup plan|create|retire|restore commands create and verify an adjacent private zstd recovery point, and require the exact current plan acknowledgement before destructive retirement or restore. Restore uses a durable rollback journal and recovers interrupted DB/sidecar swaps before opening the database. Operator cache cleanup also collects acknowledged/expired delivery spools and aged unreferenced spools while protecting pending replay. The daemon stores at most 64 content-free daily snapshots in a private sidecar for growth comparison. These are admission limits, not an OS-enforced quota. See storage operations.

• Partial means partial. Unreadable shards, source changes, incomplete indexes, missing keys and unavailable processors produce explicit coverage or errors. Already admitted current-epoch messages, the native inbox and authorized CAS hits can remain readable with bounded-stale receipts while live refresh is degraded. Bounded absence does not prove deletion or global nonexistence. Validated read windows are distinct from the continuous sync frontier; local contexts preserve gap evidence, legacy completeness is revalidated in bounded work, and an empty filtered page can still carry a signed scan continuation.

• Narrow native compatibility. Other builds, key rotation and new shards require supported-profile/key enrollment work. Automatic key extraction/refresh, arbitrary video transcoding, a desktop UI and WGO runtime adapters are not implemented.

Private directories use 0700, data files 0600, source databases use read-only SQLCipher handles, and macOS credentials live in Keychain. Linux core credentials use an owner-private, no-follow file store; filesystem permissions do not establish disk encryption. The source account and conversation egress ceiling require operator authorization, independently of reader policy and optional semantic consent. Messages and attachments are untrusted data, never instructions. Read the Security boundary before enabling native access.

Verify and explore

uv sync --frozen --extra dev --extra macos-wechat --extra voice
uv run python -m unittest discover -s tests -t . -p 'test_*.py'
uv run python -m compileall -q src tests examples
uv run ruff check src tests examples
uv run pyright
uv build
uv run python scripts/check-installed-wheel.py
git diff --check

Code pushes and PRs run the portable gate. The full macOS gate runs on main pushes, PRs, or manual Synthetic source gates dispatch; a feature-branch push alone does not run macOS. Documentation-only changes skip automatic CI. GitHub requires the workflow on the default branch before enabling manual dispatch; until promotion, use a PR for hosted macOS coverage.

Both CI jobs run the same installed-wheel gate after building. It checks exact source/license payload, installs frozen runtime extras in a fresh noneditable environment, runs the four real entrypoints from an empty cwd, and reads generated messages using installed imports. It does not activate an installation. Use --wheel /path/to/candidate.whl --sdist /path/to/candidate.tar.gz for separate candidate artifacts. --offline uses only cached dependencies; ordinary CI retains its normal dependency access.

The suite uses generated fixtures, including encrypted SQLCipher databases when the native extra is installed. Hosted gates separate portable Linux synthetic daemon/bridge checks from the full macOS fixture suite; native WeChat access remains macOS-only. Full macOS resource coverage also needs sips and Poppler. Real Apple speech testing is opt-in and uses synthesized audio; no real conversations or recordings belong in Git. Current state records the verified source scope and remaining limits.

English and Chinese README editions carry the same support, privacy and rights contract. The detailed accepted specification is in Chinese; stable technical contracts are linked above.

Rights and provenance

Software and functional materials use AGPL-3.0-only; independent explanatory documentation and visual assets use CC BY-NC-SA 4.0. See the exact licensing scope. The software license permits commercial use and paid services, with its source-sharing and notice conditions; the independent-content license has a NonCommercial boundary. NOTICE.md records the WGO behavioral references, the unlicensed agent-wechat revision inspected for media-layout evidence, and the optional SILK dependency boundary. Those upstream and dependency terms remain in force; the repository grants no rights to bundle the unaudited wrapped SILK codec. Licensing does not itself publish this development preview.

Sightglass is an independent project and is not affiliated with or endorsed by Tencent, WeChat, Apple or OpenAI.