NECTARIN Intelligence MCP Server
by alxvasilevvv
README.md
# NECTARIN Intelligence — remote MCP on Cloudflare Workers
[](https://unyly.org/ru/mcp/nectarin-intelligence-worker)
> **Install with Unyly** opens the live listing
> (`https://unyly.org/ru/mcp/nectarin-intelligence-worker`) — one‑click connect for
> **Cursor, VS Code, Claude Code, Claude Desktop, claude.ai and ChatGPT**. You can also
> add it manually as a custom connector with the `/mcp` URL — works in **Claude** and
> **ChatGPT** (Settings → Connectors). See [USAGE.md](USAGE.md#1-connect).
A **production** remote [Model Context Protocol](https://modelcontextprotocol.io)
server for **NECTARIN Intelligence** — an orchestrator-worker AI marketing agent
for the RU/CIS market. It runs entirely on a single Cloudflare Worker, serves MCP
over **Streamable HTTP (JSON-RPC 2.0)** with an **opt-in SSE** transport, ships
with **mock/synthetic RU data** plus **KV real-data layering**, and a
**KV-cached, model-agnostic LLM narrative** (DeepSeek wired in this deploy).
> **New in 2.52 — MCP federation through Unyly:** NECTARIN is now the marketing **hub**
> that the best specialist external MCPs plug into — always via Unyly. `mcp_federation`
> discovers complementary servers (live keyword data, web analytics, ad-platform pulls,
> creative generation, social listening, CRM, marketplace data, localization), routes by
> capability/goal/role, and returns **tracked Unyly connect links** so all installs &
> consumption flow through unyly.org. `federation_invoke` proxies an external MCP tool call at
> runtime (fail-closed until the server is connected via Unyly). v2.54 widens role coverage with a
> CMO maturity scorecard, a martech-stack rationalizer and Van Westendorp pricing research.
> v2.55 adds a B2B & CX group (ABM account scoring, NPS analysis, B2B pipeline velocity).
> v2.56 adds an Ops & Autonomy group — a cross-KPI alert engine (anomaly → action → the tool to
> run next) and a CMO function-level budget allocator — plus B2B win/loss analysis.
> v2.57 deepens autonomy with `autonomous_plan` (breaches/goal → an ordered diagnose→act→measure
> plan that chains tools, with owners & expected impact) and adds a Marketing Ops & Leadership
> group — a marketing OKR planner and a content-team capacity/throughput planner.
> v2.58 adds a Foresight & Strategy group — `demand_forecast` (Holt linear-trend forecast + optional
> multiplicative seasonality + confidence band), `customer_journey_map` (lifecycle → channels/content/KPI
> with conversion & gap analysis) and `competitive_positioning_map` (2-axis perceptual map + white-space).
> v2.59 adds a Market & Revenue Science group — `marketing_roi_waterfall` (period-over-period revenue/ROAS
> bridge decomposing the change into volume/efficiency/AOV drivers), `conjoint_analysis` (part-worth
> utilities → attribute importance, share-of-preference logit & willingness-to-pay) and `tam_sam_som`
> (top-down/bottom-up market-sizing funnel with a reality check & CAGR projection).
> v2.64 lands the **real-data pilot (Phase D)**: one documented, versioned tenant-metrics
> KV schema (`src/tenantdata.ts`) that existing models read via an opt-in `useTenantData:true`
> flag — `kpi_alert_engine` pulls current KPI values/targets and `funnel_model` derives real
> conversion rates + AOV. Strictly non-breaking: inert unless mode=`kv` + a blob exists; prod
> (authless/mock) is byte-identical and returns a graceful "configure tenant data" note.
> v2.61 deepens **autonomy (Phase D)**: `benchmark_kpi_check` (KPI vs RU/CIS bands),
> `alert_to_skill` (breaches → marketing_skill playbook + first tool), plus launch tools
> `brand_health_index` and `gtm_launch_readiness`, and a **tenant data scaffold**
> (`tenant_metrics_snapshot`, KV key `tenant:<id>:metrics`, mode via `NECTARIN_TENANT_DATA_MODE`).
> v2.60 wires the **live Unyly federation gateway**: set `UNYLY_GATEWAY_TOKEN` (self-issued in the
> Unyly dashboard) and `federation_invoke` proxies any registered server at
> `gateway.unyly.org/mcp/<slug>` — one token, no per-server URL config. Per-server `FED_<KEY>_URL`
> overrides still work.
> v2.65 ships the **autonomy loop (Phase D)** — `autonomous_execute`, a GUARDED runner that
> moves alert→action→measure from planning to safe execution: **dry-run by default** (zero
> side effects, deterministic), **execute only** with `confirm:true`+`approvalToken` and **team+**
> gating, WRITE/external steps routed **only** through the fail-closed Unyly federation
> (`federation_invoke`) — no gateway token ⇒ no network, degrade to "connect via Unyly" — and a
> per-step **audit trail** (simulated | executed | skipped | blocked). No recursive local
> tool fan-out. `board_report` gains an opt-in `useTenantData:true` (real spend/revenue/ROAS from KV).
> v2.66 adds a **Design & Creative Ops** group of deterministic design-SPEC tools (NOT image
> generation): `design_system_spec` (brand → HSL-wheel palette + modular type scale + spacing/
> radius/elevation tokens + WCAG contrast check, pro+), `banner_layout_spec` (per-format RU banner
> specs — canonical sizes, layout zones, text limits, font floors for vk/yandex/telegram/ok/web) and
> `ad_spec_checker` (RU ad-law linter — ORD/ЕРИР, ratio, text-over-image, weight, CTA, regulated
> legal gate). **Actual image/asset rendering is delegated to a federated creative-generation MCP via
> Unyly** (`mcp_federation` → `creative_gen`) — NECTARIN produces the spec, the federated MCP renders.
> v2.67 widens **profession coverage 22 → 26** with a **Profession-Breadth** group of deterministic,
> methodology-grounded role planners: `programmatic_trading_plan` (DSP/programmatic trader — deal-type
> mix PMP/open/PG, bid strategy, pacing, expected impressions/reach and viewability-adjusted effective
> CPM, pro+), `marketplace_seo_plan` (WB/Ozon/Yandex Market listing SEO — listing-optimization score,
> keyword→slot mapping, ranking checklist, projected organic-visibility uplift), `lifecycle_flow_planner`
> (lifecycle/CRM automation — triggered cross-channel flow blueprint with stage timing, per-step
> conversion and revenue) and `plg_activation_model` (PLG/SaaS — signup→activated→retained activation
> funnel with levers and projected MRR, pro+). New router roles: **programmatic trader**, **marketplace
> listing specialist**, **lifecycle/automation** and **PLG growth**.
> **110 tools / 85 prompts.**
> **New in 2.51 — skills & growth science:** an extensible **playbook layer**
> (`marketing_skill`) chains tools into 10 repeatable end-to-end workflows (cut CAC,
> retention boost, launch, measurement setup…), plus two growth models —
> `cohort_retention_curve` (power-law fit + LTV) and `viral_loop` (k-factor + referral
> economics). **77 tools / 54 prompts.**
> **New in 2.50 — consumption transparency:** `tools/call` now returns **quota headers**
> (`X-Plan`, `X-Quota-Limit/Used/Remaining/Period`) so clients see their allowance inline, plus
> a visual **`GET /dashboard`** HTML page over `/usage`. See **[ROADMAP.md](./ROADMAP.md)** for
> the global plan (Marketing-OS, phases A–D, MCP federation via Unyly).
> **New in 2.49 — metered free tier + usage dashboard:** a per-tenant **monthly quota**
> (free = 100 calls/mo; paid tiers unlimited) creates the concrete free→paid upsell, and a
> read-only **`GET /usage`** endpoint reports `{used, quota, remaining, plan}` per tenant for
> Unyly / an internal dashboard. Owner/claimless tokens stay unlimited (authless deploy
> unaffected).
> **New in 2.48 — monetization seam:** the Unyly access tiers are now **real**. A small set
> of flagship tools (`strategy_orchestrate`, `mmm_optimize`, `incrementality_meta`,
> `geo_holdout`, `competitive_response`, `report_export` → **pro**; `board_report` → **team**)
> require a minimum plan, read from the token's `plan` claim (issued by Unyly Connect);
> below-tier calls return an upgrade CTA with a tracked Unyly link. Every `tools/call` emits a
> structured **usage** event (the billing seam Unyly aggregates), and with
> `UNYLY_ATTRIBUTION=1` successful outputs carry a tracked "install via Unyly" footer.
> Non-breaking: claimless tokens get full access, so the authless deploy is unchanged.
> **New in 2.47 — distribution through Unyly:** `connect_via_unyly` makes the connector
> self-distribute — every install/onboarding/upgrade returns a **tracked Unyly link**
> (UTM-attributed) so consumption, requests and installs all flow through the single
> Unyly front door (the metering & governance point).
> **New in 2.46 — profession coverage:** **74 tools across 22 marketing professions**,
> with a **role router** (`role_playbook`) that maps any specialist's job — SEO, PPC,
> SMM, CRM, brand, PR, media planning, analytics, e-commerce, mobile/ASO, content,
> events, affiliate, creative, pricing, compliance, agency, marketing ops, CMO — to a
> tailored toolkit, workflow and KPIs. One connector for the whole team; **install and
> access flow through a single [Unyly](https://unyly.org/ru/mcp/nectarin-intelligence-worker) front door** (Unyly Connect fronts OAuth 2.1).
> **New in 2.0:** KV LLM response cache (cold 9.8s → warm 0.2s on prod),
> `LayeredKvDataSource` for operator-uploaded real benchmarks, opt-in SSE, and
> richer `/health` + `/version` observability. See **[USAGE.md](./USAGE.md)** for
> the connection guide, full tool catalogue, recommended flows, and a ready-to-paste
> Claude system prompt.
Go live with `npx wrangler deploy` using your own Cloudflare token.
> All figures are **MOCK / synthetic**, plausible for RU/CIS in RUB. Not legal advice.
> To serve real data, upload it to KV (`benchmarks:<category>`, `playbook:<industry>`,
> `suppliers`) — `LayeredKvDataSource` overrides mock per-key (see [USAGE.md](./USAGE.md)).
---
## What's inside
- **`src/index.ts`** — the Worker. A small, spec-compliant JSON-RPC 2.0 MCP handler
(no `@modelcontextprotocol/sdk` dependency — the SDK's transports target Node's
`http`/streams, which don't exist on Workers, so a hand-rolled handler is cleaner
and dependency-free). Implements `initialize`, `tools/list`, `tools/call`,
`prompts/list`, `prompts/get`, `resources/list`, `resources/read`,
`completion/complete`, `ping`, and the `notifications/*` no-ops, with proper
JSON-RPC results/errors.
- **`src/tools.ts`** — the tool registry. It composes three groups: the 11
**Intelligence** tools (incl. the flagship `strategy_orchestrate` and the
`budget_optimizer`), the 6 **Growth & Automation** tools, and the 3 **Premium
Analytics** tools (see the tables below), each with a JSON-Schema `inputSchema`
+ async handler. The Premium Analytics group now has **11** tools.
- **`src/growth.ts`** — the 6 **Growth & Automation** tools (the funnel layer):
`roi_calculator`, `lead_qualify`, `request_nectarin_proposal`,
`book_consultation`, `automation_recipe`, `value_forecast`. Deterministic,
synthetic logic anchored to the same mock benchmarks; **no PII is sent and no
real network call is made** (proposal/booking are clearly-marked stubs).
- **`src/analytics.ts`** — the 10 **Premium Analytics** tools: `compliance_check`
(RU ad-law copy review, ФЗ-38/ОРД, optional LLM rewrite), `ab_test_planner`
(real two-proportion power analysis with inverse-normal z + Bonferroni),
`unit_economics` (LTV/CAC/payback/ROAS + verdict), `funnel_model` (full-funnel
scenarios + biggest leak), `seasonality_forecast` (12-month demand index),
`creative_score` (best-practice copy scoring), `attribution_model` (5-model
multi-touch attribution), `bid_simulator` (auction bid/win-rate curve),
`report_export` (strategy → deck/one-pager) and `localize` (RU/EN/KZ/UZ).
Deterministic and auditable.
- **`src/orchestrator.ts`** — the planner → workers (dataRetriever, analyst,
strategist, copywriter, compliance) → synthesizer pipeline. `media_plan` math is
real: `impressions = spend / CPM × 1000`, `clicks = impressions × CTR`,
`conversions = spend / CPA`, plus estimated reach and blended CPA. The flagship
**`strategy_orchestrate`** fans out to every worker in one call (benchmarks +
audience + competitors + plan/forecast + optimized split + creative + compliance
+ ROI + executive summary). **`budget_optimizer`** solves the conversion-maximizing
channel split (water-fill by CPA under a per-channel cap). The `callLLM()` seam is
**real-or-stub**: it calls Anthropic/OpenAI when `LLM_API_KEY` is set and falls
back to a deterministic stub otherwise (and on any model error), so the pipeline
never breaks.
- **`src/data.ts`** — synthetic benchmarks / suppliers / playbooks + seasonality
behind a `DataSource` interface (default `MockDataSource`;
`KvDataSource`/`HttpDataSource` stubs included). Coverage: **8 categories**
(realty, finance, auto, retail, fmcg, pharma, ecom, edtech) × **5 platforms**
(VK Ads, Yandex Direct, Telegram Ads, OLV, Avito), with a `provenance` block on
every benchmark response. See **`DATA_SCHEMA.md`** for the exact data NECTARIN
must supply.
- **`src/auth.ts`** — **real OAuth 2.1 bearer verification** via `jose`
(`createRemoteJWKSet` + `jwtVerify`) against a JWKS URL — validates signature,
issuer, audience, expiry. In production **Unyly Connect** fronts OAuth 2.1
(DCR + PKCE); this resource server only validates the token. `DEV_BYPASS=1`
disables the check for local/dev.
- **`src/ratelimit.ts`** — per-token/IP token-bucket rate limiter
(`RATE_LIMIT_PER_MIN`, default 60), with KV/Durable-Object hooks for production.
- **`src/validate.ts`** — per-tool JSON-Schema input validation (`-32602`).
### HTTP routes
| Method | Path | Purpose |
|---|---|---|
| POST | `/mcp` | JSON-RPC 2.0 MCP endpoint (auth + rate limit) |
| GET | `/.well-known/oauth-protected-resource` | OAuth discovery |
| GET | `/health` | Liveness probe |
| GET | `/version` | name + version + toolCount + commit + authMode |
| GET | `/usage` | per-tenant monthly usage `{used, quota, remaining, plan}` (auth like `/mcp`) |
| GET | `/dashboard` | HTML usage dashboard (reads `/usage` same-origin) |
| GET | `/` | Friendly index (endpoint URLs) |
### JSON-RPC error codes
`-32700` parse · `-32600` invalid request · `-32601` unknown method/tool ·
`-32602` invalid params (schema validation) · `-32603` internal (safe message) ·
`-32029` rate limited (HTTP 429). A 401 carries `WWW-Authenticate` with the
`resource_metadata` discovery pointer.
---
## Tools (110 total)
### Intelligence group (inform + orchestrate)
| Tool | What it does |
|---|---|
| `strategy_orchestrate` | **Flagship.** One call → full go-to-market strategy: benchmarks + audience + competitors + media plan/forecast + optimized split + creative concept + compliance + ROI + executive summary. |
| `budget_optimizer` | Conversion-maximizing budget split (water-fill by CPA under a per-channel cap) + uplift vs. the goal preset. |
| `ru_benchmarks` | CPM/CTR/CPA/VTR percentiles for a category × KPI (× platform). |
| `supplier_quality` | Inventory quality index, fraud risk, recommended/avoid suppliers. |
| `media_plan` | RUB budget split + real forecast (impr/clicks/conv/reach/blended CPA). |
| `category_playbook` | Territories, do's & don'ts, seasonal hooks, compliance gate. |
| `audience_insights` | Segments, JTBD, media affinities for a category. |
| `competitor_scan` | Likely competitors, activity, channels, owned territory. |
| `geo_aeo_audit` | Brand visibility inside AI answer engines + RU search. |
| `creative_brief` | Objective, proposition, mandatories + 3 concept territories. |
| `report_explain` | Plain-language report read, anomalies, prioritized fixes. |
### Growth & Automation group (convert + automate) — drives the funnel
These tools turn the agent from an advisor into a revenue engine. Together they
walk a marketer down the funnel: **acquire marketers → qualify → proposal →
managed services**, and frame NECTARIN as automation, not just advice.
| Tool | What it does | Funnel stage |
|---|---|---|
| `roi_calculator` | Projects CPA improvement, extra conversions & est. annual value from the mock benchmarks (method shown). | Acquire / show value |
| `value_forecast` | 3-scenario (conservative/base/ambitious) reach + efficiency + savings projection, assumptions stated. | Acquire / show value |
| `lead_qualify` | 0-100 fit score + recommended tier (self-serve / managed / enterprise retainer) via budget thresholds + signals. | Qualify |
| `request_nectarin_proposal` | Structured RFP/brief + **clearly-stubbed** submission reference. **Sends nothing** (no CRM/webhook/email); privacy note included. | Proposal |
| `book_consultation` | Scheduling CTA with a booking URL from `NECTARIN_BOOKING_URL` + a "what to prepare" checklist. | Proposal → close |
| `automation_recipe` | Concrete multi-agent workflow (steps, internal tools, cadence, est. time saved) NECTARIN runs as a managed service. | Managed services |
### Premium Analytics group (operate at a senior level)
These make the agent a senior operator: a RU ad-law reviewer, an experimentation
lead, and a unit-economics analyst. All math is deterministic and auditable.
| Tool | What it does |
|---|---|
| `compliance_check` | RU ad-law review of copy → 0-100 score + flagged risks (severity, **ФЗ-38** article, fix): superlatives/ФАС, comparative claims, finance (ПСК, guaranteed returns), pharma warning, alcohol/tobacco/gambling, **ОРД/ЕРИР** marking. Optional LLM rewrite. Not legal advice. |
| `ab_test_planner` | Two-proportion **power analysis**: sample size/variant, total, duration; exact z via inverse-normal (Acklam) + Bonferroni for multi-variant; guardrails. |
| `unit_economics` | LTV / LTV:CAC / payback / ROAS / contribution; CAC from spend÷customers, lifespan from churn; health verdict + levers. |
| `funnel_model` | Full-funnel projection (impressions→reach→clicks→leads→qualified→sales→revenue) with conservative/base/optimistic scenarios, per-stage drop-off, CAC/ROAS, and the **biggest leak**. |
| `seasonality_forecast` | 12-month RU/CIS demand index per category, peak/trough months, monthly budget weighting + optional annual-budget split. |
| `creative_score` | 0-100 best-practice score for ad copy (value prop, specificity, CTA, length, benefit-focus, no-CAPS) + fixes, compliance flag, optional LLM variants. |
| `attribution_model` | Multi-touch attribution over conversion paths (first/last/linear/position-based/time-decay) + which channels last-touch under/over-values. |
| `bid_simulator` | Auction bid/win-rate trade-off curve from benchmark CPC/conv-rate; recommends a bid for a target CPA or max conversions under a daily budget. |
| `report_export` | Turns a strategy/analysis into a deck — slides (title+bullets+notes), full Markdown deck and a one-pager. Composable after `strategy_orchestrate`. |
| `localize` | Translate + culturally adapt copy into RU/EN/KZ/UZ for CIS markets (LLM-backed, graceful fallback). |
| `creative_testing_matrix` | **Multi-variant test RESULTS analyzer** (the read side of `ab_test_planner`). From ≥2 arms with observed visitors+conversions, picks a control, then per arm computes CR, absolute & relative lift, a pooled **two-proportion z-test** (z, p) and significance under a **multiple-comparison-corrected α** (Bonferroni/Šidák). For non-significant arms it estimates the **additional sample** needed at target power, declares **WINNER / LOSER / KEEP TESTING / INSUFFICIENT DATA** per arm, and gives a roll-out recommendation. |
### Premium group (v2.1+ — generate, monitor, project, operate)
| Tool | What it does |
|---|---|
| `creative_variants` | Generate **and** score N ready-to-test ad variants (LLM-backed + KV-cached; deterministic template fallback). Each variant gets the `creative_score` heuristic + a compliance flag, ranked best-first. Pairs with `ab_test_planner`. |
| `anomaly_detector` | Robust median/MAD z-score anomaly detection over a metric time series (CPA/CTR/spend…) for always-on monitoring; flags per-point severity/direction and whether the latest point is anomalous. Std fallback for low-variance series. |
| `cohort_ltv` | Retention-curve cohort LTV/NPV projection (explicit curve OR churn%+periods), per-period survivors/revenue, LTV:CAC, payback period. Complements `unit_economics`. |
| `utm_builder` | Build a consistent, validated UTM tracking URL — normalizes tokens (lower/snake/kebab/preserve), URL-encodes, preserves existing query, warns on uppercase/spaces/non-ASCII, suggests a naming convention. |
| `pacing_monitor` | Budget pacing vs. an even spend curve: expected spend, pace ratio, status (under/on-track/over), projected end spend, recommended daily spend to land on budget. |
| `response_curve` | Channel saturation / diminishing-returns modeling. Fits `conversions = a·spend^b` to your current per-channel spend & conversions, then computes the conversion-maximizing budget split (closed form `share ∝ a^(1/(1-b))`) + projected conversions, per-channel marginal CPA, blended-CPA improvement and uplift vs. current. |
| `budget_pacing_forecast` | **Trend-aware** end-of-flight forecast. Projects landing spend from the **recent daily run-rate** (not just a flat average), the over/under-spend variance %, the **days to exhaust** the budget, and the recommended daily rate (and % adjustment) to land on budget; optional CPA pace. Complements `pacing_monitor` (linear). |
| `utm_taxonomy_qa` | **Batch UTM / taxonomy governance auditor.** Parses a list of tagged URLs (or raw query strings), checks each for missing required params, uppercase, spaces and non-ASCII, then aggregates a **0–100 consistency score** + grade, **near-duplicate value variants** per parameter (e.g. `facebook`/`Facebook`/`fb`), values outside an optional source/medium allow-list, and concrete fixes. Complements `utm_builder` (builds ONE link). |
### MMM group (v2.12+ — marketing mix modeling)
| Tool | What it does |
|---|---|
| `mmm_optimize` | **Marketing Mix Model (MMM-lite).** From each channel's spend & conversions **time series**, fits **adstock/carryover** (geometric decay λ, grid-searched by R²) and **saturation** (`conversions = a·adstock(spend)^b`, 0<b≤1), then computes the conversion-maximizing **steady-state** budget split via exact Lagrange bisection (marginal CPA equalized). Returns decay, carryover half-life, elasticity, fit R²/confidence, recommended spend, projected conversions, marginal CPA and uplift. |
### Planning group (v2.14+ — roadmap & scenarios)
| Tool | What it does |
|---|---|
| `gtm_calendar` | **Phased go-to-market roadmap.** Splits the horizon into **Test → Scale → Optimize** phases with goal-driven budget weights and channel emphasis, then builds a **week-by-week budget pacing curve** that leans spend into high-demand weeks using the category's monthly **seasonality index**. Returns per-phase objectives, KPIs and exit criteria, peak/soft **seasonal windows** inside the horizon, and milestones. Answers *when & in what sequence* (pairs with `media_plan`/`budget_optimizer` for *where*). Deterministic. |
| `scenario_planner` *(v2.16+)* | **What-if budget scenario comparator.** Takes current per-channel spend & conversions plus named scenarios (conservative / base / aggressive via a `budgetMultiplier` and/or absolute spend overrides) and projects each plan's conversions, blended CPA, incremental lift vs. today and — with `revenuePerConversion` — revenue, profit, ROAS & ROI%. Each channel uses a constant-elasticity diminishing-returns curve `conversions=conv₀·(spend/spend₀)^b` calibrated to its own current point. **Ranks** scenarios by objective (`max_conversions`/`min_cpa`/`max_roi`) and recommends one with a rationale + elasticity-sensitivity note. Compares *your* candidate plans head-to-head (vs `mmm_optimize`'s fitted optimum). Deterministic. |
### Pricing & Promo group (v2.17+ — discount economics)
| Tool | What it does |
|---|---|
| `promo_planner` | **Promo / discount P&L & break-even.** From regular price, variable unit cost and baseline period volume, computes the post-discount unit margin, the **break-even volume uplift** a promo must clear to avoid losing money, and — with an `expectedUpliftPct` — projected units/revenue/profit, **incremental profit** vs. baseline and **ROI on the markdown**. Supports an optional fixed promo cost and a pull-forward/cannibalization penalty. Returns a verdict (profitable / needs more uplift / margin-destroying). Deterministic trade-marketing math on your numbers. |
| `price_optimizer` | **Profit-maximizing price finder.** From ≥2 historical (price, units) points, fits a constant-elasticity demand curve `Q = a·P^(-e)` by log-log least squares, estimates the **price elasticity of demand**, and — when demand is elastic (e>1) — computes the profit-max price `P* = cost·e/(e−1)` with projected units/revenue/profit and the **uplift vs. current price**. Flags inelastic demand (no interior optimum) and low-confidence fits. Deterministic; complements `promo_planner`. |
### Audit group (v2.15+ — account health diagnostic)
| Tool | What it does |
|---|---|
| `marketing_audit` | **Senior account health audit.** Takes current per-channel spend & conversions, scores each channel's CPA against RU/CIS benchmarks (p25/p50/p75), flags **concentration risk** and **untracked** spend, computes an overall **health score (0-100) + grade A–D**, and returns a **prioritized action plan** with a concrete budget reallocation and projected extra conversions / saved spend. Optional `targetCpa` vs blended CPA. Deterministic; data-aware (KV / per-tenant). |
| `landing_cro_audit` | **Heuristic landing-page CRO audit.** Scores up to seven UX/performance dimensions you provide — page speed, bounce, mobile parity, form friction, CTA clarity, trust/social proof, CR vs benchmark — into a weighted **0-100 CRO score + grade**, returns a **prioritized issue list** (weight × gap) with concrete fixes, and a **projected CR uplift** (multiplicative, diminishing returns) that, given `monthlyVisitors` + `aov`, becomes incremental conversions & revenue. Validate with `ab_test_planner` → `creative_testing_matrix`. |
### Executive group (v2.18+ — board one-pager)
| Tool | What it does |
|---|---|
| `board_report` | **Executive one-pager (orchestrator).** Composes `marketing_audit` (health score, channel verdicts, risks, prioritized actions) + `scenario_planner` (a **+15% budget upside** scenario) into a board-ready brief: status + grade, headline metrics (spend, conversions, blended CPA, and **revenue/profit/ROI** with `revenuePerConversion`), best/worst channel, live risks, top recommendations, the budget upside and a single **next step**. Reuses the deterministic sub-tools verbatim — stays consistent with them. |
### Creative Ops group (v2.19+ — burnout detection & rotation)
| Tool | What it does |
|---|---|
| `creative_fatigue` | **Creative burnout detector.** From each creative's daily CTR series (`ctr[]` in %, or `impressions[]`+`clicks[]`), finds peak CTR, **decline from peak**, the recent least-squares trend, a 0–100 **fatigue score** + stage (fresh/maturing/fatigued/burnt), and — while CTR is still falling — the estimated **days until it crosses the refresh threshold** (default 70% of peak). Ranks creatives worst-first and recommends which to refresh now / prepare / monitor. Deterministic. |
| `creative_rotation` | **Creative rotation optimizer.** From a set of creatives (performance % + impressions served), applies an **exponential fatigue decay** (effectiveness halves every `halfLifeImpressions`), then **water-fills** next period's impressions to the highest fatigue-adjusted value, **capped per creative** (default 40%) for variety. Returns the recommended impression share, decay, status (scale/maintain/retire), the **uplift vs. even rotation**, and how many fresh creatives to produce. Complements `creative_fatigue`. |
### Influence group (v2.21+ — Маркетинг влияния)
| Tool | What it does |
|---|---|
| `influencer_planner` | **Influencer / KOL roster evaluator & mix optimizer.** For each blogger (followers, price, optional avgViews, ER%, audience match) computes reach, CPM/CPV/CPE, estimated target reach & conversions, eCPA and a value score; **flags suspicious engagement** (likely inflated/bot or dead audience vs. the typical band for the follower tier). With a `budget` it greedily picks the best mix and reports blended reach/conversions/CPA/CPM. Deterministic. |
### Media group (v2.22+ — OLV / display reach & frequency, cross-channel)
| Tool | What it does |
|---|---|
| `reach_frequency` | **OLV / display reach & frequency planner.** From a budget + CPM (or impressions directly) and the target audience universe, computes gross impressions, GRPs, **net reach** (people & %), average frequency, the full contact distribution, and **effective reach at ≥N exposures** (Poisson exposure model). With a `frequencyCap` it estimates impressions wasted above the cap and the potential reach gain from reallocating them, plus cost-per-reached-person and an under-/over-frequency verdict. Deterministic. |
| `channel_overlap` | **Omnichannel deduplicated reach estimator.** Given a shared universe and ≥2 channels' individual reach, computes the combined **net deduplicated reach** (independence / Sainsbury model), gross summed reach, the duplication/overlap (people & %), and each channel's **incremental unique reach** (leave-one-out). Flags the most additive and most duplicated channels. Deterministic planning estimate. |
| `media_flowchart` | **Media flighting / flowchart planner.** Distributes a total budget across N weeks by a flighting pattern (even / front_loaded / back_loaded / burst / pulse), returning the per-week budget, share and cumulative spend, plus a **per-channel split each week** when channel shares are given. Reports the peak week and on-air weeks. Deterministic. |
| `media_quality_score` | **Media delivery quality scorer.** From a placement's OWN delivered metrics (viewability %, IVT/bot %, video completion %, brand-safe %, on-target %), computes a weighted **0–100 quality score** + A–F grade, scores each metric vs. RU/MRC-style thresholds, flags problems and names the biggest lever. Complements `supplier_quality` (a benchmark lookup) — this scores YOUR actual delivery. Deterministic. |
| `audience_overlap` | **Audience overlap / dedup analyzer from MEASURED pairwise overlaps** (DMP / panel / cross-device) — unlike `channel_overlap` (which assumes independence). Computes **deduplicated reach** (inclusion–exclusion), the **duplication rate**, each segment's **incremental (leave-one-out)** unique contribution & redundancy, a duplication matrix, and the most additive vs. most redundant segment — to cap frequency or reallocate. Exact for 2 segments, clamped 2nd-order estimate for ≥3. |
| `frequency_cap_optimizer` | **Frequency-cap optimizer.** From a fixed impression pool (impressions, or budget + CPM) and the audience universe, (A) **diagnoses** how many impressions land on people already past each candidate cap at the natural average frequency (over-cap waste, Poisson), and (B) **optimizes**: for each cap re-solves delivery so freed impressions are reallocated, returning the resulting **net (1+) reach**, **effective reach at ≥N**, average frequency and the reach **uplift** vs. no cap. Recommends the cap that maximises ≥N effective reach. Deterministic. |
### Production group (v2.25+ — Производство)
| Tool | What it does |
|---|---|
| `production_estimator` | **Creative production budget & timeline estimator.** From a list of deliverables (asset type × quantity × complexity) and a quality tier (economy/standard/premium), applies an illustrative RU rate card to give a per-deliverable cost & effort breakdown, subtotal, contingency and optional rush surcharge, a **total cost range (±20%)**, and a **critical-path timeline** (production is partly parallel). Heuristic & deterministic — confirm with vendor quotes. |
### Experimentation group (v2.27+ — incrementality)
| Tool | What it does |
|---|---|
| `geo_holdout` | **Geo-holdout incrementality test tool.** *Design*: from expected baseline conversions in the test geos + a target lift, returns the **minimum detectable lift (MDE)**, the baseline volume required, and a recommended test duration. *Measure*: from observed test-geo conversions vs. a counterfactual (scaled control), computes incremental conversions, lift %, a count-based (Poisson) **z-test**, p-value, significance and incremental CPA. Auto-detects mode. Deterministic. |
| `incrementality_meta` | **Meta-analysis of multiple incrementality / A-B / geo tests.** Each test gives a lift % + SE (or 95% CI). Computes the **inverse-variance fixed-effect** pooled lift (z, p, CI), heterogeneity **Q & I²**, and the **DerSimonian–Laird random-effects** pooled lift (wider CI when tests disagree); returns per-test weights, both pooled estimates and an overall significance call — combine many small reads into one defensible number. |
### Competitive group (v2.30+ — war-gaming)
| Tool | What it does |
|---|---|
| `competitive_response` | **Competitive war-game simulator.** Given your spend, current competitor spend and a move (spend escalation %, new entrant, or pullback), models the impact on your **Share of Voice**, **auction CPM inflation** and **effective impressions** at a fixed budget, then sizes the **defensive budget** needed to hold a target SOV and recommends a posture (hold / partial match / defend or pivot). Deterministic auction-share dynamics. |
### Search & SEM group (v2.36+ — paid search)
| Tool | What it does |
|---|---|
| `search_planner` | **Paid-search / SEM keyword-portfolio planner** for Yandex Direct & контекст. From keywords (monthly **volume** + **CPC**, optional CTR%/CVR%/intent) and an optional monthly budget, estimates per-keyword **clicks, conversions, CPA** and the **max addressable spend**, ranks keywords by efficiency (conversions per ₽), greedily **allocates the budget** to the lowest-CPA keywords first, and returns portfolio totals — clicks, conversions, **blended CPA** and demand **coverage**. Defaults CTR 4% / CVR 2% when missing (flagged). Deterministic media math on your inputs. |
### Retail Media group (v2.37+ — marketplaces)
| Tool | What it does |
|---|---|
| `retail_media_planner` | **Marketplace / retail-media planner** for Ozon, Wildberries, Яндекс Маркет & Avito. From placements (search / catalog / banner) with a cost model (**CPC**, or **CPM + CTR**), click→order **CVR**, an **AOV**, the marketplace **commission** (take-rate) and an optional budget, computes per-placement effective CPC, orders, revenue, **ДРР** (доля рекламных расходов = ad spend / revenue) and **ROAS**, ranks placements by **profit per ₽**, greedily allocates the budget to the most profitable placements first (respecting volume caps), and returns blended portfolio economics (revenue, ДРР, ROAS, net profit after commission/COGS) with a **target-ДРР** check. Deterministic. |
### Retention / CRM group (v2.39+ — lifecycle)
| Tool | What it does |
|---|---|
| `churn_predictor` | **Churn & retention economics.** Resolves a monthly churn rate from a direct %, a cohort (`customersStart`→`customersRetained` over N months) or a monthly retention %, then computes **annualised churn**, **average lifetime** (1/churn), a survival curve to the horizon, **customers & revenue retained vs. lost**, and **LTV** (`ARPU/churn`, optionally discounted). Given a retention initiative (`reduceChurnByPp` + `programCost`) it sizes the **LTV uplift** per customer, the total uplift and the **ROI of retention**. Deterministic. |
| `rfm_segmenter` | **RFM customer segmentation.** From customers with `recencyDays` + `frequency` + `monetary`, scores each on 1–5 quintiles (recency inverted), combines R with the F/M average into the classic named segments (**Champions, Loyal, Potential Loyalist, At Risk, Can't Lose Them, Hibernating, Lost, …**), sizes every segment (customers, share %, total & avg monetary, avg recency/frequency) and attaches a concrete **CRM action**. Surfaces **Champions revenue** and **revenue at risk**. Deterministic. |
### Email / Lifecycle group (v2.44+ — рассылки)
| Tool | What it does |
|---|---|
| `email_campaign_planner` | **Email / CRM newsletter economics & cadence.** From list size, deliverability, open & click rates (CTR or click-to-open), conversion and AOV → per-send delivered→opens→clicks→orders→revenue and the key **revenue-per-email (RPE)**; with `sendsPerMonth` → **monthly & annual** revenue, orders and list attrition from unsubscribes, a **list half-life** and a **fatigue warning**; with `costPerEmail` / `platformMonthlyCost` → profit and **ROI**. Deterministic. |
### Partnerships group (v2.45+ — CPA / affiliate)
| Tool | What it does |
|---|---|
| `affiliate_program_planner` | **CPA / affiliate / partner-program economics** for RU networks (Admitad, Cityads, …) & direct partners. From AOV, gross margin, a commission model (% of AOV or fixed CPA), an optional network fee and validation rate, plus per-partner clicks & conversion → per-partner approved orders, payout, **EPC**, effective CPA, **ROAS** and net profit; ranks partners, blends the program, and derives the **sustainable commission ceiling** (`margin/(1+fee)`), flagging loss-making partners and checking a target CPA. Deterministic. |
### Distribution group (v2.47+ — single Unyly front door)
| Tool | What it does |
|---|---|
| `connect_via_unyly` | **Front door for install / access / upgrade — always through Unyly.** Returns the **tracked Unyly install link** (UTM-attributed by `source`/`role`/`plan`, with a `via=<partner>` tag), the manual MCP endpoint as a fallback, role-aware onboarding (pairs with `role_playbook`) and the access **tiers** (free / pro / team / agency). Unyly is the metering & governance point (Unyly Connect fronts OAuth 2.1). Links & guidance only — no PII, no network call. |
### Skills group (v2.51+ — composable playbooks)
| Tool | What it does |
|---|---|
| `marketing_skill` | **Extensible playbook engine.** No args ⇒ lists 10 end-to-end skills (cut CAC, retention boost, product launch, creative refresh, budget reallocation, SEO/content, social/influencer, board readout, marketplace scaling, measurement setup). Given a `skill` key/alias or free-text `goal` (RU/EN) ⇒ returns the ordered workflow (tool + why), inputs needed and KPIs. Returns the plan only. |
### Growth Lab group (v2.51+ — growth science)
| Tool | What it does |
|---|---|
| `cohort_retention_curve` | Fits a power-law retention curve r(t)=a·t^(−b) to your cohort points (log-log least squares), projects D1/D7/D30/D90/D365 + R², and (given ARPU) an LTV estimate over a horizon. |
| `viral_loop` | Referral/virality model: k-factor (i·c), amplification 1/(1−k), seed→total projection and referral-incentive economics (profit per referred, break-even ceiling). |
### Federation group (v2.52+ — hub for external MCPs via Unyly)
| Tool | What it does |
|---|---|
| `mcp_federation` | **Marketplace router.** NECTARIN is the hub; complementary specialist MCPs (live keyword/SERP data, web analytics, ad-platform pulls, creative generation, social listening, CRM, marketplace data, localization) plug in around it — always through Unyly. No args ⇒ catalogue; `capability`/`goal`/`role` ⇒ recommendations; `server` ⇒ details. Each entry includes a **tracked Unyly connect link**, the live **`gatewayUrl`** (`gateway.unyly.org/mcp/<slug>`) and the native NECTARIN tools it pairs with. |
| `federation_invoke` | **Runtime proxy (team+).** Calls a tool on a federated external MCP *through* NECTARIN: pick a `server` key + external `tool` + `arguments`; NECTARIN proxies one JSON-RPC `tools/call` and returns the upstream result. **Fail-closed** — reaches the network when `UNYLY_GATEWAY_TOKEN` is set (one token → `gateway.unyly.org/mcp/<slug>` for all servers) or when per-server `FED_<KEY>_URL` is set (override). Without either, returns a tracked Unyly connect link with no network call. Only known registry keys (no arbitrary URLs ⇒ no SSRF). |
#### Federation gateway setup (self-serve)
1. Issue a gateway token in the [Unyly dashboard](https://unyly.org) (Gateway → POST `/api/gateway-tokens`).
2. Set it as a Worker secret: `npx wrangler secret put UNYLY_GATEWAY_TOKEN`.
3. Optionally override the base URL via `UNYLY_GATEWAY_URL` (default `https://gateway.unyly.org`).
4. Call `federation_invoke(server="keyword_data", tool="...", arguments={...})` — NECTARIN routes to `https://gateway.unyly.org/mcp/keyword-data` with Bearer auth.
5. Health check: `GET https://gateway.unyly.org/mcp/ping`.
Per-server `FED_<KEY>_URL`/`FED_<KEY>_TOKEN` overrides still work and take precedence over the gateway default.
### Expansion group (v2.54+ — wider profession coverage)
| Tool | What it does |
|---|---|
| `marketing_maturity_assessment` | **CMO/transformation scorecard (pro+).** Rate 7 weighted dimensions 0–5 ⇒ a 0–100 maturity index, level 1 Nascent→5 Leading, per-dimension strengths/gaps and a prioritized 90-day roadmap. |
| `martech_stack_roi` | **Marketing-ops/RevOps stack auditor (pro+).** From tools (cost, utilization, category, optional satisfaction) ⇒ wasted spend, category redundancy, low-utilization cut candidates, projected consolidation savings and a utilization-weighted ROI proxy. |
| `pricing_psm` | **Van Westendorp PSM.** From respondents' four price points it builds the four cumulative curves and locates OPP, IPP and the acceptable band PMC→PME (drops non-monotonic respondents). |
### B2B & CX group (v2.55+ — demand-gen / revenue + customer experience)
| Tool | What it does |
|---|---|
| `abm_account_scoring` | **ABM prioritization (pro+).** Weights fit × intent × engagement into a 0–100 score, assigns a tier (1:1 / 1:few / 1:many / nurture) with a recommended play, and ranks by expected value when deal size is given. |
| `nps_analysis` | **NPS.** From raw 0–10 scores or promoter/passive/detractor counts ⇒ segment split, NPS (−100..+100), a 95% confidence interval and a benchmark band. |
| `b2b_pipeline_velocity` | **Pipeline velocity (pro+).** (opps × win-rate × deal size) ÷ cycle days ⇒ revenue/day, monthly & annual, plus a +10% lever sensitivity to find the highest-leverage improvement. |
| `win_loss_analysis` | **Win/loss (pro+).** From closed deals (outcome/reason/segment/value) ⇒ win rate by count & value, win rate by segment, top loss/win reasons and prioritized recommendations. |
### Ops & Autonomy group (v2.56+ — anomaly → action, CMO budgeting)
| Tool | What it does |
|---|---|
| `kpi_alert_engine` | **Alert engine (autonomy).** Grades KPIs vs targets ok/watch/warning/critical and routes every breach to a recommended action + the NECTARIN tool to run next (CPA↑ ⇒ budget_optimizer, CTR↓ ⇒ creative_testing_matrix, churn↑ ⇒ churn_predictor). Sorted by severity. |
| `marketing_budget_allocator` | **CMO budget by function (pro+).** Splits an annual budget across brand / demand / retention-CRM / content-SEO / martech / team, tilted by goal & business type with guardrails. (Media channel splits ⇒ `budget_optimizer`.) |
| `autonomous_plan` | **Action-plan builder (pro+).** Turns KPI breaches and/or a goal into an ORDERED, deterministic plan — diagnose → one action per breach (severity-first, each with the NECTARIN tool, the owner/role and the expected-impact direction) → measure/control. Complements `kpi_alert_engine` by sequencing alert→action→measure. Returns the recipe; does not execute tools. |
| `autonomous_execute` | **Guarded autonomy runner (team+).** Moves alert→action→measure from planning to SAFE execution. **Dry-run by default** (deterministic, zero side effects). `mode:"execute"` needs `confirm:true`+`approvalToken`; WRITE/external steps run **only** through the fail-closed Unyly federation (`federation_invoke`) — no gateway token ⇒ no network, degrade to "connect via Unyly". Read-only NECTARIN steps are described, never auto-run (no recursive fan-out). Emits a per-step audit trail (simulated \| executed \| skipped \| blocked). |
### Marketing Ops & Leadership group (v2.57+ — OKRs & content capacity)
| Tool | What it does |
|---|---|
| `marketing_okr_planner` | **OKR planner (pro+).** Turns an objective + key results into a measurable OKR set: per KR baseline → target, %Δ, an ambition band (conservative/realistic/ambitious/stretch), a leading-vs-lagging classification and the tool to drive it; flags an unbalanced (all-lagging / all-leading) set. |
| `content_calendar_planner` | **Content capacity planner.** From team size, productive hours and a content mix (effort per piece + desired share + optional planned count) ⇒ total capacity, achievable pieces per type, weekly throughput, utilization vs. plan and the bottleneck. |
### Foresight & Strategy group (v2.58+ — forecasting, journey & positioning)
| Tool | What it does |
|---|---|
| `demand_forecast` | **Demand forecast (pro+).** Projects the next N periods of any series (sales/leads/traffic/revenue) with **Holt's linear-trend** double exponential smoothing, a residual-based **confidence band** (z·RMSE·√h, widening with the horizon), the fitted level & per-period trend and MAPE. Optional **multiplicative seasonality** via classical decomposition when ≥2 full cycles are supplied. Distinct from `seasonality_forecast` (category index) and `anomaly_detector` (outliers). |
| `customer_journey_map` | **Lifecycle map & gap audit.** Maps the funnel (awareness → consideration → purchase → retention → advocacy) to channels, content and a primary KPI per stage; with stage volumes computes stage-to-stage conversion and the biggest drop-off; flags coverage **gaps** (a stage with no channels or no content). Call with no args for the best-practice template. |
| `competitive_positioning_map` | **2-axis perceptual map (pro+).** Places ≥2 competitors on a plane (e.g. price × value), splits at the mean of each axis into four quadrants, assigns each player a quadrant + value-for-money index, finds the empty quadrants (**white-space**) and — if one entry is flagged `isYou` — reports your quadrant and nearest rival by normalized distance. |
### Market & Revenue Science group (v2.59+ — revenue bridge, conjoint & market sizing)
| Tool | What it does |
|---|---|
| `marketing_roi_waterfall` | **Revenue/ROAS bridge (pro+).** Decomposes period-over-period ΔRevenue into three exact, reconciling drivers via sequential factor substitution: Revenue = Spend × Efficiency (conv/₽) × AOV (₽/conv). Returns a waterfall (start → spend → efficiency → AOV → end), each driver's signed ₽ contribution & share, and the ROAS delta. Explains **why** revenue moved (more budget? cheaper conversions? bigger basket?). Distinct from `unit_economics` (single-period) and `scenario_planner` (forward what-ifs). |
| `conjoint_analysis` | **Part-worth conjoint (lite, pro+).** From attribute level utilities computes attribute **importance** (utility-range share), the **optimal bundle** (max-utility level per attribute), **share-of-preference** across supplied profiles via a logit/BTL model, and — with a numeric price attribute — the **willingness-to-pay** (₽) per attribute. Trades off features × price; distinct from `pricing_psm` (Van Westendorp, price only). |
| `tam_sam_som` | **Market-sizing funnel.** TAM → SAM → SOM top-down (TAM × SAM share × SOM share) or bottom-up (population × penetration × obtainable share × ARPU) → sizes in customers & revenue, the SOM-as-%-of-TAM **reality check**, and an optional multi-year SOM projection at a CAGR. Light, deterministic. |
### Roles / Adoption group (v2.46+ — one connector for every marketer)
| Tool | What it does |
|---|---|
| `role_playbook` | **Role router & adoption engine.** A marketer states their profession in RU or EN (free-text, alias-matched) and gets a TAILORED playbook: primary tools (each with a role-specific "why"), the supporting toolkit, an ordered end-to-end **workflow**, the **KPIs** that role owns and example questions. Called without a role it lists all **26 supported professions** (CMO, performance/PPC, SEO, SMM, content, brand, media planning, CRM/lifecycle, e-commerce/marketplaces, influencer, PR, analytics, product/GTM, affiliate, growth, events, mobile/ASO, creative, pricing/promo, compliance, agency, marketing ops, programmatic/DSP trader, marketplace listing SEO, lifecycle/automation, PLG growth). Curated, deterministic. |
### SEO group (v2.46+ — organic search)
| Tool | What it does |
|---|---|
| `seo_opportunity` | **SEO organic-growth model.** From keywords (volume + current & target position) and a conversion rate + value, applies a **position→CTR curve** to estimate current vs. target organic traffic, incremental conversions & value per keyword, ranks opportunities and flags page-2 **quick wins** (positions 11–20). Deterministic. |
### Social / SMM group (v2.46+ — organic social)
| Tool | What it does |
|---|---|
| `social_media_planner` | **Organic SMM planner.** Per platform (VK/Telegram/Дзен/YouTube …) from followers, posts/week, organic reach % and engagement % → monthly posts, reach, impressions, engagements and follower growth; with a conversion rate + AOV → conversions & revenue. Aggregates the portfolio, recommends a cadence and flags low organic reach. Deterministic. |
### PR / Communications group (v2.46+ — earned media)
| Tool | What it does |
|---|---|
| `pr_value_estimator` | **PR / earned-media value & share of voice.** From placements (outlet, reach, tier, sentiment) → total & **deduplicated** reach, tier×sentiment **quality-adjusted reach**, an advertising-equivalent reach value (labelled context, not an endorsed KPI) and, with competitor reach, earned **share of voice**. Honest methodology with AMEC caveats. Deterministic. |
### Events group (v2.46+ — events & webinars)
| Tool | What it does |
|---|---|
| `event_roi_planner` | **Event / webinar / field ROI.** Projects the funnel invites→registrations→attendees→leads→opportunities→won deals→revenue, plus cost per registration/attendee/lead, **ROI** and breakeven deals. Deterministic. |
### Mobile / ASO group (v2.46+ — app growth)
| Tool | What it does |
|---|---|
| `aso_planner` | **App Store Optimization & mobile growth.** From store impressions, tap-through and install-conversion rates → page views & installs; with LTV (or ARPDAU×lifetime) → revenue; with a paid CPI → paid-UA economics (LTV/CPI, breakeven). Includes an **ASO uplift scenario** (+pp to install conversion → extra installs & value). Deterministic. |
### Content group (v2.46+ — content marketing)
| Tool | What it does |
|---|---|
| `content_plan_roi` | **Compounding content-marketing ROI.** Treats content as an asset: simulates the library month-by-month over a horizon (ramp → plateau → decay) → cumulative visits, conversions, value vs. spend, **ROI**, **payback month** and exit run-rate. Shows why content pays back later but compounds. Deterministic. |
### Brand group (v2.23+ — brand lift)
| Tool | What it does |
|---|---|
| `brand_lift` | **Brand-lift study calculator.** *Measure*: from a control vs. exposed survey cell (n + positive answers for ad recall / awareness / consideration / intent) computes both rates, the absolute (pp) & relative lift, a pooled **two-proportion z-test** (z, two-tailed p-value, significance at α) and a confidence interval for the lift. *Design*: from a base rate + target lift (absolute pp or relative %), α and power, returns the **required sample size per cell** (and total). Auto-detects mode. Deterministic. |
| `sov_tracker` | **Share of Voice + ESOV growth tracker.** From brand spend + competitor spends (or a given SOV) and the brand's current market share, computes **SOV**, **ESOV** (excess share of voice = SOV − share) and the predicted annual market-share growth (Binet & Field: ~0.5pp per 10pp ESOV). Also solves the SOV/spend required to hit a target share growth. Deterministic brand-growth heuristic. |
| `share_of_search` | **Share of Search demand tracker** — branded search as a *leading indicator* of market share (Les Binet). From the brand's branded-search volume + competitors' volumes (or a total category volume, or SoS directly), computes **SoS %**, the brand's **rank**, and — given current market share — the **SoS↔share gap** (demand ahead of share ⇒ poised to gain; behind ⇒ at risk). Optional previous SoS gives the **trend**; projects next-period share as it partially converges toward SoS. Distinct from `sov_tracker` (share of *spend*). Deterministic. |
### Design & Creative Ops group (v2.66+ — deterministic design SPECS, not rendering)
Deterministic design-**spec** tools. NECTARIN produces the machine-readable spec; **actual image/asset rendering is delegated to a federated creative-generation MCP via Unyly** (`mcp_federation` → `creative_gen`).
| Tool | What it does |
|---|---|
| `design_system_spec` | **Flagship (pro+).** From brand inputs (brand, industry, mood minimal/bold/premium/playful/corporate, optional `primaryColor` hex or `baseHue`, base font size) derives a deterministic design system: an **HSL-wheel palette** (primary + analogous secondary + complementary accent + light/dark neutrals, all hex), a **modular type scale** (base × ratio → h1..caption), a **4/8pt spacing scale**, **radius + elevation tokens**, and a **WCAG contrast check** for text-on-primary (relative luminance + contrast ratio, AA/AAA pass/fail + recommended text colour). Same input → same tokens. |
| `banner_layout_spec` | Per-format banner **specs** for RU platforms (vk/yandex/telegram/ok/web-IAB): canonical ad **sizes**, a **layout skeleton** per size (logo/headline/visual/CTA zones as % positions + safe margins, orientation-aware), **max text-length** recommendations and a **font-size floor** for readability. Deterministic. |
| `ad_spec_checker` | Creative **compliance/spec linter** — checks a creative's attributes against platform + RU ad-law rules (**ORD/ЕРИР** labelling, format ratio, text-over-image %, file weight, CTA, regulated-category **legal gate**) → **pass/warn/fail** per rule + prioritized fixes. Deterministic; not legal advice. |
### Profession Breadth group (v2.67+ — deterministic, methodology-grounded role planners)
Four planners that extend coverage to under-served marketing roles (programmatic/DSP trading, marketplace listing SEO, lifecycle automation, PLG). Pure math on your inputs (same input → same output).
| Tool | What it does |
|---|---|
| `programmatic_trading_plan` | **Flagship (pro+).** DSP/programmatic trader: from budget, optional target CPM/CPA, a **deal-type mix** (PMP / open exchange / PG), viewability goal, frequency cap and flight length → per-deal **bid strategy**, **budget pacing** (daily + per deal type), expected **impressions & de-duplicated reach**, and the **viewability-adjusted effective CPM** (spend / viewable impressions × 1000) vs the goal. Programmatic mechanics — distinct from `reach_frequency`/`media_flowchart`. |
| `marketplace_seo_plan` | Marketplace listing SEO (Wildberries/Ozon/Yandex Market): from category, listing attributes, search terms and competition → a 0–100 **listing-optimization score**, a **keyword→slot** mapping (title/attributes/description by volume), a **ranking-factor checklist** (pass/warn/fail + fix) and the **projected organic-visibility uplift** (volume × position-CTR). Organic ranking — distinct from `retail_media_planner` (ads) and `seo_opportunity` (web). |
| `lifecycle_flow_planner` | Lifecycle/CRM automation: designs a **triggered cross-channel FLOW** (welcome/onboarding/winback/abandoned-cart/reactivation) — ordered stages with **delay, channel, purpose, per-step conversion** → the funnel (per-step + cumulative conversions), the flow conversion rate and a **revenue projection**. The flow/automation blueprint — distinct from `email_campaign_planner` (one blast) and `rfm_segmenter`. |
| `plg_activation_model` | **Flagship (pro+).** Product-led growth (SaaS): models the **activation funnel** (signup → activated → retained) around an **aha-moment**, applies **activation-rate levers** (onboarding checklist, time-to-value, empty states, activation email, in-app guidance, social proof) and projects activated/retained users + **MRR** (from ARPU). Activation specifically — distinct from `viral_loop`/`funnel_model`/`cohort_retention_curve`. |
> **Funnel logic & safety.** All Growth figures are synthetic/illustrative and
> anchored to the same mock RU/CIS benchmarks (`src/data.ts`) — internally
> consistent, but not guarantees. No tool transmits PII or makes a real network
> call. `request_nectarin_proposal` only **returns** a brief for human review;
> the exact spot for a real CRM/webhook POST is commented in `src/growth.ts`
> (gated behind `NECTARIN_CRM_WEBHOOK_URL`, left blank on purpose).
#### Growth & Automation env vars (`wrangler.toml` `[vars]`)
| Var | Purpose | Default |
|---|---|---|
| `NECTARIN_BOOKING_URL` | Scheduling link returned by `book_consultation`. | `https://nectarin.example/booking` (placeholder) |
| `NECTARIN_CONTACT_EMAIL` | Funnel inbox shown in proposal next-steps. | `hello@nectarin.example` (placeholder) |
| `NECTARIN_BRAND_NAME` | Brand label used in copy. | `NECTARIN` |
| `NECTARIN_CRM_WEBHOOK_URL` | Where a real proposal would POST. Blank = nothing is ever sent. | `""` |
---
## Go live — exact steps
From this folder (`nectarin-intelligence-worker/`):
```bash
# 1. Install dependencies
npm install
# 2. Authenticate to Cloudflare (interactive browser login)
npx wrangler login
# …or, for CI / headless, set a scoped API token instead of logging in:
# export CLOUDFLARE_API_TOKEN="<your-token-with-Workers-Scripts-Edit>"
# (optionally also export CLOUDFLARE_ACCOUNT_ID="<your-account-id>")
# 3. Deploy
npx wrangler deploy
```
Wrangler prints the live URL, e.g.:
```
https://nectarin-intelligence.<your-subdomain>.workers.dev
```
Your **MCP endpoint** is that URL + `/mcp`:
```
https://nectarin-intelligence.<your-subdomain>.workers.dev/mcp
```
### Add to Claude (Custom Connector)
1. Claude → **Settings → Connectors → Add custom connector**.
2. Name: `NECTARIN Intelligence`. URL: the `/mcp` URL above.
3. Save. Because `DEV_BYPASS="1"` is set in `wrangler.toml`, the server accepts
requests without a token out of the box — good for a first smoke test. Turn auth
on before any real/shared use (see **Security** below).
### Smoke test with curl
```bash
# Replace with your deployed host.
HOST="https://nectarin-intelligence.<your-subdomain>.workers.dev"
# Health
curl -s "$HOST/health"
# MCP initialize
curl -s "$HOST/mcp" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
# List tools
curl -s "$HOST/mcp" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# Call media_plan (real forecast + compliance gate for finance)
curl -s "$HOST/mcp" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"media_plan","arguments":{"budget":5000000,"goal":"performance","geo":"РФ","audience":"25-45","period":"сентябрь 2026","category":"finance"}}}'
```
`initialize` returns `serverInfo`, `protocolVersion`, and `capabilities`;
`tools/list` returns all 110 tools (11 Intelligence + 6 Growth & Automation + 11 Premium Analytics + 8 Premium + 1 MMM + 2 Planning + 2 Pricing & Promo + 2 Audit + 1 Executive + 2 Creative Ops + 1 Influence + 6 Media + 3 Brand + 1 Production + 2 Experimentation + 1 Competitive + 1 Search & SEM + 1 Retail Media + 2 Retention/CRM + 1 Email/Lifecycle + 1 Partnerships + 1 Roles/Adoption + 1 SEO + 1 Social/SMM + 1 PR + 1 Events + 1 Mobile/ASO + 1 Content + 1 Distribution + 1 Skills + 2 Growth Lab + 2 Federation + 3 Expansion + 4 B2B & CX + 6 Ops & Autonomy + 2 Marketing Ops & Leadership + 3 Foresight & Strategy + 3 Market & Revenue Science + 2 Launch & Brand Health + 1 Tenant Data + 3 Design & Creative Ops + 4 Profession Breadth);
`media_plan` returns the split, forecast totals, per-channel detail, and a
STOP-GATE flag for regulated categories.
```bash
# Flagship: full orchestrated strategy in one call
curl -s "$HOST/mcp" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"strategy_orchestrate","arguments":{"brand":"Acme","category":"finance","budget":8000000,"goal":"performance","geo":"РФ"}}}'
# Optimize the channel split to maximize conversions
curl -s "$HOST/mcp" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"budget_optimizer","arguments":{"category":"retail","budget":4000000,"goal":"performance"}}}'
```
```bash
# Funnel example: ROI pitch (synthetic, anchored to mock benchmarks)
curl -s "$HOST/mcp" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"roi_calculator","arguments":{"monthly_budget":3000000,"category":"finance"}}}'
# Qualify a lead → tier recommendation
curl -s "$HOST/mcp" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"lead_qualify","arguments":{"company":"Acme","monthly_budget":6000000,"industry":"finance","goal":"performance"}}}'
```
---
## Local development
```bash
cp .dev.vars.example .dev.vars # edit if needed; .dev.vars is gitignored
npm run dev # wrangler dev → http://localhost:8787/mcp
npm run typecheck # tsc --noEmit
npm test # vitest run (30 tests)
npm run dry # wrangler deploy --dry-run --outdir dist (no Cloudflare auth needed)
```
### Tests
`npm test` runs the vitest suite against the Worker's `fetch()` handler directly:
initialize handshake, `tools/list` (110 tools), happy-path `tools/call`
(`ru_benchmarks`, `media_plan`, `roi_calculator`, `lead_qualify`,
`budget_optimizer`, `strategy_orchestrate`), invalid params (`-32602`), unknown
tool/method (`-32601`), the auth 401 path (`DEV_BYPASS` off, no token), plus unit
tests for the rate limiter and validator.
---
## Production configuration
Everything below is off by default so the server runs locally with zero secrets.
Turn it on for real/shared use.
### Environment variables (`wrangler.toml` `[vars]`)
| Var | Purpose | Default |
|---|---|---|
| `DEV_BYPASS` | `"1"` skips auth (dev). Set `"0"` to enforce OAuth. | `"1"` |
| `OAUTH_ISSUER` | Expected `iss`; also derives the JWKS URL if `OAUTH_JWKS_URL` is blank. | `""` |
| `OAUTH_AUDIENCE` | Expected `aud` (your `/mcp` URL). | `""` |
| `OAUTH_JWKS_URL` | JWKS endpoint; blank → `${OAUTH_ISSUER}/.well-known/jwks.json`. | `""` |
| `RATE_LIMIT_PER_MIN` | Requests/min per token (or IP). `0` disables. | `60` |
| `GIT_COMMIT` | Build id surfaced by `GET /version`. | `dev` |
| `NECTARIN_BOOKING_URL` / `…_CONTACT_EMAIL` / `…_BRAND_NAME` / `…_CRM_WEBHOOK_URL` | Growth funnel (placeholders; no PII sent). | see table above |
### Secrets (never in `wrangler.toml` / git)
Use Cloudflare secrets for anything sensitive:
```bash
npx wrangler secret put LLM_API_KEY # enables REAL narrative (Anthropic/OpenAI)
npx wrangler secret put NECTARIN_DATA_API_KEY # if using HttpDataSource
```
`.dev.vars` is for local dev only and is gitignored.
### Enable a real LLM narrative (optional)
`callLLM()` is **real-or-stub**. With no key it returns a deterministic stub, so
the server runs fully offline. To switch narrative copy (`media_plan` rationale,
`creative_brief` concepts, `geo_aeo_audit` summary, and the `strategy_orchestrate`
executive summary) to a real model:
```bash
npx wrangler secret put LLM_API_KEY # required to go live
```
Optional `[vars]`: `LLM_PROVIDER` (`anthropic` default | `openai`), `LLM_MODEL`
(per-provider default otherwise), `LLM_BASE_URL` (proxy/Azure/self-host). Any model
error degrades gracefully back to the stub — a tool call never fails because of the LLM.
### Enable OAuth 2.1 (real bearer verification)
1. In `wrangler.toml` `[vars]` set `DEV_BYPASS = "0"` and fill `OAUTH_ISSUER`,
`OAUTH_AUDIENCE` (= your `/mcp` URL), and optionally `OAUTH_JWKS_URL`.
2. That's it — `src/auth.ts` already verifies the JWT with `jose`
(`createRemoteJWKSet` + `jwtVerify`): signature, issuer, audience, expiry. A
failed/missing token → HTTP 401 with `WWW-Authenticate: Bearer error=…,
resource_metadata="…"`. **Unyly Connect** is the authorization server (DCR +
PKCE, issuance/rotation, per-tenant scopes); this Worker only validates.
### Rate limits
Backend precedence (auto-selected in `fetch()`, reported by `/health` & `/version`):
- **Durable Object** (`RATE_LIMITER`, bound in this deploy) — *strongly
consistent*: one DO instance per key owns a token bucket, so even a parallel
burst is counted exactly. Verified on prod: a 120-request burst at 60/min
returned ~64×200 / ~56×429.
- **KV** (`NECTARIN_KV`) — global, cross-isolate fixed-window (eventually
consistent; can over-admit under a burst). Used if no DO.
- **Memory** — per-isolate token bucket. Used if neither binding is present.
- Everything is **fail-open**: a DO/KV error degrades to the next layer (down to
memory), so an infra hiccup never hard-locks the public connector.
- `RATE_LIMIT_PER_MIN` sets the ceiling (default 60).
- Over-limit → JSON-RPC `-32029` + HTTP 429 with `Retry-After`/`X-RateLimit-*`.
### Per-tenant data (`X-Tenant-Id`)
With KV bound, each request may carry an `X-Tenant-Id` header (alphanumerics /
`._-`, ≤64 chars). The Worker then resolves benchmark/playbook/supplier lookups
in the order **tenant override → global override → bundled mock**, where the
tenant layer reads `tenant:<id>:benchmarks:<category>` (etc.) from KV. This is
request-scoped via `AsyncLocalStorage` — concurrent requests never share or race
each other's data source, and no tool code changes. An absent/invalid header (or
no KV) transparently falls back to the shared data. Reported by `/health` &
`/version` (`perTenant`). To populate a tenant:
`npx wrangler kv key put --remote --namespace-id <id> "tenant:acme:benchmarks:retail" '<json>'`.
**Tenant metrics (v2.61, structured schema v2.64):** store a read-only metrics blob at
`tenant:<id>:metrics`. Set `NECTARIN_TENANT_DATA_MODE=kv` to read from KV (default `mock`
returns a demo blob and keeps every tool on its prior synthetic behavior). Inspect config
via `tenant_metrics_snapshot(tenantId=…)` (now reports a `dataStatus` block: `configured`,
`blobExists`, `schemaVersion`, `updatedAt`).
The **v2.64 real-data pilot (Phase D)** defines one documented, versioned superset schema
(`src/tenantdata.ts`) that several tools read via an opt-in `useTenantData:true` flag:
```jsonc
{
"schemaVersion": 1, // integer; bump on a breaking shape change
"updatedAt": "2026-07-01T00:00:00Z", // ISO8601 / free-form label
"currency": "RUB",
"funnel": { // absolute counts for a period
"impressions": 1200000, "clicks": 24000,
"leads": 1800, "qualified": 900, "sales": 260,
"spend": 2400000, "revenue": 5600000
},
"channels": [ // optional per-channel breakdown
{ "name": "VK Ads", "spend": 900000, "revenue": 2100000, "conversions": 90 }
],
"kpis": { // current KPI VALUES
"cpa": 9230, "ctr": 2.0, "roas": 2.33,
"cac": 9230, "ltv": 21000, "aov": 21538,
"churnPct": 4.5, "convRatePct": 1.08
},
"targets": { "cpa": 8000, "ctr": 2.5, "roas": 3.0, "churnPct": 3.0 } // optional
}
```
Every section is optional — a blob may carry only `kpis`, only `funnel`, or both.
- `kpi_alert_engine(useTenantData:true)` — pulls current KPI values (and matching
`targets`) from `kpis`, grades them, and routes breaches to actions/tools. Manual
`metrics` still win per KPI name.
- `funnel_model(useTenantData:true)` — derives real click→lead / lead→sale conversion
rates (and AOV) from `funnel` counts; explicit `leadRatePct`/`aov`/etc. overrides win.
The flag is **strictly opt-in and non-breaking**: it is inert unless mode=`kv` AND a blob
exists at the resolved key. In mock/authless/owner mode (prod default) the tools behave
exactly as before and, when the flag is set, return a clear "configure tenant data" note.
In `kv` mode with an authenticated `X-Tenant-Id`, a mismatched `tenantId` argument is
rejected (IDOR guard). Populate a blob with:
`npx wrangler kv key put --remote --namespace-id <id> "tenant:acme:metrics" '<json>'`.
### Swapping the data source (mock → real)
1. Provide the datasets in **`DATA_SCHEMA.md`** (`benchmarks`, `playbooks`,
`suppliers`) via KV, D1, or an internal HTTP API.
2. Implement `KvDataSource` or `HttpDataSource` in `src/data.ts` (stubs included).
3. Add the binding in `wrangler.toml`, then call `setDataSource(...)` **once** at
the top of `fetch()` in `src/index.ts`. No tool/orchestrator changes needed.
4. (Optional) Swap `callLLM()` in `src/orchestrator.ts` for a real model `fetch()`.
---
## Wiring real data later
`src/data.ts` defines a **`DataSource`** interface (`getMetric`,
`getCategoryBenchmarks`, `getPlaybook`, `getSuppliers`); the default is
`MockDataSource` over inline synthetic objects. Tools read **only** through this
interface, so going real is a one-line wiring change — no upstream edits.
1. Create the store and paste its ID into the commented block in `wrangler.toml`:
```bash
npx wrangler kv namespace create NECTARIN_KV
# or
npx wrangler d1 create nectarin-intelligence
```
2. Implement `KvDataSource` or `HttpDataSource` in `src/data.ts` (commented stubs
included) against the data described in **`DATA_SCHEMA.md`**.
3. Call `setDataSource(new KvDataSource(env.NECTARIN_KV))` once at the top of
`fetch()` in `src/index.ts`.
4. Swap `callLLM()` in `src/orchestrator.ts` from the stub to an Anthropic/OpenAI
`fetch()` call (key from `wrangler secret`) for real narrative copy.
> **`DATA_SCHEMA.md`** is the client handoff: it lists the exact tables/collections
> (`benchmarks`, `playbooks`, `suppliers`), columns, types, example rows, and which
> tool consumes each. Hand it to NECTARIN to source the data.
---
## Resources & prompts exposed
- Resources: `nectarin://methodology`, `nectarin://glossary`, and
**`nectarin://catalog`** — a live `application/json` catalog of every tool
(title, description, input schema, behavioral annotations) + prompts, generated
from the registry on read so it never drifts.
- **Tool annotations**: `tools/list` returns MCP `ToolAnnotations` hints + a
display `title` per tool. Pure tools are `readOnlyHint`/`idempotentHint` true,
`openWorldHint` false; LLM-backed (`creative_variants`, `localize`) are
non-idempotent/open-world; `request_nectarin_proposal` is not read-only.
- Prompts (13): `build_media_plan`, **`full_strategy`** (one-shot flagship via
`strategy_orchestrate`), `competitor_teardown`, the two funnel
orchestrators **`sell_nectarin_services`** (roi_calculator → value_forecast →
lead_qualify → request_nectarin_proposal → book_consultation) and
**`automate_my_marketing`** (automation_recipe → roi_calculator →
book_consultation), plus **`creative_lab`** (creative_variants →
compliance_check → ab_test_planner), **`growth_monitor`**
(anomaly_detector → cohort_ltv + unit_economics), **`launch_flight`**
(media_plan → seasonality_forecast → utm_builder → pacing_monitor) and
**`performance_review`** (anomaly_detector → attribution_model →
bid_simulator → budget_optimizer), **`saturation_reallocation`**
(response_curve → pacing_monitor) for diminishing-returns budget splits, and
**`mmm_planning`** (mmm_optimize) for time-series adstock + saturation modeling,
**`quarter_plan`** (gtm_calendar) for a phased Test→Scale→Optimize roadmap
with seasonally-weighted weekly budget pacing, **`account_audit`**
(marketing_audit) for a health-scored account diagnostic + action plan, and
**`scenario_review`** (scenario_planner) to compare conservative/base/aggressive
budget scenarios head-to-head and recommend one by conversions, CPA or ROI, and
**`promo_review`** (promo_planner) for discount break-even & promo ROI,
**`price_optimization`** (price_optimizer) for the profit-maximizing price,
**`influencer_plan`** (influencer_planner) for the best influencer mix,
**`olv_plan`** (reach_frequency) for OLV/media reach & frequency, and
**`brand_lift_study`** (brand_lift) to measure or size a brand-lift study,
**`omnichannel_reach`** (channel_overlap) for cross-channel deduplicated reach,
**`production_budget`** (production_estimator) for a production budget & timeline,
**`flighting_plan`** (media_flowchart) for a weekly media flowchart,
**`geo_test`** (geo_holdout) to design/measure a geo incrementality test,
**`sov_analysis`** (sov_tracker) for Share of Voice & ESOV growth,
**`media_quality_check`** (media_quality_score) for delivery quality scoring,
**`competitive_wargame`** (competitive_response) to war-game a competitor move,
**`pacing_forecast`** (budget_pacing_forecast) for a trend-aware pacing forecast,
**`audience_dedup`** (audience_overlap) for measured audience deduplication,
**`creative_rotation_plan`** (creative_rotation) for fatigue-aware rotation,
**`utm_audit`** (utm_taxonomy_qa) for batch UTM taxonomy QA,
**`meta_analysis`** (incrementality_meta) to pool multiple tests, and
**`exec_report`** (board_report) for a board-ready one-pager (audit + upside), and
**`creative_fatigue_check`** (creative_fatigue) to spot burning-out creatives.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessSyncing