Artefact MCP Server

🚀 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 的 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},
)

📚 詳細文檔

資源文檔

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 或其他位置 解決方案：

1. 使用 Python 方法（推薦）： 切換到 python3 -m artefact_mcp 方法（見上面的 Claude Desktop 部分）。Python 總是在 PATH 中。
2. 使用完整的 uvx 路徑： 找到你的 uvx 位置並使用完整路徑：

# 查找 uvx 位置
which uvx
# 示例輸出：/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
# 應該看到："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。

配置說明

自定義屬性映射（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

可用配置選項：

示例 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

可用配置選項：

示例配置：

• 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 工具將使用你的自定義閾值而不是內置預設。

定價說明

購買許可證

替代方案與比較

• 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 許可證。