jev-marketing
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jev-marketing score these creative briefs for hook and brand fit"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Jev Marketing
Seven marketing decisions. One small engine.
An open-source Python toolkit for inspecting ads, scoring briefs, reviewing search terms, detecting fatigue signals, comparing landing-page promises, and assessing business lead fit. Deterministic calculations handle counts and dates. Optional Jev calls handle structured classification and scoring.
Explore the interactive demo · Read the source · MIT license

The browser presentation uses synthetic examples and frozen, deterministic engine output. It does not call a model. There are no benchmark or return-on-investment claims.
Seven workflows
Workflow | What it does | What to review |
| Tags supplied ad records by hook, creative format, and offer; calculates observed days running. | Tags describe the imported sample, not the entire ad library. |
| Groups observed 60-day longevity by format with eligible denominators and censored records. | Descriptive sample counts, not survival probabilities or profitability. |
| Scores the hook, brand fit, and readiness of a supplied creative brief. | Scores do not predict ad performance. Low confidence routes to review. |
| Classifies supplied search terms and exports negative keyword candidates. | Review conversions and match types before changing an account. |
| Compares frequency and CTR across two sufficiently sized observation windows. | A fatigue signal is an observation, not causal proof. |
| Scores supplied ad promises against supplied landing-page text. | No crawling, usability audit, factual verification, or conversion prediction. |
| Scores submitted business facts from 0 to 100 against an explicit ideal-customer profile. | Business fit only, with no sensitive demographic criteria. |
Related MCP server: PrePilot MCP Server
Quickstart
Python 3.11 or newer recommended. The runtime uses the Python standard library, with no third-party runtime dependencies.
git clone https://github.com/stas4000/jev-marketing.git
cd jev-marketing
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m jev_marketing demoOn Windows, activate with .venv\Scripts\activate instead. No API key or network call is needed for the demo. The installed jev-marketing command exposes the same interface.
Run one workflow and save its output:
python -m jev_marketing list
python -m jev_marketing run ad_tags \
--input examples/ad_tags.json --mode demo --output ad-tags.jsonReview a CSV search-term export with a separate context file:
python -m jev_marketing run search_terms \
--input examples/search_terms.csv \
--context examples/search_terms_context.json \
--mode demo --output search-review.jsonCSV import is supported for search_terms; other workflows use JSON. The tool produces JSON, including candidates and their evidence, without writing to an ad account.
Input schema
Each JSON input is an object containing records plus the context required by its workflow. Start from the complete, runnable files in examples/.
Context | Fields |
Observation date |
|
Brand |
|
Ideal customer |
|
Workflow | Record fields |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Dates, numeric values, record IDs, and workflow-specific constraints are validated before analysis. Fatigue windows must have equal duration and must not overlap. Input and output records retain source IDs so results can be traced to the supplied data.
Live Jev
Live calls are opt-in. Store credentials in environment variables, never input files or command-line flags. Set TYPESAFE_API_KEY securely in your environment for the default direct provider, or OPENROUTER_API_KEY for OpenRouter.
# Uses TYPESAFE_API_KEY from your environment.
python -m jev_marketing run briefs \
--input examples/briefs.json --mode live \
--provider typesafe --output live-briefs.json
# Uses OPENROUTER_API_KEY from your environment.
python -m jev_marketing run leads \
--input examples/leads.json --mode live \
--provider openrouter --output live-leads.jsonProvider | Endpoint | Model | Environment variable |
TypeSafe |
|
|
|
OpenRouter |
|
|
|
The five language workflows use typed choice or score questions. survival and fatigue are calculations and do not need a model, including in live mode. The default review threshold is 0.7; override with --confidence-threshold when you have validation evidence for your use case.
Jev scores use an explicit three-level rubric: weak, partial, or strong support. The result maps these levels to a 0–100 presentation. This is a rubric score, not a precise business probability. The deterministic demo uses illustrative confidence 0.5, which routes its model-based examples to review under the default threshold. Demo probabilities are fixtures, not calibrated uncertainty.
Live mode sends supplied context and records to the configured provider. Minimize personal data and use only data you are authorized to process. Provider failures are surfaced without automatic retries; output files are replaced only after a complete successful run. Usage fields reflect provider data where available; unavailable billing and token values remain unknown.
Official references: API contract, choice primitive, score primitive, models. Provider availability and model aliases may change.
Output and evidence
Every result includes schema_version, workflow, mode, method, limits, usage, and rows, with a summary where relevant. Each row retains its source ID, decision, confidence where applicable, and supporting evidence. The schema also carries workflow-specific tags, scores, counts, or candidate fields.
The presentation's docs/data.json is generated by the engine, not manually written:
python -m jev_marketing demo --output docs/data.json
python -m http.server 8080 --directory docsOpen http://localhost:8080. The no-build site works from GitHub Pages under a repository subpath. Readers can select all seven examples, inspect input and output, and download the selected JSON. It has no account connection or analytics. The page loads Roboto from Google Fonts, with a local system-font fallback.
Measured live check
On 20 September 2026, a separate live check sent nine synthetic records through four workflows on OpenRouter. The provider reported $0.00021126 for nine calls. Sequential wall time was 4.767 seconds, including CLI startup. The resolved model was typesafe/jev-1.13-20260917.
A buyer query was kept, while job-seeking and educational queries became negative candidates. Matched and mismatched landing examples scored 99 and 0; matching and poor-fit business leads scored 99 and 0. Both creative briefs were retained for review because their confidence was low. These are observed synthetic-case outputs, not evidence of production accuracy, calibrated confidence, or typical latency and cost.
See the sanitized live check results. The interactive browser workbench continues to show deterministic demo results, not this live run.
MCP
The same workflows are available through a newline-delimited MCP stdio server:
python -m jev_marketing mcpConfigure an MCP client to launch that command from this checkout or its installed environment. Use the client's tool discovery to inspect the seven workflow schemas. Credentials for live calls must be supplied through the server process environment. MCP tools share the CLI validation and decision engine.
Tests
All external provider calls in the test suite are mocked:
python -m unittest discover -s tests -v
python -m jev_marketing demo --output /tmp/jev-marketing-demo.jsonSee CONTRIBUTING.md for fixture regeneration and browser checks.
Limitations
This is an imported-data toolkit. It does not scrape Meta's ad library, connect to an ad account, apply negatives, upload conversions, or change budgets.
An ad observed running for 60 days may be unprofitable. The longevity summary describes the supplied sample and its observation window; it does not model survival or generalize to all ads.
Keyword heuristics in demo mode are intentionally limited. They exist for reproducibility and interface inspection, not production-quality language understanding.
Live results depend on the model, supplied evidence, rubric, and thresholds. A confident result can still be wrong. Validate on your own held-out examples.
Fatigue thresholds are a transparent heuristic. Inadequate data must remain insufficient; CTR movement does not identify its cause.
Lead scoring uses an explicit business profile and rejects supported sensitive-field inputs. Free text still needs review: do not submit sensitive personal facts or proxy criteria.
A landing-page alignment score is not factual, legal, accessibility, or conversion assurance.
No speed, cost, accuracy, or return-on-investment guarantees are made.
Provenance
Inspired by this seven-workflow marketing post. This repository is an independent implementation by Stas Sorokin, not an official TypeSafe product. All bundled company, ad, search-term, brief, and lead examples are synthetic. The original post is inspiration, not experimental evidence for this toolkit.
MIT licensed. See LICENSE.
Available Tools
7 toolsad_tagsC
Imported records only, not a complete ad library. Tags are judgments; days observed are not profitability. Default demo mode uses synthetic heuristic decisions, never Jev.
Inputs: input (required), mode, provider, confidence_threshold.
briefsC
Rubric scores are judgments, not predictions of ad survival, performance, or conversion lift. Default demo mode uses synthetic heuristic decisions, never Jev.
Inputs: input (required), mode, provider, confidence_threshold.
fatigueB
Heuristic alert on comparable supplied windows, not causal proof. Audience, placement, spend and seasonality can confound it. Default demo mode uses synthetic heuristic decisions, never Jev.
Inputs: input (required), mode, provider, confidence_threshold.
landing_matchC
Supplied text only. No page fetching or visual, legal, tracking, accessibility, or conversion audit. Default demo mode uses synthetic heuristic decisions, never Jev.
Inputs: input (required), mode, provider, confidence_threshold.
leadsB
Business facts versus the supplied ICP only. No enrichment, protected-trait scoring, or automatic rejection. Default demo mode uses synthetic heuristic decisions, never Jev.
Inputs: input (required), mode, provider, confidence_threshold.
search_termsC
Negative keyword candidates require human review. No keyword match types inferred and no ad accounts changed. Default demo mode uses synthetic heuristic decisions, never Jev.
Inputs: input (required), mode, provider, confidence_threshold.
survivalA
Descriptive 60-day longevity in this supplied cohort only. Selection/survivor bias can dominate. Not calibrated survival odds or profitability. Default demo mode uses synthetic heuristic decisions, never Jev.
Inputs: input (required), mode, provider, confidence_threshold.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a clearly distinct marketing analytics domain: ad tags, cohort survival, creative briefs, search terms, fatigue, landing page match, and lead qualification. No two tools overlap in purpose or output, and the descriptions reinforce their unique boundaries.
All tool names are lowercase nouns, with underscores used only for multi-word names (ad_tags, search_terms, landing_match). They are consistent in style, though they do not follow a verb_noun action pattern, making the naming slightly less predictable for an agent.
Seven tools is well within the ideal 3-15 range and directly matches the apparent scope of a marketing assessment suite. Each tool earns its place and covers a different facet without bloat.
The set covers the main aspects one would expect from a marketing audit/analysis server: ad tagging, longevity, creative quality, search term negatives, fatigue, landing page alignment, and lead fit. Minor gaps exist, such as no tool for budgeting, audience analysis, or reporting/export, but these do not severely hinder the core diagnostic purpose.
Maintenance
Related MCP Connectors
Creative-intelligence MCP for campaign strategy, ad builds, QA, and reporting.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Marketing MCP: social, email, SMS, CRM, paid ads, analytics. OAuth; confirm before send/spend.
Work with marketing activity and available campaign data in your connected workspace. Setup: In a remote MCP client that supports Streamable HTTP and OAuth, add https://platform.samuelz.com/api/v1/mcp/operator?toolset=marketing. Sign in to Samuelz and select your authorized workspace. An active workspace membership and the relevant module permissions are required. Review the requested permissions before authorizing. Existing approval requirements continue to apply.
Related MCP Servers
- AlicenseCqualityCmaintenanceMCP server for Salesforce marketing and revenue ops teams. 47 tools covering leads, contacts, accounts, campaigns, campaign members, tasks, and 17 reporting tools including campaign ROI, lead-source attribution, pipeline-by-campaign, multi-touch campaign influence, MQL trend, forecast summary, and the native SFDC Reports API.471-
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to compose and execute marketing campaigns by mapping free-form intent to a deterministic plan of over 1,000 production-tested skills, supporting multiple workflows across paid ads, SEO, content, and more.MIT
- AlicenseAqualityDmaintenanceProvides MCP tools for lead qualification, enabling evidence gathering from CRM, scoring, and knowledge base with role-based access and deterministic decision gating.4AGPL 3.0
- FlicenseAqualityDmaintenanceAn MCP server that turns discovery → enrichment → scoring → outreach into callable tools, scoped to 72BPM's four practice areas.8-