Mediagraph命令行界面
一个二进制文件，暴露了整个 Mediagraph API到人工智能代理和外壳。作为CLI发货(mediagraph )以及MCP服务器(mediagraph serve)--相同的代码路径，相同的身份验证，相同的输出形状。
关于Mediagraph： 一个数字资产管理（DAM）平台，用于大规模组织、共享和人工智能标记媒体。了解更多 www.mediagraph.io.
为代理工作流构建：每个工具调用在stdout上返回JSON，在stderr上返回稳定代码的错误，全局标志处理无聊的事情（身份验证、分页、重试、模拟运行、轮询）。
安装
npm install -g @mediagraph/cli # ships the `mediagraph` command认证
交互式（开发人员机器）
mediagraph auth login # opens a browser, completes OAuth, persists tokens
mediagraph auth status # {authenticated, organization, user, token}令牌以加密方式存储在 ~/.mediagraph/tokens.enc 并自动刷新。
无头（CI、沙盒、代理）
使用个人访问令牌。设置两个环境变量：
export MEDIAGRAPH_PAT=""
export MEDIAGRAPH_ORGANIZATION_ID=""
mediagraph auth status # → {authenticated: true, mode: "pat", ...}在Mediagraph中生成PAT→ 简介→ 个人访问令牌，或通过 mediagraph create_personal_access_token --name "ci".
CLI使用情况
mediagraph [flags] # invoke any tool, prints JSON
mediagraph --help # show flags for a tool
mediagraph list-tools [--brief] # every tool, JSON
mediagraph search-tools "" # ranked keyword search over the registry
mediagraph sync ... # continuous folder sync (see below)
mediagraph serve # start the MCP server on stdio
mediagraph auth login | logout | status工具标志
每个工具的标志都来源于其JSON模式：
# Flag form
mediagraph search_assets --q "tag_text:nature" --per_page 5
mediagraph create_bulk_job --asset_ids 12,34,56 --tag_names sunset --tag_mode add
# Or pass the whole input as JSON
mediagraph search_assets --json '{"q":"tag_text:nature","per_page":5}'类型强制：数字、布尔值(--flag / --no-flag)、数组（逗号分隔、重复或JSON）、对象（仅JSON）。
全球旗帜
这些工具适用于任何工具：
| 标志 | 目的 |
|---|---|
--all | 自动分页 list_* 工具直到用完 |
--limit N | 分页时限制总行数（默认10000） |
--dry-run | 打印HTTP调用而不是执行——突变的安全预览 |
--wait | a之后 create_*，轮询兄弟状态工具，直到终端 |
--wait-timeout SEC | 帽子 --wait 持续时间（默认值600） |
--envelope | 将stdout封装在 {ok, tool, data, meta:{duration_ms, ...}} |
--brief | 修剪 list-tools 描述到一行 |
示例：
# Get all assets matching a query, capped at 500
mediagraph search_assets --q "tag_text:nature" --all --limit 500
# Preview a destructive op
mediagraph delete_asset --id 42 --dry-run
# Block until a bulk job finishes
mediagraph create_bulk_job --asset_ids 1,2,3 --tag_names sunset --tag_mode add --wait输出合同
- 标准输出 --仅支持JSON（始终可解析）。随着
--envelope，包裹在{ok, tool, data, meta}. - 标准错误 --结构化误差包络：
{ok: false, code, error, hint?, context?}. - 退出码 —
0成功，1运行时/工具/网络，2参数解析错误，3需要身份验证。
稳定的错误代码： AUTH_REQUIRED, BAD_ARGS, UNKNOWN_COMMAND, UNKNOWN_TOOL, NOT_FOUND, RUN_LOCKED, NETWORK, RATE_LIMITED, TOOL_ERROR, CONFIG_ERROR, INTERNAL.
客户荣誉 Retry-After 在429/503（增量秒和HTTP日期形式）上，上限回退为60秒，表面 X-PAT-Disabled 作为结构化身份验证错误。
搜索语法
这 q 参数打开 search_assets 接受高级操作员：
| 形式 | 示例 | 含义 |
|---|---|---|
| 期限 | dog | 在所有可搜索字段（cross_fields）中进行匹配 |
| 短语 | "red barn" | 两个术语在同一字段中，按顺序排列 |
| 排除 | NOT dog, -dog | 排除匹配项 |
| 合并 | dog AND cat, dog OR cat | 布尔运算 |
| 现场 | tag_text:nature, filename.keyword:IMG.jpg | 字段范围 |
| 通配符 | tag_text:part*, tag_text:?artial | * 任何字符， ? 一个字符 |
| 存在 | tag_text:** / NOT tag_text:** | 有任何价值/没有价值 |
| 集团 | (dog OR cat) AND ext:jpg | 带圆括号 |
常见字段： tag_text, filename.keyword, description, title, ext, creator_text, copyright, city, state, country.
连续文件夹同步
将远程存储文件夹镜像到本地目录（反之亦然），并按计划保持同步。对崩溃和重启具有弹性：每次运行都是幂等的，状态保持不变 ~/.mediagraph/sync//state.json，并在下一次运行中恢复飞行中的操作。
三种模式： 下载 （只拉取--自动获取新资产和新资产 data_version_number 颠簸；仅元数据更改不会重新下载）， 上传 （仅推送--哈希+跳过不变，镜像文件夹结构）， 双向的 （土地冲突 .conflict-v 本地文件旁边）。
mediagraph sync init my-pull --mode download \
--storage-folder-id 42 --local-path ~/Pictures/mediagraph \
--frequency hourly
mediagraph sync run my-pull # one-shot reconciliation; safe to repeat
mediagraph sync install my-pull # registers a launchd job (macOS)
mediagraph sync status my-pull # JSON summary of last run线束选项（ run 命令在所有情况下都是相同的）：
- 操作系统调度程序（推荐）:
mediagraph sync install在macOS上编写launchd plist。重新启动后幸存，捕获日志。 - 编码代理循环：在克劳德法典中，
/loop 1h mediagraph sync run. - 长期观察者:
mediagraph sync watch无需cron即可实现低延迟。 - 手册：快跑
mediagraph sync run无论何时。
发现工具
CLI附带了约157个工具。不要全部加载--搜索：
mediagraph search-tools "rename file" --limit 5
mediagraph search-tools "watermark"
mediagraph create_bulk_job --help # one tool, full schema工具组：资产、搜索和过滤器、集合/灯箱/存储文件夹、标签和分类、标签导入、权限和共享、自定义元字段、批量作业和上传、重命名预设、元下载（后台CSV导出）、工作流、评论、通知、webhooks、管理员（用户组、邀请、PAT、组织预算）。
用作MCP服务器
对于Claude Desktop和其他MCP客户：
{
"mcpServers": {
"mediagraph": {
"command": "npx",
"args": ["@mediagraph/cli", "serve"]
}
}
}MCP服务器公开了相同的工具和一些资源：
mediagraph://asset/{id}--资产详细信息mediagraph://collection/{id}--资产催收mediagraph://lightbox/{id}--带资产的灯箱mediagraph://search?q={query}--搜索结果
它还包括一个交互式视觉画廊(search_assets_visual)用于Claude Desktop内的缩略图浏览、内联编辑、评级、标记和批量下载。
环境
| 变量 | 默认值 | 用途 |
|---|---|---|
MEDIAGRAPH_PAT | -- | 个人访问令牌（无头身份验证） |
MEDIAGRAPH_ORGANIZATION_ID | -- | 组织id（PAT需要） |
MEDIAGRAPH_API_URL | https://api.mediagraph.io | API主机 |
MEDIAGRAPH_OAUTH_URL | https://mediagraph.io | OAuth主机 |
MEDIAGRAPH_CLIENT_ID | *（捆绑）* | OAuth客户端id（自定义应用程序） |
MEDIAGRAPH_CLIENT_SECRET | -- | OAuth客户端机密（机密客户端） |
MEDIAGRAPH_REDIRECT_PORT | 52584 | 本地OAuth回调端口 |
MEDIAGRAPH_SYNC_ROOT | ~/.mediagraph/sync | 覆盖同步状态目录 |
代理技能档案
SKILL.md 包括用于代理（Claude等）的内容——它涵盖了身份验证、JSON I/O契约、搜索语法、功能映射和常见工作流。把它放到你的经纪人的技能目录中。
安全
- 加密的令牌
~/.mediagraph/tokens.enc - OAuth为公共客户端使用PKCE
- PAT身份验证使用HTTP Basic+
OrganizationId标头（与Mediagraph服务器端路径匹配） - 访问令牌在过期前自动刷新
- 没有错误记录或暴露的秘密
发展
git clone https://github.com/mediagraph-io/mediagraph-mcp.git
cd mediagraph-mcp
npm install
npm run build # tsup bundle to dist/
npm test # vitest, ~110 tests
npm run typecheck运行本地构建：
node dist/index.js auth status
node dist/index.js search_assets --q "test" --per_page 5与MCP检查员一起测试：
npx @modelcontextprotocol/inspector node dist/index.js serve许可证
麻省理工学院——见 许可证.
支持
- Mediagraph --产品信息、定价、演示
- API文档
-