From bd5cfaf270f977f8dcf4b19ce6aa97158ad8f77e Mon Sep 17 00:00:00 2001 From: 2977094657 <2977094657@qq.com> Date: Fri, 12 Jun 2026 16:44:34 +0800 Subject: [PATCH] =?UTF-8?q?docs(mcp):=20=E5=90=8C=E6=AD=A5=20Copilot=20Ski?= =?UTF-8?q?ll=20=E5=8F=AA=E8=AF=BB=E6=8E=A5=E5=85=A5=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 19 ++++----- skills/wechat-mcp-copilot/SKILL.md | 6 +-- .../references/analytics.md | 2 +- .../wechat-mcp-copilot/references/export.md | 29 ------------- .../references/failure-recovery.md | 7 ++-- skills/wechat-mcp-copilot/references/media.md | 3 +- .../wechat-mcp-copilot/references/mobile.md | 8 ++-- .../wechat-mcp-copilot/references/moments.md | 3 +- .../wechat-mcp-copilot/references/routing.md | 11 +++-- .../references/setup-system.md | 41 ------------------- 10 files changed, 25 insertions(+), 104 deletions(-) delete mode 100644 skills/wechat-mcp-copilot/references/export.md delete mode 100644 skills/wechat-mcp-copilot/references/setup-system.md diff --git a/README.md b/README.md index cac2267..1c1ef25 100644 --- a/README.md +++ b/README.md @@ -161,7 +161,7 @@ npm run dev ## MCP 服务 -后端提供 MCP JSON-RPC over HTTP 服务，默认只监听 `127.0.0.1`。手机接入局域网时，在应用内打开 **设置 -> MCP 接入 -> 允许手机局域网接入 MCP**，后端会切换为监听 `0.0.0.0` 并重启。 +后端提供 MCP JSON-RPC over HTTP 服务，默认只监听 `127.0.0.1`。手机接入局域网时，在应用内打开 **设置 -> MCP 接入 -> 允许手机局域网接入 MCP**，后端会切换为监听 `0.0.0.0` 并重启；设置页展示和复制的接入地址会使用电脑实际局域网 IP，例如 `http://192.168.x.x:10392/mcp`，而不是不可被其他设备访问的 `127.0.0.1`。 MCP 入口需要 token 鉴权。设置页提供 **MCP Token**、**AI 接入提示词** 和 **Skill Markdown** 三个独立复制区；token 可一键复制或重置，重置后旧 token 立即失效。手机端或外部 AI 客户端访问 `/mcp`、`/mcp/skill/bundle`、`/mcp/skill` 时，都应带上 `Authorization: Bearer `。兼容客户端也可以使用 `X-MCP-Token` 请求头或 `?token=` 查询参数，但推荐使用 Bearer token。 @@ -169,23 +169,20 @@ MCP 入口需要 token 鉴权。设置页提供 **MCP Token**、**AI 接入提 工具调用成功时，客户端优先读取 `result.structuredContent`，`content[0].text` 只是给通用 MCP 客户端展示的 JSON 文本副本。业务未就绪时仍可能返回 JSON-RPC success，但 `result.isError=true`；协议错误或参数错误则返回 JSON-RPC `error`。 +MCP 仅暴露读取数据与获取媒体资源 URL/参数的能力；系统设置、索引与缓存构建、数据准备、导出、实时同步、本地修订、数据删除等操作类能力不通过 MCP 暴露，请在桌面/网页应用内使用。 + 工具按包分层： - `wechat.core`: 状态、工具目录、账号列表、账号信息 -- `wechat.setup`: 密钥读取、数据库解密、已解密目录导入、媒体密钥保存、批量媒体处理入口 -- `wechat.system`: 健康检查、后端端口、日志路径、大图辅助插件状态等系统能力 - `wechat.mobile`: 面向手机和外部代理的聚合入口，默认返回小结果和下一步建议 -- `wechat.contacts`: 联系人列表、模糊解析、联系人导出 +- `wechat.contacts`: 联系人列表、模糊解析 - `wechat.chat`: 会话、消息、搜索、发送者筛选、上下文、锚点、合并转发/AppMsg 解析、统计 -- `wechat.moments`: 朋友圈时间线、用户、同步、图片/视频/文章封面 URL -- `wechat.media`: 聊天/朋友圈图片、视频、表情、头像、语音文件 URL、远程图片代理与资源辅助 +- `wechat.moments`: 朋友圈时间线、用户、图片/视频/文章封面 URL +- `wechat.media`: 聊天/朋友圈图片、视频、表情、头像、语音文件 URL、远程图片代理与资源辅助；只返回 URL 或资源参数，不提供下载缓存或打开本机目录操作 - `wechat.biz`: 公众号/服务号与微信支付记录 -- `wechat.analytics`: 年度总结与卡片懒加载 -- `wechat.export`: 聊天、朋友圈、账号归档导出任务、下载 URL 与进度 SSE URL -- `wechat.admin`: 微信检测、索引、实时同步等管理能力 -- `wechat.editing`: 消息编辑、修复、恢复与审计 +- `wechat.analytics`: 年度总结与聚合分析读取；年度总结只读取应用内已生成的缓存，未生成时请先在应用内打开年度总结 -媒体、视频、SSE 进度和 ZIP 导出不会直接塞进 MCP JSON 响应；相关工具返回可访问 URL、`streamUrl`、任务状态或资源参数。 +媒体和视频不会直接塞进 MCP JSON 响应；相关工具返回可访问 URL 或资源参数。 配套 skill 可通过 HTTP 加载，访问时需要带 MCP token： diff --git a/skills/wechat-mcp-copilot/SKILL.md b/skills/wechat-mcp-copilot/SKILL.md index bbfc8ef..4ed87cc 100644 --- a/skills/wechat-mcp-copilot/SKILL.md +++ b/skills/wechat-mcp-copilot/SKILL.md @@ -1,7 +1,7 @@ --- name: wechat-mcp-copilot version: "1.0.0" -description: Use WeChatDataAnalysis MCP to inspect local WeChat accounts, contacts, sessions, messages, Moments, media, exports, and analytics through a small routed playbook. Trigger when the user asks to search, summarize, export, diagnose, or reason over local WeChat data. +description: Use WeChatDataAnalysis MCP to inspect local WeChat accounts, contacts, sessions, messages, Moments, media, and analytics through a small routed playbook. Trigger when the user asks to search, summarize, diagnose, or reason over local WeChat data. --- # WeChat MCP Copilot @@ -12,7 +12,7 @@ Use WeChatDataAnalysis MCP like an investigator: start broad, resolve fuzzy targ 1. Start with `references/routing.md`. 2. Load only one domain reference after routing. -3. Load `references/pagination-budget.md` before broad searches, exports, or multi-page scans. +3. Load `references/pagination-budget.md` before broad searches or multi-page scans. 4. Use `references/failure-recovery.md` when MCP, database readiness, or empty results are unclear. 5. For phone, ScreenMemo, or external MCP clients, prefer `wechat.mobile.*` facade tools before low-level tools. 6. Do not load the full tool catalog unless the user asks about available tools. @@ -21,12 +21,10 @@ Use WeChatDataAnalysis MCP like an investigator: start broad, resolve fuzzy targ - `references/routing.md`: first-hop intent routing. - `references/mobile.md`: phone-friendly facade tools and compact response rules. -- `references/setup-system.md`: setup, keys, decrypt, import, health, and system operations. - `references/target-resolution.md`: fuzzy contact/session resolution. - `references/chats.md`: chat sessions, messages, search, and context. - `references/moments.md`: Moments timeline, posters, likes, comments, media. - `references/media.md`: images, videos, emoji, files, voice resources without transcription. -- `references/export.md`: chat, Moments, and account archive export jobs. - `references/analytics.md`: wrapped cards, counts, rankings, and aggregate analysis. - `references/pagination-budget.md`: limits, cursors, result clipping, stopping rules. - `references/failure-recovery.md`: empty result, not-ready database, ambiguous targets, retries. diff --git a/skills/wechat-mcp-copilot/references/analytics.md b/skills/wechat-mcp-copilot/references/analytics.md index 1d46163..185c798 100644 --- a/skills/wechat-mcp-copilot/references/analytics.md +++ b/skills/wechat-mcp-copilot/references/analytics.md @@ -13,7 +13,7 @@ Use this for annual summaries, rankings, counts, and aggregate questions. ## Rules - Prefer `get_wrapped_meta` then `get_wrapped_card` for mobile or constrained contexts. +- Wrapped annual tools read existing generated cache only; if a cache is missing, ask the user to open Wrapped in the desktop/web app first. - Use `get_wrapped_annual` only when the user needs the whole annual dataset. - For broad statistics, prefer aggregate tools or targeted searches over full message pagination. - Always state the account, time range, and metric basis when answering. - diff --git a/skills/wechat-mcp-copilot/references/export.md b/skills/wechat-mcp-copilot/references/export.md deleted file mode 100644 index 1d61466..0000000 --- a/skills/wechat-mcp-copilot/references/export.md +++ /dev/null @@ -1,29 +0,0 @@ -# Export - -Use export only when the user asks for an artifact. - -## Chat Export - -1. Resolve target session if `scope=selected`. -2. Confirm time range, format, media options, and output directory when needed. -3. Preview targets with `wechat.export.preview_chat_targets`. -4. Create job with `wechat.export.create_chat_export`. -5. Poll `wechat.export.get_chat_export`. -6. Return `wechat.export.get_chat_export_download` when ready. -7. Use `wechat.export.get_chat_export_events_url` when the client can consume SSE progress. - -## Moments Export - -Use `wechat.export.create_moments_export`, `wechat.export.get_moments_export`, `wechat.export.get_moments_export_download`, and `wechat.export.get_moments_export_events_url`. - -## Account Archive - -Use `wechat.export.create_account_archive`, `wechat.export.get_account_archive`, `wechat.export.get_account_archive_download`, and `wechat.export.cancel_account_archive`. - -## Contacts Export - -Use `wechat.contacts.export_contacts` only when the user asks for a contacts file. It writes JSON or CSV to a local output directory. - -Do not silently export all history and all media unless the user explicitly asked for that scope. - -For phone clients, prefer `wechat.mobile.export_job` unless exact low-level export options are required. diff --git a/skills/wechat-mcp-copilot/references/failure-recovery.md b/skills/wechat-mcp-copilot/references/failure-recovery.md index b702d1d..5bda30b 100644 --- a/skills/wechat-mcp-copilot/references/failure-recovery.md +++ b/skills/wechat-mcp-copilot/references/failure-recovery.md @@ -8,9 +8,8 @@ Use this when MCP status, DB readiness, or results are suspicious. 2. `wechat.core.get_status` 3. `wechat.core.list_accounts` 4. `wechat.core.get_account_info` -5. Search index status with `wechat.chat.get_search_index_status` when message search fails. -6. Moments availability by checking account info and `wechat.moments.list_users`. -7. Setup readiness: load `setup-system.md` for keys, decrypt, import, health, or media-key problems. +5. Moments availability by checking account info and `wechat.moments.list_users`. +6. For backend diagnostics, MCP LAN access, data preparation, index/cache build, export, realtime sync, local editing, or system settings, direct the user to the desktop/web app. ## Empty Results @@ -18,4 +17,4 @@ Use this when MCP status, DB readiness, or results are suspicious. - Try contact/session resolution with a simpler keyword. - Try session search before global message search when a target is known. - For Moments, resolve poster identity before timeline filtering. -- If setup is not ready, stop content tools and explain the missing readiness condition. +- If data is not ready, stop content tools and explain that data preparation is handled in the desktop app, not through MCP. diff --git a/skills/wechat-mcp-copilot/references/media.md b/skills/wechat-mcp-copilot/references/media.md index b136682..e769dd8 100644 --- a/skills/wechat-mcp-copilot/references/media.md +++ b/skills/wechat-mcp-copilot/references/media.md @@ -13,7 +13,6 @@ Use this for image, video, emoji, file, link, and voice resources. - `wechat.media.get_decrypted_resource_url` - `wechat.media.get_proxy_image_url` - `wechat.media.get_favicon_url` -- `wechat.media.open_chat_media_folder` - `wechat.biz.get_proxy_image_url` - `wechat.moments.get_media_url` - `wechat.moments.get_article_thumb_url` @@ -25,6 +24,6 @@ Use this for image, video, emoji, file, link, and voice resources. - Media tools return URLs or resource metadata; they do not inline large binary payloads. - Voice resources are files only. Do not transcribe voice messages. - For phone clients, prefer `wechat.mobile.get_media_links` first. -- `open_chat_media_folder` is a desktop-host action; do not use it for phone-only flows. +- MCP does not open local folders or download media into cache; use returned URLs in the client. - Locate the message first, then fetch media URL by message fields such as `server_id`, `username`, `md5`, or returned media references. - For Moments, prefer local media URL fields from timeline records. Use remote video/article helpers only when the timeline record has a remote URL or article URL. diff --git a/skills/wechat-mcp-copilot/references/mobile.md b/skills/wechat-mcp-copilot/references/mobile.md index d34e1cd..6f6a60c 100644 --- a/skills/wechat-mcp-copilot/references/mobile.md +++ b/skills/wechat-mcp-copilot/references/mobile.md @@ -13,18 +13,18 @@ Use this for phone, ScreenMemo, and external MCP clients unless the user needs a - `wechat.mobile.search_moments`: compact Moments search. - `wechat.mobile.get_media_links`: URL-only media lookup. - `wechat.mobile.get_analytics`: compact analytics by metric. -- `wechat.mobile.export_job`: preview/create/status/download/cancel export jobs. ## Budget Rules - Keep `limit` at 10-20 for first calls. - Use `offset` or returned cursor fields for paging. -- Do not call full annual analytics by default; use `metric=digest` or a single card. +- Do not call full annual analytics by default; use `metric=digest` or a single card. Wrapped annual data is cache-only through MCP. - Do not fetch binary media through MCP. Use returned URLs in the app. -- Use low-level tools only for debugging, editing, raw fields, unusual media, or exact export control. +- Use low-level tools only for debugging, raw fields, or unusual media URL construction. +- Data preparation, index/cache build, export, realtime sync, local editing, system settings, and data deletion tools are not exposed through MCP. ## Recovery -- If `ready=false`, load `setup-system.md`. +- If `ready=false`, stop content tools and direct the user to the desktop/web app for data preparation or backend diagnostics. - If target resolution is ambiguous, ask for one clarifying clue or show top candidates. - If search returns nothing, try `resolve_target` and then `get_chat_context` before declaring no data. diff --git a/skills/wechat-mcp-copilot/references/moments.md b/skills/wechat-mcp-copilot/references/moments.md index 85cbaf1..28460d7 100644 --- a/skills/wechat-mcp-copilot/references/moments.md +++ b/skills/wechat-mcp-copilot/references/moments.md @@ -14,5 +14,4 @@ Use this for 朋友圈, posts, likes, comments, shared links, and Moments media. - Person names must be resolved to username before filtering timeline by `usernames`. - Keyword search is for post content/topic, not poster identity. - Do not request raw XML by default. -- Use `wechat.moments.sync_latest` only when the user explicitly wants fresh local sync or status indicates data is stale. - +- Realtime/local sync tools are not exposed through MCP; ask the user to refresh data in the app when Moments data looks stale. diff --git a/skills/wechat-mcp-copilot/references/routing.md b/skills/wechat-mcp-copilot/references/routing.md index 55116c0..6fb9490 100644 --- a/skills/wechat-mcp-copilot/references/routing.md +++ b/skills/wechat-mcp-copilot/references/routing.md @@ -8,17 +8,16 @@ Use this first for every WeChatDataAnalysis MCP task. - Status, readiness, "why can't I find anything": `wechat.core.get_status`, or `wechat.mobile.get_overview` for phone clients. - Available tools or packages: `wechat.core.list_tools`. - Account selection: `wechat.core.list_accounts`, then `wechat.core.get_account_info`. -- Key/decrypt/import/backend health problems: load `setup-system.md`. +- Backend health, logs, MCP LAN access, port, system settings, key/decrypt/import/data preparation, index/cache build, export, realtime sync, local editing, or data deletion requests: explain that these operations are not exposed through MCP and should be handled in the desktop/web app. - Fuzzy person/group/official account: load `target-resolution.md`. - Chat content, recent messages, keyword search: load `chats.md`. - Moments / 朋友圈 / likes / comments / post media: load `moments.md`. - Images, videos, emoji, files, voice resources: load `media.md`. -- Export requests: load `export.md`. -- Rankings, yearly summary, activity stats: load `analytics.md`. -- Empty results or setup errors: load `failure-recovery.md`. +- Rankings, yearly summary, activity stats: load `analytics.md`; if Wrapped cache is missing, ask the user to generate it in the app. +- Empty results or readiness errors: load `failure-recovery.md`. ## Mixed Intent -Resolve the target first, then load only the main domain reference. Do not load chats, moments, media, export, and analytics together unless the user explicitly asks for a broad audit. +Resolve the target first, then load only the main domain reference. Do not load chats, moments, media, and analytics together unless the user explicitly asks for a broad audit. -For phone clients, keep using `mobile.md` until the user needs a low-level fallback such as editing, raw fields, special media URL construction, or exact export options. +For phone clients, keep using `mobile.md` until the user needs a low-level fallback such as raw fields or special media URL construction. diff --git a/skills/wechat-mcp-copilot/references/setup-system.md b/skills/wechat-mcp-copilot/references/setup-system.md deleted file mode 100644 index 65b3c56..0000000 --- a/skills/wechat-mcp-copilot/references/setup-system.md +++ /dev/null @@ -1,41 +0,0 @@ -# Setup And System - -Use this when the database is not ready, keys are needed, decrypted data must be imported, or the backend itself needs inspection. - -## Setup Tools - -- `wechat.setup.get_saved_keys`: read saved DB/media keys for an account or wxid directory. -- `wechat.setup.get_database_key`: desktop workflow to extract the DB key from local WeChat. -- `wechat.setup.get_image_key`: fetch and save image AES/XOR keys. -- `wechat.setup.decrypt_databases`: decrypt databases from `db_storage_path` and a DB key. -- `wechat.setup.get_decrypt_stream_url`: SSE URL for decrypt progress. -- `wechat.setup.preview_import_decrypted`: validate an already-decrypted account directory. -- `wechat.setup.get_import_decrypted_stream_url`: SSE URL for import progress. -- `wechat.setup.cancel_import_decrypted`: cancel an import job by `job_id`. -- `wechat.setup.save_media_keys`: save media XOR/AES keys. -- `wechat.setup.decrypt_all_media`: decrypt all local `.dat` image resources. -- `wechat.setup.get_decrypt_all_media_stream_url`: SSE URL for bulk media decrypt progress. -- `wechat.setup.get_download_all_emojis_stream_url`: SSE URL for bulk emoji download progress. - -## System Tools - -- `wechat.system.health_check` -- `wechat.system.api_root` -- `wechat.system.get_backend_log_file` -- `wechat.system.open_backend_log_file` -- `wechat.system.get_backend_port` -- `wechat.system.set_backend_port_setting` -- `wechat.system.set_backend_port_and_restart` -- `wechat.system.get_img_helper_status` -- `wechat.system.toggle_img_helper` -- `wechat.system.pick_directory` -- `wechat.system.log_frontend_server_error` - -## Rules - -- Stream tools return `streamUrl`; the client consumes SSE outside the MCP JSON response. -- `set_backend_port_setting` persists the setting and may require backend restart by the user/client flow. -- `set_backend_port_and_restart` changes the port through the desktop restart flow and will disrupt the current backend connection. -- `open_backend_log_file` and `pick_directory` are desktop-host GUI actions; do not use them for phone-only flows. -- DB key extraction and image helper toggling depend on the local desktop WeChat state. -- Import/decrypt/media bulk operations write local files; summarize expected impact before running them.