GHL MCP Server
---
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.
## 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
```bash
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
```python
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:
```python
# Replaying this call does not create a duplicate contact.
contacts.upsert({"email": "jane@example.com"}, idempotency_key="sync-run-2026-11-21")
```
## Webhooks
```python
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:
```bash
python examples/demo_webhooks.py
```
## Governed MCP server
```bash
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.
```bash
# 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`](docs/MCP.md).
## Offline development
```bash
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:
```bash
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.
```python
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](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:
```bash
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](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](LICENSE).
*(内容由AI生成,仅供参考)*
TDQS
Scored across 5 tools
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.
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.
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.
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.