@zenaigc/zenmcp 0.1.0 → 0.1.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/INSTALL.md ADDED
@@ -0,0 +1,77 @@
1
+ # ZenMCP Agent 自助安装指南
2
+
3
+ 请按以下七步执行。涉及安装缺失依赖时先征得用户同意;平台 Key 不得在对话或日志中回显明文。
4
+
5
+ ## 1. 检查本机环境
6
+
7
+ 运行 `node -v`,确认 Node.js 版本 ≥ 22;运行 `ffmpeg -version`、`ffprobe -version`,并检查 Google Chrome 已安装且可启动。
8
+
9
+ 有缺失时,先告知用户需要安装的组件并征得同意,再按系统安装:
10
+
11
+ - macOS:使用 `brew`,例如 `brew install node@22 ffmpeg`、`brew install --cask google-chrome`。确保 Node.js 的 bin 目录在 PATH 中。
12
+ - Windows:使用 `winget`,例如 `winget install OpenJS.NodeJS.LTS`、`winget install Gyan.FFmpeg`、`winget install Google.Chrome`。
13
+ - Linux:使用 `apt` 安装 Node.js、FFmpeg 和 Google Chrome(Chrome 使用官方 deb 包交给 `apt` 安装)。先检查 apt 软件源提供的 Node.js 是否 ≥ 22;不满足时先说明需要配置兼容的软件源,获得用户同意后再处理。
14
+
15
+ 安装后重新打开终端并重复检查;Node.js 必须 ≥ 22,FFmpeg 安装应同时提供 ffprobe。
16
+
17
+ ## 2. 安装 ZenMCP
18
+
19
+ ```bash
20
+ npm install -g @zenaigc/zenmcp
21
+ ```
22
+
23
+ ## 3. 运行本机自检
24
+
25
+ ```bash
26
+ zenmcp-doctor
27
+ ```
28
+
29
+ 确认输出 `"ok": true`,否则按检查结果修复环境再运行。此时在终端直接运行,`config` 中 `ZENMCP_BASE_URL` 与 `ZENMCP_TOKEN` 两项显示为 `false` 是正常的;这两项只表示当前进程是否配置环境变量,不影响本机自检结果,也不验证平台 Key 或服务器连通性。
30
+
31
+ ## 4. 获取平台 Key
32
+
33
+ 引导用户登录 ZenAIGC 官网 https://zenaigc.com 获取平台 Key。**官网域名切换前请使用 https://api.zenaigc.com 登录获取**。
34
+
35
+ Key 不得在对话中回显明文。由用户自行粘贴进配置,或由 Agent 写入配置文件但不回显;不要把真实 Key 放入命令记录或日志。
36
+
37
+ ## 5. 配置 MCP 客户端
38
+
39
+ 通用配置块如下,将 `<平台Key>` 替换为用户的平台 Key:
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "zenmcp": {
45
+ "command": "zenmcp",
46
+ "env": {
47
+ "ZENMCP_TOKEN": "<平台Key>"
48
+ }
49
+ }
50
+ }
51
+ }
52
+ ```
53
+
54
+ 无需配置 `ZENMCP_BASE_URL`,已内置默认地址 `https://api.zenaigc.com/api/v1`。编辑已有配置时合并 `zenmcp` 项,保留其他 MCP 服务。
55
+
56
+ - **WorkBuddy**:写入 `~/.workbuddy/mcp.json`,或在客户端 MCP 设置中添加上述配置块。
57
+ - **豆包电脑版**:左侧「技能·连接器」→ 添加 MCP,填入上述配置块,或命令填 `zenmcp`、环境变量填 `ZENMCP_TOKEN`。
58
+ - **SuperOne**:在其 MCP 设置中添加上述配置块。
59
+ - **Claude Code**:命令格式为 `claude mcp add zenmcp -s user -e ZENMCP_TOKEN=<Key> -- zenmcp`;不要在对话中回显真实 Key,避免将含真实 Key 的命令保存在历史或日志中。
60
+ - **Claude Desktop**:在 `claude_desktop_config.json` 中添加上述配置块。
61
+ - **OpenClaw**:在其 MCP 配置中添加上述配置块。
62
+
63
+ 命令查找失败时按以下顺序处理:
64
+
65
+ - Windows 上 `command` 用 `zenmcp.cmd`。
66
+ - GUI 客户端找不到命令时,`command` 改用 `command -v zenmcp`(Windows 用 `where zenmcp`)得到的绝对路径。
67
+ - 如果仍然报 `node` 找不到,`command` 填 `node` 的绝对路径,`args` 填 `["<npm root -g>/@zenaigc/zenmcp/dist/src/mcp/server.js"]`;将 `<npm root -g>` 替换为运行 `npm root -g` 得到的真实目录。
68
+
69
+ ## 6. 安装 Skill
70
+
71
+ 从 `$(npm root -g)/@zenaigc/zenmcp/skills/zenmcp/SKILL.md` 复制到客户端的 skills 目录,例如 `~/.agents/skills/zenmcp/SKILL.md`;Claude Code 为 `~/.claude/skills/zenmcp/SKILL.md`。先创建目标目录。Windows 上使用 `npm root -g` 的输出定位源文件,再复制到对应目录。
72
+
73
+ 客户端不支持 skills 时跳过这一步。
74
+
75
+ ## 7. 验证连通性
76
+
77
+ 重启客户端或重载 MCP,调用只读工具 `account_status`;返回积分信息即为连通。若提示 Key 未配置,检查客户端 MCP 环境变量后重载,排查时不要回显 Key。
File without changes
@@ -11,6 +11,7 @@ import { PopTitleRenderer } from '../effects/index.js';
11
11
  import { Engine, analyzeReference, draftJob, safeError } from '../engine/steps.js';
12
12
  import { DirectGeneration } from '../engine/direct.js';
13
13
  import { trimMedia } from '../acquire/trim.js';
14
+ export const DEFAULT_BASE_URL = 'https://api.zenaigc.com/api/v1';
14
15
  const inputSchema = z.object({
15
16
  job: jobSchema, reference: z.string().min(1),
16
17
  output: z.object({ duration_seconds: z.number().int(), resolution: z.enum(['480P', '720P', '1080P']), ratio: z.string(), seed: z.number().int().optional() }),
@@ -52,7 +53,7 @@ const SERVER_INSTRUCTIONS = `Zenmcp tools are atomic. Combine them as follows.
52
53
  - post_unavailable: the post was deleted, is private, or is region-locked.`;
53
54
  /** Background tasks live in this MCP process; state and attempts survive its restart. */
54
55
  export function createServer(engine, socialOptions = {}) {
55
- const server = new McpServer({ name: 'zenmcp', version: '0.1.0' }, { instructions: SERVER_INSTRUCTIONS });
56
+ const server = new McpServer({ name: 'zenmcp', version: '0.1.1' }, { instructions: SERVER_INSTRUCTIONS });
56
57
  const active = new Map();
57
58
  server.registerTool('fetch_social_post', {
58
59
  description: '解析抖音/小红书/B站/TikTok/Instagram/X 分享口令或链接,下载视频或图集到本地目录,返回本地路径与标题/正文/话题。免费、限次;不分析内容。视频可直接交给 analyze_reference。',
@@ -152,18 +153,18 @@ export function createServer(engine, socialOptions = {}) {
152
153
  server.registerTool('get_generation', { description: '只读查询直通生成状态、账单摘要与本地输出。', inputSchema: { directory: z.string() } }, guarded(async (i) => { const result = await direct.get(i); return { ...result, markdown: formatGenerationText(result) }; }));
153
154
  return server;
154
155
  }
155
- export function createEngine(baseUrl, tokens) {
156
+ export function createEngine(baseUrl = DEFAULT_BASE_URL, tokens) {
156
157
  const capturedToken = process.env.ZENMCP_TOKEN;
157
158
  delete process.env.ZENMCP_TOKEN;
158
159
  const provider = tokens ?? { token: async () => {
159
160
  const value = capturedToken ?? process.env.ZENMCP_TOKEN;
160
161
  if (!value)
161
- throw new Error('ZENMCP_TOKEN 未配置');
162
+ throw new Error('ZENMCP_TOKEN 未配置(请前往 https://zenaigc.com 登录获取平台 Key)');
162
163
  return value;
163
164
  } };
164
165
  return new Engine({ effects: job => new PopTitleRenderer(job), gateway: new CloudGateway({ baseUrl, tokens: provider }), tokens: provider, catalogLabel: '云端 catalog(仅运行工具时读取;Wan 可用性以返回目录为准)' });
165
166
  }
166
- export async function startServer(baseUrl, tokens) {
167
+ export async function startServer(baseUrl = DEFAULT_BASE_URL, tokens) {
167
168
  const server = createServer(createEngine(baseUrl, tokens));
168
169
  await server.connect(new StdioServerTransport());
169
170
  return server;
@@ -171,8 +172,6 @@ export async function startServer(baseUrl, tokens) {
171
172
  // Importing this module in an embedding host never starts network or stdio work.
172
173
  const entry = process.argv[1] ? await (await import('node:fs/promises')).realpath(process.argv[1]).catch(() => process.argv[1]) : '';
173
174
  if (entry && import.meta.url === (await import('node:url')).pathToFileURL(entry).href) {
174
- const baseUrl = process.env.ZENMCP_BASE_URL;
175
- if (!baseUrl)
176
- throw new Error('ZENMCP_BASE_URL 未配置');
175
+ const baseUrl = process.env.ZENMCP_BASE_URL?.trim() || DEFAULT_BASE_URL;
177
176
  await startServer(baseUrl);
178
177
  }
package/package.json CHANGED
@@ -1,13 +1,15 @@
1
1
  {
2
2
  "name": "@zenaigc/zenmcp",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "zenmcp": "dist/src/mcp/server.js",
7
7
  "zenmcp-doctor": "dist/src/doctor.js"
8
8
  },
9
9
  "files": [
10
- "dist"
10
+ "dist",
11
+ "INSTALL.md",
12
+ "skills"
11
13
  ],
12
14
  "engines": {
13
15
  "node": ">=22"
@@ -0,0 +1,27 @@
1
+ ---
2
+ name: zenmcp
3
+ description: 用户需要生图、生视频、复刻短视频或进行 ZenMCP 环境配置自检时使用。
4
+ ---
5
+
6
+ # ZenMCP
7
+
8
+ 环境异常或未安装时运行 `zenmcp-doctor`,或参照同包内的 `INSTALL.md`(安装包根目录,在线地址:https://api.zenaigc.com/install.md)。安装缺失依赖前须征得用户同意。
9
+
10
+ ## 13 个工具的编排
11
+
12
+ - 直出生成:`list_models` → `quote_generation` → 展示报价并获得用户明确批准的积分 → `run_generation` → `get_generation`。
13
+ - 每次生成使用新的空目录。本地素材上传前须获得用户同意,并传 `consent_confirmed: true`;提交时携带报价的 `requestDigest`。
14
+ - 视频复刻:`fetch_social_post` 或用户提供的本地视频 → `analyze_reference` → 用户确认最终素材及属性后 `import_assets(confirmed: true)` → `plan_job` 报价 → 获批后 `execute_job` → `get_job`;修改走 `revise_job`。
15
+ - 分享链接先调用 `fetch_social_post`,每帖使用新的空目录,同一任务不重复抓取同一链接。本地视频跳过抓取,直接分析;抓取与分析无需用户确认。
16
+ - 视频超过约 30 秒或报价提示时长限制时,先征求用户同意保留的片段,再用 `trim_media` 截取并分析截取后的文件。
17
+ - 图集先展示图片,由用户确认哪些是产品或模特素材。最终素材及属性确认前不得调用 `import_assets`。
18
+ - 额度查询:用只读工具 `account_status` 查询。
19
+
20
+ ## 禁令与错误处理
21
+
22
+ - 不得自动批准积分;`plan_job`、`quote_generation` 只报价,付费执行须获得用户明确批准。
23
+ - 不得自动 `retryAfterRelease`;释放后重试须重新取得用户明确批准。
24
+ - 不得自行抓取社媒网页。
25
+ - 不要声称知道视频内口播原话;帖子标题、正文和话题只是配文。
26
+ - `share_link_unresolved`:请用户复制完整链接;`unsupported_platform`:说明支持抖音、小红书、B站、TikTok、Instagram、X。
27
+ - `rate_limited`:说明已达每日限额,次日重试;`post_unavailable`:说明帖子可能已删除、私密或受地区限制。