@luoyi-dsh/instagram-mcp 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.md +128 -76
  2. package/README.zh-Hant.md +196 -0
  3. package/client.js +870 -0
  4. package/cordis.patch.yml +1 -1
  5. package/dist/index.d.ts.map +1 -1
  6. package/dist/index.js +139 -5
  7. package/dist/index.js.map +1 -1
  8. package/dist/service.d.ts +6 -0
  9. package/dist/service.d.ts.map +1 -1
  10. package/dist/service.js.map +1 -1
  11. package/dist/tools/mcpTools.d.ts.map +1 -1
  12. package/dist/tools/mcpTools.js +6 -0
  13. package/dist/tools/mcpTools.js.map +1 -1
  14. package/package.json +11 -1
package/README.md CHANGED
@@ -1,38 +1,46 @@
1
- # DSH Instagram FastMCP 核心服務插件 (`@luoyi-dsh/instagram-mcp`)
1
+ # DSH Instagram FastMCP Core Service Plugin (`@luoyi-dsh/instagram-mcp`)
2
2
 
3
- ![Banner](assets/banner.png)
3
+ <div align="center">
4
4
 
5
- > **DeepSeek Harness (DSH)** 官方底層 Instagram 核心服務外掛。
6
- > 負責自動管理獨立的 Python FastMCP 子進程、維持登入 Session 憑證，並向 DSH Tools 與其他外掛提供標準 Model Context Protocol (MCP) 操作介面。
5
+ ![DSH Instagram MCP Banner](assets/banner.png)
6
+
7
+ **[English](README.md) | [繁體中文](README.zh-Hant.md)**
8
+
9
+ </div>
10
+
11
+ > Official foundational Instagram FastMCP service plugin for **DeepSeek Harness (DSH)**.
12
+ > Manages the Python FastMCP child process lifecycle, maintains persistent Instagram session credentials and 2FA challenges, and provides standard Model Context Protocol (MCP) tools for DSH AI models and consumer plugins.
7
13
 
8
14
  ---
9
15
 
10
- ## 🌟 核心特性
11
-
12
- 1. **Python 虛擬環境自動維護**：
13
- - 自動檢測系統 Python / `uv` 環境。
14
- - 自動於插件目錄建立獨立 `.venv` 並安裝依賴清單 (`instagrapi`, `mcp<2`, `pydantic` 等)。
15
- 2. **FastMCP Stdio 子進程生命週期**：
16
- - 以 MCP 標準 Stdio 通訊協定管理 Python 伺服器子進程。
17
- - 支援優雅重啟、斷線重連與進程清理。
18
- 3. **Instagram Session 持久化與雙重驗證**：
19
- - 支援帳號密碼登入、Session 快取載入 (`data/ig_session.json`) 與 2FA 驗證碼挑戰。
20
- 4. **全域單例共享服務 (Zero-Error Singleton)**：
21
- - 導出 `getSharedMcpService()` 與 `getSharedMcpClient()`，供業務層插件 (`dsh-instagram-plugin`、`dsh-instagram-scroll`) 安全共享底層連線與登入狀態，完全免除 Cordis 的屬性存取拋錯。
22
- 5. **標準 MCP Tools 註冊**：
23
- - 向 DSH `ctx.tools` 註冊 9 項 Instagram 核心底層工具，供 AI 主模型直接調用。
16
+ ## 🌟 Key Features
17
+
18
+ 1. **Automated Python Environment Management**:
19
+ - Auto-detects host Python or `uv` environments.
20
+ - Automatically initializes an isolated `.venv` within the vendor directory and provisions all dependencies (`instagrapi`, `mcp<2`, `pydantic`, etc.).
21
+ 2. **FastMCP Stdio Subprocess Lifecycle**:
22
+ - Manages Python MCP server over standard stdio protocol.
23
+ - Supports graceful restarts, reconnection handling, and automatic process teardown on shutdown.
24
+ 3. **Session Persistence & 2FA Handling**:
25
+ - Supports username/password authentication, persistent session cache reuse (`data/ig_session.json`), and interactive two-factor authentication (2FA) challenges.
26
+ 4. **Zero-Error Shared Singleton Service**:
27
+ - Exports `getSharedMcpService()` and `getSharedMcpClient()`, enabling consumer plugins (`dsh-instagram-plugin`, `dsh-instagram-scroll`) to safely access underlying connections and login state without Cordis property access errors.
28
+ 5. **9 Standard Model Context Protocol (MCP) Tools**:
29
+ - Registers 9 core Instagram primitives with DSH `ctx.tools` for direct AI function calling.
30
+ 6. **Dedicated Web REST API**:
31
+ - Exposes `/api/instagram/mcp/*` endpoints to read/update configuration, query live daemon and login health, reboot the subprocess, and perform credential checks.
24
32
 
25
33
  ---
26
34
 
27
- ## 📦 安裝方式
35
+ ## 📦 Installation
28
36
 
29
- 使用 DSH CLI 安裝外掛：
37
+ Install via DSH Plugin CLI:
30
38
 
31
39
  ```bash
32
40
  dsh plugin --profile web add @luoyi-dsh/instagram-mcp
33
41
  ```
34
42
 
35
- 或透過 npm 安裝：
43
+ Or via standard npm:
36
44
 
37
45
  ```bash
38
46
  npm install @luoyi-dsh/instagram-mcp
@@ -40,105 +48,149 @@ npm install @luoyi-dsh/instagram-mcp
40
48
 
41
49
  ---
42
50
 
43
- ## 🛠️ 提供之 9 項標準 MCP 工具
51
+ ## 🛠️ Provided MCP Tools (9 Core Primitives)
44
52
 
45
- | 工具名稱 | 說明 | 參數 |
53
+ | Tool Name | Description | Parameters |
46
54
  | :--- | :--- | :--- |
47
- | **`ig_check_status`** | 檢查 FastMCP 服務狀態與當前 Instagram 登入情形 | 無 |
48
- | **`ig_login`** | 登入 Instagram 帳號或重新驗證 Session 快取 | `username`, `password`, `two_factor_code`, `proxy_url` |
49
- | **`ig_search_hashtag`** | 搜尋指定 Hashtag 標籤之精選/最新貼文清單 | `hashtag` (string), `limit` (number) |
50
- | **`ig_get_post_context`** | 抓取指定貼文之完整內文、發布者資訊與相鄰留言上下文 | `media_pk` (string), `comment_limit` (number) |
51
- | **`ig_post_comment`** | 於指定貼文發表新留言，或對特定留言進行巢狀回覆 | `media_pk` (string), `text` (string), `reply_to_comment_pk` (可選) |
52
- | **`ig_get_unread_dms`** | 讀取最新或未讀之 Instagram 私訊對話線程 | `limit` (number) |
53
- | **`ig_send_dm`** | 發送 Instagram Direct Message 私訊給特定線程 | `thread_id` (string), `text` (string) |
54
- | **`ig_get_timeline_feed`** | 抓取使用者首頁動態牆 (Timeline Feed) 貼文清單 | `limit` (number) |
55
- | **`ig_like_media`** | 對指定的 Instagram 貼文按讚 | `media_pk` (string) |
55
+ | **`ig_check_status`** | Check FastMCP service status and current Instagram login details | None |
56
+ | **`ig_login`** | Authenticate Instagram account or validate existing session cache | `username`, `password`, `two_factor_code`, `proxy_url` |
57
+ | **`ig_search_hashtag`** | Search top and recent posts for a specified hashtag | `hashtag` (string), `limit` (number) |
58
+ | **`ig_get_post_context`** | Fetch complete post caption, author metadata, and adjacent comments | `media_pk` (string), `comment_limit` (number) |
59
+ | **`ig_post_comment`** | Publish a comment or reply to an existing comment on a post | `media_pk` (string), `text` (string), `reply_to_comment_pk` (optional) |
60
+ | **`ig_get_unread_dms`** | Read unread or latest Instagram direct message threads | `limit` (number) |
61
+ | **`ig_send_dm`** | Send a direct message to a specific thread | `thread_id` (string), `text` (string) |
62
+ | **`ig_get_timeline_feed`** | Retrieve posts from user's timeline feed | `limit` (number) |
63
+ | **`ig_like_media`** | Like a specific Instagram post | `media_pk` (string) |
56
64
 
57
65
  ---
58
66
 
59
- ## 💻 使用範例
67
+ ## 💻 Usage Examples
68
+
69
+ ### 1. Natural Language Invocation in DSH Chat
70
+
71
+ In DSH conversations, the host model automatically determines and calls appropriate MCP tools:
72
+
73
+ - **Search Hashtags**: "Search for the top 5 recent posts under #deepseek on Instagram."
74
+ - **Inspect Post Details**: "Look up post PK 3123456789012345678 and show me the full caption and comments."
75
+ - **Leave Comments**: "Comment on post 3123456789012345678: 'Great architecture overview, thanks for sharing!'"
76
+ - **Check DMs**: "Check if I have any unread direct messages on Instagram."
77
+ - **Send Direct Message**: "Send a DM to thread 17841400000000000 saying: 'Hello, inquiry received!'"
78
+
79
+ ### 2. Via HTTP REST API (DSH Web Routes)
60
80
 
61
- ### 1. DSH AI 自然語言直接調用
81
+ > 💡 **Tip**: Default DSH Web port is **3080**.
62
82
 
63
- 在 DSH 對話中，AI 模型會根據上下文自動調用合適的 MCP 工具：
83
+ - **Read Configuration**:
84
+ ```bash
85
+ curl http://127.0.0.1:3080/api/instagram/mcp/config
86
+ ```
64
87
 
65
- - **搜尋標籤**：「幫我搜尋 Instagram 上關於 #deepseek 標籤的最新 5 則貼文」
66
- - **貼文內文與留言**：「這篇貼文 PK 是 3123456789012345678，幫我看完整內文與留言」
67
- - **發表留言**：「在貼文 3123456789012345678 下留言：『架構非常完整，感謝分享！』」
68
- - **檢查私訊**：「查看我目前有沒有未讀的 Instagram 私訊」
69
- - **發送私訊**：「發送私訊給線程 17841400000000000 說：『您好，已收到您的諮詢！』」
88
+ - **Update Configuration**:
89
+ ```bash
90
+ curl -X POST http://127.0.0.1:3080/api/instagram/mcp/config \
91
+ -H "Content-Type: application/json" \
92
+ -d '{"autoStart":true}'
93
+ ```
70
94
 
71
- ### 2. TypeScript / Node.js 跨插件調用
95
+ - **Get Service Health & Login Status**:
96
+ ```bash
97
+ curl http://127.0.0.1:3080/api/instagram/mcp/status
98
+ ```
72
99
 
73
- 其他 DSH 外掛（如業務層擴充插件）可直接匯入單例客戶端：
100
+ - **Restart FastMCP Subprocess**:
101
+ ```bash
102
+ curl -X POST http://127.0.0.1:3080/api/instagram/mcp/restart
103
+ ```
104
+
105
+ - **Perform Login / 2FA Challenge**:
106
+ ```bash
107
+ curl -X POST http://127.0.0.1:3080/api/instagram/mcp/login \
108
+ -H "Content-Type: application/json" \
109
+ -d '{"username":"your_user","password":"your_password"}'
110
+ ```
111
+
112
+ ### 3. Cross-Plugin TypeScript / Node.js API
113
+
114
+ Consumer DSH plugins can directly import and call the shared client:
74
115
 
75
116
  ```typescript
76
117
  import { getSharedMcpClient } from '@luoyi-dsh/instagram-mcp'
77
118
 
78
119
  const mcpClient = getSharedMcpClient()
79
120
  if (mcpClient && mcpClient.ready) {
80
- // 搜尋指定標籤
121
+ // Search hashtag
81
122
  const posts = await mcpClient.igSearchHashtag('tech', 10)
82
123
 
83
- // 抓取貼文詳細內容
124
+ // Fetch post details
84
125
  const context = await mcpClient.igGetPostContext('3123456789012345678', 5)
85
126
 
86
- // 發送私訊
127
+ // Send Direct Message
87
128
  await mcpClient.igSendDm({
88
129
  thread_id: '17841400000000000',
89
- text: '感謝您的來訊！',
130
+ text: 'Thanks for reaching out!',
90
131
  })
91
132
  }
92
133
  ```
93
134
 
94
135
  ---
95
136
 
96
- ## ⚙️ 設定參數說明
137
+ ## ⚙️ Configuration Parameters
97
138
 
98
- 可於 DSH 設定面板或插件目錄下的 `data/config.json` 中配置：
139
+ Configurable via the DSH Web UI or `data/config.json`:
99
140
 
100
- | 欄位名稱 | 型別 | 預設值 | 說明 |
141
+ | Field | Type | Default | Description |
101
142
  | :--- | :--- | :--- | :--- |
102
- | **`username`** | string | `""` | Instagram 使用者名稱 |
103
- | **`password`** | string | `""` | Instagram 登入密碼（存在有效 Session 時可留空） |
104
- | **`twoFactorCode`** | string | `""` | 2FA 雙步驟驗證碼 |
105
- | **`sessionPath`** | string | `"data/ig_session.json"` | Session 快取檔案路徑 |
106
- | **`proxyUrl`** | string | `""` | 代理伺服器 URL（例如 `http://127.0.0.1:7890`，選填） |
107
- | **`pythonPath`** | string | `""` | 自訂 Python 可執行檔路徑（留空則自動探測系統 Python / uv） |
108
- | **`autoStart`** | boolean | `true` | 啟動 DSH 時是否自動啟動 FastMCP 子進程並嘗試登入 |
143
+ | **`username`** | string | `""` | Instagram username |
144
+ | **`password`** | string | `""` | Instagram password (can be left blank if valid session exists) |
145
+ | **`twoFactorCode`** | string | `""` | 2FA two-step verification code |
146
+ | **`sessionPath`** | string | `"data/ig_session.json"` | Path to the session cache file |
147
+ | **`proxyUrl`** | string | `""` | Outbound proxy URL (e.g. `http://127.0.0.1:7890`, optional) |
148
+ | **`pythonPath`** | string | `""` | Custom Python binary path (auto-detects Python / uv if blank) |
149
+ | **`autoStart`** | boolean | `true` | Automatically launch FastMCP subprocess and authenticate on startup |
109
150
 
110
151
  ---
111
152
 
112
- ## 📁 目錄結構
153
+ ## 📁 Directory Structure
113
154
 
114
155
  ```text
115
156
  dsh-instagram-mcp/
116
- ├── cordis.patch.yml # DSH bundle patch 宣告
117
- ├── package.json # 模組定義與依賴宣告
118
- ├── tsconfig.json # TypeScript 編譯設定
157
+ ├── cordis.patch.yml # DSH bundle patch manifest
158
+ ├── package.json # Module definitions and dependencies
159
+ ├── tsconfig.json # TypeScript compiler configuration
160
+ ├── CHANGELOG.md # Version release notes
161
+ ├── README.md # English documentation (This file)
162
+ ├── README.zh-Hant.md # Traditional Chinese documentation
119
163
  ├── assets/
120
- │ └── banner.png # 宣傳圖示與橫幅
164
+ │ ├── banner.png # Promotional banner
165
+ │ └── zh-Hant.md # Localized documentation
166
+ ├── client.js # DSH Web UI control panel
121
167
  ├── vendor/
122
- │ └── instagram-mcp/ # 獨立 Python FastMCP 核心模組
123
- │ ├── requirements.txt # Python 依賴清單
124
- │ ├── server.py # FastMCP Stdio 伺服器入口
125
- │ ├── auth.py # 帳號認證、Session 復原與 2FA
126
- │ └── core.py # 貼文、留言、私訊、標籤等核心操作
168
+ │ └── instagram-mcp/ # Standalone Python FastMCP core
169
+ │ ├── requirements.txt # Python dependencies
170
+ │ ├── server.py # FastMCP Stdio server entrypoint
171
+ │ ├── auth.py # Authentication, session restoration & 2FA
172
+ │ └── core.py # Core operations (posts, comments, DMs, tags)
127
173
  └── src/
128
- ├── index.ts # 外掛入口與單例服務掛載
129
- ├── service.ts # InstagramMcpService 服務狀態管理器
130
- ├── config.ts # Schemastery 設定模型定義
131
- ├── types.ts # 型別與資料結構宣告
174
+ ├── index.ts # Plugin entrypoint, singleton service, and REST API
175
+ ├── service.ts # InstagramMcpService runtime status manager
176
+ ├── config.ts # Schemastery config schema
177
+ ├── types.ts # TypeScript interfaces
132
178
  ├── lib/
133
- │ ├── env.ts # Python 虛擬環境檢查與依賴安裝
134
- │ ├── mcp.ts # FastMCP Client 子進程通訊封裝
135
- │ └── hostdeps.ts # DSH 宿主相容層
179
+ │ ├── env.ts # Python venv validation & package installer
180
+ │ ├── mcp.ts # FastMCP client subprocess wrapper
181
+ │ └── hostdeps.ts # DSH runtime compatibility layer
136
182
  └── tools/
137
- └── mcpTools.ts # 向 DSH Tools 註冊之 9 項核心工具
183
+ └── mcpTools.ts # 9 core MCP tools registration
138
184
  ```
139
185
 
140
186
  ---
141
187
 
142
- ## 📄 授權條款
188
+ ## 📜 Releases & Changelog
189
+
190
+ For detailed release history and changes, please refer to [CHANGELOG.md](CHANGELOG.md).
191
+
192
+ ---
193
+
194
+ ## 📄 License
143
195
 
144
- 本專案採用 [MIT License](LICENSE) 開源授權。
196
+ This project is licensed under the [MIT License](LICENSE).
package/README.zh-Hant.md ADDED
@@ -0,0 +1,196 @@
1
+ # DSH Instagram FastMCP 核心服務插件 (`@luoyi-dsh/instagram-mcp`)
2
+
3
+ <div align="center">
4
+
5
+ ![DSH Instagram MCP Banner](assets/banner.png)
6
+
7
+ **[English](README.md) | [繁體中文](README.zh-Hant.md)**
8
+
9
+ </div>
10
+
11
+ > **DeepSeek Harness (DSH)** 官方底層 Instagram 核心服務外掛。
12
+ > 負責自動管理獨立的 Python FastMCP 子進程、維持登入 Session 憑證，並向 DSH Tools 與其他外掛提供標準 Model Context Protocol (MCP) 操作介面。
13
+
14
+ ---
15
+
16
+ ## 🌟 核心特性
17
+
18
+ 1. **Python 虛擬環境自動維護**：
19
+ - 自動檢測系統 Python / `uv` 環境。
20
+ - 自動於插件目錄建立獨立 `.venv` 並安裝依賴清單 (`instagrapi`, `mcp<2`, `pydantic` 等)。
21
+ 2. **FastMCP Stdio 子進程生命週期**：
22
+ - 以 MCP 標準 Stdio 通訊協定管理 Python 伺服器子進程。
23
+ - 支援優雅重啟、斷線重連與進程清理。
24
+ 3. **Instagram Session 持久化與雙重驗證**：
25
+ - 支援帳號密碼登入、Session 快取載入 (`data/ig_session.json`) 與 2FA 驗證碼挑戰。
26
+ 4. **全域單例共享服務 (Zero-Error Singleton)**：
27
+ - 導出 `getSharedMcpService()` 與 `getSharedMcpClient()`，供業務層插件 (`dsh-instagram-plugin`、`dsh-instagram-scroll`) 安全共享底層連線與登入狀態，完全免除 Cordis 的屬性存取拋錯。
28
+ 5. **標準 MCP Tools 註冊**：
29
+ - 向 DSH `ctx.tools` 註冊 9 項 Instagram 核心底層工具，供 AI 主模型直接調用。
30
+ 6. **專屬 Web REST API**：
31
+ - 提供 `/api/instagram/mcp/*` 路由供前端控制面板讀寫配置、查詢運行狀態、重啟子進程及進行登入挑戰。
32
+
33
+ ---
34
+
35
+ ## 📦 安裝方式
36
+
37
+ 使用 DSH CLI 安裝外掛：
38
+
39
+ ```bash
40
+ dsh plugin --profile web add @luoyi-dsh/instagram-mcp
41
+ ```
42
+
43
+ 或透過 npm 安裝：
44
+
45
+ ```bash
46
+ npm install @luoyi-dsh/instagram-mcp
47
+ ```
48
+
49
+ ---
50
+
51
+ ## 🛠️ 提供之 9 項標準 MCP 工具
52
+
53
+ | 工具名稱 | 說明 | 參數 |
54
+ | :--- | :--- | :--- |
55
+ | **`ig_check_status`** | 檢查 FastMCP 服務狀態與當前 Instagram 登入情形 | 無 |
56
+ | **`ig_login`** | 登入 Instagram 帳號或重新驗證 Session 快取 | `username`, `password`, `two_factor_code`, `proxy_url` |
57
+ | **`ig_search_hashtag`** | 搜尋指定 Hashtag 標籤之精選/最新貼文清單 | `hashtag` (string), `limit` (number) |
58
+ | **`ig_get_post_context`** | 抓取指定貼文之完整內文、發布者資訊與相鄰留言上下文 | `media_pk` (string), `comment_limit` (number) |
59
+ | **`ig_post_comment`** | 於指定貼文發表新留言，或對特定留言進行巢狀回覆 | `media_pk` (string), `text` (string), `reply_to_comment_pk` (可選) |
60
+ | **`ig_get_unread_dms`** | 讀取最新或未讀之 Instagram 私訊對話線程 | `limit` (number) |
61
+ | **`ig_send_dm`** | 發送 Instagram Direct Message 私訊給特定線程 | `thread_id` (string), `text` (string) |
62
+ | **`ig_get_timeline_feed`** | 抓取使用者首頁動態牆 (Timeline Feed) 貼文清單 | `limit` (number) |
63
+ | **`ig_like_media`** | 對指定的 Instagram 貼文按讚 | `media_pk` (string) |
64
+
65
+ ---
66
+
67
+ ## 💻 使用範例
68
+
69
+ ### 1. DSH AI 自然語言直接調用
70
+
71
+ 在 DSH 對話中，AI 模型會根據上下文自動調用合適的 MCP 工具：
72
+
73
+ - **搜尋標籤**：「幫我搜尋 Instagram 上關於 #deepseek 標籤的最新 5 則貼文」
74
+ - **貼文內文與留言**：「這篇貼文 PK 是 3123456789012345678，幫我看完整內文與留言」
75
+ - **發表留言**：「在貼文 3123456789012345678 下留言：『架構非常完整，感謝分享！』」
76
+ - **檢查私訊**：「查看我目前有沒有未讀的 Instagram 私訊」
77
+ - **發送私訊**：「發送私訊給線程 17841400000000000 說：『您好，已收到您的諮詢！』」
78
+
79
+ ### 2. 透過 HTTP REST API 調用 (DSH Web 路由)
80
+
81
+ > 💡 **提示**：DSH Web 預設埠號為 **3080**。
82
+
83
+ - **取得當前 MCP 配置**：
84
+ ```bash
85
+ curl http://127.0.0.1:3080/api/instagram/mcp/config
86
+ ```
87
+
88
+ - **更新 MCP 配置**：
89
+ ```bash
90
+ curl -X POST http://127.0.0.1:3080/api/instagram/mcp/config \
91
+ -H "Content-Type: application/json" \
92
+ -d '{"autoStart":true}'
93
+ ```
94
+
95
+ - **獲取 MCP 運行與登入狀態**：
96
+ ```bash
97
+ curl http://127.0.0.1:3080/api/instagram/mcp/status
98
+ ```
99
+
100
+ - **重啟 FastMCP 子進程**：
101
+ ```bash
102
+ curl -X POST http://127.0.0.1:3080/api/instagram/mcp/restart
103
+ ```
104
+
105
+ - **手動觸發登入 / 2FA 驗證**：
106
+ ```bash
107
+ curl -X POST http://127.0.0.1:3080/api/instagram/mcp/login \
108
+ -H "Content-Type: application/json" \
109
+ -d '{"username":"your_user","password":"your_password"}'
110
+ ```
111
+
112
+ ### 3. TypeScript / Node.js 跨插件調用
113
+
114
+ 其他 DSH 外掛（如業務層擴充插件）可直接匯入單例客戶端：
115
+
116
+ ```typescript
117
+ import { getSharedMcpClient } from '@luoyi-dsh/instagram-mcp'
118
+
119
+ const mcpClient = getSharedMcpClient()
120
+ if (mcpClient && mcpClient.ready) {
121
+ // 搜尋指定標籤
122
+ const posts = await mcpClient.igSearchHashtag('tech', 10)
123
+
124
+ // 抓取貼文詳細內容
125
+ const context = await mcpClient.igGetPostContext('3123456789012345678', 5)
126
+
127
+ // 發送私訊
128
+ await mcpClient.igSendDm({
129
+ thread_id: '17841400000000000',
130
+ text: '感謝您的來訊！',
131
+ })
132
+ }
133
+ ```
134
+
135
+ ---
136
+
137
+ ## ⚙️ 設定參數說明
138
+
139
+ 可於 DSH 設定面板或插件目錄下的 `data/config.json` 中配置：
140
+
141
+ | 欄位名稱 | 型別 | 預設值 | 說明 |
142
+ | :--- | :--- | :--- | :--- |
143
+ | **`username`** | string | `""` | Instagram 使用者名稱 |
144
+ | **`password`** | string | `""` | Instagram 登入密碼（存在有效 Session 時可留空） |
145
+ | **`twoFactorCode`** | string | `""` | 2FA 雙步驟驗證碼 |
146
+ | **`sessionPath`** | string | `"data/ig_session.json"` | Session 快取檔案路徑 |
147
+ | **`proxyUrl`** | string | `""` | 代理伺服器 URL（例如 `http://127.0.0.1:7890`，選填） |
148
+ | **`pythonPath`** | string | `""` | 自訂 Python 可執行檔路徑（留空則自動探測系統 Python / uv） |
149
+ | **`autoStart`** | boolean | `true` | 啟動 DSH 時是否自動啟動 FastMCP 子進程並嘗試登入 |
150
+
151
+ ---
152
+
153
+ ## 📁 目錄結構
154
+
155
+ ```text
156
+ dsh-instagram-mcp/
157
+ ├── cordis.patch.yml # DSH bundle patch 宣告
158
+ ├── package.json # 模組定義與依賴宣告
159
+ ├── tsconfig.json # TypeScript 編譯設定
160
+ ├── CHANGELOG.md # 版本更新紀錄
161
+ ├── README.md # 英文說明文件
162
+ ├── README.zh-Hant.md # 繁體中文說明文件
163
+ ├── assets/
164
+ │ ├── banner.png # 宣傳圖示與橫幅
165
+ │ └── zh-Hant.md # 本地化說明文件
166
+ ├── client.js # DSH Web 前端面板
167
+ ├── vendor/
168
+ │ └── instagram-mcp/ # 獨立 Python FastMCP 核心模組
169
+ │ ├── requirements.txt # Python 依賴清單
170
+ │ ├── server.py # FastMCP Stdio 伺服器入口
171
+ │ ├── auth.py # 帳號認證、Session 復原與 2FA
172
+ │ └── core.py # 貼文、留言、私訊、標籤等核心操作
173
+ └── src/
174
+ ├── index.ts # 外掛入口、單例服務掛載與 REST API
175
+ ├── service.ts # InstagramMcpService 服務狀態管理器
176
+ ├── config.ts # Schemastery 設定模型定義
177
+ ├── types.ts # 型別與資料結構宣告
178
+ ├── lib/
179
+ │ ├── env.ts # Python 虛擬環境檢查與依賴安裝
180
+ │ ├── mcp.ts # FastMCP Client 子進程通訊封裝
181
+ │ └── hostdeps.ts # DSH 宿主相容層
182
+ └── tools/
183
+ └── mcpTools.ts # 向 DSH Tools 註冊之 9 項核心工具
184
+ ```
185
+
186
+ ---
187
+
188
+ ## 📜 版本發布紀錄 (Releases)
189
+
190
+ 詳細版本演進與更新紀錄，請參閱 [CHANGELOG.md](CHANGELOG.md)。
191
+
192
+ ---
193
+
194
+ ## 📄 授權條款
195
+
196
+ 本專案採用 [MIT License](LICENSE) 開源授權。