TownSpot API 和代理发现

TownSpot 发布用于公共发现的机器可读发现文档、经过身份验证的事件写入工作流程、抓取提交 MCP 工具和操作收据。

发现文件

这些众所周知的 URL 可帮助代理和集成客户端发现 TownSpot 服务，而无需硬编码假设。

/.well-known/api-catalog - https://www.townspot.co/.well-known/api-catalog
/.well-known/openid-configuration - https://www.townspot.co/.well-known/openid-configuration
/.well-known/oauth-protected-resource - https://www.townspot.co/.well-known/oauth-protected-resource
/.well-known/mcp/server-card.json - https://www.townspot.co/.well-known/mcp/server-card.json

面向 AI 助手的公共 MCP

可将 ChatGPT、Claude 或其他 MCP 客户端连接到 TownSpot——由本地人共同打造的活动指南。你可以询问整座城市或某个街区正在发生什么。无需账户，也不能创建或编辑活动。

https://api.townspot.co/api/mcp/events
传输方式：远程 Streamable HTTP。
身份验证：无需。
可用工具：解析城市或城镇、列出城镇、获取城镇、按城市或城镇搜索已发布活动、获取活动以及获取场地。
活动搜索和活动详情结果包含当地时间、明确的城市和街区、日程标签、TownSpot 规范链接，以及在用户同意允许时显示的公开“Spotted by”署名。
搜索限制：每次请求最多20个结果，日期范围最多31天。
此公共连接器仅用于发现。TownSpot 的独立 API 负责受保护的公开提交和经过身份验证的编辑；CLI 还会执行运营者录入检查。
支持： https://www.townspot.co/contact-us

最简连接请求：

POST https://api.townspot.co/api/mcp/events
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "your-client", "version": "1.0.0" }
  }
}

提交与运营者 API

以下示例独立于公共市场连接器。活动来源提交是匿名的，但受保护且有速率限制；审核和编辑操作需要适当的 TownSpot 凭据。

通过公共活动列表或规范城镇页面查找活动。
通过 MCP 工具提交事件源 URL，并包含用于安全重试的幂等性密钥。
使用审核端点或经过身份验证的 MCP 工具审核或更新创建的事件。

公共端点

这些端点公开了城镇、活动、场地、MCP 抓取到提交流程和操作收据的主要发现和事件写入表面。

https://api.townspot.co/api/locations/list
https://api.townspot.co/api/locations/get-by-slug
https://api.townspot.co/api/events/list
https://api.townspot.co/api/submit/event
https://api.townspot.co/api/mcp — MCP tools now include submit_event_from_url plus action receipts and idempotency support for write flows.
https://api.townspot.co/api/submit/event/{uuid}
https://api.townspot.co/api/events/{uuid}/review
https://api.townspot.co/api/p/venues/{slug}
https://api.townspot.co/api/openapi.json
https://api.townspot.co/api/healthz
https://api.townspot.co/api/venue-admin/{slug}/events/{eventUuid}

请求和响应示例

查找城镇的公共活动。

GET https://api.townspot.co/api/events/list?zone_id=1&date=2026-05-09

{
  "results": [
    {
      "uuid": "event-uuid",
      "title": "Community market",
      "startTime": "2026-05-09T10:00:00.000Z",
      "venueName": "Town Hall",
      "zoneId": 1
    }
  ]
}

通过 MCP 从源 URL 提交事件。

POST https://api.townspot.co/api/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "submit-1",
  "method": "tools/call",
  "params": {
    "name": "submit_event_from_url",
    "arguments": {
      "url": "https://example.com/events/community-market",
      "idempotencyKey": "community-market-2026-05-09"
    }
  }
}

使用经过身份验证的请求查看事件。

GET https://api.townspot.co/api/events/{uuid}/review
Authorization: Bearer {supabaseJwt}

{
  "event": {
    "uuid": "event-uuid",
    "title": "Community market",
    "status": "ready_for_review"
  },
  "actions": ["approve", "edit", "request_more_info"]
}

验证

受保护的 TownSpot 管理员和场地经理 API 使用 Supabase Auth 颁发的不记名令牌。

使用 OpenID Connect 和 OAuth 元数据文档以编程方式发现授权、令牌、JWKS 和受保护资源详细信息。公共提交工具还可以使用事件编辑令牌、提交者电子邮件链接或已存在该流程的场地管理令牌。 MCP 写入工具可以包括幂等密钥和返回操作收据，以便代理可以干净地重试。

规范 URL 模式

https://www.townspot.co/{countryCode}/{townSlug}
https://www.townspot.co/event/{eventSlug}-{eventUuid}
https://www.townspot.co/venue/{venueSlug}