Artefact MCP Server

🚀 Artefact Revenue Intelligence MCP Server

AIネイティブな収益オペレーティングシステムのインターフェース。バージョン管理されたGTMインテリジェンス（シグナル、コミット、クローズドループ測定）を、任意のAIエージェントが利用できます。

🚀 クイックスタート

PyPIを通じたインストール

pip install artefact-mcp

Smitheryを通じたインストール

npx @smithery/cli install artefact-revenue-intelligence

Claudeコード

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

次に、以下のような質問をします。

• "パイプラインで検出しているシグナルは何ですか？"
• "私たちの支配的なスケーリング制約は何ですか？"
• "Growthエンジンの健全性を分析してください"
• "GTMの変更を提案してください：ICPを50 - 200人の従業員を持つSaaS企業に絞り込む"
• "HubSpotのデータでRFM分析を実行してください"
• "この見込み客を評価してください：SaaS企業、年収500万ドル、オンタリオ州に80人の従業員"
• "退出基準テストを含めてパイプラインの健全性を評価してください"

Claudeデスクトップ

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"}
])

✨ 主な機能

シグナルインテリジェンス

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エージェントが、コミットの構造（意図、差分、影響範囲、リスクレベル、エビデンス、および測定計画）に従って、構造化されたGTMの変更を提案できるようにします。8つのエンティティタイプ（ICP、ペルソナ、ポジショニング、パイプラインステージ、退出基準、GTMモーション、スコアリングモデル、プレイブック）をサポートします。

分析ツール

run_rfm — RFM分析

顧客を最近性、頻度、および金額の価値でスコアリングします。11のカテゴリ（ChampionsからLostまで）にセグメント化し、上位のパフォーマーからICPパターンを抽出します。現在はシグナルフレーミングも含まれており、勝敗パターン、収益集中、およびリスクのある顧客のシグナルを検出します。B2Bサービス、SaaS、および製造業のプリセットをサポートします。

qualify — ICP三角測量フレームワーク

見込み客を3つの次元（企業属性適合性（業界、収益、従業員数、地理的な位置）、行動適合性（テクノロジースタック、エンゲージメント、購入履歴）、および成長シグナル（採用、資金調達、拡張））でスコアリングします。現在は制約のコンテキストも含まれており、見込み客の適合性を支配的なスケーリング制約にマッピングします。エンゲージメント戦略とともに、層別分類（理想的/強い/中程度/弱い）を返します。

score_pipeline_health — パイプラインの健全性スコア

オープンな商談について、速度メトリクス、ステージ間のコンバージョン率、ボトルネックの特定、およびリスクのある商談の検出を分析します。現在はオプションの退出基準テスト（商談ごとの基準ごとの合格/不合格）もサポートしており、速度異常およびコンバージョン低下のシグナルフレーミングを含みます。0 - 100の健全性スコアを返します。

📚 ドキュメント

なぜArtefact MCPなのか？

従来のICPモデルは企業属性にとどまります。私たちは3つの次元を三角測量し、適切なプロファイル、適切な行動、そして適切な軌道を持つ見込み客を特定します。

対象ユーザー

• HubSpotを使用し、AIによるシグナル検出とパイプラインインテリジェンスを望むB2B収益チーム
• ClaudeまたはCursorから制約分析と価値エンジンの健全性を利用する必要があるRevOpsマネージャー
• クライアントにRFM分析、ICPスコアリング、およびエビデンスに基づくGTM推奨事項を提供するコンサルタント
• MCPとの収益インテリジェンス統合を構築する開発者
• GTM戦略について推論し、変更を提案するための構造化されたインターフェースを必要とするAIエージェント

リソース

ICP三角測量のデータ要件

⚠️ 重要な注意

qualifyツールは、すべての3つの次元にわたる特定のデータを必要とします。

✅ ネイティブなHubSpotデータ（企業属性 + 部分的な行動）：

• 企業属性適合性： 業界、収益、従業員数、地理的な位置 — 標準的なプロパティ
• 行動適合性（部分的）： テクノロジースタック、コンテンツエンゲージメント、購入履歴 — カスタムプロパティまたはワークフロー

⚠️ 外部のエンリッチメントが必要（Clay、Clearbit、または手動調査）：

• 成長シグナル（行動適合性 — 重要な次元）： 採用傾向、資金調達ラウンド、製品の立ち上げ、拡張シグナル、報道記事
• HubSpotはネイティブで成長シグナルを追跡しません
• 成長シグナルがない場合： 三角測量の3つ目の次元（見込み客の勢いと購買力の指標）が失われます

完全なガイドを参照： AIアシスタントにmethodology://data-requirementsを読み上げさせて、完全なセットアップ手順とClay統合ワークフローを確認してください。

🔧 技術詳細

トラブルシューティング

サーバー切断エラー（uvx PATH問題）

問題： Claudeデスクトップでuvxをコマンドとして使用すると、「MCP artefact-revenue: Server disconnected」エラーが表示されます。

原因： Claudeデスクトップ（およびその他のサンドボックス化されたアプリケーション）は、PATHにあるuvxにアクセスできない場合があります。これは、uvxが以下の方法でインストールされた場合によく発生します。

• Homebrew → ~/.local/bin/uvx
• curlインストール → ~/.cargo/bin/uvxまたはその他の場所

解決策：

1. Pythonメソッドを使用する（推奨）： python3 -m artefact_mcpメソッドに切り替えます（上記のClaudeデスクトップセクションを参照）。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を実行します。

設定

カスタムプロパティマッピング（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ツールはこれらのカスタムプロパティを自動的に取得してスコアリングします。

例の設定ファイル： リポジトリには2つの例の設定が含まれています。

• 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

利用可能な設定オプション：

例の設定：

• rfm_thresholds.example.json — パーセンタイルベースの金額スコアリング（ほとんどのユースケースに推奨）
• rfm_thresholds.fixed_monetary.example.json — 固定ドル閾値による金額スコアリング

固定閾値を使用するタイミング：

• 顧客の価値を定義する特定の収益階層がある場合（例：10万ドル以上 = エンタープライズ）
• 顧客ベースの収益のばらつきが大きく、パーセンタイルがビジネス価値と一致しない場合
• 異なる期間にわたって一貫したスコアリングが必要な場合

"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ツールは、組み込みのプリセットではなく、カスタム閾値を使用します。

価格

ライセンスを購入する

代替案と比較

• HubSpot公式MCPサーバー — CRMオブジェクトへの読み取り専用CRUDアクセス。スコアリングやインテリジェンスはありません。
• CData HubSpot MCP — HubSpotデータへのSQLベースのアクセス。組み込みの方法論はありません。
• Zapier MCP — アクショントリガーとワークフロー自動化。異なるユースケースです。
• Artefact MCP — スコアリングモデルが組み込まれた収益インテリジェンス用に特別に設計されています。

FAQ

Q: 収益インテリジェンスにはどのMCPサーバーを使用すればよいですか？ A: Artefact MCPは、GTMをコードベースのように扱う唯一のMCPサーバーです。シグナル検出、制約分析、価値エンジンの健全性、および構造化されたGTMコミット提案があります。さらに、B2B収益チーム向けに設計されたICP三角測量、RFM分析、およびパイプラインの健全性スコアリングも備えています。

Q: これは公式のHubSpot MCPサーバーを置き換えるものですか？ A: それぞれ異なる目的を持っています。HubSpotのサーバーはCRMオブジェクトへのCRUDアクセスを提供します。Artefact MCPはそのデータに基づいてインテリジェンスとスコアリングを提供します。

Q: HubSpot APIキーなしでこれを使用できますか？ A: はい。すべてのツールはsource="sample"を使用して組み込みのデモデータで動作します。

Q: これは外部にどのようなデータを送信しますか？ A: ツールの結果はローカルに留まります。唯一の外部呼び出しは、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のスコアリングロジックです。

スター履歴

📄 ライセンス

Business Source License 1.1 — AIアシスタントを介してMCPツールに接続するために無料で使用できます。スコアリング方法論は、競合製品に抽出することはできません。2030年にMITライセンスに変更されます。