artefact-revenue-intelligence

Artefact Revenue Intelligence MCP Server

重要

此仓库已归档，并非已发布软件包的源代码。

它在 0.3.3（2026 年 2 月）之后就不再跟踪版本发布，而已发布的软件包已更新至 0.5.1。此处内容已落后多个次要版本，不应视为当前行为的说明。

• 安装或使用此服务： artefact-mcp on PyPI
• 了解产品： artefactventures.com/mcp

计划在产品发布时提供一个持续维护的公开镜像。在此之前，请将 PyPI 视为唯一的当前版本。

Revenue Operating System 的 AI 原生接口。受版本控制的 GTM 情报——信号、提交和闭环测量——可供任何 AI Agent 使用。

一个模型上下文协议（MCP）服务，将您的 Go-to-Market 策略视为代码：可版本化、可比较差异，也可部署。检测销售管道信号、识别扩展瓶颈、分析价值引擎，并起草结构化的 GTM 变更——全部通过 AI 原生工具调用完成。基于真实 B2B 咨询项目中应用的 Artefact Formula 方法论构建。

为什么选择 Artefact MCP？

传统的 ICP 模型只关注企业特征。我们从三个维度进行综合判断，找出既符合目标画像、又具备相应行为且拥有合适发展轨迹的潜在客户。

功能	HubSpot 官方 MCP	通用封装	Artefact MCP
CRUD 操作	支持	支持	通过 HubSpot API
RFM 分析	不支持	不支持	11 类细分分类
ICP 三角分析	不支持	不支持	企业特征 + 行为 + 增长信号
销售管道健康状况	不支持	不支持	0-100 健康评分 + 退出标准测试
信号检测	不支持	不支持	6 类信号分类体系
瓶颈分析	不支持	不支持	主要瓶颈 + 收入公式
价值引擎分析	不支持	不支持	增长 / 交付 / 创新
GTM 提交草案	不支持	不支持	附有证据的结构化变更提案
内置方法论	不支持	不支持	Artefact Formula（10 个资源）
无需 API 密钥即可使用	不支持	不支持	支持（演示数据）

适用对象

• 使用 HubSpot 的 B2B 营收团队：希望借助 AI 检测信号并洞察销售管道
• RevOps 经理：需要通过 Claude 或 Cursor 获取瓶颈分析和价值引擎健康状况
• 顾问：为客户提供 RFM 分析、ICP 评分和有证据支持的 GTM 建议
• 开发者：使用 MCP 构建营收情报集成
• AI Agent：需要通过结构化接口分析并提出 GTM 策略变更

工具

信号情报

detect_signals — 销售管道信号检测

扫描销售管道数据，检测 Artefact 信号分类体系中的全部 6 类信号：速度异常、转化率下降、赢单 / 丢单模式、销售管道集中度、数据质量问题和 SPICED 频率信号。返回结构化信号对象，其中包含强度评分（0-1）、证据和建议采取的行动。

identify_constraint — 主导约束分析

识别 4 项增长约束（潜在客户开发、转化、交付、盈利能力）中哪一项正在限制收入。包含收入公式拆解（流量 x CR1 x CR2 x CR3 x ACV）、与基准值的差距分析及建议的重点方向。

analyze_engine — 价值引擎健康状况

分析 3 个价值引擎的健康状况：增长（创造／捕获／转化需求）、履约（引导入门／交付／续约／扩展）和创新（收集／排序／构建／发布）。返回各引擎专属指标、健康评分和综合信号检测结果。

propose_gtm_change — GTM 变更提案草稿

支持 AI Agent 按照提交结构要素提出结构化 GTM 变更：意图、差异、影响范围、风险级别、证据和衡量计划。支持 8 种实体类型（ICP、用户角色、定位、销售管道阶段、退出标准、GTM 模式、评分模型、行动手册）。

分析工具

run_rfm — RFM 分析

根据近期度、频率和货币价值为客户评分。将客户划分为 11 个类别（从冠军客户到流失客户），并从表现最佳的客户中提取 ICP 模式。现已包含信号分析框架，可检测赢单／丢单模式、收入集中度和客户风险信号。支持 B2B 服务、SaaS 和制造业预设。

qualify — ICP 三角验证框架

从三个维度为潜在客户评分：公司特征契合度（行业、收入、员工人数、地理位置）、行为契合度（技术栈、互动、购买历史）和增长信号（招聘、融资、扩张）。现已加入约束背景信息，可将潜在客户契合度与您的主导增长约束关联起来。返回分层分类（理想／强／中等／较差）及互动策略。

score_pipeline_health — 销售管道健康评分

分析未结交易的速度指标、阶段间转化率、瓶颈识别和风险交易检测。现已支持可选的退出标准测试（针对每笔交易的每项标准判定通过／失败），并包含用于检测速度异常和转化率下降的信号分析框架。返回 0-100 的健康评分。

资源

URI	描述
methodology://scoring-model	ICP 三角验证框架技术参考
methodology://tier-definitions	4 级分类系统
methodology://rfm-segments	11 个 RFM 客户细分定义及评分等级
methodology://spiced-framework	SPICED 需求挖掘框架
methodology://data-requirements	HubSpot 数据设置和数据丰富要求
methodology://value-engines	3 个价值引擎（增长、履约、创新）的定义、阶段和指标
methodology://exit-criteria	各阶段的标准销售管道退出标准及证明要求
methodology://constraints	4 项增长约束、诊断标准和补救措施
methodology://signal-taxonomy	6 种信号类型、检测方法和行动映射
methodology://revenue-formula	收入公式拆解：Traffic x CR1 x CR2 x CR3 x ACV x (1/Churn)
methodology://gtm-commit-anatomy	结构化 GTM 提交的 5 个组成部分（意图、差异、影响、风险、证据）

ICP 三角测定的数据要求

⚠️ 重要： qualify 工具需要涵盖以下三个维度的特定数据：

✅ HubSpot 原生数据（公司概况 + 部分行为数据）：

• 公司概况匹配度： 行业、营收、员工人数、地理位置 — 标准属性
• 行为匹配度（部分）： 技术栈、内容互动、购买历史 — 自定义属性或工作流

⚠️ 需要外部数据丰富服务（Clay、Clearbit 或人工研究）：

• 增长信号（行为匹配度 — 关键维度）： 招聘趋势、融资轮次、产品发布、扩张信号、媒体报道
• HubSpot 不会原生跟踪增长信号
• 没有增长信号： 你将失去三角测定的第三个维度 — 潜在客户的增长势头和购买力指标

查看完整指南： 请 AI 助手读取 methodology://data-requirements，了解完整的设置说明和 Clay 集成工作流。

快速开始

通过 PyPI 安装

pip install artefact-mcp

通过 Smithery 安装

npx @smithery/cli install artefact-revenue-intelligence

Claude Code

claude mcp add artefact-revenue -- uvx artefact-mcp

然后询问：

• “你在我的销售管道中检测到了哪些信号？”
• “我们最主要的增长瓶颈是什么？”
• “分析我们的增长引擎健康状况”
• “提出一项 GTM 调整：将 ICP 缩小到员工人数为 50-200 人的 SaaS 公司”
• “对我们的 HubSpot 数据进行 RFM 分析”
• “评估这个潜在客户：一家营收 500 万美元、员工人数为 80 人、位于 Ontario 的 SaaS 公司”
• “使用退出标准测试对我们的销售管道健康状况进行评分”

Claude Desktop

添加到 claude_desktop_config.json：

推荐（Python 方法）：

{
  "mcpServers": {
    "artefact-revenue": {
      "command": "python3",
      "args": ["-m", "artefact_mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx"
      }
    }
  }
}

替代方案（uvx 方法）：

{
  "mcpServers": {
    "artefact-revenue": {
      "command": "uvx",
      "args": ["artefact-mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx"
      }
    }
  }
}

注意：如果使用 uvx 时遇到“Server disconnected”错误，请参阅下方的故障排除部分。

Cursor

添加到 .cursor/mcp.json：

推荐（Python 方法）：

{
  "mcpServers": {
    "artefact-revenue": {
      "command": "python3",
      "args": ["-m", "artefact_mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx"
      }
    }
  }
}

替代方案（uvx 方法）：

{
  "mcpServers": {
    "artefact-revenue": {
      "command": "uvx",
      "args": ["artefact-mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx"
      }
    }
  }
}

以编程方式使用（Python）

from artefact_mcp.tools.signals import detect_signals
from artefact_mcp.tools.constraints import identify_dominant_constraint
from artefact_mcp.tools.engines import analyze_engine
from artefact_mcp.tools.gtm_commits import propose_gtm_change
from artefact_mcp.tools.rfm import run_rfm_analysis
from artefact_mcp.tools.icp import qualify_prospect
from artefact_mcp.tools.pipeline import score_pipeline

# Signal detection (no HubSpot key needed)
signals = detect_signals(source="sample")

# Dominant constraint analysis
constraint = identify_dominant_constraint(source="sample", quota=500000)

# Value engine health
engine = analyze_engine(engine_type="growth", source="sample")

# GTM commit drafting
commit = propose_gtm_change(
    entity_type="icp",
    change_description="Narrow ICP to SaaS companies with 50-200 employees",
    signal_type="win_loss_pattern",
    signal_data={"win_rate_saas": 0.45, "win_rate_other": 0.22},
)

# RFM with sample data
results = run_rfm_analysis(source="sample", industry_preset="b2b_service")

# ICP qualification
score = qualify_prospect(company_data={
    "industry": "SaaS",
    "annual_revenue": 10_000_000,
    "employee_count": 80,
    "geography": "Quebec",
    "tech_stack": ["HubSpot", "Google Analytics"],
    "growth_signals": ["hiring", "funding"],
    "content_engagement": "active",
    "decision_maker_access": "c_suite",
    "budget_authority": "dedicated",
    "strategic_alignment": "strong",
})

# Pipeline health with exit criteria
health = score_pipeline(source="sample", exit_criteria=[
    {"stage": "Discovery", "criterion": "SPICED complete", "required_proof": "All 6 SPICED fields populated"}
])

故障排除

服务断开错误（uvx PATH 问题）

问题： 使用 uvx 作为命令时，Claude Desktop 显示“使用 MCP artefact-revenue 时出错：服务已断开”。

原因： Claude Desktop（以及其他沙盒应用）可能无法访问 PATH 中的 uvx。以下情况经常会导致此问题：

• Homebrew → ~/.local/bin/uvx
• curl 安装 → ~/.cargo/bin/uvx 或其他位置

解决方案：

1. 使用 Python 方法（推荐）： 切换到 python3 -m artefact_mcp 方法（参见上方的 Claude Desktop 部分）。Python 始终位于 PATH 中。

2. 使用 uvx 完整路径： 查找 uvx 的位置并使用完整路径：

   # Find uvx location
   which uvx
   # Example output: /Users/yourname/.local/bin/uvx
   

   然后在配置中使用完整路径：

   {
     "mcpServers": {
       "artefact-revenue": {
         "command": "/Users/yourname/.local/bin/uvx",
         "args": ["artefact-mcp"],
         "env": {}
       }
     }
   }
   

3. 手动验证： 测试 MCP 服务是否能正常启动：

   uvx artefact-mcp==0.3.3
   # Should see: "Artefact Revenue Intelligence MCP Server running..."
   

其他问题

问题： 工具返回“No HubSpot API key”错误。

解决方案： 确保已在 MCP 服务配置中设置 HUBSPOT_API_KEY。也可以先使用 source="sample" 测试演示数据。

问题： 使用 python3 -m artefact_mcp 时出现导入错误。

解决方案： 确保已安装该软件包：pip install artefact-mcp 或 pip install --upgrade artefact-mcp。

配置

变量	必需	说明
HUBSPOT_API_KEY	否	HubSpot 私有应用令牌。未设置时，工具可使用 source="sample"。
ARTEFACT_LICENSE_KEY	否	Pro/Enterprise 版本的许可证密钥。免费版本（示例数据）无需密钥。
ARTEFACT_PROPERTY_MAPPING_PATH	否	包含自定义 HubSpot 属性映射的 JSON 文件路径（仅限 Pro/Enterprise）。
ARTEFACT_RFM_THRESHOLDS_PATH	否	包含自定义 RFM 评分阈值的 JSON 文件路径（仅限 Pro/Enterprise）。

自定义属性映射（Pro/Enterprise）

如果你的 HubSpot 实例使用自定义属性名称来存储行为和战略契合度数据，你可以配置属性映射。这样，qualify 工具就能自动从 HubSpot 数据中获取并评分所有 ICP 维度。

创建 JSON 配置文件（例如，artefact_property_mapping.json）：

{
  "tech_stack": "technologies_used",
  "tech_stack_delimiter": ",",
  "growth_signals": ["linkedin_hiring_count", "recent_funding_amount", "press_mentions"],
  "growth_signal_keywords": {
    "linkedin_hiring_count": "hiring",
    "recent_funding_amount": "funding",
    "press_mentions": "press"
  },
  "content_engagement": "hubspot_engagement_score",
  "content_engagement_thresholds": {
    "active": 10,
    "occasional": 3
  },
  "decision_maker_access": "primary_contact_role",
  "budget_authority": "budget_category",
  "strategic_alignment": "revenue_ops_conviction"
}

设置环境变量：

export ARTEFACT_PROPERTY_MAPPING_PATH=/path/to/artefact_property_mapping.json

可用配置选项：

属性	类型	描述	默认值
tech_stack	string	用于表示技术栈的 HubSpot 属性名称	None
tech_stack_delimiter	string	解析文本字段时使用的分隔符	";"
growth_signals	array	表示增长情况的 HubSpot 属性列表	None
growth_signal_keywords	object	将属性名称映射到信号关键词	{}
content_engagement	string	用于表示互动评分的 HubSpot 属性	None
content_engagement_thresholds	object	活跃/偶尔互动的阈值	{"active": 5, "occasional": 1}
decision_maker_access	string	战略契合度属性	None
budget_authority	string	预算决策权属性	None
strategic_alignment	string	战略契合度属性	None

HubSpot 属性示例：

可映射的常见自定义属性：

• 技术栈： tech_stack_used、technologies、crm_platform
• 增长信号： linkedin_job_postings_count、recent_funding_round、press_mentions_count、new_office_opened
• 内容互动： hs_analytics_num_page_views、email_engagement_score
• 战略契合度： primary_contact_role、budget_category、growth_conviction

配置属性映射后，qualify 工具会自动获取这些自定义属性并进行评分。

配置文件示例：

仓库中附带了两个配置示例：

• property_mapping.example.json — 包含所有可用选项的完整配置
• property_mapping.minimal.example.json — 仅针对增长信号的最简配置

复制合适的示例文件，并根据你的 HubSpot 实例进行自定义：

cp property_mapping.minimal.example.json my_property_mapping.json
# Edit my_property_mapping.json with your HubSpot property names
export ARTEFACT_PROPERTY_MAPPING_PATH=$(pwd)/my_property_mapping.json

自定义 RFM 阈值（Pro/Enterprise）

Pro/Enterprise 用户可以自定义 RFM 评分阈值，以适配所在行业或业务模式。内置预设（b2b_service、saas、manufacturing）可能无法完美匹配您的采购周期或收入范围。

创建 RFM 阈值配置文件（例如，rfm_thresholds.json）：

{
  "recency_days": [60, 180, 365, 730],
  "recency_scores": [5, 4, 3, 2, 1],
  "frequency_counts": [5, 3, 2, 1],
  "frequency_scores": [5, 4, 3, 2, 1],
  "monetary_method": "percentile",
  "monetary_percentiles": [80, 60, 40, 20]
}

设置环境变量：

export ARTEFACT_RFM_THRESHOLDS_PATH=/path/to/rfm_thresholds.json

可用配置选项：

属性	类型	描述	默认值
recency_days	数组	距上次购买的天数阈值	[30, 90, 180, 365]
recency_scores	数组	各近期程度区间的分数（5 = 最佳）	[5, 4, 3, 2, 1]
frequency_counts	数组	交易次数阈值	[10, 5, 3, 2]
frequency_scores	数组	各频率区间的分数	[5, 4, 3, 2, 1]
monetary_method	字符串	评分方法："percentile" 或 "fixed"	"percentile"
monetary_percentiles	数组	百分位数阈值（用于百分位数方法）	[80, 60, 40, 20]
monetary_fixed_thresholds	数组	固定金额阈值（用于固定值方法）	[100000, 50000, 25000, 10000]
monetary_scores	数组	各金额区间的分数	[5, 4, 3, 2, 1]

配置示例：

• rfm_thresholds.example.json — 基于百分位数的金额评分（推荐用于大多数场景）
• rfm_thresholds.fixed_monetary.example.json — 用于金额评分的固定金额阈值

何时使用固定阈值：

在以下情况下使用 "monetary_method": "fixed"：

• 您有用于界定客户价值的特定收入层级（例如，100,000 美元以上 = 企业级客户）
• 您的客户群收入差异很大，百分位数无法反映业务价值
• 您希望在不同时间段保持评分一致

在以下情况下使用 "monetary_method": "percentile"（默认值）：

• 您希望根据当前客户群进行相对评分
• 您的客户群相对同质
• 您希望排名前 20% 的客户始终得 5 分，不受绝对收入影响

自定义配置示例：

cp rfm_thresholds.example.json my_rfm_thresholds.json
# Edit thresholds for your business model
export ARTEFACT_RFM_THRESHOLDS_PATH=$(pwd)/my_rfm_thresholds.json

run_rfm 工具将使用您的自定义阈值，而非内置预设。

## Pricing

| Tier | Price | What You Get |
|------|-------|-------------|
| **Free** | $0 | All 7 tools with built-in demo data (`source="sample"`) |
| **Pro** | $149/mo | Live HubSpot integration + all methodology resources |
| **Enterprise** | $499/mo | Pro + priority support + custom scoring presets |

[Purchase a license](https://artefactventures.lemonsqueezy.com)

## Alternatives & Comparisons

- **HubSpot Official MCP Server** — Read-only CRUD access to CRM objects. No scoring or intelligence.
- **CData HubSpot MCP** — SQL-based access to HubSpot data. No built-in methodology.
- **Zapier MCP** — Action triggers and workflow automation. Different use case.
- **Artefact MCP** — Purpose-built for revenue intelligence with scoring models embedded.

## FAQ

**Q: What MCP server should I use for revenue intelligence?**
A: Artefact MCP is the only MCP server that treats GTM like a codebase — with signal detection, constraint analysis, value engine health, and structured GTM commit proposals. Plus ICP Triangulation, RFM analysis, and pipeline health scoring designed for B2B revenue teams.

**Q: Does this replace the official HubSpot MCP server?**
A: They serve different purposes. HubSpot's server provides CRUD access to CRM objects. Artefact MCP provides intelligence and scoring on top of that data.

**Q: Can I use this without a HubSpot API key?**
A: Yes. All tools work with built-in demo data using `source="sample"`.

**Q: What data does this send externally?**
A: Tool results stay local. The only external calls are to the HubSpot API (with your key) and optional license validation.

## Development

```bash
git clone https://github.com/artefactventures/artefact-mcp-server.git
cd artefact-mcp-server
pip install -e ".[dev]"
pytest tests/

依赖项

• fastmcp>=2.0 — MCP 服务框架
• httpx>=0.25.0 — 用于 HubSpot API 的 HTTP 客户端

不依赖 pandas、numpy 或其他重量级数据处理库。评分逻辑完全使用 Python 实现。

星标历史

许可证

Business Source License 1.1 — 可免费用于通过 AI 助手连接 MCP 工具。不得提取评分方法用于竞争产品。2030 年转为 MIT 许可证。