CREHQ Location Intelligence

CREHQ MCP 服务

一个 Model Context Protocol 服务，可将 CREHQ 的实时位置情报 REST API转化为 Claude 和其他 AI Agent 可直接使用的工具。向 Agent 提问：“Chipotle 下一家店应该开在哪里？”、“这家门店隶属于哪个酒店连锁？”、“这个地址曾经由哪些商家入驻？”，或*“Aspen Dental 有哪些信用信号？”*——Agent 就能基于 CREHQ 权威且经过多来源验证的数据库，给出真正有依据的回答。该数据库涵盖特许经营和多门店品牌、独立门店、FDD 财务数据、信用信号，以及门店级租户历史；数据来源包括政府记录、特许经营申报文件和品牌发布的数据。

这是对 CREHQ 现有生产环境 API（https://crehq.com/wp-json/crehq/v1）的轻量封装。它不会存储数据，也不会在服务器端修改任何内容——只需使用你的 API 密钥进行身份验证并转发调用。

---

提供的功能（33 个工具）

升级／付费墙路由

• crehq_request_upgrade — 沙盒用户请求信用信号、FDD／Item 19、选址标准、房地产要求、联系人、来源溯源、变更历史、批量下载、市场空白、共同租赁或门店时间线等高级数据时使用。使用免费沙盒密钥时，此工具会在 CREHQ 中记录升级意向，并向用户提供清晰的升级路径，而不是告知用户数据不存在。
• crehq_intelligence_preview — 对于 Pro 自助服务密钥，该工具会使用每月 1 次的受控情报预览额度，并返回范围有限的证据摘要，不会暴露高级数据表原始内容或再分发权。

实体隶属关系

• crehq_resolve_entity_affiliation — 根据门店网址、名称或地址，查询有证据支持的隶属状态、规范品牌、运营方和母公司，覆盖酒店、餐厅、零售、医疗保健、银行、汽车经销商、电动汽车充电及其他位置类别。有效结果包括：品牌门店、独立门店、非商业门店和未能解析。付费访问响应会保留准确的结账网址和 CREHQ 意向 ID。结账后系统会通过电子邮件发送新的 Pro 密钥，必须先安装该密钥再重试；当前凭据不会直接升级。

公司／品牌

• crehq_companies_list — 列出品牌，并按类别和扩张状态筛选
• crehq_companies_search — 查询品牌名称 → CREHQ 公司 ID（从这里开始）
• crehq_company_get — 规范品牌档案、经验证的门店数量、所有权信息
• crehq_company_credit_signals — 信用档案、发起方／发行方背景、评级、资本结构
• crehq_company_franchise — FDD 费用、特许权使用费、投资额、Item 19 数据
• crehq_company_real_estate — 选址标准和目标地理区域
• crehq_company_contacts — 房地产／开发决策者联系人

位置

• crehq_locations_list — 按品牌／州／类别列出门店记录
• crehq_location_get — 获取单个位置的完整属性和验证记录
• crehq_locations_search — 按多个字段模糊搜索位置
• crehq_locations_nearby — 围绕经纬度坐标进行半径搜索（贸易区绘图）
• crehq_locations_bulk — 按 ID 列表、品牌列表或 GeoJSON 多边形批量提取数据
• crehq_locations_events — 跨品牌的开业／关闭／搬迁生命周期动态
• crehq_location_history — 查看单家实体门店的完整事件日志

历史记录与核心差异化功能

• crehq_company_changes — 获取单个品牌在指定日期范围内的变更动态
• crehq_company_occupancy — 查询某个时间点的门店名录（某个过去日期的门店分布）
• crehq_site_timeline — 查看某个地址历年来入驻过的所有品牌 高级情报（Intel 和 Enterprise 层级）
• crehq_whitespace — 竞争对手已入驻但品牌尚未入驻的市场
• crehq_co_tenancy — 哪些品牌聚集在该品牌门店附近
• crehq_location_site_profile — 单个地点的 CREHQ 建模选址概况
• crehq_company_site_pattern — 根据观测到的足迹／背景信息得出的品牌实际选址模式
• crehq_recent_location_context — 最近观测到的／新开门店数据行，包含客流、人口统计信息和覆盖标记

建模选址概况的输出必须描述为根据观测到的地点／背景数据由 CREHQ 建模得出，除非响应中包含明确的企业声明选址要求来源，否则不得将其描述为企业声明的选址要求。

建模选址概况的 REST 路由正在等待明确的生产环境批准。在这些路由发布之前，即使 MCP 目录中列出了这三种工具供本地测试，它们也可能返回 404。

数据集

• crehq_datasets_list / crehq_dataset_get / crehq_dataset_download / crehq_dataset_categories
• crehq_purchased_datasets_list — 列出连接的密钥所有者购买的数据集快照，包括快照日期和托管 MCP 访问状态。
• crehq_purchased_dataset_locations — 在托管访问时段内查询买家拥有的时间点数据集快照中的数据行。

趋势

• crehq_trends_company — 某品牌的门店／费用／财务时间序列
• crehq_trends_geographic — 都会区／州的集中度和增长速度

---

获取 API 密钥

1. 免费沙盒（每月 1,000 次调用，2 req/s，无需信用卡；每个品牌的行数有月度限制，且每个响应都会显示确切的行数限额）： https://crehq.com/developers/sandbox/ — 输入邮箱，完成浏览器验证挑战，即可通过邮件收到密钥。 密钥仅通过邮件发送，格式类似 crehq_live_xxxxxxxx…。 沙盒密钥可执行有限范围的地点查询（按品牌调用 crehq_locations_list，以及按半径调用 crehq_locations_nearby），并且每月可调用一次实体关联解析器。如果用户请求高级情报，请调用 crehq_request_upgrade；该工具会记录请求的主题，以便 CREHQ 跟进，并告知用户需要升级哪些内容。
2. Pro MCP — 每月 $99，通过 Stripe 自助结账。包含有限范围的 D1 地点查询、选定的 D2 来源字段、每月 25,000 次核心调用、每月最多 250 次关联解析器调用，以及每月一次受控情报预览。请访问 https://crehq.com/developers/sandbox/#pro-checkout。
3. 数据集／情报／Enterprise — 需要文件时，可购买授权的时间点数据集快照；高级情报、数据刷新计划、API／Feed 交付、再分发、嵌入式使用权和 SLA 则需企业授权。请参阅 https://crehq.com/pricing/。

---

在 Agent 中试用 CREHQ 的最快方法

1. 在 https://crehq.com/developers/sandbox/ 获取沙盒密钥。
2. 对于托管／远程 MCP 客户端，添加 https://mcp.crehq.com/mcp 并使用该密钥进行授权。
3. 对于本地 stdio 客户端，使用 npx -y crehq-mcp-server 安装，并设置 CREHQ_API_KEY。
4. 提问：使用 CREHQ 确定 https://www.earleycrescent.org/ 上场所的品牌、运营方和母公司关联关系。

自助获取的密钥可使用关联解析器、有限范围的地点查询、升级路由、已购数据集访问权限和受控情报预览。后端仍会强制执行密钥实际拥有的 Free、Pro 和已购数据集权益；如有需要，会返回结构化的升级或购买响应。Intel 和 Enterprise 密钥则可根据密钥对应的 CREHQ 层级使用更广泛的 API 工具。

---

安装与构建

需要 Node.js ≥ 18。

使用 npx 安装已发布的 stdio 服务：

CREHQ_API_KEY=crehq_live_xxxxx npx crehq-mcp-server

或从源代码构建：

git clone <this-repo> crehq-mcp-server
cd crehq-mcp-server
npm install
npm run build          # compiles TypeScript → dist/
cp .env.example .env    # then edit .env and set CREHQ_API_KEY

在配置客户端之前，先使用在线 API 验证密钥：

export CREHQ_API_KEY=crehq_live_xxxxx
./test.sh               # exercises 6 read endpoints with curl

独立运行服务（该服务通过 stdio 使用 MCP，因此会等待 stdin 上的客户端连接 — 按 Ctrl-C 退出）：

CREHQ_API_KEY=crehq_live_xxxxx node dist/index.js

---

连接到 Claude Desktop

将以下内容添加到你的 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "crehq": {
      "command": "npx",
      "args": ["-y", "crehq-mcp-server"],
      "env": {
        "CREHQ_API_KEY": "crehq_live_your_key_here"
      }
    }
  }
}

重启 Claude Desktop。CREHQ 工具会显示在工具（🔌）菜单中。

其他 MCP 客户端

任何支持 stdio 的 MCP 客户端（Claude Code、Cursor、Cline、Continue、 mcp CLI、自定义 @modelcontextprotocol/sdk 客户端等）都以相同方式连接 ——将 node dist/index.js 作为服务命令运行，并在环境中设置 CREHQ_API_KEY。

Claude Code：

claude mcp add crehq --env CREHQ_API_KEY=crehq_live_xxxxx -- npx crehq-mcp-server

托管的远程连接器

托管的 Cloudflare Worker 版本位于 remote/。它提供相同的 CREHQ 连接器， 作为远程 MCP 服务，地址为 https://mcp.crehq.com/mcp，支持 OAuth／密钥交换 以及对高级工具的范围控制。相关部署说明位于 remote/DEPLOY.md，连接器提交 文案位于 remote/CONNECTOR-SUBMISSION.md。

MCP Registry 元数据位于 server.json，注册表所有权通过 package.json 中的 mcpName 声明。

维护者工作流

GitHub Actions 负责可重复的发布流程：

• CI 会在每次推送时构建并测试 stdio 包和托管的 Worker。
• Deploy Remote MCP 会将 remote/ 的更改部署到 Cloudflare Workers，然后 验证 https://mcp.crehq.com/health。
• Publish npm 会根据 vX.Y.Z 标签或手动工作流调度发布 stdio 包。如果该包 版本已存在，则会安全跳过。

所需的仓库密钥已命名如下：

• NPM_TOKEN
• CLOUDFLARE_API_TOKEN
• CLOUDFLARE_ACCOUNT_ID

---

配置

环境变量	必需	默认值	用途
CREHQ_API_KEY	是	—	你的 crehq_live_… 密钥
CREHQ_API_BASE	否	https://crehq.com/wp-json/crehq/v1	覆盖 API 基础地址（暂存环境／代理）
CREHQ_TIMEOUT_MS	否	30000	每个请求的超时时间，单位为毫秒
CREHQ_API_SURFACE	否	auto	自动检测 sandbox 或完整密钥；调试时可设为 selfserve 或 full

---

错误处理

工具不会导致 Agent 的当前轮次崩溃；发生故障时会返回易读的消息和修复提示：

• 未设置密钥 → 提示你设置 CREHQ_API_KEY 并提供 sandbox 链接。
• 401／403 → “密钥无效或已撤销／端点不属于你的套餐”＋升级链接。对于信用信号、 FDD、选址标准、联系人、溯源信息、更改历史、批量数据、空白区域、共同租赁 或站点时间线，请调用 crehq_request_upgrade。
• 404 → “检查 id／slug；请先使用搜索工具解析。”
• 429 → 遵循 Retry-After；提醒你免费套餐的速率限制为每秒 2 个请求。
• 自助服务指南 → API 对自身限制的说明会原样传递：API 的 message、 row_budget（已用量／上限／依据／重置时间）、full_dataset 选项、 upgrade_url／enterprise_url、did_you_mean slug，以及品牌所服务的市场。 成功的自助服务调用会先返回简短的指南块（coverage_note、 total_available／has_more、row_budget、full_dataset、resolved_from、 market_scope，以及 Enhanced (D2) 预览标签、字段和说明），然后才是 JSON 行。
• 5xx／超时／网络 → 提供瞬时错误指南，建议采用退避策略重试。

分页、缓存和流游标（X-WP-Total、X-CREHQ-Next-Since、 X-CREHQ-Cache、速率限制标头）会显示在每个结果的“响应元数据”页脚中， 以便 Agent 正确进行分页和轮询。

---

测试说明

构建、类型检查、MCP 协议握手、工具目录、参数验证，以及完整的 HTTP 请求／响应／错误流程，均已通过针对线上生产 API 的端到端验证（真实请求会返回正确提示信息 403 Invalid or revoked API key）。获取真实数据行需要有效密钥——沙盒密钥通过电子邮件发送，因此请设置 CREHQ_API_KEY 并运行 ./test.sh，以确认线上数据响应。

---

许可证

MIT。CREHQ 数据根据你的 API 层级／合同单独授权。