内容
# xcircl-agent
**验证美国受监管的医疗服务提供者数据，用于您的应用程序或人工智能。源链接，带时间戳。**
[](./LICENSE)
[](https://xcircl.com/data/coverage/)
[](https://xcircl.com/data/coverage/)
[](https://xcircl.com/data/coverage/)
[](https://xcircl.com/data/coverage/)
查询美国受监管的医疗服务提供者（目前为GLP-1 / 减肥诊所；更多垂直领域即将推出），使用自然语言或函数调用 — 作为 **MCP服务器**，适用于Claude/ChatGPT，或作为 **TypeScript SDK**，适用于您自己的产品。免费层无需API密钥；验证合规信号和现金价格需购买密钥。
> 上方徽章中的计数值实时从 [`/api/v1/coverage/`](https://xcircl.com/api/v1/coverage/) 拉取 — 随着数据集的增长，数字会更新。
## 30秒快速入门（无需密钥，无需安装）
```bash
curl -sL "https://xcircl.com/api/v1/providers/?vertical=glp1&state=TX&limit=3"
```
```jsonc
{
"tier": "free",
"notice": "免费层：仅身份字段。验证合规信号、价格和时间戳需要密钥 — 请参阅 /developers/pricing/。",
"pagination": { "total": 15, "limit": 3, "offset": 0, "returned": 3 },
"data": [
{
"entity_id": "ent_f47550b79f755d70b58b183a",
"slug": "alegro-health-mckinney-tx",
"vertical": "glp1",
"name": "Alegro Health",
"city": "McKinney",
"state": "TX",
"business_mode": "online",
"latitude": 33.198119,
"longitude": -96.708802,
"npi": "1053066357"
}
// …
]
}
```
真实数据，真实API，零设置。`完整字段（cash_price，compliance）每月99美元自助服务 → [xcircl.com/developers](https://xcircl.com/developers/)`。
## 从Claude（MCP服务器）使用
```bash
git clone https://github.com/xcircl/xcircl-agent.git
cd xcircl-agent && npm install && npm run build
```
**Claude 代码：**
```bash
claude mcp add xcircl -- node /path/to/xcircl-agent/packages/mcp-server/dist/index.js
# 使用密钥（解锁价格 + 合规字段）：
claude mcp add xcircl -e XCIRCL_API_KEY=your-key -- node /path/to/xcircl-agent/packages/mcp-server/dist/index.js
```
**Claude Desktop** (`claude_desktop_config.json`)：
```json
{
"mcpServers": {
"xcircl": {
"command": "node",
"args": ["/path/to/xcircl-agent/packages/mcp-server/dist/index.js"],
"env": { "XCIRCL_API_KEY": "可选 — 免费层省略" }
}
}
}
```
然后直接询问：*“在休斯顿找到GLP-1诊所并检查他们的合规性。”*
服务器暴露了三个工具：
| 工具 | 功能 |
|---|---|
| `search_providers` | 按垂直领域 / 城市 / 州 / 商业模式筛选 |
| `get_provider` | 通过 `entity_id` 或 slug 获取完整记录 |
| `check_compliance` | LegitScript / 州许可证 / FDA 信号（付费字段 — 工具仍然在没有密钥的情况下回答并说明如何解锁） |
## 从您的代码（TypeScript SDK）使用
```bash
npm install && npm run build # 从仓库根目录
```
```ts
import { XcirclClient } from '@xcircl/sdk';
const xcircl = new XcirclClient(); // 无密钥 → 免费层
// const xcircl = new XcirclClient({ apiKey: process.env.XCIRCL_API_KEY });
const { data, notice } = await xcircl.searchProviders({
vertical: 'glp1',
city: 'Austin',
state: 'TX',
});
for (const p of data) console.log(p.name, p.city, p.npi);
if (notice) console.log(notice); // 密钥会添加什么
```
可运行的示例（两者无需密钥）：
```bash
node examples/01-find-clinics.mjs Houston TX # 查找诊所
node examples/02-ai-tool-use.mjs # 为Claude提供实时xcircl工具（自带ANTHROPIC_API_KEY）
```
## 数据来源
每个记录都从官方、可引用的来源中汇总 — 每个付费信号都带有其 **来源和验证时间戳**：
- **[NPPES](https://npiregistry.cms.hhs.gov/)** — CMS国家提供者标识符注册表，用于提供者身份（名称、位置、NPI）。
- **[FDA 数据仪表盘](https://datadashboard.fda.gov/)** — 药物/生物制剂警告信筛选（自2019年以来的合规行动）。
- **州许可委员会** — 医疗和药店许可记录。
- **[LegitScript](https://www.legitscript.com/)** — 认证状态检查。
- **提供者网站** — 已发布的现金价格，记录了来源页面和检查日期。
此仓库不包含 **任何数据文件** — 它是围绕xcircl API的开源壳（MCP服务器 + SDK + 文档）。数据存活在服务器端，字段分层由服务器端强制执行。唯一的演示数据源是实时 [`/api/v1/sample/`](https://xcircl.com/api/v1/sample/) 端点（~50个干净的记录在付费模式下）。
## 免费 vs 付费字段
| 字段 | 免费（无密钥 / 免费密钥） | Builder+（$99/mo 及以上） |
|---|:---:|:---:|
| `entity_id`, `slug`, `vertical`, `name` | ✅ | ✅ |
| `city`, `state`, `latitude`, `longitude` | ✅ | ✅ |
| `business_mode`, `npi` | ✅ | ✅ |
| `legitscript` — 认证信号 | — | ✅ |
| `license` — 州许可证记录 | — | ✅ |
| `fda` — 警告信筛选 | — | ✅ |
| `price` — 已发布的现金价格 | — | ✅ |
| 每个信号的来源 + `verified_at` | — | ✅ |
## 计划
| 计划 | 价格 | 字段 | 请求 | 垂直领域 |
|---|---|---|---|---|
| **免费** | $0（在 [xcircl.com/developers](https://xcircl.com/developers/) 注册） | 身份字段 | 1,000/月 | 所有 |
| **Builder** | **$99/月** — 信用卡自助服务 | **所有字段** | 5,000/月 | 1（密钥绑定） |
| **Developer** | $750/月 · 创始客户（前10名）：$375/月锁定12个月 | 所有字段 | 25,000/月 | 多个 |
| **企业** | [联系销售](https://xcircl.com/developers/) | 所有字段 + 导出 | 无限 | 所有 |
- **无密钥**：完全可用，100%真实数据，加上关于付费字段的一行通知 — 免费体验是一个真正的演示，您遇到的障碍是字段/垂直/容量障碍，而不是“无法运行”的障碍。
- 速率限制和垂直绑定由密钥强制执行，与字段分层相同 — 此客户端包含零门控逻辑。
完整字段字典：[docs/schema.md](./docs/schema.md) · 记录的生产测试运行：[docs/verification.md](./docs/verification.md)。
## 仓库布局
```
packages/mcp-server/ MCP服务器（stdio）— search_providers / get_provider / check_compliance
packages/sdk-ts/ @xcircl/sdk — 零依赖TypeScript客户端
examples/ 可运行的示例（查找诊所，AI工具使用）
docs/schema.md 字段字典（免费/付费分层）
```
## 许可证
[MIT](./LICENSE) — 开源壳；自由构建。
