mastergo-magic-mcp-private 0.1.5

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 (4) hide show
  1. package/README.md +133 -0
  2. package/README.zh-CN.md +131 -0
  3. package/dist/index.js +502 -0
  4. package/package.json +49 -0
package/README.md ADDED
@@ -0,0 +1,133 @@
1
+ # MasterGo Magic MCP (fork)
2
+
3
+ [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mastergo-design/mastergo-magic-mcp)
4
+
5
+ This repository is a **fork** of [mastergo-design/mastergo-magic-mcp](https://github.com/mastergo-design/mastergo-magic-mcp). It publishes to npm as **`mastergo-magic-mcp-private`** and adds optional **Cookie** support and a small **userscript** helper. Everything else (what the MCP does, MasterGo token, permissions, Smithery, LINGMA walkthroughs, etc.) is the same as upstream—see the links below instead of duplicating them here.
6
+
7
+ **中文文档（本仓库）：** [README.zh-CN.md](README.zh-CN.md)
8
+
9
+ ## Upstream documentation
10
+
11
+ Read the **official** README for full usage (tutorial, how to get `MG_MCP_TOKEN`, team account / file requirements, Smithery, LINGMA with screenshots, and generic client patterns):
12
+
13
+ - **English:** [github.com/mastergo-design/mastergo-magic-mcp — README.md](https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/README.md)
14
+ - **中文:** [github.com/mastergo-design/mastergo-magic-mcp — README.zh-CN.md](https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/README.zh-CN.md)
15
+
16
+ When you follow upstream examples, replace **`@mastergo/magic-mcp`** with **`mastergo-magic-mcp-private`** in `npm` / `npx` commands and MCP `args` (see [Migration](#migration-from-upstream)).
17
+
18
+ **Cursor MCP** (official): [Using MCP in Cursor](https://docs.cursor.com/context/model-context-protocol#using-mcp-tools-in-agent)
19
+
20
+ ---
21
+
22
+ ## Migration from upstream
23
+
24
+ If you used **`@mastergo/magic-mcp`** before:
25
+
26
+ | | Upstream | This fork |
27
+ |---|----------|-----------|
28
+ | npm package | `@mastergo/magic-mcp` | `mastergo-magic-mcp-private` |
29
+ | npx | `npx @mastergo/magic-mcp …` | `npx mastergo-magic-mcp-private …` |
30
+ | MCP `args` | `-y @mastergo/magic-mcp` | `-y mastergo-magic-mcp-private` |
31
+ | Binary (`package.json` → `bin`) | `mastergo-magic-mcp` | `mastergo-magic-mcp-private` |
32
+
33
+ ### BREAKING: rename from `magic-mcp-private` (npm)
34
+
35
+ This fork’s npm package was previously published as **`magic-mcp-private`**. It is now **`mastergo-magic-mcp-private`** (aligned with this repository name).
36
+
37
+ - Remove the old dependency or global install if applicable: e.g. `npm uninstall magic-mcp-private` (add `-g` if you installed globally).
38
+ - Install or run with the new name: `npm install mastergo-magic-mcp-private` or `npx -y mastergo-magic-mcp-private ...`.
39
+ - Update MCP configs: replace `-y magic-mcp-private` with `-y mastergo-magic-mcp-private`, and use the **`mastergo-magic-mcp-private`** CLI name anywhere you previously invoked **`magic-mcp-private`**.
40
+
41
+ ---
42
+
43
+ ## CLI & environment (fork-specific)
44
+
45
+ Full options are listed here because **`--cookie`** and cookie env vars are additions on top of upstream.
46
+
47
+ ```text
48
+ npx mastergo-magic-mcp-private --token=YOUR_TOKEN [--url=API_URL] [--cookie=COOKIE] [--rule=RULE_NAME] [--debug] [--no-rule]
49
+ ```
50
+
51
+ | Flag / env | Notes |
52
+ |------------|--------|
53
+ | `--token` | Required. Same MasterGo token as upstream (`MG_MCP_TOKEN` / `MASTERGO_API_TOKEN`). |
54
+ | `--url` | Optional. Default in dev often `http://localhost:3000`; production often `https://mastergo.com`. |
55
+ | `--cookie` | Optional. Sent as HTTP `Cookie` on MasterGo API calls. Prefer env vars in CI; **do not commit** real values. |
56
+ | `--rule` / `--debug` / `--no-rule` | Same idea as upstream. |
57
+ | `API_BASE_URL` | Same as upstream. |
58
+ | `MG_MCP_COOKIE` / `MASTERGO_API_COOKIE` | Optional cookie string for API calls. CLI `--cookie` wins if both are set. |
59
+ | `RULES` | Same as upstream (JSON array string). |
60
+
61
+ ### Cookie usage examples
62
+
63
+ Gateways sometimes need a session cookie in addition to the token. Use **placeholders** in docs and git; never commit real cookies.
64
+
65
+ **Priority:** explicit per-request `Cookie` (if you customize HTTP) overrides CLI `--cookie`, which overrides the env vars above.
66
+
67
+ **One-line CLI:**
68
+
69
+ ```bash
70
+ npx mastergo-magic-mcp-private --token=YOUR_TOKEN --url=https://mastergo.com --cookie="session_id=<YOUR_VALUE>; path=/"
71
+ ```
72
+
73
+ **MCP client via `env` only:**
74
+
75
+ ```json
76
+ {
77
+ "mcpServers": {
78
+ "mastergo-magic-mcp-private": {
79
+ "command": "npx",
80
+ "args": ["-y", "mastergo-magic-mcp-private", "--token=<YOUR_TOKEN>", "--url=https://mastergo.com"],
81
+ "env": {
82
+ "MG_MCP_COOKIE": "<YOUR_COOKIE_STRING>"
83
+ }
84
+ }
85
+ }
86
+ }
87
+ ```
88
+
89
+ You can use `MASTERGO_API_COOKIE` instead of `MG_MCP_COOKIE` if you prefer symmetry with `MASTERGO_API_TOKEN`.
90
+
91
+ ### Browser userscript (optional)
92
+
93
+ To copy a **non-HttpOnly** cookie from the current tab for `MG_MCP_COOKIE`, see **[userscripts/README.md](userscripts/README.md)**. HttpOnly cookies are not visible to page scripts.
94
+
95
+ ### Cursor: minimal `mcp.json` example
96
+
97
+ Same structure as [upstream README — Cursor](https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/README.md) (find the Cursor / `mcp.json` example); only the package name changes:
98
+
99
+ ```json
100
+ {
101
+ "mcpServers": {
102
+ "mastergo-magic-mcp-private": {
103
+ "command": "npx",
104
+ "args": [
105
+ "-y",
106
+ "mastergo-magic-mcp-private",
107
+ "--token=<MG_MCP_TOKEN>",
108
+ "--url=https://mastergo.com"
109
+ ],
110
+ "env": {}
111
+ }
112
+ }
113
+ }
114
+ ```
115
+
116
+ For **cline** and other editors, follow the upstream README and replace the package name with **`mastergo-magic-mcp-private`**.
117
+
118
+ ---
119
+
120
+ ## Local development
121
+
122
+ ```bash
123
+ npm install
124
+ npm run build
125
+ ```
126
+
127
+ Point your MCP config at **`dist/index.js`** (absolute path), same as upstream local debugging, with your token and `--url` as needed.
128
+
129
+ ---
130
+
131
+ ## License
132
+
133
+ ISC
package/README.zh-CN.md ADDED
@@ -0,0 +1,131 @@
1
+ # MasterGo Magic MCP（fork）
2
+
3
+ [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mastergo-design/mastergo-magic-mcp)
4
+
5
+ 本仓库是 [mastergo-design/mastergo-magic-mcp](https://github.com/mastergo-design/mastergo-magic-mcp) 的 **fork**，在 npm 上发布为 **`mastergo-magic-mcp-private`**，并增加可选的 **Cookie** 支持与浏览器**油猴脚本**辅助。其余能力（MCP 功能说明、MasterGo 令牌获取、权限与团队文件要求、Smithery、LINGMA 图文步骤等）与上游一致——**请直接阅读官方 README**，本文不再重复粘贴。
6
+
7
+ ## 官方文档（上游）
8
+
9
+ 完整用法请查看 **官方** 文档（教程、获取 `MG_MCP_TOKEN`、账户/文件权限、Smithery、LINGMA 截图流程、各客户端通用配置等）：
10
+
11
+ - **中文：** [github.com/mastergo-design/mastergo-magic-mcp — README.zh-CN.md](https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/README.zh-CN.md)
12
+ - **English:** [github.com/mastergo-design/mastergo-magic-mcp — README.md](https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/README.md)
13
+
14
+ 对照官方示例时，请把 **`@mastergo/magic-mcp`** 换成 **`mastergo-magic-mcp-private`**（`npm` / `npx` / MCP `args`），详见下文 [从上游迁移](#从上游迁移)。
15
+
16
+ **Cursor 官方说明：** [在 Cursor 中使用 MCP](https://docs.cursor.com/context/model-context-protocol#using-mcp-tools-in-agent)
17
+
18
+ ---
19
+
20
+ ## 从上游迁移
21
+
22
+ 若曾使用 **`@mastergo/magic-mcp`**：
23
+
24
+ | | 上游 | 本 fork |
25
+ |---|------|---------|
26
+ | npm 包名 | `@mastergo/magic-mcp` | `mastergo-magic-mcp-private` |
27
+ | npx | `npx @mastergo/magic-mcp …` | `npx mastergo-magic-mcp-private …` |
28
+ | MCP `args` | `-y @mastergo/magic-mcp` | `-y mastergo-magic-mcp-private` |
29
+ | 可执行命令（`package.json` → `bin`） | `mastergo-magic-mcp` | `mastergo-magic-mcp-private` |
30
+
31
+ ### **BREAKING**：由 `magic-mcp-private` 更名为现包名（npm）
32
+
33
+ 本 fork 曾在 npm 上以 **`magic-mcp-private`** 发布，现已统一为 **`mastergo-magic-mcp-private`**（与仓库名一致）。
34
+
35
+ - 若曾安装旧包：可执行 `npm uninstall magic-mcp-private`（若曾全局安装请加 `-g`）。
36
+ - 新安装或运行：使用 `npm install mastergo-magic-mcp-private` 或 `npx -y mastergo-magic-mcp-private ...`。
37
+ - 更新 MCP 配置：将 `-y magic-mcp-private` 改为 `-y mastergo-magic-mcp-private`；脚本中原调用 **`magic-mcp-private`** 的请改为 **`mastergo-magic-mcp-private`**。
38
+
39
+ ---
40
+
41
+ ## 命令行与环境变量（本 fork 增量说明）
42
+
43
+ 在官方参数基础上，本 fork 增加 **`--cookie`** 及 Cookie 相关环境变量，完整示例如下：
44
+
45
+ ```text
46
+ npx mastergo-magic-mcp-private --token=YOUR_TOKEN [--url=API_URL] [--cookie=COOKIE] [--rule=RULE_NAME] [--debug] [--no-rule]
47
+ ```
48
+
49
+ | 参数 / 环境变量 | 说明 |
50
+ |-----------------|------|
51
+ | `--token` | 必填，与上游相同的 MasterGo 令牌（`MG_MCP_TOKEN` / `MASTERGO_API_TOKEN`）。 |
52
+ | `--url` | 可选，本地开发常见 `http://localhost:3000`，线上多为 `https://mastergo.com`。 |
53
+ | `--cookie` | 可选，发往 MasterGo API 的 `Cookie`。**勿将真实值写入仓库**；生产环境优先环境变量。 |
54
+ | `--rule` / `--debug` / `--no-rule` | 与上游含义一致。 |
55
+ | `API_BASE_URL` | 与上游一致。 |
56
+ | `MG_MCP_COOKIE` / `MASTERGO_API_COOKIE` | 可选；若同时配置 CLI `--cookie`，以 CLI 为准。 |
57
+ | `RULES` | 与上游一致（JSON 数组字符串）。 |
58
+
59
+ ### Cookie 使用示例
60
+
61
+ 除 Token 外若还需会话 Cookie，文档与 Git 中请使用占位符。
62
+
63
+ **优先级：** 若在更底层自行设置请求 `Cookie`，以该值为准；否则 CLI `--cookie` 优先于 `MG_MCP_COOKIE` / `MASTERGO_API_COOKIE`。
64
+
65
+ **命令行一行示例：**
66
+
67
+ ```bash
68
+ npx mastergo-magic-mcp-private --token=YOUR_TOKEN --url=https://mastergo.com --cookie="session_id=<YOUR_VALUE>; path=/"
69
+ ```
70
+
71
+ **仅用 MCP `env` 注入 Cookie：**
72
+
73
+ ```json
74
+ {
75
+ "mcpServers": {
76
+ "mastergo-magic-mcp-private": {
77
+ "command": "npx",
78
+ "args": ["-y", "mastergo-magic-mcp-private", "--token=<YOUR_TOKEN>", "--url=https://mastergo.com"],
79
+ "env": {
80
+ "MG_MCP_COOKIE": "<YOUR_COOKIE_STRING>"
81
+ }
82
+ }
83
+ }
84
+ }
85
+ ```
86
+
87
+ 可与 `MASTERGO_API_TOKEN` 命名对称，使用 `MASTERGO_API_COOKIE` 代替 `MG_MCP_COOKIE`。
88
+
89
+ ### 浏览器油猴脚本（可选）
90
+
91
+ 从页签复制**非 HttpOnly** Cookie 供 `MG_MCP_COOKIE` 使用，见 **[userscripts/README.md](userscripts/README.md)**。HttpOnly 无法被页面脚本读取。
92
+
93
+ ### Cursor：最小 `mcp.json` 示例
94
+
95
+ 结构与 [上游 README 中的 Cursor 配置示例](https://github.com/mastergo-design/mastergo-magic-mcp/blob/main/README.zh-CN.md) 相同，仅包名替换为 **`mastergo-magic-mcp-private`**：
96
+
97
+ ```json
98
+ {
99
+ "mcpServers": {
100
+ "mastergo-magic-mcp-private": {
101
+ "command": "npx",
102
+ "args": [
103
+ "-y",
104
+ "mastergo-magic-mcp-private",
105
+ "--token=<MG_MCP_TOKEN>",
106
+ "--url=https://mastergo.com"
107
+ ],
108
+ "env": {}
109
+ }
110
+ }
111
+ }
112
+ ```
113
+
114
+ **cline** 等客户端请按上游 README 配置，并将包名改为 **`mastergo-magic-mcp-private`**。
115
+
116
+ ---
117
+
118
+ ## 本地开发
119
+
120
+ ```bash
121
+ npm install
122
+ npm run build
123
+ ```
124
+
125
+ 在 MCP 配置中使用 **`dist/index.js`** 的绝对路径，带上 token、`--url` 等，与上游本地调试方式相同。
126
+
127
+ ---
128
+
129
+ ## 许可证
130
+
131
+ ISC