金大哥 - artefact-mcp-server MCP 详情

article

README

🚀 Artefact Revenue Intelligence MCP Server

Artefact Revenue Intelligence MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，它将企业的 Go-to-Market (GTM) 策略视为代码，具备版本控制、差异比较和可部署等特性。通过 AI 原生工具调用，它能够检测销售管道信号、识别业务扩展限制、分析价值引擎，并起草结构化的 GTM 变更方案。该服务器基于 Artefact Formula 方法构建，此方法源自真实的 B2B 咨询项目。

🚀 快速开始

通过 PyPI 安装

pip install artefact-mcp

通过 Smithery 安装

npx @smithery/cli install artefact-revenue-intelligence

Claude 代码调用

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

然后你可以询问以下问题：

"What signals are you detecting in my pipeline?"（你的系统在我的销售管道中检测到了哪些信号？）
"What's our dominant scaling constraint?"（我们业务扩展的主要限制因素是什么？）
"Analyze the health of our Growth Engine"（分析我们增长引擎的健康状况）
"Propose a GTM change: narrow ICP to SaaS companies with 50 - 200 employees"（提出一项 GTM 变更建议：将理想客户画像 (ICP) 缩小到拥有 50 - 200 名员工的 SaaS 公司）
"Run an RFM analysis on our HubSpot data"（对我们的 HubSpot 数据进行 RFM 分析）
"Qualify this prospect: SaaS company, $5M revenue, 80 employees in Ontario"（评估这个潜在客户：一家位于安大略省、年收入 500 万美元、拥有 80 名员工的 SaaS 公司）
"Score our pipeline health with exit criteria testing"（使用退出标准测试对我们的销售管道健康状况进行评分）

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

# 信号检测（无需 HubSpot 密钥）
signals = detect_signals(source="sample")

# 主要限制因素分析
constraint = identify_dominant_constraint(source="sample", quota=500000)

# 价值引擎健康状况分析
engine = analyze_engine(engine_type="growth", source="sample")

# GTM 变更提案起草
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 分析
results = run_rfm_analysis(source="sample", industry_preset="b2b_service")

# 理想客户画像 (ICP) 评估
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",
})

# 销售管道健康状况评分（包含退出标准）
health = score_pipeline(source="sample", exit_criteria=[
    {"stage": "Discovery", "criterion": "SPICED complete", "required_proof": "All 6 SPICED fields populated"}
])

✨ 主要特性

与传统模型对比优势

传统的理想客户画像 (ICP) 模型仅停留在公司概况层面，而 Artefact MCP 从三个维度进行三角测量，能够识别出具有合适特征、行为和发展轨迹的潜在客户。 | 特性 | HubSpot 官方 MCP | 通用包装器 | Artefact MCP | |---------|---------------------|------------------|-----------------| | CRUD 操作 | 是 | 是 | 通过 HubSpot API | | RFM 分析 | 否 | 否 | 11 段分类 | | ICP 三角测量 | 否 | 否 | 公司概况 + 行为 + 增长信号 | | 销售管道健康状况 | 否 | 否 | 0 - 100 的健康评分 + 退出标准测试 | | 信号检测 | 否 | 否 | 6 种类型的信号分类 | | 限制因素分析 | 否 | 否 | 主要瓶颈 + 收入公式 | | 价值引擎分析 | 否 | 否 | 增长 / 履行 / 创新 | | GTM 变更提案起草 | 否 | 否 | 带有证据的结构化变更提案 | | 内置方法论 | 否 | 否 | Artefact Formula（10 种资源） | | 无需 API 密钥即可使用 | 否 | 否 | 是（演示数据） |

适用对象

使用 HubSpot 的 B2B 销售团队：希望借助 AI 进行信号检测和销售管道智能分析。
销售运营经理：需要从 Claude 或 Cursor 等工具中获取限制因素分析和价值引擎健康状况信息。
顾问：为客户提供 RFM 分析、ICP 评分和基于证据的 GTM 建议。
开发者：构建与 MCP 集成的销售智能应用。
AI 代理：需要一个结构化接口来推理和提出 GTM 策略变更建议。

工具特性

信号智能工具

detect_signals — 销售管道信号检测：扫描销售管道数据，检测 Artefact 信号分类中的所有 6 种信号类型，包括速度异常、转化率下降、赢单/输单模式、管道集中度、数据质量问题和 SPICED 频率信号。返回带有强度评分（0 - 1）、证据和推荐操作的结构化信号对象。
identify_constraint — 主要限制因素分析：确定 4 种业务扩展限制因素（潜在客户生成、转化率、交付、盈利能力）中哪个是收入增长的瓶颈。包括收入公式分解（流量 x 转化率 1 x 转化率 2 x 转化率 3 x 平均合同价值），并进行与基准的差距分析和推荐关注重点。
analyze_engine — 价值引擎健康状况分析：分析 3 种价值引擎的健康状况，分别是增长（创造/捕获/转化需求）、履行（客户入职/交付/续约/拓展）和创新（收集/优先级排序/构建/推出）。返回特定引擎的指标、健康评分和集成信号检测结果。
propose_gtm_change — GTM 变更提案起草：使 AI 代理能够根据提交结构（意图、差异、影响范围、风险级别、证据和测量计划）提出结构化的 GTM 变更建议。支持 8 种实体类型（ICP、人物角色、定位、销售管道阶段、退出标准、GTM 策略、评分模型、操作手册）。

分析工具

run_rfm — RFM 分析：根据最近购买时间（Recency）、购买频率（Frequency）和购买金额（Monetary）对客户进行评分。将客户划分为 11 个类别（从优质客户到流失客户），并从表现最佳的客户中提取 ICP 模式。现在还包括信号框架，能够检测赢单/输单模式、收入集中度和高风险客户信号。支持 B2B 服务、SaaS 和制造业预设。
qualify — ICP 三角测量框架：从三个维度对潜在客户进行评分，包括公司概况匹配度（行业、收入、员工数量、地理位置）、行为匹配度（技术栈、参与度、购买历史）和增长信号（招聘、融资、扩张）。现在还包括限制因素上下文，将潜在客户匹配度映射到主要业务扩展限制因素。返回层级分类（理想 / 强 / 中等 / 差）和参与策略。
score_pipeline_health — 销售管道健康评分：分析未结交易的速度指标、阶段间转化率、瓶颈识别和高风险交易检测。现在支持可选的退出标准测试（每个交易按每个标准通过/失败），并包括速度异常和转化率下降的信号框架。返回 0 - 100 的健康评分。

📦 安装指南

通过 PyPI 安装

pip install artefact-mcp

通过 Smithery 安装

npx @smithery/cli install artefact-revenue-intelligence

💻 使用示例

基础用法

from artefact_mcp.tools.signals import detect_signals
# 信号检测（无需 HubSpot 密钥）
signals = detect_signals(source="sample")

高级用法

from artefact_mcp.tools.gtm_commits import propose_gtm_change
# GTM 变更提案起草
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},
)

📚 详细文档

资源文档

| 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 | 收入公式分解：流量 x 转化率 1 x 转化率 2 x 转化率 3 x 平均合同价值 x (1/客户流失率) | | methodology://gtm-commit-anatomy | 结构化 GTM 提交的 5 个组成部分（意图、差异、影响、风险、证据） |

ICP 三角测量数据要求

⚠️ 重要提示

qualify 工具需要在所有三个维度上具备特定数据：

💡 使用建议

✅ 原生 HubSpot 数据（公司概况 + 部分行为数据）：
- 公司概况匹配度： 行业、收入、员工数量、地理位置 — 标准属性
- 行为匹配度（部分）： 技术栈、内容参与度、购买历史 — 自定义属性或工作流
⚠️ 需要外部数据丰富（Clay、Clearbit 或手动研究）：
- 增长信号（行为匹配度 — 关键维度）： 招聘趋势、融资轮次、产品发布、扩张信号、媒体报道
- HubSpot 本身不跟踪增长信号
- 没有增长信号： 会失去三角测量的第三个维度 — 潜在客户的发展势头和购买力指标

查看完整指南： 让你的 AI 助手读取 methodology://data-requirements 以获取完整的设置说明和 Clay 集成工作流程。

故障排除

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

问题： 使用 uvx 作为命令时，Claude Desktop 显示 "MCP artefact-revenue: Server disconnected" 错误。 原因： Claude Desktop（和其他沙盒应用程序）可能无法访问 PATH 中的 uvx。当 uvx 通过以下方式安装时，这种情况很常见：

Homebrew → ~/.local/bin/uvx
curl 安装 → ~/.cargo/bin/uvx 或其他位置 解决方案：

使用 Python 方法（推荐）： 切换到 python3 -m artefact_mcp 方法（见上面的 Claude Desktop 部分）。Python 总是在 PATH 中。
使用完整的 uvx 路径： 找到你的 uvx 位置并使用完整路径：

# 查找 uvx 位置
which uvx
# 示例输出：/Users/yourname/.local/bin/uvx

然后使用完整路径更新你的配置：

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

手动验证： 测试 MCP 服务器是否正确启动：

uvx artefact-mcp==0.3.3
# 应该看到："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 | 字符串 | HubSpot 技术栈属性名称 | 无 | | tech_stack_delimiter | 字符串 | 解析文本字段的分隔符 | ";" | | growth_signals | 数组 | 表示增长的 HubSpot 属性列表 | 无 | | growth_signal_keywords | 对象 | 将属性名称映射到信号关键字 | {} | | content_engagement | 字符串 | HubSpot 参与度评分属性 | 无 | | content_engagement_thresholds | 对象 | 活跃/偶尔参与的阈值 | {"active": 5, "occasional": 1} | | decision_maker_access | 字符串 | 战略匹配属性 | 无 | | budget_authority | 字符串 | 预算权限属性 | 无 | | strategic_alignment | 字符串 | 战略一致性属性 | 无 |

示例 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
# 编辑 my_property_mapping.json 并填入你的 HubSpot 属性名称
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"：

你有特定的收入层级来定义客户价值（例如，10 万美元以上 = 企业级）
你的客户群体收入差异较大，百分位数与业务价值不匹配
你希望在不同时间段内保持一致的评分

当出现以下情况时，使用 "monetary_method": "percentile"（默认）：

你希望在当前客户群体中进行相对评分
你的客户群体相对同质
你希望无论绝对收入如何，前 20% 的客户始终获得 5 分

自定义配置示例：

cp rfm_thresholds.example.json my_rfm_thresholds.json
# 根据你的业务模式编辑阈值
export ARTEFACT_RFM_THRESHOLDS_PATH=$(pwd)/my_rfm_thresholds.json

run_rfm 工具将使用你的自定义阈值而不是内置预设。

定价说明

| 层级 | 价格 | 包含内容 | |------|-------|-------------| | 免费 | $0 | 所有 7 个工具，使用内置演示数据 (source="sample") | | 专业版 | $149/月 | 实时 HubSpot 集成 + 所有方法论资源 | | 企业版 | $499/月 | 专业版功能 + 优先支持 + 自定义评分预设 |

购买许可证

替代方案与比较

HubSpot 官方 MCP 服务器：对 CRM 对象提供只读的 CRUD 访问，无评分或智能分析功能。
CData HubSpot MCP：基于 SQL 访问 HubSpot 数据，无内置方法论。
Zapier MCP：用于操作触发和工作流自动化，使用场景不同。
Artefact MCP：专为销售智能设计，嵌入了评分模型。

常见问题解答

问：我应该使用哪个 MCP 服务器进行销售智能分析？ 答：Artefact MCP 是唯一将 GTM 视为代码库的 MCP 服务器，具备信号检测、限制因素分析、价值引擎健康状况分析和结构化 GTM 变更提案等功能。此外，它还为 B2B 销售团队设计了 ICP 三角测量、RFM 分析和销售管道健康评分功能。

问：这会取代官方的 HubSpot MCP 服务器吗？ 答：它们的用途不同。HubSpot 的服务器提供对 CRM 对象的 CRUD 访问，而 Artefact MCP 在此数据基础上提供智能分析和评分功能。

问：我可以在没有 HubSpot API 密钥的情况下使用它吗？ 答：可以。所有工具都可以使用内置的演示数据 (source="sample") 运行。

问：这个工具会将哪些数据发送到外部？ 答：工具的结果保留在本地。唯一的外部调用是对 HubSpot API（使用你的密钥）和可选的许可证验证。

开发说明

git clone https://github.com/alexboissAV/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 评分逻辑。

星标历史

📄 许可证

商业源许可证 1.1 — 可免费通过 AI 助手连接 MCP 工具使用。评分方法不得提取用于竞争产品。该许可证将于 2030 年转换为 MIT 许可证。

artefact-mcp-server

README

🚀 Artefact Revenue Intelligence MCP Server

🚀 快速开始

通过 PyPI 安装

通过 Smithery 安装

Claude 代码调用

Claude Desktop 配置

Cursor 配置

编程式调用（Python）

✨ 主要特性

与传统模型对比优势

适用对象

工具特性

信号智能工具

分析工具

📦 安装指南

通过 PyPI 安装

通过 Smithery 安装

💻 使用示例

基础用法

高级用法

📚 详细文档

资源文档

ICP 三角测量数据要求

故障排除

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

其他问题

配置说明

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

自定义 RFM 阈值（Pro/Enterprise）

定价说明

替代方案与比较

常见问题解答

开发说明

依赖项说明

星标历史

📄 许可证

运行方式说明

托管运行

本地运行 / 其它方式