Skip to main content
Glama

AIGC: Label: "1" ContentProducer: 001191440300708461136T1XGW3 ProduceID: a60f8e46820ea466ef0868a20e79d739_64158b3be5e411f184bd52540072b1e8 ReservedCode1: ADkDg75IRrLxsmT7VnbMUurc8BBlgxLfJaAPJHOg7LWEW+ueKuioY8QFZATuWTNEoJRqsGNUWG3hepfwmbLmL0XuCNH64gdvihEnI1zsBxixRDIeuyfWuZ+sGc9Or4GFJdx0SR/5NygP6xaEPWOnfr1LmPFUBGE20oVc7hSW4hLlshTWaPLYF31SDDQ= ContentPropagator: 001191440300708461136T1XGW3 PropagateID: a60f8e46820ea466ef0868a20e79d739_64158b3be5e411f184bd52540072b1e8 ReservedCode2: ADkDg75IRrLxsmT7VnbMUurc8BBlgxLfJaAPJHOg7LWEW+ueKuioY8QFZATuWTNEoJRqsGNUWG3hepfwmbLmL0XuCNH64gdvihEnI1zsBxixRDIeuyfWuZ+sGc9Or4GFJdx0SR/5NygP6xaEPWOnfr1LmPFUBGE20oVc7hSW4hLlshTWaPLYF31SDDQ=

ghl-automation-engine

HighLevel (GoHighLevel) integration engine for teams that put automations in production and cannot afford them to be quietly wrong.

The GoHighLevel ecosystem already has a 900-tool MCP server. Tool count is not the bottleneck. Reliability is. This project is deliberately narrow: it makes the failure modes visible instead of silent.

Related MCP server: ghl-context-mcp

The four failures this exists to prevent

Failure

What it looks like in production

What this library does

Silent pagination truncation

Page 2 of 5 fails, the caller returns page 1, a downstream workflow treats 100 contacts as "all contacts" and archives the rest

Cursor walking is exhaustive by contract: you get a Collection with an honest complete flag, or a GhlPartialResultError carrying what was collected

Refresh-token stampede

12 concurrent workers see an expired token, all refresh, the provider rotates the refresh token, 11 calls return invalid_grant, the integration hard-fails

Single-flight refresh under a lock with a double-checked expiry, and the rotated token is persisted before the lock is released

PII in logs

A debug line logs the contact upsert body and every email address lands in the log aggregator

Recursive redaction of credentials, emails, and phone numbers before any log record is emitted

Untestable integrations

Every test needs a live sub-account and a private token, so there are no tests

An offline mock server with fault injection; the whole suite runs on a clean machine in seconds

Webhook replays processed twice

A captured delivery is resent, or a platform retry arrives after a partial write, and the contact is created or the invoice is paid twice

Signature + timestamp window + an atomic seen-set; a duplicate returns 200 with process=false, so the sender stops retrying and your code does not run again

Install

git clone <this repo>
cd ghl-automation-engine
python -m pytest

No dependencies. The runtime uses only the standard library, so pytest is the only thing you need, and CI needs no Docker and no network.

Quickstart

from ghl_client import ContactsResource, GhlClient, PrivateIntegrationToken

client = GhlClient(
    PrivateIntegrationToken(token="pit-..."),
    location_id="loc_...",
)

contacts = ContactsResource(client)
result = contacts.search(query="@example.com")

if not result.complete:
    raise SystemExit(f"refusing to act on {len(result)} of an unknown total")

for contact in result.items:
    ...

Idempotent writes:

# Replaying this call does not create a duplicate contact.
contacts.upsert({"email": "jane@example.com"}, idempotency_key="sync-run-2026-11-21")

Webhooks

from ghl_webhooks import Receiver

receiver = Receiver(["whsec_..."])

def handle_delivery(headers, raw_body):
    intake = receiver.handle(headers, raw_body)
    if intake.should_process:
        dispatch(intake.event)      # a real, first-time, verified event
    return intake.http_status, {"status": intake.status.value}

Three things this does that a naive handler does not:

  • Order matters. Nothing is parsed until the signature verifies, and no event id is claimed until every other check has passed — so an attacker cannot burn event ids to block genuine deliveries.

  • Duplicates are visible. A repeat delivery answers 200 with process=false. The sender stops retrying; your application does not re-run. "Received" and "acted on" are different questions and both get an answer.

  • Unknown event types are kept. An unrecognised type is delivered with event.is_known == False and its raw body intact. Silently discarding it is how an integration appears healthy while ingesting nothing.

Signature framing (header names, hex vs base64, what exactly is signed) is configuration rather than a guess, because getting it wrong silently rejects real traffic. See docs/adr/ADR-002-webhook-signature-framing.md for the default assumption and how to confirm it against one captured delivery.

Run the intake demo — no network, no credentials:

python examples/demo_webhooks.py

Governed MCP server

export GHL_PIT_TOKEN=pit-...      export GHL_LOCATION_ID=loc_...
export GHL_MCP_MODE=read-write    # default is read-only
export GHL_MCP_APPROVAL_SECRET=... # required before any write will run
ghl-mcp                            # JSON-RPC over stdio

Five tools: get_contact, search_contacts, upsert_contact, rate_limit_status, server_governance. Scope is narrow on purpose — a tool that returns a plausible empty result is worse than a tool that is absent, so the unimplemented ones are listed with reasons instead of being faked.

The part that matters is the interceptor every call passes through, in this order:

  1. Mode. Read-only unless the operator turned writes on. A refusal is read_only_mode, never a 200 with an empty body.

  2. Schema. Unknown properties are rejected, so there is no locationId to argue about — cross-account access is not a policy, it is a shape that does not exist.

  3. Location. The server is bound to one sub-account; an unbound client gets cross_location rather than a default location.

  4. Approval. A write needs a single-use, short-lived token issued for that tool and those exact arguments. A token for one contact cannot be spent on another.

  5. Budget. Session ceilings stop a loop before the platform rate limiter or the invoice does.

# the human approves one specific change
ghl-mcp approve --tool upsert_contact \
  --args '{"email":"ada@example.com","first_name":"Ada"}'

upsert_contact also takes dry_run: true, which returns the payload it would send and touches nothing. server_governance reports the active policy, the PII allowlist, and the blocked-tool list. Without GHL_PIT_TOKEN the server exits 2 and says why, instead of starting up to answer 401s that an agent would narrate as "no contacts found".

Full detail: docs/MCP.md.

Offline development

python -m ghl_mock --port 8080
python examples/demo_offline.py     # full round trip against the mock

The mock can be told to fail on purpose, which is the point:

curl -X POST localhost:8080/__admin/inject \
  -H 'content-type: application/json' \
  -d '{"path": "/contacts/search", "status": 429, "times": 1, "retry_after": "2"}'

Architecture

src/ghl_client/
  errors.py       typed hierarchy; retryable is a property of the error, not the caller
  ratelimit.py    sliding-window budget, 90 req / 10 s (platform allows 100)
  retry.py        Retry-After (seconds and HTTP-date), capped at 120 s, full jitter
  transport.py    the only module that touches a socket; injectable
  auth.py         private tokens + OAuth with single-flight refresh and persistence
  pagination.py   exhaustive cursor walking with loop detection
  client.py       versioning, budgeting, redaction, request ids
  resources/      contacts (search, idempotent upsert)
src/ghl_mock/
  store.py        in-memory contacts with email/phone dedupe and cursor paging
  app.py          stdlib HTTP server + fault injection admin endpoints
src/ghl_mcp/
  server.py       JSON-RPC over stdio; call_tool is the only path to a handler
  governance.py   mode, approval tokens bound to arguments, session budget, location guard
  tools.py        five tools, each declaring scope, risk, endpoint and dry-run support
  registry.py     tool specs; carries requires_location per tool
  schema.py       strict JSON Schema subset: unknown keywords raise instead of being ignored
  projection.py   PII allowlist and field truncation for anything a model will read
  audit.py        one JSON line per call: digests, decision, duration — never the arguments
src/ghl_webhooks/
  signature.py    HMAC verification; header/encoding/prefix/signed-payload are configuration
  replay.py       timestamp window + atomic seen-set behind a one-method store protocol
  events.py       event parsing that preserves unknown types instead of dropping them
  receiver.py     ordered intake: size -> signature -> timestamp -> parse -> claim
src/ghl_attribution/
  mapping.py      required field keys, live id binding, drift as a startup error
  events.py       webhook body -> touch; "no campaign signal" is a first-class answer
  policy.py       which fields may be written: blanks + activity time, credit preserved
  ledger.py       event claim store (in-process default, protocol for a durable one)
  engine.py       discovery -> claim -> compare -> upsert; dry run returns the delta

Design decisions worth defending:

  • Mock before client. The contract is written down as executable mock behaviour first, so the client is developed against a specification rather than against whatever the live API happened to return at 3 a.m.

  • Errors carry context. Status, method, path, request id, and location id are attached at the point of failure, so a support ticket does not need a repro.

  • No dependency on the platform's SDK. The SDK pulls its own HTTP stack and its own opinions about retries; both would fight with the retry and budget logic above.

  • A dropped connection is a dataset, not a surprise. urllib wraps neither ECONNRESET nor Windows' WSAECONNABORTED, so the transport types them itself: every socket-level failure becomes a retryable GhlTransportError instead of a bare OSError that a calling workflow has no reason to handle.

Attribution engine

The server is only half of it: leads arrive from forms, quizzes, and landing pages, and the reason to send them to GoHighLevel is attribution. ghl_attribution does that without the two failure modes that make attribution worthless — a lead re-credited on every later visit, and one lead in the CRM three times over.

from ghl_attribution import AttributionEngine

engine = AttributionEngine(client)                 # resolves custom field ids at startup
result = engine.ingest({                            # webhook body, verbatim
    "event_id": "evt-9f2",
    "email": "lead@example.com",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring",
    "occurred_at": "2026-11-20T10:00:00Z",
})
result.status        # IngestStatus.APPLIED
result.applied       # ("utm_source", "utm_medium", "utm_campaign", "first_touch_at", "last_touch_at")
  • Credit is append-only. A later touch from another source advances last_touch_at and nothing else. utm_source=direct from a returning lead cannot erase the campaign that paid for them.

  • Two idempotency layers. The event claim stops a redelivered webhook, the client's upsert ledger stops a duplicate contact after a failed retry, and the claim is released on failure so a retry is the same operation.

  • Refuses to start on schema drift. Missing, retyped, or duplicated custom fields raise AttributionMappingError with every problem listed — before the first write, not after the reports break.

  • dry_run=True returns the exact field payload without writing.

Full detail, including the required field keys: docs/ATTRIBUTION.md.

A worked case runs offline — seven relay deliveries (two of them redeliveries), a later touch, a direct revisit, a dry run, and a mid-flight schema drift:

python examples/case_lead_attribution.py

It ends with two contacts, the paid-search credit intact, and the drift refused before the first write. Write-up: docs/CASE-STUDY-ATTRIBUTION.md — figures that need a real deployment are marked TBD, not guessed.

Status

Built and tested:

  • typed errors, sliding-window rate budget, retry with Retry-After

  • OAuth single-flight refresh with file persistence

  • exhaustive cursor pagination with partial-result signalling

  • contacts search and idempotent upsert

  • offline mock server with fault injection (429 / 5xx / auth rejection)

  • webhook intake: HMAC verification, timestamp window, replay seen-set, unknown-type preservation

  • governed MCP server: read-only default, argument-bound single-use approvals, dry_run, location guard, session budget, digest-only audit log, blocked tools declared not faked

  • attribution engine: append-only first-touch credit, event claim + upsert ledger, custom-field discovery with drift refusal, dry-run plans

  • attribution case study: reproducible demo + page, invariants pinned by tests

  • 198 tests, no network, no credentials

Not built yet, on purpose — in this order:

  1. live smoke tests behind an opt-in environment flag

  2. durable replay store adapter (Redis/Postgres) beyond the in-process default

  3. multi-touch weighting (first touch is the only model implemented today)

License

MIT. See LICENSE. (内容由AI生成,仅供参考)

Available Tools

5 tools
get_contactA
Read-onlyIdempotent

Fetch one contact by id. Returns allowlisted fields only.

Inputs: contact_id (required).

rate_limit_statusA
Read-onlyIdempotent

Remaining request budget in the client's local sliding window. No network call.

Inputs: no named parameters.

search_contactsA
Read-onlyIdempotent

Search contacts in the bound sub-account. Paginates every cursor and reports complete=false when a limit stopped the walk. Returns allowlisted fields only.

Inputs: limit, query.

server_governanceA
Read-onlyIdempotent

This server's own policy: mode, approval requirement, PII allowlist, and the tools that are deliberately not implemented.

Inputs: no named parameters.

upsert_contactA
Idempotent

Create or update a contact, deduplicated on email/phone. Idempotent on replay. Pass dry_run=true to preview the change without writing.

Inputs: tags, email, phone, dry_run, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation4/5

    The three contact tools (search_contacts, get_contact, upsert_contact) have crisp, non-overlapping boundaries. The two meta tools, server_governance and rate_limit_status, are both 'server self-info' and could be momentarily confused, but their descriptions clearly separate policy from budget.

    Naming Consistency4/5

    All names use snake_case, and the contact tools follow a clean verb_noun pattern (search/get/upsert_contact). server_governance and rate_limit_status break the verb_noun pattern as noun phrases, a minor deviation that is still readable.

    Tool Count4/5

    Five tools is well within a sensible scope for a narrowly bound contact sub-account server. Two of the five are diagnostic/meta rather than domain operations, making the functional surface slightly thin.

    Completeness3/5

    Create/update, single fetch, and search are covered, but there is no delete/archive operation and no way to list or filter beyond cursor pagination (e.g. by tag or owner). Agents will hit a dead end if a contact must be removed or bulk-managed.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to pull focused GoHighLevel context before talking to a contact, including contact lookup, timeline summaries, pipeline positions, and appointments, with optional guarded writes. It helps agents brief themselves on a person without exposing raw CRM API noise.
      6 npm
      MIT
    • F
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to operate GoHighLevel agencies through the official v2 API, managing contacts, deals, conversations, appointments, tags, custom fields, workflows, and pipeline reports with bulk operations and fail-closed security.
      12
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables governed access to a canonical Customer Graph across CRM and customer-service records, with per-field provenance, propose-only identity merges, field-level masking, records-only reply drafting, tiered policy and kill-switch enforcement, and hash-chained receipts for auditable reads and internal writes.
      9
      MIT