@luoyi-dsh/instagram-mcp 1.0.0 → 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.
- package/README.md +141 -158
- package/README.zh-Hant.md +196 -0
- package/client.js +870 -0
- package/cordis.patch.yml +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +139 -5
- package/dist/index.js.map +1 -1
- package/dist/service.d.ts +6 -0
- package/dist/service.d.ts.map +1 -1
- package/dist/service.js.map +1 -1
- package/dist/tools/mcpTools.d.ts.map +1 -1
- package/dist/tools/mcpTools.js +6 -0
- package/dist/tools/mcpTools.js.map +1 -1
- package/package.json +11 -1
package/README.md
CHANGED
|
@@ -1,213 +1,196 @@
|
|
|
1
|
-
# DSH Instagram FastMCP
|
|
1
|
+
# DSH Instagram FastMCP Core Service Plugin (`@luoyi-dsh/instagram-mcp`)
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
|
|
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.
|
|
5
13
|
|
|
6
14
|
---
|
|
7
15
|
|
|
8
|
-
## 🌟
|
|
9
|
-
|
|
10
|
-
1. **Python
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
2. **FastMCP Stdio
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
3. **
|
|
17
|
-
-
|
|
18
|
-
4.
|
|
19
|
-
-
|
|
20
|
-
5.
|
|
21
|
-
-
|
|
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.
|
|
22
32
|
|
|
23
33
|
---
|
|
24
34
|
|
|
25
|
-
##
|
|
35
|
+
## 📦 Installation
|
|
26
36
|
|
|
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 項核心工具
|
|
37
|
+
Install via DSH Plugin CLI:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
dsh plugin --profile web add @luoyi-dsh/instagram-mcp
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Or via standard npm:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm install @luoyi-dsh/instagram-mcp
|
|
52
47
|
```
|
|
53
48
|
|
|
54
49
|
---
|
|
55
50
|
|
|
56
|
-
## 🛠️
|
|
51
|
+
## 🛠️ Provided MCP Tools (9 Core Primitives)
|
|
57
52
|
|
|
58
|
-
|
|
|
53
|
+
| Tool Name | Description | Parameters |
|
|
59
54
|
| :--- | :--- | :--- |
|
|
60
|
-
| **`ig_check_status`** |
|
|
61
|
-
| **`ig_login`** |
|
|
62
|
-
| **`ig_search_hashtag`** |
|
|
63
|
-
| **`ig_get_post_context
|
|
64
|
-
| **`ig_post_comment`** |
|
|
65
|
-
| **`ig_get_unread_dms`** |
|
|
66
|
-
| **`ig_send_dm`** |
|
|
67
|
-
| **`ig_get_timeline_feed
|
|
68
|
-
| **`ig_like_media`** |
|
|
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) |
|
|
69
64
|
|
|
70
65
|
---
|
|
71
66
|
|
|
72
|
-
## 💻
|
|
67
|
+
## 💻 Usage Examples
|
|
73
68
|
|
|
74
|
-
###
|
|
69
|
+
### 1. Natural Language Invocation in DSH Chat
|
|
75
70
|
|
|
76
|
-
|
|
71
|
+
In DSH conversations, the host model automatically determines and calls appropriate MCP tools:
|
|
77
72
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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!'"
|
|
82
78
|
|
|
83
|
-
|
|
84
|
-
「這篇貼文 PK 是 3123456789012345678，幫我看完整內文與底下留言」
|
|
85
|
-
-> AI 將調用：ig_get_post_context(media_pk="3123456789012345678", comment_limit=10)
|
|
79
|
+
### 2. Via HTTP REST API (DSH Web Routes)
|
|
86
80
|
|
|
87
|
-
|
|
88
|
-
「在貼文 3123456789012345678 下留言：『很實用的架構分享，收藏了！』」
|
|
89
|
-
-> AI 將調用：ig_post_comment(media_pk="3123456789012345678", text="很實用的架構分享，收藏了！")
|
|
81
|
+
> 💡 **Tip**: Default DSH Web port is **3080**.
|
|
90
82
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
83
|
+
- **Read Configuration**:
|
|
84
|
+
```bash
|
|
85
|
+
curl http://127.0.0.1:3080/api/instagram/mcp/config
|
|
86
|
+
```
|
|
94
87
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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
|
+
```
|
|
99
94
|
|
|
100
|
-
|
|
95
|
+
- **Get Service Health & Login Status**:
|
|
96
|
+
```bash
|
|
97
|
+
curl http://127.0.0.1:3080/api/instagram/mcp/status
|
|
98
|
+
```
|
|
101
99
|
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
```
|
|
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
|
-
```
|
|
100
|
+
- **Restart FastMCP Subprocess**:
|
|
101
|
+
```bash
|
|
102
|
+
curl -X POST http://127.0.0.1:3080/api/instagram/mcp/restart
|
|
103
|
+
```
|
|
119
104
|
|
|
120
|
-
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
"params": {
|
|
127
|
-
"name": "ig_post_comment",
|
|
128
|
-
"arguments": {
|
|
129
|
-
"media_pk": "3123456789012345678",
|
|
130
|
-
"text": "寫得很詳盡！謝謝分享。"
|
|
131
|
-
}
|
|
132
|
-
}
|
|
133
|
-
}
|
|
134
|
-
```
|
|
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
|
+
```
|
|
135
111
|
|
|
136
|
-
|
|
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 程式碼中跨插件調用
|
|
112
|
+
### 3. Cross-Plugin TypeScript / Node.js API
|
|
154
113
|
|
|
155
|
-
|
|
114
|
+
Consumer DSH plugins can directly import and call the shared client:
|
|
156
115
|
|
|
157
116
|
```typescript
|
|
158
|
-
import { getSharedMcpClient } from 'dsh
|
|
117
|
+
import { getSharedMcpClient } from '@luoyi-dsh/instagram-mcp'
|
|
159
118
|
|
|
160
119
|
const mcpClient = getSharedMcpClient()
|
|
161
120
|
if (mcpClient && mcpClient.ready) {
|
|
162
|
-
//
|
|
121
|
+
// Search hashtag
|
|
163
122
|
const posts = await mcpClient.igSearchHashtag('tech', 10)
|
|
164
|
-
console.log('搜尋結果:', posts)
|
|
165
123
|
|
|
166
|
-
//
|
|
124
|
+
// Fetch post details
|
|
167
125
|
const context = await mcpClient.igGetPostContext('3123456789012345678', 5)
|
|
168
126
|
|
|
169
|
-
//
|
|
127
|
+
// Send Direct Message
|
|
170
128
|
await mcpClient.igSendDm({
|
|
171
129
|
thread_id: '17841400000000000',
|
|
172
|
-
text: '
|
|
130
|
+
text: 'Thanks for reaching out!',
|
|
173
131
|
})
|
|
174
132
|
}
|
|
175
133
|
```
|
|
176
134
|
|
|
177
135
|
---
|
|
178
136
|
|
|
179
|
-
## ⚙️
|
|
137
|
+
## ⚙️ Configuration Parameters
|
|
180
138
|
|
|
181
|
-
|
|
139
|
+
Configurable via the DSH Web UI or `data/config.json`:
|
|
182
140
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
141
|
+
| Field | Type | Default | Description |
|
|
142
|
+
| :--- | :--- | :--- | :--- |
|
|
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 |
|
|
192
150
|
|
|
193
151
|
---
|
|
194
152
|
|
|
195
|
-
##
|
|
153
|
+
## 📁 Directory Structure
|
|
196
154
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
155
|
+
```text
|
|
156
|
+
dsh-instagram-mcp/
|
|
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
|
|
163
|
+
├── assets/
|
|
164
|
+
│ ├── banner.png # Promotional banner
|
|
165
|
+
│ └── zh-Hant.md # Localized documentation
|
|
166
|
+
├── client.js # DSH Web UI control panel
|
|
167
|
+
├── vendor/
|
|
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)
|
|
173
|
+
└── src/
|
|
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
|
|
178
|
+
├── lib/
|
|
179
|
+
│ ├── env.ts # Python venv validation & package installer
|
|
180
|
+
│ ├── mcp.ts # FastMCP client subprocess wrapper
|
|
181
|
+
│ └── hostdeps.ts # DSH runtime compatibility layer
|
|
182
|
+
└── tools/
|
|
183
|
+
└── mcpTools.ts # 9 core MCP tools registration
|
|
202
184
|
```
|
|
203
185
|
|
|
204
|
-
|
|
205
|
-
```powershell
|
|
206
|
-
dsh plugin --profile web add link:c:\Users\asiat\Downloads\dsh\dsh-instagram-mcp
|
|
207
|
-
```
|
|
186
|
+
---
|
|
208
187
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
188
|
+
## 📜 Releases & Changelog
|
|
189
|
+
|
|
190
|
+
For detailed release history and changes, please refer to [CHANGELOG.md](CHANGELOG.md).
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## 📄 License
|
|
195
|
+
|
|
196
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
# DSH Instagram FastMCP 核心服務插件 (`@luoyi-dsh/instagram-mcp`)
|
|
2
|
+
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
|
|
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) 開源授權。
|