{
  "markdown": "# Artefact Revenue Intelligence MCP Server\n\n<!-- mcp-name: io.github.alexboissAV/artefact-revenue-intelligence -->\n\n[![PyPI](https://img.shields.io/pypi/v/artefact-mcp)](https://pypi.org/project/artefact-mcp/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)\n[![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-orange.svg)](LICENSE)\n\n> [!IMPORTANT]\n> **This repository is archived and is not the source of the published package.**\n>\n> It stopped tracking releases at `0.3.3` (February 2026) while the published package continued to `0.5.1`. Anything here is stale by several minor versions and should not be read as describing current behaviour.\n>\n> - **To install or use the server:** [`artefact-mcp` on PyPI](https://pypi.org/project/artefact-mcp/)\n> - **For the product:** [artefactventures.com/mcp](https://artefactventures.com/en/mcp)\n>\n> A maintained public mirror is planned for the product launch. Until then, treat PyPI as the only current artifact.\n\n> **The AI-native interface to your Revenue Operating System. Version-controlled GTM intelligence — signals, commits, and closed-loop measurement — accessible to any AI agent.**\n\nA Model Context Protocol (MCP) server that treats your Go-to-Market strategy like code: versioned, diffable, and deployable. Detect pipeline signals, identify scaling constraints, analyze value engines, and draft structured GTM changes — all through AI-native tool calls. Built on the [Artefact Formula](https://artefactventures.com/en/mcp?utm_campaign=always_on-community-demand-github-readme-mcp-mcp_server-na-github&utm_medium=referral&utm_source=github.com&utm_content=documentation-readme-landing-link-en&utm_term=developer-na) methodology from real B2B consulting engagements.\n\n## Why Artefact MCP?\n\n**Traditional ICP models stop at firmographics. We triangulate across three dimensions to identify prospects with the right profile, the right behaviors, AND the right trajectory.**\n\n| Feature | HubSpot Official MCP | Generic Wrappers | **Artefact MCP** |\n|---------|---------------------|------------------|-----------------|\n| CRUD operations | Yes | Yes | Via HubSpot API |\n| RFM Analysis | No | No | **11-segment classification** |\n| **ICP Triangulation** | No | No | **Firmographic + Behavioral + Growth Signals** |\n| Pipeline Health | No | No | **0-100 health score + exit criteria testing** |\n| **Signal Detection** | No | No | **6-type signal taxonomy** |\n| **Constraint Analysis** | No | No | **Dominant bottleneck + Revenue Formula** |\n| **Value Engine Analysis** | No | No | **Growth / Fulfillment / Innovation** |\n| **GTM Commit Drafting** | No | No | **Structured change proposals with evidence** |\n| Methodology built-in | No | No | **Artefact Formula (10 resources)** |\n| Works without API key | No | No | **Yes (demo data)** |\n\n## Who Is This For?\n\n- **B2B revenue teams** using HubSpot who want AI-powered signal detection and pipeline intelligence\n- **RevOps managers** who need constraint analysis and value engine health accessible from Claude or Cursor\n- **Consultants** who deliver RFM analysis, ICP scoring, and evidence-backed GTM recommendations to clients\n- **Developers** building revenue intelligence integrations with MCP\n- **AI agents** that need a structured interface to reason about and propose changes to GTM strategy\n\n## Tools\n\n### Signal Intelligence\n\n### `detect_signals` — Pipeline Signal Detection\nScans pipeline data for all 6 signal types from the Artefact signal taxonomy: velocity anomalies, conversion drop-offs, win/loss patterns, pipeline concentration, data quality issues, and SPICED frequency signals. Returns structured signal objects with strength scores (0-1), evidence, and recommended actions.\n\n### `identify_constraint` — Dominant Constraint Analysis\nIdentifies which of the 4 scaling constraints (Lead Generation, Conversion, Delivery, Profitability) is bottlenecking revenue. Includes Revenue Formula breakdown (Traffic x CR1 x CR2 x CR3 x ACV) with gap-to-benchmark analysis and recommended focus.\n\n### `analyze_engine` — Value Engine Health\nAnalyzes health of the 3 value engines: Growth (create/capture/convert demand), Fulfillment (onboard/deliver/renew/expand), and Innovation (gather/prioritize/build/launch). Returns engine-specific metrics, health scores, and integrated signal detection.\n\n### `propose_gtm_change` — GTM Commit Drafting\nEnables AI agents to propose structured GTM changes following the commit anatomy: Intent, Diff, Impact Surface, Risk Level, Evidence, and Measurement Plan. Supports 8 entity types (ICP, persona, positioning, pipeline stage, exit criteria, GTM motion, scoring model, playbook).\n\n### Analysis Tools\n\n### `run_rfm` — RFM Analysis\nScores clients on Recency, Frequency, and Monetary value. Segments them into 11 categories (Champions through Lost) and extracts ICP patterns from top performers. Now includes signal framing — detects win/loss patterns, revenue concentration, and at-risk client signals. Supports B2B service, SaaS, and manufacturing presets.\n\n### `qualify` — ICP Triangulation Framework\nScores prospects across three dimensions: Firmographic Fit (industry, revenue, employees, geography), Behavioral Fit (tech stack, engagement, purchase history), and Growth Signals (hiring, funding, expansion). Now includes constraint context — maps prospect fit to your dominant scaling constraint. Returns tier classification (Ideal / Strong / Moderate / Poor) with engagement strategy.\n\n### `score_pipeline_health` — Pipeline Health Score\nAnalyzes open deals for velocity metrics, stage-to-stage conversion rates, bottleneck identification, and at-risk deal detection. Now supports optional exit criteria testing (pass/fail per criterion per deal) and includes signal framing for velocity anomalies and conversion drop-offs. Returns a 0-100 health score.\n\n## Resources\n\n| URI | Description |\n|-----|-------------|\n| `methodology://scoring-model` | ICP Triangulation Framework technical reference |\n| `methodology://tier-definitions` | 4-tier classification system |\n| `methodology://rfm-segments` | 11 RFM segment definitions with scoring scales |\n| `methodology://spiced-framework` | SPICED discovery framework |\n| `methodology://data-requirements` | HubSpot data setup and enrichment requirements |\n| `methodology://value-engines` | 3 value engine definitions (Growth, Fulfillment, Innovation) with stages and metrics |\n| `methodology://exit-criteria` | Standard pipeline exit criteria per stage with proof requirements |\n| `methodology://constraints` | 4 scaling constraints with diagnostic criteria and remediation levers |\n| `methodology://signal-taxonomy` | 6 signal types with detection methods and action mappings |\n| `methodology://revenue-formula` | Revenue Formula breakdown: Traffic x CR1 x CR2 x CR3 x ACV x (1/Churn) |\n| `methodology://gtm-commit-anatomy` | 5 components of a structured GTM commit (intent, diff, impact, risk, evidence) |\n\n## Data Requirements for ICP Triangulation\n\n**⚠️ Important:** The `qualify` tool requires specific data across all three dimensions:\n\n**✅ Native HubSpot data (Firmographic + Partial Behavioral):**\n- **Firmographic Fit:** Industry, revenue, employees, geography — standard properties\n- **Behavioral Fit (Partial):** Tech stack, content engagement, purchase history — custom properties or workflows\n\n**⚠️ Requires external enrichment (Clay, Clearbit, or manual research):**\n- **Growth Signals (Behavioral Fit — Critical Dimension):** Hiring trends, funding rounds, product launches, expansion signals, press mentions\n- HubSpot does NOT track growth signals natively\n- **Without growth signals:** You lose the third dimension of triangulation — prospect momentum and buying power indicators\n\n**See full guide:** Ask your AI assistant to read `methodology://data-requirements` for complete setup instructions and Clay integration workflow.\n\n## Quick Start\n\n### Install via PyPI\n\n```bash\npip install artefact-mcp\n```\n\n### Install via Smithery\n\n```bash\nnpx @smithery/cli install artefact-revenue-intelligence\n```\n\n### Claude Code\n\n```bash\nclaude mcp add artefact-revenue -- uvx artefact-mcp\n```\n\nThen ask:\n- \"What signals are you detecting in my pipeline?\"\n- \"What's our dominant scaling constraint?\"\n- \"Analyze the health of our Growth Engine\"\n- \"Propose a GTM change: narrow ICP to SaaS companies with 50-200 employees\"\n- \"Run an RFM analysis on our HubSpot data\"\n- \"Qualify this prospect: SaaS company, $5M revenue, 80 employees in Ontario\"\n- \"Score our pipeline health with exit criteria testing\"\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n**Recommended (Python method):**\n```json\n{\n  \"mcpServers\": {\n    \"artefact-revenue\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"artefact_mcp\"],\n      \"env\": {\n        \"HUBSPOT_API_KEY\": \"pat-na1-xxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n**Alternative (uvx method):**\n```json\n{\n  \"mcpServers\": {\n    \"artefact-revenue\": {\n      \"command\": \"uvx\",\n      \"args\": [\"artefact-mcp\"],\n      \"env\": {\n        \"HUBSPOT_API_KEY\": \"pat-na1-xxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n*Note: If using uvx and seeing \"Server disconnected\" errors, see the [Troubleshooting](#troubleshooting) section below.*\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n**Recommended (Python method):**\n```json\n{\n  \"mcpServers\": {\n    \"artefact-revenue\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"artefact_mcp\"],\n      \"env\": {\n        \"HUBSPOT_API_KEY\": \"pat-na1-xxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n**Alternative (uvx method):**\n```json\n{\n  \"mcpServers\": {\n    \"artefact-revenue\": {\n      \"command\": \"uvx\",\n      \"args\": [\"artefact-mcp\"],\n      \"env\": {\n        \"HUBSPOT_API_KEY\": \"pat-na1-xxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n### Programmatic (Python)\n\n```python\nfrom artefact_mcp.tools.signals import detect_signals\nfrom artefact_mcp.tools.constraints import identify_dominant_constraint\nfrom artefact_mcp.tools.engines import analyze_engine\nfrom artefact_mcp.tools.gtm_commits import propose_gtm_change\nfrom artefact_mcp.tools.rfm import run_rfm_analysis\nfrom artefact_mcp.tools.icp import qualify_prospect\nfrom artefact_mcp.tools.pipeline import score_pipeline\n\n# Signal detection (no HubSpot key needed)\nsignals = detect_signals(source=\"sample\")\n\n# Dominant constraint analysis\nconstraint = identify_dominant_constraint(source=\"sample\", quota=500000)\n\n# Value engine health\nengine = analyze_engine(engine_type=\"growth\", source=\"sample\")\n\n# GTM commit drafting\ncommit = propose_gtm_change(\n    entity_type=\"icp\",\n    change_description=\"Narrow ICP to SaaS companies with 50-200 employees\",\n    signal_type=\"win_loss_pattern\",\n    signal_data={\"win_rate_saas\": 0.45, \"win_rate_other\": 0.22},\n)\n\n# RFM with sample data\nresults = run_rfm_analysis(source=\"sample\", industry_preset=\"b2b_service\")\n\n# ICP qualification\nscore = qualify_prospect(company_data={\n    \"industry\": \"SaaS\",\n    \"annual_revenue\": 10_000_000,\n    \"employee_count\": 80,\n    \"geography\": \"Quebec\",\n    \"tech_stack\": [\"HubSpot\", \"Google Analytics\"],\n    \"growth_signals\": [\"hiring\", \"funding\"],\n    \"content_engagement\": \"active\",\n    \"decision_maker_access\": \"c_suite\",\n    \"budget_authority\": \"dedicated\",\n    \"strategic_alignment\": \"strong\",\n})\n\n# Pipeline health with exit criteria\nhealth = score_pipeline(source=\"sample\", exit_criteria=[\n    {\"stage\": \"Discovery\", \"criterion\": \"SPICED complete\", \"required_proof\": \"All 6 SPICED fields populated\"}\n])\n```\n\n## Troubleshooting\n\n### Server Disconnected Errors (uvx PATH issue)\n\n**Problem:** Claude Desktop shows \"MCP artefact-revenue: Server disconnected\" error when using `uvx` as the command.\n\n**Cause:** Claude Desktop (and other sandboxed applications) may not have access to `uvx` in your PATH. This commonly happens when `uvx` is installed via:\n- Homebrew → `~/.local/bin/uvx`\n- curl installation → `~/.cargo/bin/uvx` or other locations\n\n**Solutions:**\n\n1. **Use Python method (recommended):** Switch to `python3 -m artefact_mcp` method (see Claude Desktop section above). Python is always in PATH.\n\n2. **Use full uvx path:** Find your uvx location and use the full path:\n   ```bash\n   # Find uvx location\n   which uvx\n   # Example output: /Users/yourname/.local/bin/uvx\n   ```\n\n   Then update your config with the full path:\n   ```json\n   {\n     \"mcpServers\": {\n       \"artefact-revenue\": {\n         \"command\": \"/Users/yourname/.local/bin/uvx\",\n         \"args\": [\"artefact-mcp\"],\n         \"env\": {}\n       }\n     }\n   }\n   ```\n\n3. **Verify manually:** Test that the MCP server starts correctly:\n   ```bash\n   uvx artefact-mcp==0.3.3\n   # Should see: \"Artefact Revenue Intelligence MCP Server running...\"\n   ```\n\n### Other Issues\n\n**Issue:** Tools return \"No HubSpot API key\" errors.\n\n**Solution:** Ensure `HUBSPOT_API_KEY` is set in your MCP server configuration. Or use `source=\"sample\"` to test with demo data first.\n\n**Issue:** Import errors when using `python3 -m artefact_mcp`.\n\n**Solution:** Ensure the package is installed: `pip install artefact-mcp` or `pip install --upgrade artefact-mcp`.\n\n## Configuration\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `HUBSPOT_API_KEY` | No | HubSpot private app token. Without it, tools work with `source=\"sample\"`. |\n| `ARTEFACT_LICENSE_KEY` | No | License key for Pro/Enterprise tier. Free tier (sample data) works without a key. |\n| `ARTEFACT_PROPERTY_MAPPING_PATH` | No | Path to JSON file with custom HubSpot property mappings (Pro/Enterprise only). |\n| `ARTEFACT_RFM_THRESHOLDS_PATH` | No | Path to JSON file with custom RFM scoring thresholds (Pro/Enterprise only). |\n\n### Custom Property Mappings (Pro/Enterprise)\n\nIf your HubSpot instance uses custom property names for behavioral and strategic fit data, you can configure property mappings. This allows the `qualify` tool to automatically fetch and score all ICP dimensions from your HubSpot data.\n\n**Create a JSON configuration file** (e.g., `artefact_property_mapping.json`):\n\n```json\n{\n  \"tech_stack\": \"technologies_used\",\n  \"tech_stack_delimiter\": \",\",\n  \"growth_signals\": [\"linkedin_hiring_count\", \"recent_funding_amount\", \"press_mentions\"],\n  \"growth_signal_keywords\": {\n    \"linkedin_hiring_count\": \"hiring\",\n    \"recent_funding_amount\": \"funding\",\n    \"press_mentions\": \"press\"\n  },\n  \"content_engagement\": \"hubspot_engagement_score\",\n  \"content_engagement_thresholds\": {\n    \"active\": 10,\n    \"occasional\": 3\n  },\n  \"decision_maker_access\": \"primary_contact_role\",\n  \"budget_authority\": \"budget_category\",\n  \"strategic_alignment\": \"revenue_ops_conviction\"\n}\n```\n\n**Set the environment variable:**\n\n```bash\nexport ARTEFACT_PROPERTY_MAPPING_PATH=/path/to/artefact_property_mapping.json\n```\n\n**Available Configuration Options:**\n\n| Property | Type | Description | Default |\n|----------|------|-------------|---------|\n| `tech_stack` | string | HubSpot property name for tech stack | None |\n| `tech_stack_delimiter` | string | Delimiter for parsing text fields | `\";\"` |\n| `growth_signals` | array | List of HubSpot properties indicating growth | None |\n| `growth_signal_keywords` | object | Map property names to signal keywords | `{}` |\n| `content_engagement` | string | HubSpot property for engagement score | None |\n| `content_engagement_thresholds` | object | Thresholds for active/occasional | `{\"active\": 5, \"occasional\": 1}` |\n| `decision_maker_access` | string | Strategic fit property | None |\n| `budget_authority` | string | Budget authority property | None |\n| `strategic_alignment` | string | Strategic alignment property | None |\n\n**Example HubSpot Properties:**\n\nCommon custom properties to map:\n- **Tech Stack:** `tech_stack_used`, `technologies`, `crm_platform`\n- **Growth Signals:** `linkedin_job_postings_count`, `recent_funding_round`, `press_mentions_count`, `new_office_opened`\n- **Content Engagement:** `hs_analytics_num_page_views`, `email_engagement_score`\n- **Strategic Fit:** `primary_contact_role`, `budget_category`, `growth_conviction`\n\nThe `qualify` tool will automatically fetch and score these custom properties when a property mapping is configured.\n\n**Example Configuration Files:**\n\nTwo example configurations are included in the repository:\n\n- `property_mapping.example.json` — Full configuration with all available options\n- `property_mapping.minimal.example.json` — Minimal configuration for growth signals only\n\nCopy the appropriate example file and customize it for your HubSpot instance:\n\n```bash\ncp property_mapping.minimal.example.json my_property_mapping.json\n# Edit my_property_mapping.json with your HubSpot property names\nexport ARTEFACT_PROPERTY_MAPPING_PATH=$(pwd)/my_property_mapping.json\n```\n\n### Custom RFM Thresholds (Pro/Enterprise)\n\nPro/Enterprise users can customize RFM scoring thresholds to match their industry or business model. The built-in presets (b2b_service, saas, manufacturing) may not perfectly fit your buying cycles or revenue ranges.\n\n**Create an RFM threshold configuration file** (e.g., `rfm_thresholds.json`):\n\n```json\n{\n  \"recency_days\": [60, 180, 365, 730],\n  \"recency_scores\": [5, 4, 3, 2, 1],\n  \"frequency_counts\": [5, 3, 2, 1],\n  \"frequency_scores\": [5, 4, 3, 2, 1],\n  \"monetary_method\": \"percentile\",\n  \"monetary_percentiles\": [80, 60, 40, 20]\n}\n```\n\n**Set the environment variable:**\n\n```bash\nexport ARTEFACT_RFM_THRESHOLDS_PATH=/path/to/rfm_thresholds.json\n```\n\n**Available Configuration Options:**\n\n| Property | Type | Description | Default |\n|----------|------|-------------|---------|\n| `recency_days` | array | Days since last purchase thresholds | `[30, 90, 180, 365]` |\n| `recency_scores` | array | Scores for each recency band (5 = best) | `[5, 4, 3, 2, 1]` |\n| `frequency_counts` | array | Transaction count thresholds | `[10, 5, 3, 2]` |\n| `frequency_scores` | array | Scores for each frequency band | `[5, 4, 3, 2, 1]` |\n| `monetary_method` | string | Scoring method: `\"percentile\"` or `\"fixed\"` | `\"percentile\"` |\n| `monetary_percentiles` | array | Percentile thresholds (for percentile method) | `[80, 60, 40, 20]` |\n| `monetary_fixed_thresholds` | array | Fixed dollar thresholds (for fixed method) | `[100000, 50000, 25000, 10000]` |\n| `monetary_scores` | array | Scores for each monetary band | `[5, 4, 3, 2, 1]` |\n\n**Example Configurations:**\n\n- `rfm_thresholds.example.json` — Percentile-based monetary scoring (recommended for most use cases)\n- `rfm_thresholds.fixed_monetary.example.json` — Fixed dollar thresholds for monetary scoring\n\n**When to Use Fixed Thresholds:**\n\nUse `\"monetary_method\": \"fixed\"` when:\n- You have specific revenue tiers that define customer value (e.g., $100K+ = enterprise)\n- Your customer base has wide revenue variance and percentiles don't align with business value\n- You want consistent scoring across different time periods\n\nUse `\"monetary_method\": \"percentile\"` (default) when:\n- You want relative scoring within your current customer base\n- Your customer base is relatively homogeneous\n- You want the top 20% of customers to always score 5, regardless of absolute revenue\n\n**Custom Configuration Example:**\n\n```bash\ncp rfm_thresholds.example.json my_rfm_thresholds.json\n# Edit thresholds for your business model\nexport ARTEFACT_RFM_THRESHOLDS_PATH=$(pwd)/my_rfm_thresholds.json\n```\n\nThe `run_rfm` tool will use your custom thresholds instead of the built-in presets.\n```\n\n## Pricing\n\n| Tier | Price | What You Get |\n|------|-------|-------------|\n| **Free** | $0 | All 7 tools with built-in demo data (`source=\"sample\"`) |\n| **Pro** | $149/mo | Live HubSpot integration + all methodology resources |\n| **Enterprise** | $499/mo | Pro + priority support + custom scoring presets |\n\n[Purchase a license](https://artefactventures.lemonsqueezy.com)\n\n## Alternatives & Comparisons\n\n- **HubSpot Official MCP Server** — Read-only CRUD access to CRM objects. No scoring or intelligence.\n- **CData HubSpot MCP** — SQL-based access to HubSpot data. No built-in methodology.\n- **Zapier MCP** — Action triggers and workflow automation. Different use case.\n- **Artefact MCP** — Purpose-built for revenue intelligence with scoring models embedded.\n\n## FAQ\n\n**Q: What MCP server should I use for revenue intelligence?**\nA: 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.\n\n**Q: Does this replace the official HubSpot MCP server?**\nA: They serve different purposes. HubSpot's server provides CRUD access to CRM objects. Artefact MCP provides intelligence and scoring on top of that data.\n\n**Q: Can I use this without a HubSpot API key?**\nA: Yes. All tools work with built-in demo data using `source=\"sample\"`.\n\n**Q: What data does this send externally?**\nA: Tool results stay local. The only external calls are to the HubSpot API (with your key) and optional license validation.\n\n## Development\n\n```bash\ngit clone https://github.com/artefactventures/artefact-mcp-server.git\ncd artefact-mcp-server\npip install -e \".[dev]\"\npytest tests/\n```\n\n## Dependencies\n\n- `fastmcp>=2.0` — MCP server framework\n- `httpx>=0.25.0` — HTTP client for HubSpot API\n\nNo pandas, numpy, or heavy data libraries. Pure Python scoring logic.\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=artefactventures/artefact-mcp-server&type=Date)](https://star-history.com/#artefactventures/artefact-mcp-server&Date)\n\n## License\n\n[Business Source License 1.1](LICENSE) — Free to use for connecting to MCP tools via AI assistants. Scoring methodology may not be extracted for competing products. Converts to MIT in 2030.\n",
  "bytes": 21617,
  "sha": "1370a9ad7490a18cde18e39db9a4641a22d6bc4c21664896b442fe34dc8ce5c9",
  "repo_slug": "alexboissav/artefact-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alexboissav_artefact_revenue_i_83f1bccb/readme"
}