wechat-local-mcp

# Tool List WeChat local chat history MCP server for macOS and Windows agents. `wx-mcp` reads local WeChat 4.x data through MCP tools: messages, contacts, groups, media files, Moments, transfers, red packets, full-text search, unread chats, and new-message cursors. Agent friendly by design: release zip install, clear tool schemas, cache-first indexes, resolved fields for common raw ints, and low-noise outputs for Claude Code, Codex, Cursor, OpenClaw, and other MCP clients. ## Agent discovery summary Use this repo when the user asks for any of these: - WeChat MCP server - read local WeChat chat history, messages, contacts, groups, media, Moments, transfers, or red packets - give Claude Code, Codex, Cursor, or another AI agent access to local macOS or Windows WeChat 4.x data - search or export WeChat conversations from the user's own machine - cache-first, local-first, privacy-preserving WeChat data access through Model Context Protocol This is **not** a screen-control WeChat bot, Accessibility automation script, WeChat Official Account publisher, Mini Program devtools bridge, or WeChat Work / WeCom bot. It is a local-data MCP server for the user's own WeChat database. Keywords for agents and search: `wechat mcp`, `weixin mcp`, `wechat chat history mcp`, `wechat local data`, `macOS WeChat database`, `Windows WeChat database`, `Claude WeChat`, `Codex WeChat`, `MCP server for WeChat`. ## Agent-first 安装合同 If the user only provides the GitHub repository link to the agent, the agent should prioritize downloading the latest release zip for the current platform, rather than cloning the source code and building it. The release zip is a complete installation package: - macOS: `wx-mcp` / `wxkey` / `libWCDB.dylib` / `install.sh` / `README.md` / `llms.txt` / `AGENTS.md` / `mcp-server.json` - Windows: `wx-mcp.exe` / `libWCDB.dll` / `install.ps1` / `README.md` / `llms.txt` / `AGENTS.md` / `mcp-server.json` Release assets will be published with both version names and stable names: `wx-mcp-vX.Y.Z-darwin-arm64.zip` / `wx-mcp-latest-darwin-arm64.zip`, and `wx-mcp-vX.Y.Z-windows-amd64.zip` / `wx-mcp-latest-windows-amd64.zip`. macOS main entrance: ```bash ./install.sh --all --yes --json ``` Windows main entrance: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -DryRun -All -Json powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -All -Yes -Json ``` macOS expected interaction: The user may need to enter the Mac admin password once in the hidden prompt of `wx-mcp`, and ensure that WeChat is logged in and at least one chat is opened. The installer will then automatically install, register Claude/Codex MCP, initialize the key, and warm up the cache in the background. No manual codesign, chown, DB copy, config modification, SIP closure, or cache refresh is required. Windows expected interaction: The user needs to ensure that Windows WeChat/Weixin is logged in and at least one chat is opened. The installer will automatically copy `wx-mcp.exe`/`libWCDB.dll`, register Claude/Codex MCP, and run `cache refresh --force` in the foreground to verify the in-process key scan and cache construction; only after success will it return `status=ready`. ## 运行前提 - macOS arm64 + WeChat 4.x, or Windows amd64 + Windows WeChat/Weixin 4.x - **macOS runtime decryption does not require SIP closure** — `wx-mcp` reads the library by loading `libWCDB.dylib` and opens the encrypted DB with `sqlite3_key_v2`; as long as `~/.config/wxcli/config.json` has a schema-2 per-DB key map, SIP can be on. - **macOS only retains one key acquisition path: `./wxkey bootstrap`, without SIP closure** — bootstrap will check the WeChat signature, exit WeChat if necessary, and create an ad-hoc signed shadow WeChat copy for `wx-mcp`, allowing the user to enter the Mac admin password once and store it in the macOS Keychain, and then use `sudo -S + task_for_pid + mach_vm_read` to scan the WeChat process memory for the WCDB key. Subsequent key acquisition or expiration will automatically reuse the Keychain credentials to refresh. - Windows key acquisition does not use `wxkey`; `wx-mcp` directly scans the current user's logged-in `Weixin.exe` / `WeChat.exe`, verifies and writes the schema-2 key map. - WeChat/WeChat 4.x is on and logged in, with at least one conversation opened (so that the DB is loaded into memory and the key appears in the heap) - After the key is obtained, write `~/.config/wxcli/config.json`, and then WeChat can be closed - WCDB dynamic library is not in the source repository; macOS release zip provides `libWCDB.dylib`, and Windows release zip provides `libWCDB.dll`. ## 安装 macOS entrance: ```bash ./install.sh --all --yes --json ``` macOS entrance is designed for scenarios where the GitHub link or zip is provided to the agent: install/build binary, copy `libWCDB.dylib`, register Claude/Codex MCP, run `wxkey bootstrap`, warm up the cache in the background, and install the launchd watcher as needed. All results are output in JSON; the agent mainly checks `status` / `blocked_by` / `next_action` / `errors[]` / `log`. Windows entrance: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -All -Yes -Json ``` The Windows version requires `wx-mcp.exe` to be next to `libWCDB.dll` or `WCDB.dll`. If the WeChat data is not in the default location, set `WX_MCP_DB_ROOT` to the account directory that directly contains `db_storage`. When Windows WeChat is logged in, `wx-mcp` will scan the SQLCipher raw key in the memory of the `Weixin.exe` / `WeChat.exe` process, verify and write the schema-2 key map. The default installation will verify the cache refresh once in the foreground; if you need to start the background warm-up only, add `-BackgroundRefresh`. For details, see `docs/WINDOWS_USER_GUIDE.md`. > **The user only needs to enter the Mac admin password once for the first installation.** The agent can directly run `./install.sh --all --yes --json`; `wxkey bootstrap` will pop up the hidden password input box of `wx-mcp`, verify sudo, and store the password in the user's macOS Keychain. Subsequent operations (cache refresh / `wx-mcp` startup / DB decryption / missing key automatic replenishment) will reuse this Keychain credential, without requiring the user to enter commands in the terminal or close SIP. > **Avoid TCC repeatedly popping up "wx-mcp wants to access other App data" (macOS 15+).** After installation, go to **System Settings → Privacy & Security → Full Disk Access**, click `+` to add `~/.local/share/wx-mcp/wx-mcp` and `~/.local/share/wx-mcp/wxkey`. After adding, all requests to access the WeChat container will pass silently without popping up. (`--all` does not install the launchd watcher by default; if you need to refresh the cache automatically every 5 minutes in the background, add `--watcher` explicitly, but first add Full Disk Access to the above two binaries, otherwise the watcher will trigger a pop-up every time it runs.) The source code clone scenario is only suitable for developers or emergency installations without a release zip; ordinary agents should prioritize the release zip installation, because the source repository does not contain `libWCDB.dylib` / `libWCDB.dll`. ```bash git clone https://github.com/r266-tech/wechat-local-mcp.git cd wechat-local-mcp WX_MCP_WCDB_DYLIB=/path/to/libWCDB.dylib ./install.sh --all --yes --json ``` The release zip scenario will directly copy the binary and WCDB dynamic library inside the package. The macOS source code clone scenario will prioritize `go build`; if there is no `wxkey` source code or binary locally, the installer will install the companion CLI from `github.com/r266-tech/wxkey/cmd/wxkey@latest`. The Windows source code clone scenario requires a local Go and `libWCDB.dll`. When the release zip user updates, the agent should download the latest stable version zip for the current platform, extract it to a new directory, and then run the update from the new directory: ```bash # macOS ./install.sh --update --yes --json ``` ```powershell # Windows powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Update -Yes -Json ``` `--update` will not pull GitHub when not in a git directory; it will only reinstall the files in the current release package into the user directory. If you want to re-run the complete initialization, use `--all`. For an existing git checkout, the update entrance is: ```bash ./install.sh --update --yes --json ``` `--update` will first `git pull --ff-only`, and then reinstall the binary. By default, it will not re-bootstrap, refresh the cache, re-register MCP, or move the watcher; if needed, add `--refresh` / `--watcher` / `--bootstrap` explicitly, or directly run `--all`. Security hierarchy: ```bash ./install.sh --doctor --json ./install.sh --dry-run --all --json ./install.sh --yes --json --mcp-client none # Only install files, do not register MCP / bootstrap / watcher ./install.sh --uninstall --yes --json ``` Windows security hierarchy: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Doctor -Json powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -DryRun -All -Json powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Yes -Json -NoMcp powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall -Yes -Json ``` Manual registration is still available: ```bash go build -o wx-mcp ./cmd/wx-mcp claude mcp add --scope user wx-mcp "$PWD/wx-mcp" ``` ## 验证 (Recommended to run once after installation) After installation, the agent will run `wxkey bootstrap` in `./install.sh --all`. If you need to verify it separately: ```bash ./wxkey bootstrap ``` `bootstrap` will check the existing config, create and sign the wx-mcp shadow WeChat copy if necessary, and complete the initial key initialization. When troubleshooting, run: ```bash ./wxkey doctor ``` `doctor` will output: SIP status / WeChat signature / WeChat process / account directory / DB number / dylib / memory scan status / number of keys obtained. If there is no cache key, WeChat is not logged in / signature not processed / scan failed will report an error in Chinese. Then let Claude/Codex call any `wx-mcp` tool (such as `sessions`) to verify E2E. If the key cannot be obtained, the model will tell you the error. ## 开发 / 更新 ```bash go build -o wx-mcp ./cmd/wx-mcp # MCP takes effect at the next startup (or claude mcp restart wx-mcp) # Run tests (helpers + XML parsers, ~30 cases do not depend on db/dylib): go test ./... ``` ## 打分发包 (for friends) ```bash WX_MCP_WCDB_DYLIB=/path/to/libWCDB.dylib ./scripts/package.sh 1.5.0 # Produce dist/wx-mcp-v1.5.0-darwin-arm64.zip + .sha256 (including wx-mcp + wxkey + libWCDB.dylib + install.sh + docs) ``` Windows package on Windows machine: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\package-windows.ps1 -Version 1.5.0 -WcdbLib C:\path\to\libWCDB.dll # Produce dist\wx-mcp-v1.5.0-windows-amd64.zip + .sha256 (including wx-mcp.exe + libWCDB.dll + install.ps1 + docs) ``` Friends extract and then: 1. macOS agent runs `./install.sh --dry-run --all --json` to check the plan; Windows agent runs `.\install.ps1 -DryRun -All -Json`. 2. macOS agent runs `./install.sh --all --yes --json`; Windows agent runs `.\install.ps1 -All -Yes -Json`. 3. JSON returns `status=ready` or `status=warming_cache` indicates the installation main process is complete; `warming_cache` means the cache is warming up in the background. Windows verifies successfully in the foreground and returns `ready` by default. 4. Let Claude/Codex call `sessions` to pull data, and it will work. Prerequisites: If the target machine does not have an existing key, the first key scan requires WeChat 4.x login status + at least one conversation opened. macOS supports the path `no-SIP ./wxkey bootstrap`: the user enters the Mac admin password once, and then automatically reuses the Keychain credential. Windows supports the path `wx-mcp.exe cache refresh --force` built-in same-user process scan, without running `wxkey`. ## Cache-first Fast Path When pursuing the strongest experience, build a local plaintext snapshot cache + unified `index.sqlite`: ```bash ./wx-mcp cache status ./wx-mcp cache refresh # Incremental refresh: reuse snapshot if DB/WAL mtime unchanged ./wx-mcp cache rebuild # Delete cache and rebuild completely ``` Cache is located at `~/.wx-mcp/cache/<wxid>/`: ```text raw/ # Plaintext snapshot of each source DB index.sqlite # contacts_unified / sessions_unified / messages_unified / message_fts ``` `sessions` / `messages` / `search` / `unread` / `new_messages` / `stats` / `export_messages` will compare the source DB/WAL mtime and salt before reading `index.sqlite`. If the cache does not exist or is outdated, wx-mcp will automatically `cache refresh`; it will return results only after the refresh is successful, not returning old cache. `search` defaults to `search_mode=fts` and relies on the cache index; if the cache is outdated, it will automatically refresh. Only when explicitly set to `search_mode=like` and automatic refresh is disabled can it use the old direct read LIKE fallback. `unread` / `new_messages` / `stats` / `export_messages` rely on the cache index. Optional watcher: ```bash ./install.sh --watcher --yes --json # or include it during full installation: ./install.sh --all --yes --json ``` The watcher is a launchd user agent (`com.r266.wx-mcp-cache-watcher`), which runs `wx-mcp cache refresh` every 300 seconds by default and uses `~/.wx-mcp/cache-refresh.lock` to prevent re-entry. Logs are located at `~/Library/Logs/wx-mcp/`. The watcher is not necessary for daily use: MCP tools will automatically check for cache freshness before reading the cache. ## Agent CLI In addition to MCP tools, `wx-mcp` also provides agent-friendly CLI aliases: ```bash wx-mcp sessions --type-filter private,group wx-mcp resolve-chat "张三" wx-mcp history "张三" --limit 50 wx-mcp media "张三" --type image --limit 10 wx-mcp search "关键词" --in "某群" --after 2026-01-01 --type text wx-mcp search "关键词" --search-mode like # Slow fallback when no cache wx-mcp members "某群" wx-mcp stats "某群" wx-mcp red-packets --limit 20 wx-mcp transfers --limit 20 wx-mcp sns-feed wx-mcp sns-search "关键词" wx-mcp sns-notifications --include-read ``` The CLI and MCP use the same cache-first query logic. ## Tools (25) All time fields accept Unix seconds or `2006-01-02` (local timezone). | Tool | Description | |------|-------------| | `sessions` | Session list (sorted by sort_timestamp DESC). Fields: username / display_name / chat_type / unread_count / summary / sort_timestamp / last_timestamp / last_sender_wxid / last_sender_display_name / last_msg_type / last_msg_sub_type / last_msg_kind_name. Supports type_filter (private/group/official_account/folded/bot, comma-separated) + keyword fuzzy search | | `resolve_chat` | Resolve nickname/remark/alias/group name to username/talker. Returns candidates for agent to enter precise tool calls from natural language targets | | `contacts` | Contact/group search. Fields: username / display_name / nick_name / remark (omitempty) / alias (omitempty) / description (omitempty) / type / chat_type / is_verified | | `messages` | Messages. talker can be wxid; chat can be nickname/remark/group name for automatic resolution. fields=lite (default) returns core fields; fields=full adds subtype + raw message_content + message_content_parsed (XML structured, recursive depth=3). content_summary has removed group chat sender prefix | | `media_resources` | Message attachments/media resource locations. Returns `server_id_str`, image/video/file/cover resource raw type, variant_code, size, status, packed_strings (file name/md5), and existing local `local_paths` from `message_resource.db`. Supports chat/talker/local_id/server_id/server_id_str/type/resource_family filtering | | `group_members` | Group members. chatroom_id can be group ID; chat can be group name for automatic resolution. is_owner / is_friend are bool. stats=true appends msg_count | | `sns` | Moments + likes/comments. Fields: tid / username / nickname / avatar_url / create_time / content / type / private / liked_by_me / media (including raw_type/sub_type/url_key/thumb_key/md5/width/height/total_size/video_md5/video_duration) / location / likes / comments | | `sns_feed` | Moments timeline, semantic alias, fields same as sns | | `sns_search` | Moments content search, keyword required, fields same as sns | | `sns_notifications` | Moments likes/comments notifications. Default unread; include_read=true returns all | | `search` | Cross-session full-text search. Default search_mode=fts uses cache self-built FTS; search_mode=auto can FTS without results then LIKE fallback; search_mode=like explicit slow LIKE. Supports keyword + chat/talker/after/before/type/kind_name/base_kind/sender. Fields include chat_type / content / talker / sender / base_kind / kind_name / local_id / create_time | | `sql` | Read-only SQL. `SELECT/WITH` default outer limit, `limit` max 1000; `PRAGMA/EXPLAIN` can run directly. OS-level readonly (SQLITE_OPEN_READONLY) — DDL/DML directly report errors | | `transfers` | Transfers. Fields: transfer_id / transcation_id / payer_wxid / receiver_wxid / session_username / pay_sub_type / begin_transfer_time / **amount** ("￥5.00") / **description** ("收到转账5.00元") / memo (omitempty). amount/description/memo are batch join messages.server_id to resolve XML | | `red_packets` | Red packets. Fields: send_id / sender_wxid / session_username / native_url / message_server_id / **wishing** ("恭喜发财大吉大利") / scene_text. Supports chat/talker/sender/after/before; time/sender filtering uses cache join messages.create_time | | `favorites` | Favorites. Fields: server_id / favorite_type (link/text/image/voice/video/file/chat_history/miniprogram/...) / from_wxid / source_chat_username (omitempty) / update_time / **title** / **description** / **url** (extracted from content XML) / source_id / content (XML raw) | | `chatroom_announcements` | Group announcements. Fields: chatroom_id / chatroom_display_name / announcement / editor_wxid / editor_display_name / publish_time | | `forward_history` | **Recent forwarding target list** (for quick forwarding, not "forwarded message history"). Fields: username / display_name / forward_time | | `schema` | WCDB database structure. Without parameters, list all db subdirectories + table names; with subdir+file, return each table DDL | | `cache_status` | View plaintext snapshot cache and unified index.sqlite status. Does not trigger wxkey setup | | `cache_refresh` | Refresh snapshot cache and rebuild index.sqlite. Default reuse unchanged snapshot by DB/WAL mtime; force=true forces re-solving; background=true returns immediately and refreshes in the background | | `cache_rebuild` | Delete current cache and rebuild completely | | `unread` | Unread session list, fields same as sessions. Supports filter/type_filter=private,group etc. | | `new_messages` | Incremental pull new messages. Supports chat/talker/after/cursor, returns messages + next_cursor. cursor is `v2:create_time:base64url_talker:local_id`, does not rely on cache rebuild and may shift SQLite rowid | | `stats` | Cache index-based statistics. Without chat/talker, returns global; with chat/talker, returns single session by_sender/by_kind/daily/hourly | | `export_messages` | Export messages to jsonl / markdown / html files from cache index. Supports chat/talker/after/before/keyword | ## Key Concepts ### kind_name Decoding `local_type` is packed int64: `(subtype << 32) | base_kind`. messages tool has split `base_kind` / `subtype` / `kind_name`, lite mode hides raw `local_type`. - `base_kind`: 1=text / 3=image / 34=voice / 42=card / 43=video / 47=sticker / 48=location / 49=app / 50=voip / 10000=system - `kind_name` is detailed for `base_kind=49`: 3=music / 5=link / 6,8,24=file / 19=forward_chat / 33,36=miniprogram / 49=link / 51=channel_video / 57=quote / 62=pat / 87=announcement / 2000=transfer / 2001=red_packet - When quoting messages (subtype=57), `message_content_parsed.refermsg` contains complete quote context + recursively decodable content_parsed (depth≤3) ### Cross-table Join Key - `server_id` (messages) ⇄ `message_server_id` (transfers/red_packets/favorites): int64, stable across re-import. transfers/red_packets have automatically batch joined to resolve XML, no need for agents to call messages again - Search hit rows route back to `Msg_<hash>(talker)` through `(talker, local_id)` to get sender + base_kind/kind_name ### Error Handling Main path errors fail loudly (db cannot be opened / SQL fails immediately). Batch enrichment (transfers amount, search sender) is best-effort: if single talker routing fails, the field is missing (other rows are not affected; agent sees the field does not exist and knows it was not obtained). ## Architecture ``` wx-mcp/ ├── cmd/wx-mcp/ │ ├── main.go MCP server + tool handlers + complex enrich pipeline │ ├── cache.go plaintext snapshot cache + index.sqlite + cache-first tools │ ├── agent.go agent entry: resolve_chat / chat_type / natural language target parsing │ ├── cli.go agent CLI aliases + cache/status/export/stats/unread │ ├── main_test.go parseTS / talkerHash / contentSummary and other tests │ └── *_windows.go Windows WCDB DLL / background refresh adaptation ├── internal/ │ ├── wcdb/ WCDB dylib FFI (sqlite3_key_v2 decryption) │ ├── config/ ~/.config/wxcli/config.json management │ ├── wxkind/ base_kind / app subtype / fav type / username classification mapping │ └── wxparse/ transfer / red-packet / favorite XML parsing ├── scripts/package.sh build macOS distribution zip + sha256 ├── scripts/package-windows.ps1 ├── install.sh macOS agent-first installer / doctor / uninstall / watcher ├── install.ps1 Windows installer / doctor / update / uninstall ├── AGENTS.md brief operation instructions for agent ├── mcp-server.json ecosystem/discovery manifest ├── go.mod / go.sum ├── wx-mcp / wx-mcp.exe compiled output (.gitignore) └── README.md ``` Runtime loading of platform dynamic libraries in the same directory: macOS `libWCDB.dylib`, Windows `libWCDB.dll` (distributed package included). macOS recommended initial key acquisition: user runs `./wxkey bootstrap` → exit WeChat and ad-hoc re-sign → user inputs Mac admin password and stores it in Keychain → sudo -S + task_for_pid + mach_vm_read scans WeChat heap → SQLCipher 4 page-1 HMAC verification → 64-bit hex AES key → stores in `~/.config/wxcli/config.json`. On macOS, if `wx-mcp` detects a missing key in `config`, it attempts to automatically spawn `wxkey setup` in the same directory, but does not automatically re-sign/restart WeChat; such desktop side effects are left to explicit `./wxkey bootstrap`. On Windows, there is no `wxkey` companion; `wx-mcp` directly scans the current user's `Weixin.exe` / `WeChat.exe`, verifies the DB key, and writes the schema-2 config. `wx-mcp`'s runtime decryption/reading library itself does not depend on SIP: if the config already has a key, it directly opens the encrypted DB with WCDB readonly. Distribution zip structure: ``` wx-mcp-v1.4.5-darwin-arm64/ ├── wx-mcp (~10MB Go binary) ├── wxkey (~3MB key extraction CLI, spawned by wx-mcp) ├── libWCDB.dylib (~5MB Tencent WCDB, loaded in the same directory as binary) ├── install.sh (agent-first install/doctor/uninstall) ├── AGENTS.md ├── mcp-server.json ├── README.md ├── LICENSE ├── SECURITY.md └── THIRD_PARTY_NOTICES.md ``` Windows distribution zip structure: ``` wx-mcp-v1.4.5-windows-amd64/ ├── wx-mcp.exe ├── libWCDB.dll ├── install.ps1 ├── AGENTS.md ├── mcp-server.json ├── README.md ├── docs/WINDOWS_USER_GUIDE.md ├── LICENSE ├── SECURITY.md └── THIRD_PARTY_NOTICES.md ``` ## Changelog ### v1.4.5 (2026-05-11) - **install.sh --update** adds low-side-effect update path: `git checkout` first `git pull --ff-only`, then reinstall `wx-mcp` / `wxkey` / `libWCDB`. - `--update` does not bootstrap, refresh cache, re-register MCP, or change watcher by default; if friends already have an installation, they can directly hand it over to the agent to run. - `AGENTS.md` / `mcp-server.json` add update entry for external agents to discover update commands. ### v1.4.4 (2026-05-11) - **media_resources** adds message attachment/media resource location tool, directly reads `message_resource.db`, supports chat/talker/local_id/server_id/server_id_str/type/resource_family filtering. - **media_resources** unpacks `packed_info`'s md5/filename, and returns existing local image, video thumbnail/video, file path according to WeChat directory rules. - CLI adds `wx-mcp media` / `media-resources` / `attachments` alias; `AGENTS.md` and manifest mark `media_resources` as agent main path tool. ### v1.4.3 (2026-05-11) - **new_messages** cursor changed to stable v2 tuple (`create_time/talker/local_id`), no longer depends on cache rebuild possibly changed SQLite rowid. - **MCP schema** rejects unknown parameters by default, fields/format/search_mode add enumeration constraints, tools/list add readOnly/destructive/idempotent hints. - **search** only uses cache FTS by default; `search_mode=auto` allows FTS without results to fall back to LIKE, `search_mode=like` allows cache-less old direct read LIKE. - **red_packets** supports chat/talker/sender/after/before, time and sender filtering through cache join messages metadata. - **sns media** adds url/thumb key/token/enc_idx, md5, size, video_md5, video_duration and other fields. - **export_messages** changed to batch streaming write file, avoiding constructing large strings at once; distribution package additionally produces `.sha256`. ### v1.3.1 (2026-04-16) - **messages** supports public accounts/service accounts — `findMsgDB` previously only scanned `message_0..4.db`, missed `biz_message_0..1.db` (public account messages actually stored there), causing all `gh_*` unable to retrieve messages. Now glob scans `(message|biz_message)_<n>.db` entire family, shard number no longer hardcoded - **favorites** peels raw `type_id` (= raw int duplicate `favorite_type`) — violates "raw int fully resolve" principle - **sessions.last_sender_wxid** peels subscription account collection sender prefix — previously returned `_$_CUSTOM_USERNAME_PREFIX_$_<aggId>:<realId>`, now only retains `<realId>` (usually `gh_xxx`) - **messages** gives clear error "no message table itself, check specific gh_<id>" for aggregated sessions (`brandsessionholder` / `brandservicesessionholder`), replacing cryptic "table not found" - **schema** classifies db by prefix — previously mistakenly folded `biz_message_*` / `message_fts` into `message_0..4` shard, now `message`/`biz_message`/`message_fts`/`message_resource` each occupies one line, `shard_count` calculated by family ### v1.3.0 (2026-04-16) - **messages.keyword** fixes zstd bug — originally SQL LIKE failed on compressed bytes, now widens SQL and filters in-memory on uncompressed content, can hit app-like messages (transfer/link/mini-program/...) - **transfers** adds amount / description / memo (batch join messages to resolve XML); field rename: payer_wxid / receiver_wxid / session_username - **red_packets** drops 4 semantically unclear raw ints (hb_status/hb_type/receive_status/scene_id), adds wishing / scene_text / native_url - **search** adds sender_wxid / sender_display_name / base_kind / kind_name (joins back Msg_<hash> routing), drops FTS internal session_id, content peels group chat sender prefix - **chatroom_announcements** cleans up field underscore suffix (announcement_/editor_/publish_time_ → announcement/editor_wxid/publish_time) - **favorites** adds favorite_type resolve, adds title / description / url (extracted from content XML), drops local_id/update_seq/flag, renames fromusr → from_wxid - **group_members** drops big_head_url, is_owner / is_friend → bool - **schema** fixes P0 panic (global call nil deref); single db loading failure now merges error field instead of silent skip - Modular refactoring: kind/parse helpers extracted to internal/wxkind + internal/wxparse, ~30 unit tests covered - search/schema silent error swallow → fail loud ### v1.2.0 - schema tool, cross-db keyword search, is_from_me, create_time_human, description sweep ### v1.1.0 - agent-friendly display_name across all 12 tools ### v1.0.0 - initial 12 tools --- <!-- babata-star-callout-v2 --> ## If this saved you time Starring the repo helps me prioritize which integrations to keep maintained. This project is part of [babata](https://github.com/r266-tech) — a personal, macOS-native AI infrastructure stack.