phototology

@phototology/mcp

面向视觉智能的持久记忆。分析一次，永久记住。

点击安装按钮即可一步添加 MCP 服务。安装后，系统会提示你填写 PHOTOTOLOGY_API_KEY。其他编辑器请参阅下方的设置部分。

Phototology 视觉智能注册服务的 MCP 服务。任何支持 MCP 的 Agent（Claude Code、Cursor、VS Code Copilot、Claude Desktop）都可以将 Phototology 作为工具调用。照片只需分析一次，并按感知哈希建立索引；此后同一账号的任何调用者都可以永久免费获取分析结果。

npx @phototology/mcp

交互式向导会询问你的 API 密钥，并为你选择的编辑器写入配置。

不使用 Phototology 与使用 Phototology

**不使用：**每个需要理解照片的 Agent 都要从头调用视觉模型。同一张图片、同一个问题，每次都要全额付费。

**使用：**首次调用时，每个镜头会扣除 1 个额度。此后对该照片的每次调用都可免费返回缓存的镜头结果。注册库会随着使用不断积累。

何时使用 Phototology

适合以下情况：

• Agent 需要多次理解同一张照片。注册库让每次重新读取都免费。
• 你需要结构化字段（日期、状况、文本、位置等），而不是自由形式的文字。
• 成本可预测性很重要。每个工具和每个镜头都会提前说明所需额度。

以下情况请考虑其他方案：

• 你需要实时视频或流式摄像头画面。Phototology 分析静态图像。
• 你需要识别某个具体的具名人物。Phototology 会描述人物，但绝不会比对身份。
• 你希望模型围绕图像进行对话。Phototology 返回结构化数据，而不是对话。

Phototology 与无状态视觉封装器的对比

能力	无状态视觉封装器	Phototology
对同一张照片重复调用	每次都要再次调用视觉模型付费	永久免费缓存，并按感知哈希建立索引
跨调用记忆	无	持久注册库（sha256 + pHash）
输出	自由形式文本	结构化 JSON，每个镜头对应一组字段
Agent 的成本	不透明	按工具、按镜头披露额度成本
近似重复项检测	无	精确匹配（sha256）和感知匹配（pHash）

持久注册库、基于感知哈希的去重以及免费的重新读取，正是它们之间的区别。

Phototology 不会做什么

明确说明，方便 Agent 正确选择调用方式：

• 不会进行身份识别。 people 镜头会报告物理观察结果和人数，绝不会提供姓名或人脸匹配结果。
• 不会在 MCP 内结账。 purchase_credits 会返回钱包深层链接。Stripe 结账需要使用浏览器。
• 暂不支持 C2PA 签名。 enrich_photo 会写入 EXIF、IPTC 和 XMP。formats: ["c2pa"] 会被拒绝。
• 暂不提供远程端点。 服务通过 stdio 运行。托管传输方式将在后续推出。
• 没有本地模型。 每次分析调用都会访问托管的 Phototology API。需要 API 密钥和网络连接。

7 个工具一览

工具	功能	费用
analyze_photo	对单张图像运行 AI 视觉分析，并按镜头返回结构化事实。接受 imageUrl、imageBase64 或 imagePath。	每个镜头 1 个积分。同一照片上重新运行已缓存的镜头：免费。
analyze_batch	在一次调用中分析 1 到 200 张照片。内部会先按 URL 查询（最多同时处理 20 个），然后以受限并发（最多同时处理 5 个，与 API 的每用户上限一致）分析缓存未命中的照片。若要处理数千张，请按每批 200 张循环调用。接受 imageUrls、imagesBase64 或 imagePaths（支持 glob）。返回 { summary, results }；传入 dryRun: true 可查看批次费用，而不实际消耗积分。	每张未缓存照片的每个镜头 1 个积分。缓存命中免费。试运行免费。
lookup_photo	检查单张照片是否已分析，并返回所有已缓存的镜头结果。接受 sha256、pHash、imageUrl、imageBase64 或 imagePath（按顺序逐级回退）。	免费。
enrich_photo	将已缓存的镜头输出写入照片的 EXIF/IPTC/XMP 元数据，让结构化智能信息随文件一同保存。接受 imageUrl、imageBase64 或 imagePath，以及可选的 outputPath，用于将增强后的副本保存为新文件（不会写入原文件；除非设置 overwrite: true，否则会拒绝覆盖已有文件）。返回增强后照片的 JPEG 小预览。若照片带有有效的内容凭证，则不会对其进行修改：分析结果会保存到旁侧的 <imagePath>.xmp 文件（sidecarSavedTo），或作为 sidecar.xmp 返回，并附带 mode: 'sidecar'、reason、credentials 和通俗易懂的 note。传入 breakCredentials: true 可强制写入副本。	每次调用 5 个积分。
list_lenses	列出可用的镜头和镜头组，并提供说明和输出字段。	免费。
get_credits	查询账户积分余额：可用积分总数 total 及其美元价值 usd；有正在处理的预留积分时，也会返回 reserved。	免费。
purchase_credits	返回钱包深层链接，用户可打开该链接购买更多积分。	免费。

工具如何串联。 从免费操作开始：对单张图像调用 lookup_photo，或在批量处理前调用 get_credits。然后仅分析缓存未命中的照片：单张使用 analyze_photo，两张或更多使用 analyze_batch。最后用 enrich_photo 将结果写入文件。list_lenses 和 purchase_credits 是免费辅助工具，可随时调用。

资源

URI	提供内容
phototology://lenses	镜头和镜头组目录，与 list_lenses 返回的数据相同。
phototology://photo/{sha256}	一条注册记录：其中包含哈希值、已运行的镜头及其回执。读取免费。不在注册表中的照片会返回 PHOTO_NOT_IN_REGISTRY。

analyze_photo、analyze_batch 和 lookup_photo 会将所提及的每张照片关联到其 phototology://photo/{sha256} 资源。

收据

分析和查询结果会附带 receipts：签名记录，说明哪些透镜分析了哪张照片、使用了哪个模型，以及分析时间。API 读取照片的内容凭证时，结果还会附带 credentials。要验证收据，可使用 @phototology/sdk 中的 verifyReceiptSignature（离线验证）或 client.verifyReceipt（服务端验证，免费）。

目前哪些用户会收到收据。 目前只有 pt_test_ 密钥会收到收据。这些收据由已发布的沙盒密钥签名，该密钥绝不会为实时数据背书：它们用于检查你的集成，而不是照片。目前尚未发布生产环境的实时签名密钥，因此，在发布之前，使用 pt_live_ 密钥进行全新分析时会收到 receipts: []，并附带警告 RECEIPT_UNAVAILABLE；从注册表返回的结果则会附带 RECEIPT_NONE_STORED（目前尚未存储任何实时收据）。分析及其计费不受影响。

分析结果中的 receipts 为空时，warnings 会说明原因（如果全新分析的透镜未产生输出，则既不会生成收据，也不会发出警告）：

Code	含义
RECEIPT_UNAVAILABLE	此次调用无法签署收据：未配置并发布实时签名密钥，或签名失败或超时。分析本身已完成。
RECEIPT_NONE_STORED	结果来自注册表，且没有已存储的收据涵盖所请求的透镜（该分析早于收据功能，或发布时未附带收据）。
RECEIPT_NOT_ISSUED_MULTI_IMAGE	此次调用发送了多张图片；收据仅针对单张图片的调用签发。
RECEIPT_NOT_ISSUED_BESPOKE	此次调用使用了自定义提取架构；此类调用不会获得收据。
RECEIPT_NOT_ISSUED_NO_ACCOUNT	此密钥未关联账户，因此没有可为收据注明的注册表记录。

analyze_photo 结果和已分析的 analyze_batch 行会附带这些警告。lookup_photo 以及从注册表返回的批次行会附带照片已存储的收据，不会附带收据警告：此处列表为空表示没有已存储的收据涵盖该照片。

enrich_photo 中的凭证。 enrich 结果中的 credentials 块描述的是输入照片，即写入前读取的照片。即使 credentials 显示输入照片有内容凭证，设置 breakCredentials: true 后，写入的副本也不再携带有效的内容凭证。

定价

• 1 个积分 = $0.01 = 在一张照片上运行一次透镜。 在一张照片上叠加五个透镜 = 5 个积分 = $0.05。
• 注册即可获得 1,000 个免费积分： 验证电子邮箱后发放。仅限一次，不会定期发放。
• 查询、透镜发现、余额读取和购买链接始终免费。
• 命中缓存不收费。 在同一张照片上重新运行相同的透镜，会免费返回缓存输出。注册表会让不同会话中的重复运行也保持免费。
• 自定义架构提取 = 每张图片 5 个积分（每额外叠加一个透镜，再加 1 个积分）。
• 审核免费且始终启用。 它是安全基础设施，永不计费。

积分包（均为每积分 $0.01，无批量折扣）

套餐	积分	价格
入门版	1,000	$10
专业版	10,000	$100
商业版	100,000	$1,000

首次购买可获双倍积分。 你首次购买的积分包可获得双倍积分。首次购买入门版 $10 套餐可获得 2,000 个积分。没有订阅；仅通过积分包按需付费。

本地文件

所有三个接受图像的工具（analyze_photo、analyze_batch、lookup_photo）都支持三种输入模式。根据照片的来源选择合适的模式：

输入字段	使用场景
imageUrl	照片位于可公开获取的 URL。
imagePath	照片位于用户本地磁盘上，且能被运行 MCP 服务的机器访问（通常是用户的笔记本电脑）。传入绝对路径（/Users/...）或以 ~/ 开头的路径（~/photos/...）。MCP 会读取文件、验证文件，并转发其字节。不能用于 Agent 沙盒路径（例如 Claude 的 /mnt/user-data/uploads/...）：本地安装的 MCP 无法访问该沙盒。对于 Agent 沙盒中的上传文件，请使用 imageBase64（小图像）或 imageUrl（可托管任意大小的图像）。
imageBase64	图像字节已作为 base64 字符串存储在内存中。实用大小范围：约 50-150KB 的 JPEG / 约 70-200K 个 base64 字符。超过此范围后，LLM 驱动的客户端会在 MCP 收到完整载荷之前耗尽输出令牌预算（3.4MB 的 JPEG 会生成约 4.57M 个字符）。对于较大的图像，优先使用 imageUrl 或 imagePath。

批量处理时：本地路径使用 imagePaths: string[]（支持 ~/vacation/*.jpg 这样的 glob），base64 数组使用 imagesBase64: string[]，并可与 imageUrls 自由组合。

lookup_photo 使用 imagePath / imageBase64 时，会运行透明的 sha256→pHash 级联检查。它始终免费，并会同时检查完全匹配和感知相似匹配。

注册表按以下顺序进行匹配：sha256（字节相同）、解码后的像素（图像相同但元数据不同）、PDQ（例如重新编码、旋转或翻转后的近似重复图像，距离不超过 31，且图像的 PDQ 质量至少为 50），然后是 pHash。在进行上述检查之前，lookup_photo 会先尝试读取 enrich_photo 写入文件 IPTC Extension（RegistryID）中的注册表 ID，因此经过增强的副本仍能找到其原始记录；命中时会返回 matchedBy: "registryId"。如果 enrich_photo 写入了注册表 ID，也会在结果中报告 registryId。

每张图像上限：原始文件 10MB。每次批量调用上限：共 200 个输入。支持的格式：JPEG、PNG、GIF、WebP、AVIF、TIFF。在 API 能够解码之前，HEIC/HEIF 文件会被拒绝，并提示进行转换。

设置：选择编辑器

Claude Code

在终端中运行一次：

claude mcp add phototology --scope user -e PHOTOTOLOGY_API_KEY=pt_live_... -- npx -y @phototology/mcp

这会将服务写入 ~/.claude.json，这样所有项目都能使用它。改用 --scope project 则会将其写入项目根目录下的 .mcp.json，并与代码仓库共享。如果手动编辑，这两个文件的格式如下：

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Cursor

项目中的 .cursor/mcp.json（或全局的 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

VS Code Copilot

.vscode/mcp.json：

{
  "servers": {
    "phototology": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Gemini CLI

~/.gemini/settings.json：

{
  "mcpServers": {
    "phototology": {
      "command": "npx",
      "args": ["-y", "@phototology/mcp"],
      "env": { "PHOTOTOLOGY_API_KEY": "pt_live_..." }
    }
  }
}

Codex CLI

~/.codex/config.toml：

[mcp_servers.phototology]
command = "npx"
args = ["-y", "@phototology/mcp"]

[mcp_servers.phototology.env]
PHOTOTOLOGY_API_KEY = "pt_live_..."

编辑配置后，重启编辑器。你应该能在 phototology 下看到已注册的 7 个工具。

前 5 分钟

按顺序尝试以下提示词：

1. 发现功能。 “使用 phototology MCP，告诉我有哪些镜头可用。” Agent 会调用 list_lenses，并向你展示所有可用的镜头和镜头组合。
2. 查看余额。 “我有多少 phototology 积分？” Agent 会调用 get_credits，并报告你可用的积分余额。
3. 低成本分析。 “只用 dating 镜头分析这张照片：<url>。” Agent 会选择 lenses: ["dating"]，花费 1 个积分，而不是运行完整目录。
4. 免费重新查询。 使用不同的问题重复查询同一个 URL，且问题已由缓存的镜头回答。无需花费积分。
5. 积分用完。 耗尽积分池后，再尝试一次分析。Agent 会收到包含钱包深层链接的结构化错误，并清楚地呈现该错误。

配套技能

软件包在 node_modules/@phototology/mcp/skills/ 下附带了五个可选技能。将其中任意技能复制到你的 Claude 技能目录（~/.claude/skills/<skill-name>/）即可安装：

• phototology:lookup-first：在消耗额度前务必先检查注册表（单张照片）。
• phototology:check-credits：批量处理前预先读取余额。
• phototology:smart-stack：针对具体问题，智能挑选成本最低的镜头子集。
• phototology:photo-shared：用户分享、附加、拖入或提及图像时始终启用。通过 Phototology 处理照片，以最低成本获得准确答案。
• phototology:batch-analyze：处理包含 2 张或以上照片的任务。调用 analyze_batch，而不是循环调用 analyze_photo。先查询，只分析未命中的照片，并显示节省的额度。

安装后，Agent 会在上下文匹配时调用这些技能。

可选：在附加图像时自动触发（Claude Code）

如果你希望 Claude Code 在你附加图像时立即自动提示使用 Phototology（无需模型自行判断），请将此钩子添加到 ~/.claude/settings.json：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "image",
        "command": "echo 'User shared an image. Consider phototology:photo-shared to route it through the registry-first analysis path.'"
      }
    ]
  }
}

该钩子会在每条包含图像的提示词中注入系统提示，引导模型在选择其他内容前优先使用 phototology:photo-shared 技能。如果你希望由模型自行判断，可以跳过此钩子。

镜头参考

镜头	所属输出字段
dating	estimatedDate、techAnchors、temporalMarkers、title、genre、caption、dateAnchors、season、holiday、event、visibleDates、reproduction
people	physicalObservations、collectionDynamics、peopleCount
location	location
atmosphere	atmosphere、emotions、warmCaption、semanticDescription
entities	entities
accessibility	accessibility
photo-quality	quality、visualFaults、rotation、documentClassification、scan
text-content	textContent
composition	composition
moderation	moderation
describe	describe
condition	condition
authenticity	authenticity
color-palette	colorPalette
automobile	automobile
vehicle-condition	overallCondition、componentGrades、observations、accidentIndicators、photoQuality、missingViews、vehicleContext、photos、sellerSummary

在 analyze_photo 上通过 lenses: [...] 传入上述任意镜头，或者使用一个组合多个镜头的堆栈（full-analysis、quick-scan、automobile、claims、property、ecommerce、memorial、vehicle-condition）。工具架构中的堆栈枚举是权威列表；发布后新镜头会自动显示在此处。

命名说明。 旧工具名为 list_modules，旧参数名为 modules / preset。当前名称为 list_lenses / lenses / stack。重命名期间，旧名称仍可作为 analyze_photo 中已弃用的别名使用。新代码请优先使用新名称。

差异计费

Phototology 会根据感知哈希，按账户记住每张照片。同一图像的第二次调用中，已运行过的镜头均不消耗额度。只有新镜头才会调用大模型。传入 refresh: true 可绕过缓存并重新运行。

环境变量

变量	必填	描述
PHOTOTOLOGY_API_KEY	是	你的 API 密钥（pt_live_... 或 pt_test_...）。请访问 https://phototology.com/signup 注册账号并获取密钥。
PHOTOTOLOGY_BASE_URL	否	API 基础 URL。默认值：https://api.phototology.com。
PHOTOTOLOGY_MCP_NO_TELEMETRY	否	设置为 1，即可停用匿名客户端发现遥测（见下文）。
DO_NOT_TRACK	否	设置为 1，即可停用遥测。效果与 PHOTOTOLOGY_MCP_NO_TELEMETRY 相同；它遵循许多 CLI 采用的跨工具惯例。
PHOTOTOLOGY_MCP_ALLOWED_DIRS	否	服务可以读取照片和写入丰富信息副本的文件夹，以 : 分隔（Windows 上使用 ;），例如 /Users/me/Pictures:/Volumes/Archive。未设置时，允许使用任何本地路径。路径会在解析符号链接后进行检查，因此，如果允许文件夹中的链接指向其他位置，会被拒绝并返回 PATH_OUTSIDE_ALLOWED_DIRS。

以 pt_test_ 开头的密钥使用测试沙盒（即时响应、零费用、固定测试数据）。沙盒按 IP 地址限制为每分钟 2 个请求、每天 10 个请求；超出限制后，工具会返回带有 retryAfterSeconds 的 RATE_LIMITED 错误，而不会等待。API 返回的每个工具错误都以一行 JSON 开头（包含 code、retryable 以及 retryAfterSeconds 或 actionUrl 等字段），后面跟着一句说明；错误结果不含 structuredContent。沙盒密钥无法读取注册表或余额，也无法向照片写入元数据：lookup_photo、get_credits 和 enrich_photo 会返回 SANDBOX_KEY 错误。要使用这些功能，请访问 https://phototology.com/signup 注册账号并获取密钥。

匿名遥测

MCP 服务与编辑器完成初始化握手时，会将编辑器声明的名称和版本（例如 claude-desktop 0.7.0、cursor 0.42）以及 MCP 软件包版本发送到 api.phototology.com，以便我们了解哪些客户端正在连接。每次调用工具后，服务都会发送一条事件，其中包含工具名称、调用是否成功、耗时、失败时的错误代码，以及以下统计信息：扣除的点数、运行的镜头数、提交的照片数、缓存命中数，以及 analyze_photo 调用是否完全命中缓存。遥测与工具调用使用相同的域名。软件包不包含第三方 SDK，且仅使用你的 API 密钥作为凭据。不会发送图像内容、文件路径、提示词、对话文本或工具输入/输出。

在与 PHOTOTOLOGY_API_KEY 相同的环境变量区块中设置 PHOTOTOLOGY_MCP_NO_TELEMETRY=1 或 DO_NOT_TRACK=1，即可停用遥测。当进程以 NODE_ENV=test 运行时，遥测也会停用。

安全模型

完整策略见 SECURITY.md。简而言之：

• 读取内容。 仅读取你指定的文件，路径须为绝对路径（或 ~/ 路径）。如果设置了 PHOTOTOLOGY_MCP_ALLOWED_DIRS，则只读取这些文件夹中的文件，并在解析符号链接后进行检查。enrich_photo 只会写入你提供的 outputPath，或写入携带有效内容凭据的照片旁边的 <imagePath>.xmp；如果设置了允许文件夹，也只会写入这些文件夹中。
• 发送内容。 将图像字节（或你提供的 URL 或哈希）发送到 api.phototology.com，以及在匿名遥测中所述的遥测负载。
• 绝不发送的内容。 遥测中不会包含文件路径、工具输入或输出，也不会包含你的对话文本。
• 不构成安全边界的内容。 工具注解（如 readOnlyHint）只是提供给编辑器的提示，并非强制措施。服务本身以你的用户权限运行，不是沙盒。请保持编辑器的工具确认功能开启。
• 报告漏洞。 请发送邮件至 [email protected]。请勿创建公开问题单。

常见问题

为什么 analyze_photo 同时接受 lenses 和 modules？ 品牌名称已于 2026-04 从“module”统一为“lens”。更名期间，MCP 接口同时接受这两个名称；SDK 仍使用 modules。新代码请优先使用 lenses。

为什么审核从不计费？ 审核是安全基础设施，而不是可选功能。每次分析都会进行 CSAM 和非法内容检测。将其列为单独的收费项目会产生不良激励。

get_credits 和 lookup_photo 有什么区别？ get_credits 会读取你的账户余额。lookup_photo 会检查某张特定图片之前是否分析过。两者都免费，但回答的是不同的问题。

为什么 purchase_credits 返回的是“深层链接”，而不是直接完成结账？ Stripe 结账需要浏览器。MCP 无法完成付款；用户必须打开工具返回的 URL。

链接

• TypeScript SDK：npm install @phototology/sdk
• API 文档
• OpenAPI 规范
• GitHub

许可证

MIT