stkoecn / im-mcp

# im-mcp (本地绿泡泡 & DuangDuang AI 检索 MCP Server)
基于 **Model Context Protocol (MCP)** 规范构建的本地 IM（绿泡泡 & DuangDuang）聊天记录与通讯录检索服务。
极简、只读、完全离线本地运行，让 Claude Desktop、Cursor、Cline、Pi 等 AI Agent 能够安全、高速地检索与总结你的工作沟通、群聊记录和知识库。
> 💡 **复制即用提示词（直接发给你的 AI Agent / 客户端）**：
> 
> [code] 
> 注：原底层参考项目以 Git Submodule 形式统一归档在 `reference/` 目录下（`reference/wechat-local-viewer` 与 `reference/dingwave-V3`）。
---
## ✨ 核心特性
- ⚡ **超低延迟**：直接基于本地解密 SQLite 数据库，毫秒级响应。
- 🔒 **纯本地与只读**：所有数据均在本地，绝不上云；以只读方式运行，不破坏原始数据。
- 📦 **按需安装（Optional Dependencies）**：一个仓库，两套独立入口；支持只装绿泡泡、只装DuangDuang或全量安装。
- 💬 **丰富格式解析**：
 - **绿泡泡**：支持普通文本、引用消息、富文本卡片、小程序、传输文件（PDF/Excel/Word等）。
 - **DuangDuang**：支持多表分片聚合（`tbmsg_000`~`tbmsg_127`）、联系人实名映射、Markdown卡片、协同日程通知、文件附件提取。
---
## 🔍 支持的客户端与系统版本 (Compatibility)
| 平台 | 支持版本范围 | 实测验证版本 | 架构与平台 | 解密 / 同步原理 |
|---|---|---|---|---|
| **绿泡泡 (WeChat)** | **绿泡泡 4.x** 全系列 *(兼容 3.9.x)* | **`4.1.15.13`** (Windows 最新版) **`4.1.35.15`** (macOS ARM64 最新版) **`4.1.15` (270115)** (macOS x86_64 实测验证) `4.1.11.x` 等 | Windows x64 macOS (Apple Silicon & Intel) | **Windows**: 运行时扫描 `Weixin.exe` Config.Cipher 动态提取 Salt 密钥； **macOS**: 原生 `CommonCrypto` (CCCrypt) 零额外依赖解密，支持 passphrase PBKDF2 派生；离线 HMAC 校验并解密 WCDB SQLite |
| **DuangDuang (DingTalk)** | **DuangDuang 7.x** 全系列 *(涵盖 V2 与 V3)* | **`7.6.0.x`** (最新版) `7.5.x` / `7.0.x` | Windows x64 / macOS | 纯离线读取用户目录 `user_config`，通过 PBKDF2-HMAC-SHA1 + MD5 推导 AES-128 密钥并合并 WAL 事务 |
---
## 🧰 提供的 MCP Tools
### 1. 绿泡泡 (`wechat-mcp`)
共 29 个工具，全部只读（`sync_wechat_database` / `start_sync` / `set_auto_sync` 会触发本地快照重建，但不向微信发送任何消息）。
> 本 fork 相对上游新增 / 修复的完整清单见 CHANGELOG.md。
**消息检索**
| 工具名称 | 说明 | 适用场景 |
|---|---|---|
| `search_wechat_messages` | 全文检索聊天消息（多词 AND，可限定会话 / 发言人 / 时间窗，支持 `offset` 分页；每条带 `snippet` 命中上下文） | “找一下群里谁发过关于‘某某需求’的讨论” |
| `get_session_history` | 获取指定会话的最近对话（时间正序，可限定天数） | “总结一下这个项目群最近 50 条消息都在聊什么” |
| `get_messages_by_date` | 按指定日期拉取全量或限定会话记录（支持 `offset` 分页） | “帮我汇总 2026-10-16 那天所有沟通做日报” |
| `get_messages_by_range` | 按自定义时间范围（支持跨天与任意时段、按人过滤、`offset` 分页）拉取记录 | “拉一下上周三到周五这个群聊了什么” |
| `get_messages_since` | 增量游标：只取 `after_id` / `after_time` 之后的新消息，返回 `next_cursor` 与 `has_more` | “面板刷新新消息 / 脚本增量同步，不重复拉全量” |
**会话与通讯录**
| 工具名称 | 说明 | 适用场景 |
|---|---|---|
| `list_wechat_sessions` | 查询群聊或联系人列表（获取唯一 ID，含未读快照 `unread`） | “帮我看看关于‘量化’有哪些群” |
| `get_unread_sessions` | 列出有未读消息的会话（按最近活跃倒序） | “还有哪些群没看” |
| `get_session_overview` | 单个会话的轻量概览（累计条数 / 范围消息量 / 发言人数 / 峰值时段 / 类型 TopN / 首末时间） | “切群先看一眼这个群多大、什么时候最热” |
| `search_contacts` | 按昵称 / 备注 / 微信号搜索联系人 | “查一下张工的微信号和备注名” |
| `list_chatroom_members` | 列出指定群聊的成员名单（自动关联昵称与微信号） | “这个群一共多少人，都有谁” |
**文件 / 图片 / 媒体 / 收藏 / 表情**
| 工具名称 | 说明 | 适用场景 |
|---|---|---|
| `get_message_image` | 按消息 ID 定位并按需解密聊天图片（支持本地物理路径或多模态 Base64） | “把刚才查到的那张聊天图片解密提取出来看下” |
| `get_chat_record` | 展开「聊天记录」合并转发消息，把被合并的正文解析为结构化条目（文本 / 图片 / 视频 / 文件） | “这条『聊天记录』里到底转了些什么” |
| `get_user_avatars` | 批量取用户 / 群 / 公众号头像的本地图片路径（供面板等宿主直接读盘渲染，不返回 base64） | “把群里发言者的头像都给我” |
| `search_shared_files` | 查找聊天中发送/接收的文件文档 | “找一下上周有人发在群里的那个理财报告 Excel” |
| `search_media