@luoyi-dsh/instagram-mcp 1.0.0 → 1.0.1
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.
- package/README.md +75 -144
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,17 +1,19 @@
|
|
|
1
|
-
# DSH Instagram FastMCP 核心服務插件 (
|
|
1
|
+
# DSH Instagram FastMCP 核心服務插件 (`@luoyi-dsh/instagram-mcp`)
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
> **DeepSeek Harness (DSH)** 官方底層 Instagram 核心服務外掛。
|
|
6
|
+
> 負責自動管理獨立的 Python FastMCP 子進程、維持登入 Session 憑證，並向 DSH Tools 與其他外掛提供標準 Model Context Protocol (MCP) 操作介面。
|
|
5
7
|
|
|
6
8
|
---
|
|
7
9
|
|
|
8
|
-
## 🌟
|
|
10
|
+
## 🌟 核心特性
|
|
9
11
|
|
|
10
12
|
1. **Python 虛擬環境自動維護**：
|
|
11
13
|
- 自動檢測系統 Python / `uv` 環境。
|
|
12
|
-
- 自動於插件目錄建立獨立 `.venv`
|
|
14
|
+
- 自動於插件目錄建立獨立 `.venv` 並安裝依賴清單 (`instagrapi`, `mcp<2`, `pydantic` 等)。
|
|
13
15
|
2. **FastMCP Stdio 子進程生命週期**：
|
|
14
|
-
- 以 MCP 標準 Stdio 通訊協定管理
|
|
16
|
+
- 以 MCP 標準 Stdio 通訊協定管理 Python 伺服器子進程。
|
|
15
17
|
- 支援優雅重啟、斷線重連與進程清理。
|
|
16
18
|
3. **Instagram Session 持久化與雙重驗證**：
|
|
17
19
|
- 支援帳號密碼登入、Session 快取載入 (`data/ig_session.json`) 與 2FA 驗證碼挑戰。
|
|
@@ -22,33 +24,18 @@
|
|
|
22
24
|
|
|
23
25
|
---
|
|
24
26
|
|
|
25
|
-
##
|
|
27
|
+
## 📦 安裝方式
|
|
26
28
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
│ ├── requirements.txt # Python 依賴清單 (instagrapi 等)
|
|
38
|
-
│ ├── server.py # FastMCP Stdio 伺服器入口
|
|
39
|
-
│ ├── auth.py # 帳號認證、Session 復原與 2FA 挑戰
|
|
40
|
-
│ └── core.py # 核心操作 (貼文、留言、私訊、標籤搜尋)
|
|
41
|
-
└── src/
|
|
42
|
-
├── index.ts # Cordis 外掛入口與單例服務掛載
|
|
43
|
-
├── service.ts # InstagramMcpService 服務狀態管理器
|
|
44
|
-
├── config.ts # Schemastery 設定模型定義
|
|
45
|
-
├── types.ts # 型別與資料結構宣告
|
|
46
|
-
├── lib/
|
|
47
|
-
│ ├── env.ts # Python 虛擬環境檢查與依賴安裝
|
|
48
|
-
│ ├── mcp.ts # FastMCP Client 子進程通訊封裝
|
|
49
|
-
│ └── hostdeps.ts # DSH 宿主相容層
|
|
50
|
-
└── tools/
|
|
51
|
-
└── mcpTools.ts # 向 DSH Tools 註冊之 9 項核心工具
|
|
29
|
+
使用 DSH CLI 安裝外掛：
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
dsh plugin --profile web add @luoyi-dsh/instagram-mcp
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
或透過 npm 安裝：
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npm install @luoyi-dsh/instagram-mcp
|
|
52
39
|
```
|
|
53
40
|
|
|
54
41
|
---
|
|
@@ -60,116 +47,46 @@ dsh-instagram-mcp/
|
|
|
60
47
|
| **`ig_check_status`** | 檢查 FastMCP 服務狀態與當前 Instagram 登入情形 | 無 |
|
|
61
48
|
| **`ig_login`** | 登入 Instagram 帳號或重新驗證 Session 快取 | `username`, `password`, `two_factor_code`, `proxy_url` |
|
|
62
49
|
| **`ig_search_hashtag`** | 搜尋指定 Hashtag 標籤之精選/最新貼文清單 | `hashtag` (string), `limit` (number) |
|
|
63
|
-
| **`ig_get_post_context
|
|
50
|
+
| **`ig_get_post_context`** | 抓取指定貼文之完整內文、發布者資訊與相鄰留言上下文 | `media_pk` (string), `comment_limit` (number) |
|
|
64
51
|
| **`ig_post_comment`** | 於指定貼文發表新留言，或對特定留言進行巢狀回覆 | `media_pk` (string), `text` (string), `reply_to_comment_pk` (可選) |
|
|
65
52
|
| **`ig_get_unread_dms`** | 讀取最新或未讀之 Instagram 私訊對話線程 | `limit` (number) |
|
|
66
53
|
| **`ig_send_dm`** | 發送 Instagram Direct Message 私訊給特定線程 | `thread_id` (string), `text` (string) |
|
|
67
|
-
| **`ig_get_timeline_feed
|
|
54
|
+
| **`ig_get_timeline_feed`** | 抓取使用者首頁動態牆 (Timeline Feed) 貼文清單 | `limit` (number) |
|
|
68
55
|
| **`ig_like_media`** | 對指定的 Instagram 貼文按讚 | `media_pk` (string) |
|
|
69
56
|
|
|
70
57
|
---
|
|
71
58
|
|
|
72
|
-
## 💻
|
|
73
|
-
|
|
74
|
-
### 方式一：在 DSH 對話中由主模型自然語言調用
|
|
75
|
-
|
|
76
|
-
只要在 DSH 介面以日常中文提問，AI 即會自動分析意圖並調用相應工具：
|
|
59
|
+
## 💻 使用範例
|
|
77
60
|
|
|
78
|
-
|
|
79
|
-
💬 範例 1：搜尋標籤貼文
|
|
80
|
-
「幫我搜尋 Instagram 上關於 #deepseek 標籤的最新 5 則貼文」
|
|
81
|
-
-> AI 將調用：ig_search_hashtag(hashtag="deepseek", limit=5)
|
|
82
|
-
|
|
83
|
-
💬 範例 2：獲取貼文上下文與留言
|
|
84
|
-
「這篇貼文 PK 是 3123456789012345678，幫我看完整內文與底下留言」
|
|
85
|
-
-> AI 將調用：ig_get_post_context(media_pk="3123456789012345678", comment_limit=10)
|
|
61
|
+
### 1. DSH AI 自然語言直接調用
|
|
86
62
|
|
|
87
|
-
|
|
88
|
-
「在貼文 3123456789012345678 下留言：『很實用的架構分享，收藏了！』」
|
|
89
|
-
-> AI 將調用：ig_post_comment(media_pk="3123456789012345678", text="很實用的架構分享，收藏了！")
|
|
63
|
+
在 DSH 對話中，AI 模型會根據上下文自動調用合適的 MCP 工具：
|
|
90
64
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
「發送私訊給線程 17841400000000000 說：『您好，已收到您的諮詢，稍後聯絡！』」
|
|
97
|
-
-> AI 將調用：ig_send_dm(thread_id="17841400000000000", text="您好，已收到您的諮詢，稍後聯絡！")
|
|
98
|
-
```
|
|
65
|
+
- **搜尋標籤**：「幫我搜尋 Instagram 上關於 #deepseek 標籤的最新 5 則貼文」
|
|
66
|
+
- **貼文內文與留言**：「這篇貼文 PK 是 3123456789012345678，幫我看完整內文與留言」
|
|
67
|
+
- **發表留言**：「在貼文 3123456789012345678 下留言：『架構非常完整，感謝分享！』」
|
|
68
|
+
- **檢查私訊**：「查看我目前有沒有未讀的 Instagram 私訊」
|
|
69
|
+
- **發送私訊**：「發送私訊給線程 17841400000000000 說：『您好，已收到您的諮詢！』」
|
|
99
70
|
|
|
100
|
-
|
|
71
|
+
### 2. TypeScript / Node.js 跨插件調用
|
|
101
72
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
#### 1. 搜尋標籤 (`ig_search_hashtag`)
|
|
105
|
-
```json
|
|
106
|
-
{
|
|
107
|
-
"jsonrpc": "2.0",
|
|
108
|
-
"id": 1,
|
|
109
|
-
"method": "tools/call",
|
|
110
|
-
"params": {
|
|
111
|
-
"name": "ig_search_hashtag",
|
|
112
|
-
"arguments": {
|
|
113
|
-
"hashtag": "coding",
|
|
114
|
-
"limit": 8
|
|
115
|
-
}
|
|
116
|
-
}
|
|
117
|
-
}
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
#### 2. 發布貼文留言 (`ig_post_comment`)
|
|
121
|
-
```json
|
|
122
|
-
{
|
|
123
|
-
"jsonrpc": "2.0",
|
|
124
|
-
"id": 2,
|
|
125
|
-
"method": "tools/call",
|
|
126
|
-
"params": {
|
|
127
|
-
"name": "ig_post_comment",
|
|
128
|
-
"arguments": {
|
|
129
|
-
"media_pk": "3123456789012345678",
|
|
130
|
-
"text": "寫得很詳盡！謝謝分享。"
|
|
131
|
-
}
|
|
132
|
-
}
|
|
133
|
-
}
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
#### 3. 貼文點讚 (`ig_like_media`)
|
|
137
|
-
```json
|
|
138
|
-
{
|
|
139
|
-
"jsonrpc": "2.0",
|
|
140
|
-
"id": 3,
|
|
141
|
-
"method": "tools/call",
|
|
142
|
-
"params": {
|
|
143
|
-
"name": "ig_like_media",
|
|
144
|
-
"arguments": {
|
|
145
|
-
"media_pk": "3123456789012345678"
|
|
146
|
-
}
|
|
147
|
-
}
|
|
148
|
-
}
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
---
|
|
152
|
-
|
|
153
|
-
### 方式三：在 TypeScript / Node.js 程式碼中跨插件調用
|
|
154
|
-
|
|
155
|
-
任何其他 DSH 外掛（如 `dsh-instagram-plugin`、`dsh-instagram-scroll`）皆可直接透過單例匯入調用底層客戶端：
|
|
73
|
+
其他 DSH 外掛（如業務層擴充插件）可直接匯入單例客戶端：
|
|
156
74
|
|
|
157
75
|
```typescript
|
|
158
|
-
import { getSharedMcpClient } from 'dsh
|
|
76
|
+
import { getSharedMcpClient } from '@luoyi-dsh/instagram-mcp'
|
|
159
77
|
|
|
160
78
|
const mcpClient = getSharedMcpClient()
|
|
161
79
|
if (mcpClient && mcpClient.ready) {
|
|
162
|
-
//
|
|
80
|
+
// 搜尋指定標籤
|
|
163
81
|
const posts = await mcpClient.igSearchHashtag('tech', 10)
|
|
164
|
-
console.log('搜尋結果:', posts)
|
|
165
82
|
|
|
166
|
-
//
|
|
83
|
+
// 抓取貼文詳細內容
|
|
167
84
|
const context = await mcpClient.igGetPostContext('3123456789012345678', 5)
|
|
168
85
|
|
|
169
|
-
//
|
|
86
|
+
// 發送私訊
|
|
170
87
|
await mcpClient.igSendDm({
|
|
171
88
|
thread_id: '17841400000000000',
|
|
172
|
-
text: '感謝您的來訊！'
|
|
89
|
+
text: '感謝您的來訊！',
|
|
173
90
|
})
|
|
174
91
|
}
|
|
175
92
|
```
|
|
@@ -178,36 +95,50 @@ if (mcpClient && mcpClient.ready) {
|
|
|
178
95
|
|
|
179
96
|
## ⚙️ 設定參數說明
|
|
180
97
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
可於 DSH 設定面板或 `data/config.json` 中配置：
|
|
98
|
+
可於 DSH 設定面板或插件目錄下的 `data/config.json` 中配置：
|
|
184
99
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
100
|
+
| 欄位名稱 | 型別 | 預設值 | 說明 |
|
|
101
|
+
| :--- | :--- | :--- | :--- |
|
|
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 子進程並嘗試登入 |
|
|
192
109
|
|
|
193
110
|
---
|
|
194
111
|
|
|
195
|
-
##
|
|
112
|
+
## 📁 目錄結構
|
|
196
113
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
114
|
+
```text
|
|
115
|
+
dsh-instagram-mcp/
|
|
116
|
+
├── cordis.patch.yml # DSH bundle patch 宣告
|
|
117
|
+
├── package.json # 模組定義與依賴宣告
|
|
118
|
+
├── tsconfig.json # TypeScript 編譯設定
|
|
119
|
+
├── assets/
|
|
120
|
+
│ └── banner.png # 宣傳圖示與橫幅
|
|
121
|
+
├── vendor/
|
|
122
|
+
│ └── instagram-mcp/ # 獨立 Python FastMCP 核心模組
|
|
123
|
+
│ ├── requirements.txt # Python 依賴清單
|
|
124
|
+
│ ├── server.py # FastMCP Stdio 伺服器入口
|
|
125
|
+
│ ├── auth.py # 帳號認證、Session 復原與 2FA
|
|
126
|
+
│ └── core.py # 貼文、留言、私訊、標籤等核心操作
|
|
127
|
+
└── src/
|
|
128
|
+
├── index.ts # 外掛入口與單例服務掛載
|
|
129
|
+
├── service.ts # InstagramMcpService 服務狀態管理器
|
|
130
|
+
├── config.ts # Schemastery 設定模型定義
|
|
131
|
+
├── types.ts # 型別與資料結構宣告
|
|
132
|
+
├── lib/
|
|
133
|
+
│ ├── env.ts # Python 虛擬環境檢查與依賴安裝
|
|
134
|
+
│ ├── mcp.ts # FastMCP Client 子進程通訊封裝
|
|
135
|
+
│ └── hostdeps.ts # DSH 宿主相容層
|
|
136
|
+
└── tools/
|
|
137
|
+
└── mcpTools.ts # 向 DSH Tools 註冊之 9 項核心工具
|
|
202
138
|
```
|
|
203
139
|
|
|
204
|
-
|
|
205
|
-
```powershell
|
|
206
|
-
dsh plugin --profile web add link:c:\Users\asiat\Downloads\dsh\dsh-instagram-mcp
|
|
207
|
-
```
|
|
140
|
+
---
|
|
208
141
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
powershell -ExecutionPolicy Bypass -File .\Updata_Plugin_Instagram.ps1
|
|
213
|
-
```
|
|
142
|
+
## 📄 授權條款
|
|
143
|
+
|
|
144
|
+
本專案採用 [MIT License](LICENSE) 開源授權。
|