# @dealsurface/mcp-server 中文文档

规范地址：https://npmcn.com/package/%40dealsurface/mcp-server/

版本：2\.13\.0
npm 元数据更新时间：2026-10-30T01:24:19.511Z
中文译文更新时间：2026-11-14T15:06:47.241Z
软件包许可：SEE LICENSE IN LICENSE

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dealsurface/mcp-server
原文对照：https://npmcn.com/package/%40dealsurface/mcp-server/?lang=original
项目主页：https://dealsurface.com/docs/mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：103 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：2 个
- 首次发布：2026-03-12T00:58:05.950Z
- 最新版本发布：2026-10-30T01:24:19.300Z
- 近 30 天下载量：2007（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 21 个）

## 中文简介

DealSurface的MCP服务器,以保险为重点的上市平台:对特定产品的前景、证据、购买委员会和外联进行排名

## 安装

```sh
npm install @dealsurface/mcp-server
```

也可以使用：`pnpm add @dealsurface/mcp-server`、`yarn add @dealsurface/mcp-server`、`bun add @dealsurface/mcp-server`

## README

# DealSurface MCP 服务器

MCP 服务器 [交易搜索面](https://dealsurface.com/) 销售情报API. AI代理商可以访问企业级的销售探矿,收购委员会分析,以及推广 — — 所有这些都有明确证据证明您需要你的产品.

## 2.7.1中有什么新鲜事

-   错误修正和可靠性改进.

## 2.7.0有什么新情况

-   `list_prospects` 接受 `complaint_line`, (中文(简体) ), `min_complaint_index` 财务报告和审定财务报表 `min_complaints`,以及 `sort_by: "complaint_index"` 可按单一独联体排序 政策线。 带行 `complaints.by_line_of_business`。 。 。 .
-   `get_prospect` 返回家庭投诉清单(`scope: "family"`,带有 每名承运人 `by_entity` 对于没有自己的NAIC编码的父母, 和观察旗 `low_sample` 不满10起申诉.
-   `account_verdict` 现在可以了 `"nurture"`:公司符合产品,但没有 显示当前触发. `deprioritize` 仅用于交易分数 1或2. 群纹细节( C)`narrative_scope: "group"`现在携带 `group_verdict` 具有相同的价值.
-   解决购买信号的重度增加 `deal_score` (+20潜力,+40强; 之前为+10 / +20,在每种产品下次加工时适用.

## 2\. 6.0中有什么新鲜事

-   `craft_outreach` 默认使用产品配置的外联模板 并接受可选 `template_key`。 。 。 .
-   新建免费 `list_outreach_templates` 工具在用户时列出活动选项 请求探索或改变拓展风格.
-   模板列表报告类型、频道和信用成本。 决定性静态消息 是免费的; 生成提示和一个静态的 AI 钩 花费一个功劳 成功.
-   外联对策确定准确的模板密钥、版本、类型、来源、, 草案所用的解决途径.
-   MCP可以浏览,选择并使用模板. 创建、编辑和默认 dealSurface Explain → Templates UI 中仍保留了变化.
-   摘录结果可包括添加剂 `company_event` 元数据(实质性) 与产品相关的当前事件) `date_is_approximate` 当日期是 锁定在源出版物或调用日期.

## 即将到来的API行为变化:前景人群

当部署此 API 更新时, 省略 `include_private` 内 `list_prospects` 或者说 `get_prospect` 将要求小组的合格人数而不是 先前只公开的默认值。 这是有意改变行为: 团队可能看到更多的公司和不同的级别/总数。 现有MCP客户 即使没有软件包升级,也会受到API部署的影响.

保留仅公开名单和公共公司排名,明确通过 `include_private: false`私人公司详情继续使用其标题 私营包容性军衔人口。 仍然对小组准入实行限制. 回应 `population` 字段解释所要求的政策和级别范围.

## 2.0.0中有什么新鲜事

2.0.0版本针对重启的 DealSurface REST API v2(`/api/v2`) (中文(简体) ). 老年人 服务器版本目标 `/api/v1`,现在返回 `410 Gone` - 升级以保持 工作时 要点 :

-   **公司家庭前景清单.** `list_prospects` 返回每行一行 企业家庭 `entity_count`编号 :`matched_entity_count`,溢价和 申诉摘要和a `total_groups`编号 :`total_entities` 信封 (替换) `total_count`) (中文(简体) ).
-   **富人过滤.** 新设 `list_prospects` 过滤器:评估状况、保险 实体类型、所有权、保费波段、业务范围(Matches Any), 被许可状态( 匹配 ALL) , 名称搜索 (`q`键,包括 `complaint_index`。词汇表被嵌入到工具图中,作为词组 无效的值会被拒绝客户端, 并显示已接受的集合 .
-   **严格过滤,显式排除.** 没有应用数据的家庭 保险过滤器不包括在内并计入 `excluded_no_data_groups`。 。 。 .
-   **辅助钻倒.** `get_prospect` 接受任意 `hierarchy.children[].ticker`; 交易地图/外联工具 上到公司家庭,在回应中这样说.
-   **新工具 `set_top_pick`** 标出/标出利益攸关方作为 他们的收购委员会角色.
-   **`framework_category` 删除** 从 `search_excerpts` (作为过滤器) 输入和作为节选的响应字段).
-   详细答复收益 `company_info`,每年 `premium`编号 :`complaints` 系列, `hierarchy`, (中文(简体) ), `narrative_scope`,以及 `excerpt_count`; 嵌入式节录为 上限为20 (使用) `search_excerpts` 其余部分).
-   A 类 `503` 从前景/节选工具中表示投影不简单 备妥`rebuilding`,或 `stale_keywords` - 永远不要"不" 前景。 A 类 `409` 与 `generation_unavailable` 表示呼号是 暂停(从冲抵 0 开始,不包含 `generation_id`(三); `analysis_unavailable` 也就是说,在目前的结果中,没有关于该公司的分析. 错误文本从原因开始 .
-   每个请求都会发出 `User-Agent: dealsurface-mcp/<version>`。 。 。 .

## 安装

### 克洛德桌面/克洛德代码

添加到您的 Claude 桌面配置文件( E)`claude_desktop_config.json`:

> **提示 (Mac) :** 点击 **克劳德** 菜单,在系统菜单栏中(不在 Claude 窗口内),转到 **设置 – 开发者**,然后单击 **"编辑配置"** ——这可以直接打开文件,如果它还没有存在,就可以创建它.

```json
{
  "mcpServers": {
    "dealsurface": {
      "command": "npx",
      "args": ["-y", "@dealsurface/mcp-server"],
      "env": {
        "DEALSURFACE_API_KEY": "ds_live_your_api_key_here"
      }
    }
  }
}
```

### 其他MCP客户

支持任何 MCP 客户端 `stdio` 传输可以使用此服务器 。 设定 `DEALSURFACE_API_KEY` 在环境中运行:

```bash
npx -y @dealsurface/mcp-server
```

## 环境变量

| 变量 | 需求 | 说明 |
| --- | --- | --- |
| `DEALSURFACE_API_KEY` | 对 | 您的 DealSurface API 密钥( 启动于 `ds_live_` 或者说 `ds_test_`(中文(简体) ) |
| `DEALSURFACE_API_URL` | 没有 | 覆盖 API 基础 URL( 仅来自服务器附件) `/api/v2`) (中文(简体) ). 默认为 `https://dealsurface.com`用于指向中转环境. |

## API 密钥范围

您的 API 密钥必须有您想要使用的工具的适当范围 :

-   **`read`** - 所有工具都需要
-   **`outreach`** - 所需额外经费 `generate_dealmap`, (中文(简体) ), `override_stakeholder_role`, (中文(简体) ), `list_outreach_templates`,以及 `craft_outreach`

访问您的 DealSurface 账户中的 API 密钥页面来管理 API 密钥和范围 .

## 可用工具

| 工具 | 范围 | 计费 | 说明 |
| --- | --- | --- | --- |
| `list_products` | 读取 | 免费 | 列出具有关键词、来源、行业和部分目标的有效产品(`include_disabled` 可选择包括已禁用的元数据) |
| `get_product` | 读取 | 免费 | 通过标识获取活动产品细节,包括 `target_segments` (单位:千美元)`include_disabled` 可选择包括已禁用的元数据) |
| `list_prospects` | 读取 | 免费 | 列出具有丰富的过滤器(实体类型、所有权、溢价、业务范围、特许状态、名称查询)和种类的公司家庭 |
| `get_prospect` | 读取 | 免费 | 全面前景分析:公司信息、溢价/投诉历史、等级、调查结果和封面证据摘录。 接受子计时器 |
| `search_excerpts` | 读取 | 免费 | Filter SEC 归档证据摘录 |
| `list_outreach_templates` | 读取 + 外联 | 免费 | 列出活动的团队外联模板和产品默认值 |
| `get_dealmap` | 读取 | 免费 | 读取购买委员会 DealMap(利益攸关方角色, org 等级) 。 公司大家庭的附属标记 |
| `generate_dealmap` | 外联 | 有条件 | 生成或刷新购买委员会 DealMap; 仅在新奥尔格图获取时计费 |
| `override_stakeholder_role` | 外联 | 免费 | 取代大赦国际指定的利益攸关方的作用 |
| `set_top_pick` | 读取 | 免费 | 标出/标出利益攸关方作为其收购委员会角色的首选 |
| `craft_outreach` | 读取 + 外联 | 0至1个信贷 | 创建邮件或 LinkedIn 从产品默认或清晰的静态消息或生成时提示的外联 |

### 计费细节

-   **免费工具** (单位:千美元)`list_products`, (中文(简体) ), `get_product`, (中文(简体) ), `list_prospects`, (中文(简体) ), `get_prospect`, (中文(简体) ), `search_excerpts`, (中文(简体) ), `list_outreach_templates`, (中文(简体) ), `get_dealmap`, (中文(简体) ), `override_stakeholder_role`, (中文(简体) ), `set_top_pick`· 不消耗信贷.
-   **`generate_dealmap`** 成功结果的10个贷项 `generation_source=org_fresh` 或者说 `org_fresh_empty` (新鲜的空洞结果加上人). 延迟结果(`org_cache` 或者说 `annotated_cache_hit`)是免费的。 这个 `force_refresh` 参数绕过缓存,只应在明确请求时使用.
-   **`craft_outreach`** 当 API 返回有效结果时, 消耗团队信用值.
-   如果您的团队没有足够的信用, 服务器会返回一个包含剩余且需要信用细节的错误 .
-   最新信用成本见API Docs和定价页.

### 比率限制和平行

对滑动的60秒窗口适用每个 API 键的限制 :

| 限制 | 适用于 | 每分钟 |
| --- | --- | --- |
| 常规 | 每个工具呼叫 | 120国 |
| 交易映射生成 | `generate_dealmap` | 20国 |
| DealMap 生成( 工作空间, 所有密钥合并) | `generate_dealmap` | 第40条 |
| 外联 | `craft_outreach` | 页:1 |

在通过公司或领导名单工作时,以平行方式而不是一次一次进行独立呼叫:最多 **10个 `generate_dealmap`** 一次打电话(每次大约需要15-45秒),最多不超过 **10个 `craft_outreach`** 马上打电话 在一个 `429`,请等待 `Retry-After` 秒后只重试被拒绝的电话 .

生成前, 呼叫 `get_dealmap` (自由而快)并跳过已经拥有"DreamMap"的公司;去重复刻录器,决心与同一个公司家族打交道. `generate_dealmap` 返回完整的 DealMap,所以没有后续 `get_dealmap` 需要打电话.

## 建议代理流程

1.  打电话 `list_products` (c) 将活动产品用于业务工具.
2.  打电话 `list_prospects` 带有 `product_id` 找到顶级公司.
3.  打电话 `get_prospect` 详细分析某家公司.
4.  打电话 `get_dealmap` (或 `generate_dealmap` 如果为空) 对于许多公司来说,它们分批平行运行(见: [比率限制和平行](https://npmcn.com/package/%40dealsurface/mcp-server/#readme-rate-limits-and-parallelism)) (中文(简体) ).
5.  打电话 `craft_outreach` 带有选定的利害关系方并省略 `template_key` 用于使用产品默认值。 对于许多线索,也按平行批次运行.
6.  打电话 `list_outreach_templates` 仅当用户请求探索或更改外联样式时,然后通过选定的返回 `template_key` 改为 `craft_outreach`。 。 。 .

## 选择 `craft_outreach`

您可以使用以下两种方法实现个人化:

-   **`selected_lead`** - 完全利益攸关方反对 `get_dealmap` 响应(首选)
-   **`lead_selector`** 轻量级选择器 : `{"node_id": "..."}`, (中文(简体) ), `{"level": "vp"}`, (中文(简体) ), `{"full_name": "Jane Doe", "level": "director"}`,或 `{"stakeholder_role": "Economic Buyer"}`

如果两者都提供, `selected_lead` 以优先为准。 如果找不到匹配, 外联仍然成功, 但包括可调用的指导 `get_dealmap` 先说.

## 解决问题

### “需要DEALSURFACE API KEY环境变量”

确保 `DEALSURFACE_API_KEY` 设置在您的 MCP 客户端配置中.

### "403被禁"或"许可不足"

您的 API 密钥可能没有所需的范围 。 只读工具需要 `read` 范围。 生成和外联工具需要 `outreach` 范围.

### "402 信贷不足"

你的团队已经没有帐单了 错误信息包括您的剩余余额和所需的入计量 。 联系您的账户管理员 .

### "429 太多请求"

有些终点比其他终点受限制更大。 详见API文档.

## 所需资源

-   节点.js 20或以后
-   带有适当范围的 DealSurface API 密钥

## 许可证

这个软件包是专有的商业软件,不是开源软件. 使用为 仅限于经授权的DoneSurface客户和其他明确批准的用户 由 DoneSurface 管理,并由适用的 DoneSurface 客户端管理 协议、API条款或服务条件: [https://dealsurface.com/terms (中文(简体) )](https://dealsurface.com/terms)。 。 。 .

一揽子和相关服务是“照旧”提供的,没有保证 或保证。 见 [自由主义](https://npmcn.com/package/%40dealsurface/mcp-server/LICENSE) 详细情况.

### 预测人口和交易地图失败

前景列表和细节默认为拥有队伍的人口。 使用 `include_private: false` 仅限公开名单或公开探矿者名单。 私营 前景细节保留了包含私人的排名。 添加剂 `population` 字段表示等级范围: 列出等级过滤的家族, 而细节 对未过滤的家庭进行排序。 在名单上, `included_if_entitled` 说明政策; 它不能保证私人排队或超越现场团队的权利. `excluded_no_data_groups` 仅计算保险-过滤保险排除.

DealMap生成允许每个API密钥每分钟20个请求(每个工作空间40个请求); a 429号,等等 `Retry-After` 秒后只重试被拒绝的电话 . 第422条区分了未解决的公司身份(`company_identity_unresolved`(中文(简体) ) 未获得的组织信息(`dealmap_data_unavailable`) (中文(简体) ). 也没有 临时服务或超时诊断。 超时后读取当前 重试前处理 Map ; 背景补全不能保证 .

## 常见问题

### @dealsurface/mcp-server 是什么？

DealSurface的MCP服务器,以保险为重点的上市平台:对特定产品的前景、证据、购买委员会和外联进行排名

### 如何安装 @dealsurface/mcp-server？

在项目目录运行 npm install @dealsurface/mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 dealsurface-mcp，可以用 npx dealsurface-mcp 直接运行。

### @dealsurface/mcp-server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dealsurface/mcp-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dealsurface/mcp-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dealsurface/mcp-server 可以商用吗？

@dealsurface/mcp-server 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @dealsurface/mcp-server 的下载量有多少？

根据 npm 官方下载统计，@dealsurface/mcp-server 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,007 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dealsurface/mcp-server 还在维护吗？

最新版本 2\.13\.0 发布于 2026/10/30（15 天前）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/03/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。