MCP 服务器（Claude 与 AI 助手）

它是酒窖数据与 MCP 客户端之间的安全桥梁。完成身份验证后，助手可按您的授权调用 VinoCellar 工具，并受订阅与账户规则约束。

确切的公开 URL 显示在 VinoCellar 应用的 MCP / 令牌页面（应用内路径 /app/mcp）的「MCP 服务器地址」区块，请原样复制。

在官方生产环境中，默认 MCP 主机为 https://mcp.vinocellar.app 。若应用显示的值不同，请始终以应用内为准（自定义构建或未来通过 EXPO_PUBLIC_MCP_SERVER_URL 配置）。

1. 打开应用 → MCP 区块（或 设置 → VinoCellar MCP → 管理令牌）。
2. 在对应区域复制服务器 URL。
3. 在 Claude Desktop（或其他客户端）中添加 MCP 服务器，并按该客户端最新文档粘贴 URL。
4. 首次连接时在浏览器中完成 OAuth 步骤；表单提示时粘贴您在应用中创建的个人令牌。

VinoCellar MCP 服务器遵循 MCP 规范，采用 Streamable HTTP 传输：客户端通过 HTTPS 与 MCP 入口通信（不是可手动浏览的通用「REST 目录」）。

首次连接时，MCP 客户端会启动类 OAuth 流程。浏览器窗口会要求粘贴您在 VinoCellar 应用中创建的个人访问令牌；MCP 服务器向 VinoCellar API 校验后，再颁发凭据，由客户端在后续 MCP 请求中以 Bearer 令牌发送。

在 MCP 界面创建的令牌带有 mcp:read 与 mcp:write 权限范围，以便助手调用 VinoCellar 注册的各工具。

若仅需确认主机可达（无需完整 MCP 会话），服务器对 GET /ping 返回纯文本 pong。

令牌用于向 MCP 服务器标识您的账户：

1. 在应用中打开 MCP 页面并创建令牌。
2. 填写清晰名称（例如「MacBook」「Cursor」）。
3. 立即复制令牌内容——仅显示一次。
4. 若设备丢失或需断开某客户端，可在同一页面撤销令牌。

请将令牌视为密码：在撤销前，持有令牌与 URL 者可通过 MCP 访问您的酒窖。

以下为向 MCP 客户端暴露的工具名称（精确标识符）：

• vinocellar_whoami — 验证连接；JSON 响应包含 mcp 对象（欢迎文案、FAQ 链接、工具提示）。
• vinocellar_help — 返回与 vinocellar_whoami 中 mcp 块相同的上手 JSON，无需再次调用资料接口。
• vinocellar_list_wines — 大范围库存列表；若按酒庄名等筛选请优先使用 vinocellar_search_wines。
• vinocellar_search_wines — 对酒瓶做文本搜索。
• vinocellar_get_caves — 列出酒窖，便于选择目标酒窖。
• vinocellar_get_cave — 按格位查看布局；提供供 vinocellar_move_bottle 使用的 log_id。
• vinocellar_move_bottle — 使用 vinocellar_get_cave 返回的 log_id 将酒瓶移到其他格位或酒窖。
• vinocellar_import_wine — 从结构化 wine_data（GeminiWineResponse 形态）添加酒款，可选正/背标 Base64 图片；账户需有有效 MCP 订阅。

MCP 工具仅限于上文列出的库存与酒窖结构操作。

应用内的 Vino 对话助手、餐酒搭配向导、品鉴日记等 AI 功能不会作为单独的 MCP 工具暴露——请使用移动应用或网页版体验。

VinoCellar 面向使用兼容 MCP 客户端的最终用户（例如 Claude Desktop）：从应用复制服务器 URL 并创建个人令牌。

没有独立的第三方 OAuth 应用，也没有「把 MCP 当作 REST」的 OpenAPI 文档：集成契约即 MCP 协议（tools/list 以及各工具在客户端中展示的描述/模式）。

积分主要用于应用内酒标扫描等 AI 流程。MCP 订阅单独计费：在订阅有效期内，通过 MCP 服务器进行的受支持操作在 VinoCellar 侧不按扫描积分余额同样方式封顶。

目前支持 Claude Desktop 及兼容 VinoCellar 传输方式的 MCP 客户端。ChatGPT 与 Gemini 兼容性计划中，请关注更新说明与本 FAQ。