Metadata-Version: 2.4
Name: artefact-mcp
Version: 0.4.3
Summary: Artefact Formula MCP. GTM Operating System builder for B2B teams. Free tools (module library, archetype router, mode diagnostic, CLAUDE.md scaffolder, gate validator) plus Pro tier for HubSpot revenue intelligence (RFM, ICP triangulation, pipeline health).
Project-URL: Homepage, https://artefactventures.com/en/mcp
Project-URL: Documentation, https://github.com/alexboissAV/artefact-mcp-server#readme
Project-URL: Repository, https://github.com/alexboissAV/artefact-mcp-server
Project-URL: Issues, https://github.com/alexboissAV/artefact-mcp-server/issues
Project-URL: Changelog, https://github.com/alexboissAV/artefact-mcp-server/blob/main/CHANGELOG.md
Project-URL: Purchase, https://artefactventures.lemonsqueezy.com
Author-email: Artefact Ventures <alex@artefactventures.com>
License: BSL-1.1
License-File: LICENSE
Keywords: ai-tools,archetype,artefact-formula,b2b,claude,claude-md,crm,customer-scoring,gate-validator,go-to-market,gtm,gtm-os,hubspot,icp-scoring,llm-tools,mcp,mcp-server,mode-diagnostic,model-context-protocol,pipeline-health,revenue-intelligence,rfm-analysis,sales-intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastmcp<3.0,>=2.0
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# Artefact Formula MCP

<!-- mcp-name: io.github.alexboissAV/artefact-formula-mcp -->

**The GTM Operating System builder for AI-native B2B teams.**

[![PyPI](https://img.shields.io/pypi/v/artefact-mcp)](https://pypi.org/project/artefact-mcp/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
[![License: BSL-1.1](https://img.shields.io/badge/License-BSL--1.1-orange.svg)](LICENSE)

> ## First prompt to try
>
> After installing, open Claude and type:
>
>     Help me build my AI Operating System
>
> The agent will route to `auto_diagnose` and walk you through 3 questions to recommend your deployment mode and starting module. No license key required.

**[View Full Documentation](https://artefactventures.com/en/mcp)**

A Model Context Protocol (MCP) server that delivers the **Artefact Formula** methodology directly into Claude (or any MCP client). Five Free tools surface the GTM Operating System builder (module library, archetype router, mode diagnostic, CLAUDE.md scaffolder, gate validator). Four Pro tools cover HubSpot revenue intelligence (RFM, ICP triangulation, pipeline health). Built on real B2B consulting engagements at [Artefact Ventures](https://artefactventures.com).

> **Strategic pivot, May 4 2026.** This package now ships the full Artefact Formula GTM Operating System builder, not only the original Revenue Intelligence Tools (those continue to work and are now part of the Pro tier). See [Roadmap](#roadmap) for ship cadence.

## Methodology concepts (1 minute glossary)

Read this first if you are new to the Artefact Formula. These terms appear throughout the tools.

- **CLAUDE.md.** A 5-section master prompt file that codes a pilot's business logic into 80 to 150 lines. Survives an LLM or infra swap. The "operating system" file.
- **Module.** A discrete unit of GTM work, organized by pillar (FOND, ARC, SKL, WFL, SNT, GOV, INT, EXT) plus mode-specific (POC, DIY). 34 modules total.
- **Pillar.** A capability area: FOND (foundation), ARC (architecture), SKL (skills library), WFL (workflows), SNT (sentinelles, governance signals), GOV (governance), INT (interfaces), EXT (export and handoff).
- **Mode.** Deployment style: Self-Serve (solo or small team, free or low-touch), POC (4-week proof of concept), DIY (sponsor wants outputs, pilot is reviewer), Co-Build (pilot has 5 to 8 h/week and learns alongside).
- **Archetype.** Technical stack family: A (Open / sovereign, Claude + Notion + Supabase), B (Google-native), C (Microsoft-native), D (Hybrid / on-prem).
- **Sentinelle.** A scheduled governance check that watches for silent failures (skill drift, stale metacontext, broken auth tokens). Concept introduced; no MCP tool ships in v0.4.0.

## Why Artefact Formula MCP?

Most MCP servers expose data. This one installs a methodology. Five Free tier tools turn the Artefact Formula into callable operations: any MCP-compatible AI agent can browse the 34-module methodology, route a pilot to the right archetype, recommend a deployment mode, scaffold a CLAUDE.md master, and validate a module's QA gate. Four Pro tier tools add live HubSpot revenue intelligence on top.

| Capability | Generic MCP | Artefact Formula MCP |
|---|---|---|
| Methodology built-in | No | **5 piliers, 4 archétypes, 34 modules** |
| Mode diagnostic (POC / DIY / Co-Build / Self-Serve) | No | **`auto_diagnose`** from a free-text pilot context |
| Archetype router (A / B / C / D) | No | **`archetype_decision`** from 5 yes/no questions |
| CLAUDE.md scaffold | No | **`generate_claude_md`** with 5-section template |
| Module library browser | No | **`module_prompt_free`** for the 34-module catalog |
| QA gate validator | No | **`gate_check`** for module-by-module advancement |
| Revenue intelligence (HubSpot) | Partial | **RFM + ICP triangulation + pipeline health** (Pro tier) |
| Free architecture coach | No | **Yes, 100% local, no license** |

## Compatible clients

The Model Context Protocol is now the standard for AI agent integration. Artefact Formula MCP works in any MCP-compatible client, including:

| Client | LLM(s) | MCP support |
|---|---|---|
| **Claude Desktop, Claude Code, claude.ai** | Claude (Anthropic) | Native since Nov 2024 |
| **ChatGPT Desktop** | GPT (OpenAI) | Native via Apps SDK + Connectors + Developer Mode (since Mar 2025, full read/write Oct 2025) |
| **Google Gemini API, Vertex AI Agent Builder, Gemini CLI** | Gemini (Google) | Native since Mar 2026 |
| **Microsoft Copilot Studio, M365 Copilot, GitHub Copilot, Security Copilot** | Multi-LLM (Microsoft) | GA across Copilot suite |
| **Cursor, Windsurf, Zed, JetBrains AI Assistant** | Multi-LLM (your choice) | Native IDE integration |
| **Vercel AI SDK, OpenAI Agents SDK** | Multi-LLM | SDK-level support |
| **Ollama, LM Studio** (local LLMs) | Llama, Mistral, etc. | Community |

Artefact Formula MCP installs once via PyPI and runs wherever your team's AI lives. You don't switch LLMs to use the methodology; the methodology comes to your LLM.

## Who is this for?

- **B2B founders and operators** (sub-$1.6M revenue) who want a structured GTM operating system without hiring a consultant
- **B2B revenue teams** (sales, marketing, RevOps, customer success) on HubSpot who want AI-powered intelligence and governance
- **Consultants and agencies** who deliver the Artefact Formula methodology to clients
- **Active mandate clients** who need a co-pilot to do their devoirs between sessions and stay on the agenda
- **Developers** building revenue intelligence integrations on the MCP standard

## Tiers

| Tier | Price | What ships in v0.4.0 |
|---|---|---|
| **Free** | $0 | The 5 GTM OS builder tools (`module_prompt_free`, `archetype_decision`, `auto_diagnose`, `generate_claude_md`, `gate_check`). 100% local, no license key. |
| **Pro** | $200/mo (license gating planned for v0.5.0) | The 4 revenue intelligence tools (RFM, ICP triangulation, pipeline health) connected to live HubSpot. |
| **Mandate** | $30K–80K | Full consulting engagement plus Pro tier license bundled for the duration. Roadmap below. |

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

> Mandate clients receive a Pro tier license key for the duration of their consulting engagement (consulting bundle key). At the end of the mandate, conversion to Pro standalone is offered automatically.

## Quick start (Free tier)

### Install via PyPI

```bash
pip install artefact-mcp
```

### Run via uvx (no install)

```bash
uvx artefact-mcp
```

### Claude Code

```bash
claude mcp add artefact -- uvx artefact-mcp
```

Then ask Claude:

- "Browse the Artefact Formula module catalog" calls `module_prompt_free` (no args returns the catalog).
- "Recommend an archetype: we are M365-heavy, no extreme sovereignty constraint" calls `archetype_decision`.
- "Diagnose the right deployment mode: solo founder, want to test free, no bandwidth for co-build" calls `auto_diagnose`.
- "Generate a CLAUDE.md master for my B2B SaaS Marketing pilot" calls `generate_claude_md`.
- "Validate the FOND-1 gate, here is my evidence" calls `gate_check`.

## Tools

### Free tier (no license, 100% local)

| Tool | Purpose |
|---|---|
| `module_prompt_free` | Browse the 34-module Artefact Formula catalog (FOND, ARC, SKL, WFL, SNT, GOV, INT, EXT pillars plus POC, DIY mode-specific). With no argument returns the catalog grouped by pillar; with a module ID returns the full body of that module. |
| `archetype_decision` | Run the 5-question decision tree to recommend an archetype (A: Open / sovereign, B: Google-native, C: Microsoft-native, D: Hybrid / on-prem). Returns archetype, stack, 3 advantages, 3 constraints, and a transparent decision path. |
| `auto_diagnose` | Recommend a deployment mode (Self-Serve / POC / DIY / Co-Build) and a starting module from a free-text pilot context. Bilingual French + English keyword scan with archetype hint. Returns a structured framing if the input is empty or ambiguous. |
| `generate_claude_md` | Render a CLAUDE.md master scaffold (5 sections, 80–150 line target) for a pilot. Empty input returns the template; partial input returns markers for missing fields; complete input returns a clean master plus QA gate questions. |
| `gate_check` | Validate a module's QA gate against pilot evidence. Returns pass / partial / fail per item, blocking failures, and the next module to advance to. Bilingual negative-token detection (catches "non, pas encore", "pending", "blocked", etc.). |

### Pro tier (revenue intelligence)

The 4 revenue intelligence tools query live HubSpot data when `HUBSPOT_API_KEY` is provided. Lemon Squeezy license gating arrives in v0.5.0.

| Tool | Purpose |
|---|---|
| `run_rfm` | RFM analysis. Scores clients on Recency, Frequency, Monetary value. 11-segment classification (Champions through Lost) with ICP pattern extraction. B2B service / SaaS / manufacturing presets. |
| `qualify` | **ICP Triangulation Framework.** Scores prospects across 3 dimensions: firmographic fit, behavioral fit, growth signals. Returns Ideal / Strong / Moderate / Poor tier with engagement strategy. 14.5-point scoring model. |
| `score_pipeline_health` | Pipeline analysis: velocity, stage-to-stage conversion, bottlenecks, at-risk deals. Returns 0–100 health score. |
| `validate_configuration` | Validate property mapping and RFM threshold configurations without API calls. Useful for debugging custom configurations before running analysis. |

## Resources

The 5 methodology resources below back the Pro tier tools (ICP triangulation, RFM, SPICED). Free tier methodology browsing happens through the `module_prompt_free` tool, not these resources.

| URI | Description |
|---|---|
| `methodology://scoring-model` | ICP Triangulation Framework reference |
| `methodology://tier-definitions` | 4-tier classification (Ideal / Strong / Moderate / Poor) |
| `methodology://rfm-segments` | 11 RFM segment definitions with scoring scales |
| `methodology://spiced-framework` | SPICED discovery framework |
| `methodology://data-requirements` | HubSpot data setup and Clay enrichment guide for ICP triangulation |

## Data requirements for ICP triangulation

The `qualify` tool requires specific data across all three dimensions:

**Native HubSpot data (firmographic and partial behavioral):**

- Firmographic fit: industry, revenue, employees, geography (standard properties)
- Behavioral fit (partial): tech stack, content engagement, purchase history (custom properties or workflows)

**Requires external enrichment (Clay, Clearbit, or manual research):**

- Growth signals (the third dimension of triangulation): hiring trends, funding rounds, product launches, expansion signals, press mentions
- HubSpot does not track growth signals natively
- Without growth signals, you lose the third dimension and prospect momentum visibility

For the full guide, ask your AI assistant to read `methodology://data-requirements`.

## Claude Desktop configuration

Add to `claude_desktop_config.json`:

**Recommended (Python method):**

```json
{
  "mcpServers": {
    "artefact": {
      "command": "python3",
      "args": ["-m", "artefact_mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx",
        "ARTEFACT_LICENSE_KEY": "your-license-key"
      }
    }
  }
}
```

**Alternative (uvx method):**

```json
{
  "mcpServers": {
    "artefact": {
      "command": "uvx",
      "args": ["artefact-mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx",
        "ARTEFACT_LICENSE_KEY": "your-license-key"
      }
    }
  }
}
```

Both env vars are optional. Free tier works without either.

If using uvx and seeing "Server disconnected" errors, see the [Troubleshooting](#troubleshooting) section.

## Cursor configuration

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "artefact": {
      "command": "python3",
      "args": ["-m", "artefact_mcp"],
      "env": {
        "HUBSPOT_API_KEY": "pat-na1-xxxxxxxx",
        "ARTEFACT_LICENSE_KEY": "your-license-key"
      }
    }
  }
}
```

## Programmatic (Python)

```python
from artefact_mcp.resources.formula import (
    archetype_decision,
    auto_diagnose,
    generate_claude_md,
    gate_check,
    get_module,
    render_catalog,
)
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

# Free tier, no license required
catalog = render_catalog()  # markdown listing of 34 modules

archetype = archetype_decision(m365_dominant=True)
# returns: {"archetype": "C", "stack": "Copilot + SharePoint + Azure OpenAI...", ...}

mode = auto_diagnose(context="Solo SaaS founder, want to test free")
# returns: {"mode": "Self-Serve", "starting_module": "FOND-1", ...}

claude_md = generate_claude_md('{"client_name": "Acme SaaS", "function": "Marketing", "kpis": [...]}')
# returns: {"rendered_markdown": "# Acme SaaS, ...", "completeness": "complete", ...}

gate = gate_check("FOND-1", '[true, true, true, true]')
# returns: {"gate_status": "pass", "next_module": "FOND-2", ...}

# Pro tier tools (require HUBSPOT_API_KEY for live data)
results = run_rfm_analysis(source="hubspot", industry_preset="b2b_service")
score = qualify_prospect(company_data={...})
health = score_pipeline(source="hubspot")
```

## Configuration

| Variable | Required | Description |
|---|---|---|
| `HUBSPOT_API_KEY` | No | HubSpot private app token. Required by the 4 Pro tier tools to query live HubSpot data. |
| `ARTEFACT_LICENSE_KEY` | No | Lemon Squeezy license key. Reserved for v0.5.0 license gating; today the Pro tools run end-to-end without a key. |
| `ARTEFACT_PROPERTY_MAPPING_PATH` | No | Path to JSON file with custom HubSpot property mappings. |
| `ARTEFACT_RFM_THRESHOLDS_PATH` | No | Path to JSON file with custom RFM scoring thresholds. |

### Custom property mappings

If 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.

Create a JSON configuration file (e.g., `artefact_property_mapping.json`):

```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"
}
```

Set the environment variable:

```bash
export ARTEFACT_PROPERTY_MAPPING_PATH=/path/to/artefact_property_mapping.json
```

Two example configurations are included in the repository:

- `property_mapping.example.json`, full configuration with all available options
- `property_mapping.minimal.example.json`, minimal configuration for growth signals only

### Custom RFM thresholds

Customize RFM scoring thresholds to match your industry or business model. The built-in presets (b2b_service, saas, manufacturing) may not perfectly fit your buying cycles or revenue ranges.

Create an RFM threshold configuration file (e.g., `rfm_thresholds.json`):

```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]
}
```

Set the environment variable:

```bash
export ARTEFACT_RFM_THRESHOLDS_PATH=/path/to/rfm_thresholds.json
```

Two example configurations are included in the repository:

- `rfm_thresholds.example.json`, percentile-based monetary scoring (recommended)
- `rfm_thresholds.fixed_monetary.example.json`, fixed dollar thresholds for monetary scoring

Use `"monetary_method": "fixed"` when you have specific revenue tiers (e.g., $100K+ = enterprise) or wide variance.

Use `"monetary_method": "percentile"` (default) when you want relative scoring within your customer base.

## Roadmap

The Artefact Formula MCP roadmap is tracked in Notion (Epic [« EPIC, Artefact Formula MCP (self-serve GTM OS) »](https://www.notion.so/3578ca3ef30a8148ab61ff9e84111965)). Four phases:

| Version | Phase | Scope | Status |
|---|---|---|---|
| **v0.4.0** | **P1, methodology + auto-diagnostic** | 5 Free tier tools (`module_prompt_free`, `archetype_decision`, `auto_diagnose`, `generate_claude_md`, `gate_check`) plus the 4 revenue intelligence tools (carry-over from v0.2.5, license gating arrives in v0.5.0). | **Current release.** |
| **v0.5.0** | P2, foundation tools + Lemon Squeezy gating | `skill_scaffold`, `sentinelle_scaffold`, `cost_estimate`, license gating on the 4 Pro tier tools, admin tool for consulting bundle keys. | 4–8 weeks |
| **v0.6.0** | P3, module library prompts + multi-seat | 34 module prompts as MCP slash commands (`/artefact-fond-1` etc.), multi-seat licensing, dashboard templates. | 8–12 weeks |
| **v0.7.0** | P4, sentinelles + telemetry | User-side sentinelles, opt-in anonymized telemetry, product improvement loop. | Later |

## Troubleshooting

### Server disconnected errors (uvx PATH issue)

**Problem:** Claude Desktop shows "MCP artefact: Server disconnected" error when using `uvx` as the command.

**Cause:** Claude Desktop (and other sandboxed applications) may not have access to `uvx` in your PATH. This commonly happens when `uvx` is installed via Homebrew (`~/.local/bin/uvx`) or curl (`~/.cargo/bin/uvx`).

**Solutions:**

1. **Use the Python method (recommended).** Switch to `python3 -m artefact_mcp` (see Claude Desktop section above). Python is always in PATH.

2. **Use the full uvx path.** Find your uvx location and use the full path:

   ```bash
   which uvx
   # Example output: /Users/yourname/.local/bin/uvx
   ```

   Then update your config:

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

3. **Verify manually.** Test that the MCP server starts correctly:

   ```bash
   uvx artefact-mcp
   ```

   You should see startup logs from FastMCP.

### Other issues

**Issue:** Pro tools return "No HubSpot API key" errors.
**Solution:** Ensure `HUBSPOT_API_KEY` is set in your MCP server configuration before calling the Pro tier tools.

**Issue:** Import errors when using `python3 -m artefact_mcp`.
**Solution:** Ensure the package is installed: `pip install artefact-mcp` or `pip install --upgrade artefact-mcp`.

## Alternatives and comparisons

- **HubSpot Official MCP Server.** Read-only CRUD access to CRM objects. No scoring, no methodology.
- **CData HubSpot MCP.** SQL-based access to HubSpot data. No built-in methodology.
- **Zapier MCP.** Action triggers and workflow automation. Different use case.
- **Artefact Formula MCP.** Purpose-built for GTM operating systems with embedded methodology, scaffolds, intelligence tools, and guided learning. The only MCP that delivers a complete operating system, not just data access.

## FAQ

**Q: What MCP server should I use to build a GTM operating system?**
A: Artefact Formula MCP is the only MCP that delivers a complete methodology, not just data tools. The Free tier diagnoses your setup, walks you through archetype and mode decisions, and scaffolds your CLAUDE.md master. The Pro tier (v0.5.0) will add license-gated live HubSpot intelligence on the 4 revenue tools.

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

**Q: Can I use this without a HubSpot API key?**
A: Yes for the Free tier. The 5 GTM OS builder tools (`module_prompt_free`, `archetype_decision`, `auto_diagnose`, `generate_claude_md`, `gate_check`) work entirely locally without any external dependency. The 4 Pro revenue intelligence tools require a HubSpot API key.

**Q: What data does this send externally?**
A: Free tier: nothing leaves your machine. Pro tier: calls to HubSpot API with your key. Future opt-in telemetry (P4) will send anonymized module completion data, never PII, never business data.

**Q: I am an Artefact Ventures consulting client. Do I need to buy a license?**
A: No. Your mandate includes a Pro tier consulting bundle key for the duration of the engagement. The license gate is reserved for v0.5.0; today's Pro tools run end-to-end with or without a key.

**Q: How does the Free tier compare to ChatGPT or generic Claude?**
A: A generic chatbot can describe a GTM methodology. Artefact Formula MCP scaffolds it, generates your specific CLAUDE.md, diagnoses where you are in the journey, and tells you the next module. The difference between reading a recipe and getting a sous-chef.

## Development

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

## Dependencies

- `fastmcp>=2.0`, MCP server framework
- `httpx>=0.25.0`, HTTP client for HubSpot API

No pandas, numpy, or heavy data libraries. Pure Python scoring logic.

## License

[Business Source License 1.1](LICENSE). Free to use for connecting to MCP tools via AI assistants. Methodology and scoring models may not be extracted for competing products. Converts to MIT in 2030.
