Dizko Events CLI 和 MCP

快速开始

推荐：添加托管连接器。它运行在我们的服务器上，因此永远不会访问你的计算机（没有可怕的本地安装警告），无需安装，也无需认证：

https://mcp.dizko.app/mcp

将其粘贴到客户端的 设置 → 连接器 → 添加自定义连接器（claude.ai、Claude Desktop、ChatGPT 开发者模式、Cursor）。每个客户端的逐步说明：https://mcp.dizko.app/install

对于 Claude Code：

claude mcp add --transport http dizko-events https://mcp.dizko.app/mcp

高级：在本地运行服务器（仅当你无法使用托管连接器时，例如免费 Claude 套餐或只支持本地服务器的客户端）。本地服务器以你的身份运行，因此 Claude Desktop 会警告它可以“访问你计算机上的所有内容”。这是任何本地 MCP 扩展的固有属性，并不是这个包过度请求的。上面的托管连接器可以避免这种情况。

npx -y dizko-events install claude-desktop   # writes the local config
# or the raw stdio snippet for any client:
{ "command": "npx", "args": ["-y", "dizko-events", "mcp"] }

Claude Desktop 一键捆绑包：npm run build:mcpb 会生成 dist/dizko-events-<version>.mcpb。

智能体框架（Hermes、OpenClaw、LangGraph、OpenAI Agents SDK、自定义循环）

框架智能体没有“连接器”界面，因此它们以编程方式集成。四条路径，从最简单的开始：

1. 通过 HTTP 进行远程 MCP：将框架的 MCP 客户端指向托管端点 https://mcp.dizko.app/mcp（streamable-http，无需认证）。适用于官方 MCP SDK、OpenAI Agents SDK、LangGraph/LangChain MCP 适配器、Pydantic AI 等。

2. stdio MCP：将 npx -y dizko-events mcp 作为子进程启动，并通过 stdio 进行 MCP 通信。

3. 原始 HTTP JSON-RPC：无需 MCP 库；向 /mcp 发送 POST 请求：

   curl -s https://mcp.dizko.app/mcp \
     -H 'content-type: application/json' \
     -H 'accept: application/json, text/event-stream' \
     -H 'mcp-method: tools/call' \
     -H 'mcp-name: search_events' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_events","arguments":{"city":"los angeles","when":"this week"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

   _meta 块正是使这个请求成为 2026-07-28 请求的原因：该修订版本是无状态的，因此没有 initialize 握手，也没有会话——每个请求都携带自己的协议版本和客户端能力。调用 server/discover 可查看端点支持哪些修订版本。使用 2025-11-25 及更早版本的客户端无需更改即可继续工作；省略 _meta，服务器会改走 2025 时代的路径来响应它们。

4. 进程内库：直接嵌入这些工具（不经过 MCP 层）。该包提供了稳定的 API：

   import { tools, callTool, searchEvents } from "dizko-events";
   // Hand `tools` (JSON Schemas) to your model as function definitions, then:
   const result = await callTool("search_events", { city: "berlin", when: "weekend" });

自主购票（Hermes / OpenClaw 集成点）

默认情况下，票务工具会返回结账交接（一个链接）。要启用有界自主购买，请提供 ticketPurchaseProvider 适配器。这仅在你嵌入该包或自行托管服务器时才可注入——托管端点运行在我们的进程中，无法接受你的支付适配器。

import { createHttpMcpServer, callTool } from "dizko-events";

const hermesAdapter = {
  canPurchase: (event, summary) => true,
  purchase: async ({ quote, confirmation_text, delivery_email, add_to_calendar }) => {
    // ... perform the bounded purchase, return { status, order_id, receipt_url }
  }
};

// Self-host with the adapter wired in:
createHttpMcpServer({ ticketPurchaseProvider: hermesAdapter }).listen(8787);

// ...or call tools in-process with it:
await callTool("purchase_ticket_order", input, { ticketPurchaseProvider: hermesAdapter });

在调用适配器之前，purchase_ticket_order 仍然需要来自 quote_ticket_order 的锁定报价和明确的书面确认。参见 get_ticket_purchase_policy。

此包向智能体和人类展示 Dizko 的实时活动库存：

• dizko-events：一个用于快速搜索、排名推荐、夜间计划、客户端安装和诊断的 CLI。

• dizko-events mcp（别名 eventchat-events-mcp）：面向本地开发人员客户端的 stdio MCP 服务器。

• dizko-events serve（别名 eventchat-events-http）：用于托管连接器/应用的 HTTP MCP 服务器。

• 面向票务优惠、锁定报价、书面确认、结账交接以及未来 Hermes/OpenClaw/Dizko 购买适配器的智能体票务工具。

为什么这比普通聊天更好

普通聊天可以描述可能的活动，但它无法可靠地知道当前库存。这个工具为智能体提供：

• 来自 Dizko /events API 的实时结构化结果。

• 针对城市、日期、类型、氛围、场地、价格、上座率、街区和艺术家的确定性过滤器。

• 可解释的排名，让推荐包含理由，而不是不透明的口味猜测。

• 用于验证的票务链接和 Dizko 活动链接。

• 一个规划工具，以紧凑的机器可读形式返回主要选项和备选方案。

• 基于同意的偏好学习：引导问题、保存的口味档案、活动后反馈、笔记派生信号和学习的排名信号。

• 负面反馈会变成学习到的回避信号，因此未来的推荐可以避开不喜欢的类型、氛围、活动类型或场地。

• 购票安全护栏：智能体可以报价并准备票务订单，但自主购买需要锁定报价、明确的书面确认和集成的购买提供方。

智能体仍然可以编写对话式散文，但其活动事实来自该工具。

CLI

无需安装即可运行：

npm exec --yes --package dizko-events -- dizko-events search --city "Los Angeles" --when week --limit 5
npm exec --yes --package dizko-events -- dizko-events recommend --city "New York" --when tonight --vibe underground,intimate --max-price 30

或安装早期访问开发人员包：

npm install -g dizko-events
eventchat-events search --city berlin --when weekend --genres techno --limit 5

从本仓库：

node ./bin/eventchat-events.js search --city berlin --when weekend --genres techno --limit 5
node ./bin/eventchat-events.js recommend --city new-york --when tonight --vibe underground,intimate --max-price 30
node ./bin/eventchat-events.js plan --city london --when weekend --event-types party --avoid mainstream
node ./bin/eventchat-events.js cities
node ./bin/eventchat-events.js doctor

doctor 检查 DNS 解析、API 健康端点、托管 MCP 端点（健康、元数据、tools/list），以及一次小型实时搜索，并报告任何失败的根本原因。每当搜索失败时，请首先运行它。

环境（所有层面——CLI、stdio MCP、托管 MCP、冒烟测试和监控——都通过同一个 src/config.js 解析端点）：

DIZKO_API_BASE_URL=https://api.dizko.app
DIZKO_WEB_BASE_URL=https://www.dizko.app
DIZKO_MCP_URL=https://mcp.dizko.app/mcp
DIZKO_API_TIMEOUT_MS=8000
DIZKO_API_RETRIES=2                  # transient network/5xx failures retry with backoff + jitter
DIZKO_API_RETRY_BASE_DELAY_MS=250
EVENTCHAT_MCP_ALLOWED_ORIGINS=https://chatgpt.com,https://chat.openai.com,https://claude.ai

瞬时网络故障（EAI_AGAIN、ETIMEDOUT、ECONNRESET、ENOTFOUND、临时 5xx）会自动重试，并在持续存在时报告为 retryable: true，同时附上根本原因、代码、主机名和目标 URL。

面向本地开发人员客户端的 MCP

从 npm 运行 stdio MCP 服务器：

npm exec --yes --package dizko-events -- eventchat-events-mcp

或从本仓库：

node ./bin/eventchat-events-mcp.js

示例 MCP 客户端配置：

{
  "mcpServers": {
    "eventchat-events": {
      "command": "node",
      "args": ["/absolute/path/to/dizko-mcp/bin/eventchat-events-mcp.js"],
      "env": {
        "DIZKO_API_BASE_URL": "https://api.dizko.app"
      }
    }
  }
}

使用 npm 的示例 MCP 客户端配置：

{
  "mcpServers": {
    "dizko-events": {
      "command": "npm",
      "args": ["exec", "--yes", "--package", "dizko-events", "--", "eventchat-events-mcp"],
      "env": {
        "DIZKO_API_BASE_URL": "https://api.dizko.app"
      }
    }
  }
}

工具：

• get_preference_onboarding：返回助手在保存偏好之前应提出的问题。

• create_event_preference_profile：在获得同意后创建一个不透明的已保存偏好档案，并返回一个档案 id 以及助手可以记住的私有档案密钥。

• save_event_preferences：仅在获得明确同意和档案密钥访问权限后保存用户偏好。

• get_event_preferences：使用档案密钥访问权限读取已保存和学习到的偏好。

• delete_event_preferences：在具有档案密钥访问权限并获得用户明确确认后，删除档案的已保存偏好和反馈。

• record_event_feedback：存储活动后的喜欢/不喜欢信号、评分或笔记，并在具有档案密钥访问权限的情况下更新学习信号。关于音乐、人群、价格、时间或场地的笔记可以成为学习到的偏好或回避信号。它会拒绝空反馈。

• get_event_feedback_prompt：在保存反馈之前，返回针对特定活动的简短活动后跟进问题。

• get_event_search_followups：在今晚/本周/周末搜索之前，仅返回缺失的当前上下文问题。

• search_events：实时结构化活动搜索。

• recommend_events：实时搜索加可解释的口味排名。

• recommend_events_for_user：使用保存的偏好和学习到的反馈，在档案密钥访问权限下提供实时推荐。

• plan_night：带有备选方案的紧凑计划。

• get_daily_roundup：一个城市的一日摘要：排名靠前的精选，外加派对、现场音乐、艺术、喜剧、讲座和美食板块。专为定期早间简报而设计；可选的档案密钥访问权限使用已保存的、学习到的和每日偏好来个性化排名。

• get_artist_events：按艺术家分组显示指定 DJ、表演者或喜剧演员的即将到来的演出。在具有档案密钥访问权限且未指定艺术家时，它会跟踪档案保存的 featuring 列表。

• get_city_pulse：某个城市未来几天的总体势头读数：最繁忙的夜晚、顶级场地、类型组合和头条活动，每项统计数据都带有证据计数。仅限公共库存。

• get_event：按活动 id 查询详情。

• get_ticket_purchase_policy：解释当前的购买模式、硬性安全规则和提供方要求。

• get_ticket_offers：返回活动的票务选项，包括结账 URL 以及是否支持自主购买。

• quote_ticket_order：创建带有数量、最高总价、票种、过期时间和停止条件的锁定报价。

• purchase_ticket_order：接受明确的书面确认，并执行集成的提供方购买，或返回所需的外部结账交接。

注解说明：搜索和推荐工具读取实时活动数据，而偏好工具只写入受 profile_id 加 profile_secret 保护的私有连接器记忆。只有 purchase_ticket_order 被标记为破坏性/开放世界，因为它是票务购买或结账交接的有界动作点。

票务说明：purchase_ticket_order 被有意标记为破坏性和开放世界，因为它是未来自主购票的动作边界。在默认的 npm/托管构建中，第三方票务链接返回 requires_external_checkout；该工具不会抓取结账页面、绕过 CAPTCHA 或扣款。真正的自主购买需要提供方适配器，例如 Hermes、OpenClaw、Dizko Checkout、合作伙伴票务 API 或经批准的委托支付流程。

认证说明：公共托管连接器以 noauth 方式提交以进行基本活动发现。保存偏好、反馈、个性化推荐、读取、更新和删除工具仍然需要用户的不透明 profile_id 加私有 profile_secret。工具描述符包含 securitySchemes: [{ "type": "noauth" }]，并在 _meta.securitySchemes 中镜像它，以实现 ChatGPT 兼容性。

删除安全说明：delete_event_preferences 还要求 confirm_delete: true，只有在用户确认要删除 Dizko 连接器偏好和反馈历史后，才应发送该参数。

保留说明：保存的偏好档案会在配置的不活动窗口后自动清理，默认 730 天，与公布的 24 个月保留政策一致。

面向 ChatGPT 和 Claude 的托管 MCP

对于普通用户，请发布托管 MCP 端点，而不是要求他们运行本地命令。

PORT=8787 node ./bin/eventchat-events-http.js

端点：

• POST /mcp：JSON-RPC MCP 端点。

• GET /health：部署健康检查。

• GET /：基本服务元数据。

• GET /privacy-policy.html：关于已保存偏好、反馈、保留和删除的公开隐私政策。

• GET /support.html：公开的支持、删除和安全联系页面。

• GET /terms.html：公开的连接器条款和可接受使用页面。

• GET /user-guide.html：面向普通用户的公开指南，包含提示、偏好记忆、反馈和删除行为。

• GET /.well-known/security.txt：漏洞报告联系元数据。

• GET /logo-512.png：用于提交元数据的 512px 连接器徽标。

当前已部署的端点：

https://mcp.dizko.app/mcp

要成为 ChatGPT 应用/插件：

1. 在公共 HTTPS 域上部署此 HTTP 服务器。

2. 在 ChatGPT 开发者模式中通过使用该 URL 创建连接器来测试它。

3. 在 Web 和移动端验证工具调用。

4. 通过 OpenAI 仪表板提交应用，包含公共 MCP URL、隐私/支持 URL、徽标、截图、测试提示和工具描述。

Claude 用户可以在其套餐/工作区支持远程 MCP 的情况下，将相同的公共 MCP URL 添加为自定义连接器。

参见 plugin-submission.md 和 submission-fields.json 以获取可用的提交文案。 参见 OPENAI_SUBMISSION_PACKET.md 获取最终的仪表板交接包。 参见 SCREENSHOT_CHECKLIST.md 获取确切的 ChatGPT 开发者模式截图提示和文件名。 参见 SUBMISSION_AUDIT.md 获取需求到证据的映射以及剩余的外部审查关卡。 参见 USER_GUIDE.md 获取普通用户提示、偏好记忆行为以及支持/隐私链接。 参见 DEPLOYMENT.md 获取 Railway、Docker、自定义域和审查步骤。 参见 OPERATIONS.md 获取健康检查、日志、回滚、偏好数据处理和重新提交触发器。 参见 golden-prompts.md 获取用于连接器发现和工具路由的直接、间接和负面提示测试。 参见 SECURITY.md 获取漏洞报告和运营保障措施。

实时冒烟测试：

npm run monitor:live
npm run smoke:live

monitor:live 是只读的，适合进行正常运行时间检查。smoke:live 还会执行临时偏好档案的创建和删除。

提交证据：

npm run verify:submission
npm run verify:submission:write
npm run verify:submission:bundle
npm run verify:submission:fields
npm run submission:status
npm run review:demo
npm run preflight:submission

bundle 命令会保存 submission-evidence/latest.json 和 submission-evidence/latest-summary.md，用于仪表盘审查准备，同时将生成的证据排除在 git 之外。证据包括已验证的端点、当前的 Railway 部署 ID、镜像摘要、公开页面检查、工具元数据、实时搜索和偏好记忆流程。 fields 命令会将稳定的仪表盘文案产物 submission-fields.json 与最新的实时证据（包括部署元数据）进行校验。 preflight 命令在一次运行中执行本地测试、实时冒烟测试、实时提交证据生成和仪表盘字段校验。 status 命令针对 OpenAI 仪表盘提交给出最终的 go/no-go 判定，指明要提交的端点，并将未解决的自定义域名状态与托管端点就绪状态分开处理。 review-demo 命令根据实时 MCP 调用生成一份脱敏的 submission-evidence/review-demo.md 记录，用于仪表盘提示词/响应的准备。

支持删除工具：

npm run preferences:delete -- --profile-id upg_... --profile-secret ups_... --preferences-path /data/preferences.json

此工具用于支持删除请求，适用于用户无法通过其 MCP 客户端调用 delete_event_preferences 的情况。

个性化流程：

1. 用户请求个性化的活动帮助。

2. 助手调用 get_preference_onboarding，并询问用户通常喜欢哪些活动、类型、氛围、预算、地点以及需要避免的事项。

3. 助手询问 Dizko 是否可以保存这些偏好。

4. 如果是，且不存在现有偏好档案，助手调用 create_event_preference_profile，并私下记住返回的 profile_id 和 profile_secret。

5. 创建响应还包含 access_instructions，这是一张面向用户的访问卡片，适用于无法在会话之间持久化连接器状态的客户端。

6. 如果偏好档案已存在，助手使用 profile_id 和 profile_secret 调用 save_event_preferences。

7. 对于今晚/本周/周末的搜索，助手调用 get_event_search_followups，询问轻量级的当前上下文问题，然后调用 recommend_events_for_user。

8. 偏好可以包含 day_filters，即按星期几设置的规则，例如周五 techno 音乐，周日放松。数组字段会添加到总体喜好中，max_price/free/nightlife 会覆盖它，但仅限该工作日：单日搜索（今晚、明天、明确日期）和每日汇总会自动应用匹配的日期。

9. 对于每日摘要（“今天有什么活动？”，即定时晨间简报），助手使用城市和偏好档案凭据调用 get_daily_roundup，并渲染热门精选，随后按类别分区展示。

10. 活动结束后，助手调用 get_event_feedback_prompt，询问用户是否去了以及是否喜欢，然后仅在用户提供喜欢/不喜欢、评分或备注后调用 record_event_feedback。

购票流程：

1. 用户请求为活动购买或预订门票。

2. 助手使用活动 ID 调用 get_ticket_offers。

3. 助手说明该报价支持自主购买还是仅支持外部结账。

4. 助手使用数量、票种、最大总额、货币和退款限制调用 quote_ticket_order。

5. 助手请求明确的书面确认，例如：Yes, buy 2 ticket(s) for Ostbahnhof XL, max total USD240. Stop if price, date, venue, ticket type, quantity, or refund terms change.

6. 助手仅在收到该确认后才调用 purchase_ticket_order。

7. 如果报价使用 external_checkout，该工具会返回 requires_external_checkout 和结账 URL。助手不得声称已购买该门票。

8. 如果配置了 Hermes、OpenClaw、Dizko Checkout 或其他集成提供商，该提供商可以执行受限购买，并返回订单/收据/门票交付状态。

提供商适配器契约：

{
  canPurchase(event, summary) {
    return true;
  },
  async purchase({ quote, confirmation_text, user_payment_profile_id, idempotency_key }) {
    return {
      purchased: true,
      status: "purchased",
      order_id: "...",
      receipt_url: "...",
      ticket_delivery_status: "pending_delivery",
      provider_response: {}
    };
  }
}

分发说明

公开的 ChatGPT 用户界面是托管的 MCP 端点以及 OpenAI 应用提交。npm 包是面向本地代理、Claude Desktop 风格 MCP 客户端、Cursor 和 Windsurf 配置以及能运行命令的技术测试人员的开发者分发路径。源代码公开，可供检查和报告问题。它仍标记为 UNLICENSED，因此发布并不授予复用许可。

在发布新的 npm 版本之前：

npm test
npm pack --dry-run --json
npm publish --access public