# JevShield — combined public documentation

This generated bundle contains the product overview, current published pricing, integrations, API reference, reference-client guide and local MCP guide. Navigation: https://jevshield.com/llms.txt. Human-readable documentation: https://jevshield.com/docs. It does not contain account data, private keys or customer records. For contractual terms and full privacy details, consult https://jevshield.com/terms and https://jevshield.com/privacy.

---

Source: https://jevshield.com/index.md

# JevShield — product overview

Source: https://jevshield.com/index.md. Human-readable website: https://jevshield.com/. Facts reviewed October 6, 2026.

> JevShield classifies contact-form messages before an integration forwards an email or creates a lead. It combines an authenticated REST API, a Contact Form 7 WordPress plugin, optional lead notifications and links to an external booking page.

## What it does

JevShield checks message content for unsolicited pitches and suspicious content, returning allow, review or block with an explanation. Allowed messages can receive buyer-intent signals informed by optional business context. The result is a recommendation: your integration applies its own submission policy. An allow result does not confirm sender identity, email delivery or a sale. Review is uncertainty, not a hosted quarantine queue.

The public [live demo](https://jevshield.com/demo) checks a message without login using TypeSafe Jev. The authenticated API uses Jev when available and falls back to local rules on provider failure; inspect the live engine and model fields. JevShield is an independent application of TypeSafe Jev, not the model provider.

## Start safely

1. Try the demo with representative, non-sensitive messages.
2. Sign in at [Dashboard](https://jevshield.com/dashboard) and create an account API key. Keep it on a trusted server or machine.
3. Connect the [WordPress plugin](https://jevshield.com/solutions/wordpress) or [REST API](https://jevshield.com/docs/api.md).
4. Start in observation: record recommendations while preserving your normal submission flow. Confirm real form delivery before enabling blocking.
5. Optionally configure notifications and a public booking URL in Dashboard → Routing. Notifications require an allowed high-intent result; a booking URL is an optional visitor action.

## Product boundaries

- Message classification complements validation, rate limits and bot checks. It is not an email gateway, firewall or replacement for all CAPTCHA/bot controls.
- Logs record checks and integration-reported actions; they do not store a recoverable inbox, resend messages or prove delivery.
- The browser helper is bypassable and exposes its account key. Use server-side checks for enforcement and key privacy.
- JevShield does not synchronize calendars or book meetings itself. An external booking provider owns availability and invitations.
- No independent accuracy, fixed latency, conversion-lift or search-ranking guarantee is published. Test your own messages and integration.
- These public Markdown files help readers and tools access documentation. Publishing them does not establish crawling, indexing, citation or ranking by any search or AI service.

## Plans

| Plan | Monthly price (USD) | Included checks |
| --- | ---: | ---: |
| Free | 0 | 100 |
| Starter | 9 | 5,000 |
| Pro | 29 | 25,000 |
| Agency | 69 | 100,000 |

[Complete billing details](https://jevshield.com/pricing.md); [human-readable pricing](https://jevshield.com/pricing).

## Processing and privacy

JevShield sends submitted message text, name and email to TypeSafe for spam classification when configured. Allowed messages may also be sent to DeepSeek for lead-intent evaluation with the supplied business context; local rules can supply fallback results. A response's engine field identifies the spam classifier, not a complete list of every provider involved in processing.

Authenticated detection logs cover 7 days. Full message text storage is off by default, but classification reasons can contain message-derived details. Disabling message storage does not disable provider processing and is not a zero-retention or no-training guarantee. Optional lead notifications send contact details and intent signals to the chosen service; message text and lead reasoning are excluded unless enabled. Email uses Resend and the verified account email. Recipients and providers may retain their own copies. Read [Privacy](https://jevshield.com/privacy) before connecting a form.

## Public documentation

- [Documentation index](https://jevshield.com/llms.txt): Short guide to the public documentation.
- [Combined documentation](https://jevshield.com/llms-full.txt): Bounded collection of this overview, pricing, integrations, API, reference-client and MCP guides.
- [Pricing in Markdown](https://jevshield.com/pricing.md): Monthly plans and quota accounting.
- [Integrations in Markdown](https://jevshield.com/integrations.md): WordPress, REST, notifications, booking, clients and MCP.
- [API reference](https://jevshield.com/docs/api.md): Request fields, examples, execution reports and errors.
- [Human-readable documentation](https://jevshield.com/docs): Full setup and troubleshooting.
- [How it works](https://jevshield.com/how-it-works); [contact-form spam guide](https://jevshield.com/guides/contact-form-spam).
- [Privacy](https://jevshield.com/privacy); [Terms](https://jevshield.com/terms).

English URLs remain unprefixed. Public HTML pages also support zh, es, pt, fr, de, ja, ko, it, id, nl, pl, tr, cs, vi, ru language prefixes with self-canonical URLs and reciprocal language links. Explicit language URLs take priority over browser-language negotiation. The Markdown resources above are shared English documents, not separate translated editions. [Sitemap](https://jevshield.com/sitemap.xml) contains public language pages; account, login, dashboard and API routes are excluded.

---

Source: https://jevshield.com/pricing.md

# JevShield pricing and quotas

Source: https://jevshield.com/pricing.md. Human-readable pricing: https://jevshield.com/pricing. Facts reviewed October 6, 2026. Plan amounts and allowances are generated from the same published-plan source used by the website.

| Plan | Monthly price (USD) | Included checks |
| --- | ---: | ---: |
| Free | 0 | 100 |
| Starter | 9 | 5,000 |
| Pro | 29 | 25,000 |
| Agency | 69 | 100,000 |

## Billing and usage

Free is an ongoing allowance of 100 checks per UTC calendar month, not a time-limited trial. No credit card or paid subscription is required for its API key and WordPress integration.

Paid plans are monthly subscriptions, not pay-as-you-go credit balances. The fee does not decrease when fewer checks are used. Paid quota follows the subscription billing period. Unused checks do not roll over. Requests above quota receive HTTP 429 without automatic overage charges.

Each valid check that reserves quota uses one check. Allow, review, block and AI-to-rules fallback results all consume quota. A timeout or service error after reservation does not automatically restore a check. There is no success-only charging promise. Status verification and execution reports use no detection quota. The public demo has separate rate limits; Dashboard Playground and MCP checks use account quota.

Creem handles checkout and the customer portal. Taxes and the final total are shown at checkout. Cancel future renewals through Account & billing; access normally continues through the current paid period. Refund requests are reviewed by support, not automatically approved. See [Terms](https://jevshield.com/terms).

## Frequently asked questions

### What does the free plan include?

100 checks per UTC calendar month, with API and WordPress access. No credit card is required.

### When do paid quotas reset?

Paid quotas follow your subscription billing period and reset on a confirmed renewal. Unused checks do not roll over.

### What happens if I reach my quota?

Checks return HTTP 429 when your quota is exhausted. We do not automatically bill overage charges. Upgrade your plan or wait for your next period.

### What counts as a check, including errors?

After a request passes validation and successfully takes 1 check from your quota, that check is used. All decisions and rule fallback count. A later HTTP 503 does not automatically return it.

### What happens when I cancel?

Cancel through your Creem customer portal. Access usually continues until the end of the current paid period. Paused or expired subscriptions, full refunds and disputes can end paid access.

## Checking your allowance

Use GET https://jevshield.com/api/v1/check with your account key in x-api-key or Authorization: Bearer. This verifies the key and returns the effective plan, quota, used and remaining without classifying a message or using detection quota. Keep the key private. [API reference](https://jevshield.com/docs/api.md) documents authentication, status codes and quota-safe error handling.

Do not infer a plan from provider token prices or the public demo. Product prices are the published subscriptions above; the final purchase total is displayed at checkout. See [Terms](https://jevshield.com/terms), [product overview](https://jevshield.com/index.md) and [integration options](https://jevshield.com/integrations.md).

---

Source: https://jevshield.com/integrations.md

# JevShield integrations

Source: https://jevshield.com/integrations.md. Human-readable setup: https://jevshield.com/docs. Facts reviewed October 6, 2026.

## WordPress and Contact Form 7

Install from the [WordPress setup guide](https://jevshield.com/solutions/wordpress) or the [official WordPress.org directory](https://wordpress.org/plugins/jevshield-ai-anti-spam/). The latest [JevShield plugin ZIP](https://jevshield.com/jevshield-ai-anti-spam.zip) includes Observe only and Block high-confidence spam modes. Website ZIP releases can precede WordPress.org releases.

New installations start with Observe only. Existing configured installations retain blocking until the administrator changes mode. Observation still sends data for processing and uses quota. Confirm actual form and email delivery before switching to blocking. When the service or quota is unavailable, the JevShield WordPress integration allows the unchecked submission.

The legacy FormShield plugin retains a separate update path and settings. Business-context and exact-email override controls from that legacy plugin are not included in the JevShield plugin. Custom integrations can pass business_context to the API; Dashboard → Routing provides account-level context.

## REST API and custom receivers

| Method | Endpoint | Purpose |
| --- | --- | --- |
| POST | https://jevshield.com/api/v1/check | Classify a form submission and return a recommendation. Reserves one account check and can dispatch a configured lead webhook. |
| GET | https://jevshield.com/api/v1/check | Read key validity, plan and remaining allowance without consuming detection quota. |
| POST | https://jevshield.com/api/v1/report | Record the action your integration actually applied. Requires the receipt from a check and uses no detection quota. |

Keep the API key on a trusted server or machine. API message text accepts up to 10,000 UTF-16 code units; full body and other field limits are in the [API reference](https://jevshield.com/docs/api.md). Custom receivers must validate and enforce their own policy: allow, review and block are recommendations. Observation means recording the result without rejecting the form and reporting the action actually applied. No automatic check retries are provided because another check can consume more quota.

[Webflow](https://jevshield.com/solutions/webflow) and [Framer](https://jevshield.com/solutions/framer) guides describe integration patterns. They do not represent native marketplace plugins or a JevShield-hosted form receiver. Preserve the original platform's form delivery and abuse controls.

## Team notifications

Configure Dashboard → Routing. Optional destinations are the verified account email and one webhook in a selected format:

| Destination | Connection | Important behavior |
| --- | --- | --- |
| Email | Verified JevShield account email, delivered using Resend | Does not accept an arbitrary recipient address. |
| Slack | Slack Incoming Webhook URL | Sends a channel message without automatic mention expansion. |
| Discord | Discord channel webhook URL | Uses a confirmed webhook response; mentions are disabled. |
| Microsoft Teams | Workflows webhook accepting Adaptive Cards | Use a supported workflow URL; legacy connector URLs are not accepted as this provider. Maintain a workflow co-owner. |
| Custom | Public HTTPS JSON endpoint, including Zapier or Make | Use it to implement downstream actions under your own connected accounts. |

An allowed high-intent check triggers configured notifications. Message text and lead reasoning are off by default; contact details and intent signals are included. Enabling notifications requires the form owner's authority to share that data. Test notifications use synthetic contact details and do not consume a detection check.

Custom events use lead.high_intent or lead.test_alert with event_id, timestamp, lead_score, lead_intent, is_high_intent, recommended_action, sender_name, email, site and an optional booking_url. Use event_id for downstream deduplication. JevShield records the latest dispatch attempt, provider, service acceptance/failure and HTTP status, not a copy of the notification body. HTTP acceptance is not proof of downstream delivery or reading. Automatic retries are not performed; a notification failure does not change the classification result.

Telegram and WhatsApp are not native notification providers in this release. A custom automation requires its own bot/business setup, destination permissions and provider-specific rules. JevShield does not bridge two people's chat histories or create their external accounts.

## Booking across different calendars

Set a public HTTPS booking URL from Calendly, Cal.com, Google appointment schedules, Microsoft Bookings or another suitable provider. Connect the host calendars in that provider. The team can receive an alert in its own IM while the visitor opens a booking page in a browser; both parties need not use the same IM or calendar application.

The booking provider controls supported calendars, busy-time checks, time zones, conflicts, invitations, rescheduling and cancellation under its own plan. Verify iCloud and meeting-platform guest support there. Importing an ICS file is a snapshot, not live availability checking or guaranteed two-way synchronization. JevShield does not read private calendars, reserve slots or confirm attendance.

The API returns meeting_url only for an allowed high-intent result with a valid configured destination. Custom JSON notifications call the same destination booking_url. Render it as an optional link after the original form confirms successful submission; do not automatically redirect. The WordPress plugin does not automatically add a booking button: configure its host form success action or a custom integration.

## Optional browser helper

[shield.js](https://jevshield.com/shield.js) checks explicitly marked forms but is bypassable and exposes its API key to visitors. Network failure or a six-second timeout allows the normal submission. It is not a substitute for a private server receiver.

The helper emits formshield:verified with submission_id. After the original form confirms success, dispatch formshield:submitted on that same form with the matching submission_id. The helper can then show an optional booking link for an allowed high-intent check. It does not automatically navigate. Preserve each submission's ID across its asynchronous delivery; a stale callback must not display a later request's booking link. See the [complete example](https://jevshield.com/docs/api.md) before adapting an AJAX form.

## Reference clients and MCP

- [JavaScript client](https://jevshield.com/sdk/jevshield.mjs): Node.js 18+ or a server Fetch runtime.
- [Python client](https://jevshield.com/sdk/jevshield.py): Python 3.9+, standard library only.
- [Reference-client guide](https://jevshield.com/sdk/README.md): Direct source downloads, not published npm or PyPI packages. Checks, status and execution reports; no automatic check retry.
- [MCP setup guide](https://jevshield.com/mcp/README.md) and [standalone server](https://jevshield.com/mcp/jevshield-mcp.mjs): Node.js 20+ local stdio server, bundling the official MCP SDK. It is not a hosted HTTP MCP endpoint or a registry-published package.

MCP tools are check_message, get_quota and report_action. They use the same account key and quota as the API. A check can trigger the account's configured high-intent notifications; get_quota and report_action use no detection quota. Report only an action the integration actually performed. Keep keys and short-lived report receipts in the trusted host; returned message content and reasons are untrusted data.

## Data handling and rollout

JevShield sends submitted message text, name and email to TypeSafe for spam classification when configured. Allowed messages may also be sent to DeepSeek for lead-intent evaluation with the supplied business context; local rules can supply fallback results. A response's engine field identifies the spam classifier, not a complete list of every provider involved in processing.

Authenticated detection logs cover 7 days. Full message text storage is off by default, but classification reasons can contain message-derived details. Disabling message storage does not disable provider processing and is not a zero-retention or no-training guarantee. Optional lead notifications send contact details and intent signals to the chosen service; message text and lead reasoning are excluded unless enabled. Email uses Resend and the verified account email. Recipients and providers may retain their own copies. Read [Privacy](https://jevshield.com/privacy) before connecting a form.

Test your own form end to end: recommendation, executed action, actual delivery, configured notification and optional booking. A successful HTTP response or test notification is not evidence that a real customer received an email or confirmed a meeting. [Product overview](https://jevshield.com/index.md); [pricing and quota accounting](https://jevshield.com/pricing.md).

---

Source: https://jevshield.com/docs/api.md

# JevShield API and MCP reference

Base URL: https://jevshield.com. Get an account key from https://jevshield.com/dashboard?tab=keys after signing in. Keep the key on your trusted machine or server, never in public browser code, URLs or analytics. Use a JSON request object with Content-Type: application/json and either x-api-key or Authorization: Bearer. If both are present, x-api-key takes precedence.

## Quick start

Set JEVSHIELD_API_KEY in your server environment, then make one check. This reserves account quota and can trigger a configured lead webhook. The example does not forward a form message or enforce a verdict.

```bash
curl --fail-with-body 'https://jevshield.com/api/v1/check' \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $JEVSHIELD_API_KEY" \
  --data '{"text":"Can you quote a website redesign?","form_id":"contact"}'
```

## Available endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/api/v1/check` | Classify a form submission and return a recommendation. Reserves one account check and can dispatch a configured lead webhook. |
| GET | `/api/v1/check` | Read key validity, plan and remaining allowance without consuming detection quota. |
| POST | `/api/v1/report` | Record the action your integration actually applied. Requires the receipt from a check and uses no detection quota. |

## Check a message

POST https://jevshield.com/api/v1/check

| Field | Type | Required | Limit | Description |
| --- | --- | --- | --- | --- |
| `text` | string | Required: text or email | 10,000 UTF-16 code units | Message content. At least text or email must contain non-whitespace content. |
| `email` | string | Required: text or email | 320 UTF-16 code units | Sender email supplied by your form. Its presence does not verify sender identity. |
| `sender_name` | string | Optional | 200 UTF-16 code units | Sender name supplied by your form. A legacy alias is also accepted. |
| `business_context` | string | Optional | 1,000 UTF-16 code units | Describe the inquiries your business wants. Empty or omitted context uses the saved account context. |
| `site` | string | Optional | 2,048 UTF-16 code units | An HTTP or HTTPS site URL. Logs retain only its hostname; invalid metadata is omitted. |
| `form_id` | string | Optional | 80 characters | An integration label using letters, numbers, underscores, colons or hyphens. Invalid metadata is omitted. |

The decoded JSON body accepts up to 16,000 UTF-16 code units. At least trimmed text or email must be nonempty. Preferred fields are text and sender_name; message and content remain aliases for text, and name remains an alias for sender_name. These aliases are for existing integrations. Sending an email string does not establish email format, ownership or sender identity.

Invalid optional site/form_id metadata is omitted rather than used for enforcement. Logs retain the hostname of a valid HTTP/HTTPS site URL, not its path, query or port. Account routing context is used when per-request business_context is empty or missing.

### Response fields

| Field | Type | Meaning |
| --- | --- | --- |
| `success` | boolean | A normal classification response was returned. |
| `is_spam` | boolean: verdict === block | Compatibility flag that matches the blocking recommendation. |
| `verdict` | allow \| review \| block | A recommendation. Review is uncertain and is not an automatic hold or rejection. |
| `score` | number: 0–1 | Spam score. A rules score is a heuristic estimate, not a calibrated probability. |
| `reason` | string | Explanation of the classification. |
| `engine` | jev \| rules | Provider failures can fall back to local rules while still consuming normal quota. |
| `detected_category, category` | string | Detected message category and its compatibility alias. |
| `model, confidence` | optional | Present on successful AI results; do not require these fields on a rules result. |
| `execution_time_ms` | number | API processing duration, not complete form-to-email delivery time. |
| `quota_remaining` | number | Account checks remaining after this reservation. |
| `lead_score` | number: 0–100 | Buyer-intent score, not evidence of a purchase or verified identity. |
| `lead_intent` | sales_inquiry \| partnership \| support \| general \| spam | Routing classification, not proof of a purchase or sender identity. |
| `lead_reason` | optional string | Explanation of the buyer-intent recommendation. |
| `is_high_intent` | boolean | High-intent signal that may trigger a configured webhook. It is not inferred solely from a score threshold. |
| `recommended_action` | book_meeting \| notify_sales \| normal_inbox \| block | Routing recommendation. Your integration decides how to act on it. |
| `meeting_url` | optional string | Returned only for a high-intent result with a configured booking URL. The API does not follow it. |
| `check_id, report_token` | optional strings | Returned when logging succeeds. Keep the report token private on your trusted machine or server. |
| `logging_status` | saved \| unavailable | Logging failure does not change the classification result. |

Illustrative response only. The values below are not a measured result, accuracy claim or latency promise. Optional fields depend on the engine and log availability; use the actual receipt from your response for reporting.

```json
{
  "success": true,
  "verdict": "allow",
  "score": 0.08,
  "reason": "Example: a relevant project inquiry.",
  "engine": "jev",
  "execution_time_ms": 420,
  "lead_score": 72,
  "lead_intent": "sales_inquiry",
  "is_high_intent": false,
  "recommended_action": "normal_inbox",
  "quota_remaining": 99,
  "logging_status": "saved",
  "check_id": "CHECK_UUID",
  "report_token": "TOKEN_FROM_CHECK"
}
```

Your integration decides whether to allow or reject a submission. Review is uncertain and is not an automatic hold. An allow verdict does not confirm identity or delivery. There is no hosted inbox or quarantine queue.

## Verify a key and quota

GET https://jevshield.com/api/v1/check with the same key header. This does not classify a message or consume detection quota.

```bash
curl --fail-with-body 'https://jevshield.com/api/v1/check' \
  -H "Authorization: Bearer $JEVSHIELD_API_KEY"
```

A valid key returns valid, plan, quota, used and remaining. An invalid or inactive verification key returns HTTP 401; POST check/report uses HTTP 403 for an invalid or inactive key.

## Execution reports and logs

After your integration actually applies an action, POST https://jevshield.com/api/v1/report with the same account key and the private receipt from that check.

| Field | Type | Required | Limit | Description |
| --- | --- | --- | --- | --- |
| `check_id` | UUID string | Required | A valid UUID | Use the identifier returned by the check that your integration acted on. |
| `report_token` | string | Required | 64 lowercase hexadecimal characters | Use the private receipt returned by that check, with the same account key. |
| `action` | allowed \| blocked \| error_allowed | Required | One supported action value | The action your integration actually applied, rather than the classification recommendation. |
| `reason` | verdict \| threshold \| uncertain \| service_error \| observe \| trusted_sender | Required | One supported reason value | The policy that explains the executed action. |

Actions: `allowed`, `blocked`, `error_allowed`.

Reasons: `verdict`, `threshold`, `uncertain`, `service_error`, `observe`, `trusted_sender`.

```bash
curl --fail-with-body 'https://jevshield.com/api/v1/report' \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $JEVSHIELD_API_KEY" \
  --data '{"check_id":"CHECK_UUID","report_token":"TOKEN_FROM_CHECK","action":"allowed","reason":"observe"}'
```

Replace CHECK_UUID and TOKEN_FROM_CHECK with your actual receipt. Use allowed/observe only if your integration allowed the submission without enforcing the verdict. Receipts expire 10 minutes after record creation and are bound to the account. Identical action-and-reason retries return HTTP 200; conflicting, expired, wrong-account or unavailable receipts return 404. Reporting consumes no detection quota. Reports are limited to 300 requests per account in a fixed 60-second window, with a decoded JSON body up to 1,000 UTF-16 code units.

Account detection logs cover 7 days. Message text storage is off by default and can be enabled in the account; processing still requires submitted message content. Public demo checks are excluded. Logs do not hold, resend or restore messages. A reported allowed action does not confirm email delivery.

## Errors, quotas and retry policy

| Status | Meaning | Handling | Scope |
| --- | --- | --- | --- |
| 400 | The check or report body fails validation. | Correct the fields and size before sending a new request. | POST check / report |
| 401 | A key is missing. Key verification also uses this status for an invalid or inactive key. | Supply the key in a request header and verify it with the quota endpoint. | GET / POST check; POST report |
| 403 | A check or report key is not accepted. | Check the key on your server and replace it through your account if necessary. | POST check / report |
| 404 | The receipt is missing, expired, belongs to another account, or conflicts with an earlier report. | Use the original receipt within 10 minutes and report only the action actually performed. | POST report |
| 413 | The HTTP server rejects a body over 128 KiB before the API handler runs. | Use the smaller documented check or report body limits. | HTTP server |
| 429 | A check has exhausted its allowance, or reports exceeded 300 requests in a fixed 60-second account window. | Read your allowance or wait for the report window. Do not blindly retry checks. | POST check / report |
| 500 | The HTTP server could not complete the request. | Handle the failure in your integration; a check may already have reserved quota. | HTTP server |
| 503 | Verification, detection or reporting could not complete. | Apply your chosen fallback policy. A timeout or failure after reservation does not automatically refund quota. | GET / POST check; POST report |

A validated check reserves one quota unit before classification. Allow/review/block and AI-to-rules fallback results all use a check. Invalid input, missing/invalid keys and exhausted quota are rejected before reservation. A timeout or service failure after reservation does not automatically refund quota. Checks have no idempotency key: retrying can consume another check. The reference clients and MCP server perform no automatic check retries. Detection throughput is not a published per-minute guarantee; budget using the account allowance.

| Plan | Monthly USD | Checks |
| --- | ---: | ---: |
| Free | 0 | 100 |
| Starter | 9 | 5,000 |
| Pro | 29 | 25,000 |
| Agency | 69 | 100,000 |

Free quota resets each UTC calendar month. Paid quota follows the subscription period. Unused checks do not roll over; there are no automatic overage charges. The monthly subscription charge does not decrease when fewer checks are used. Taxes and final checkout total are shown at checkout. The public demo has separate limits; Dashboard Playground uses account quota. See https://jevshield.com/pricing and https://jevshield.com/terms.

## Server-side examples and reference clients

Direct source downloads: [JavaScript](https://jevshield.com/sdk/jevshield.mjs), [Python](https://jevshield.com/sdk/jevshield.py), [client guide](https://jevshield.com/sdk/README.md). They are not published npm/PyPI packages. JavaScript requires Node.js 18+ or a server Fetch runtime; Python requires 3.9+. Both use a fixed HTTPS API origin, refuse redirects and do not retry checks automatically. Errors expose an HTTP status, or 0 for network/timeout failures, without revealing your key.

### JavaScript

```js
// Save /sdk/jevshield.mjs beside this server file. Node.js 18+.
import { JevShieldClient, JevShieldError } from './jevshield.mjs';

const client = new JevShieldClient(process.env.JEVSHIELD_API_KEY);
try {
  const quota = await client.status(); // No detection quota used.
  const result = await client.check({
    text: 'Can you quote a website redesign?',
    form_id: 'contact'
  });
  console.log({ verdict: result.verdict, remaining: result.quota_remaining });
  // Your server applies its own submission policy. No automatic retry.
} catch (error) {
  if (error instanceof JevShieldError) console.error(error.status, error.code);
  else throw error;
}
```

### Python

```python
# Save /sdk/jevshield.py beside this script. Python 3.9+.
import os
from jevshield import JevShieldClient, JevShieldError

client = JevShieldClient(os.environ["JEVSHIELD_API_KEY"])
try:
    quota = client.status()  # No detection quota used.
    result = client.check({
        "text": "Can you quote a website redesign?",
        "form_id": "contact"
    })
    print({"verdict": result["verdict"], "remaining": result["quota_remaining"]})
except JevShieldError as error:
    print(error.status, error.code)  # No automatic retry.
```

### PHP

```php
<?php
// Run in a server-side PHP handler with the cURL extension.
$key = getenv('JEVSHIELD_API_KEY');
if (!$key) { throw new RuntimeException('Set the server API key first.'); }
$curl = curl_init('https://jevshield.com/api/v1/check');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'x-api-key: ' . $key],
    CURLOPT_POSTFIELDS => json_encode(['text' => 'Can you quote a website redesign?'])
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
if ($body === false || $status !== 200) {
    throw new RuntimeException('Check failed; do not automatically retry.');
}
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
echo json_encode(['verdict' => $result['verdict']]);
// Apply your own submission policy; a verdict does not prove delivery.
```

## MCP server

Download [jevshield-mcp.mjs](https://jevshield.com/mcp/jevshield-mcp.mjs), [setup guide](https://jevshield.com/mcp/README.md), [SHA256SUMS](https://jevshield.com/mcp/SHA256SUMS), and [third-party notices](https://jevshield.com/mcp/THIRD_PARTY_LICENSES.txt). Requires Node.js 20+. The standalone download includes the official MCP SDK and uses local stdio transport; no package installation is required. It is not a hosted HTTP MCP endpoint or a registry-published package.

```bash
# Download the standalone server. Requires Node.js 20+.
curl --fail 'https://jevshield.com/mcp/jevshield-mcp.mjs' -o jevshield-mcp.mjs

# Set JEVSHIELD_API_KEY in your trusted process environment.
node /absolute/path/jevshield-mcp.mjs
```

For a stdio client that uses mcpServers configuration, replace the absolute file path and key placeholder. Keep this local configuration private. Your host launches the process and exchanges protocol messages over stdio; normal API requests go to https://jevshield.com.

```json
{
  "mcpServers": {
    "jevshield": {
      "command": "node",
      "args": ["/absolute/path/jevshield-mcp.mjs"],
      "env": { "JEVSHIELD_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

| Tool | Behavior |
| --- | --- |
| check_message | Makes one authenticated check, uses quota and can trigger your configured high-intent webhook. Returns a recommendation; it does not apply your form policy. |
| get_quota | Verifies the key and reads the allowance without detection quota. |
| report_action | Records an action only after you actually applied it, using the account-bound receipt. No detection quota; report limits still apply. |

Suggested prompts: "Check my remaining JevShield quota" or "Classify this contact message with JevShield and explain the verdict." Review tool calls that send message content or change execution logs. MCP errors retain the HTTP status and do not automatically retry a quota-consuming check.

MCP tool results can include a report_token visible to your trusted AI host, whose conversation history may retain it. This short-lived receipt still requires the same account key and expires after 10 minutes. Keep receipts private; the production API key is never returned by the MCP tools.

## Observe before blocking and WordPress

For custom integrations, observation is your receiver policy: call the check endpoint, record the verdict, continue normal submission flow and report the action actually applied. Observation still transmits content for processing and consumes quota.

The latest [JevShield WordPress plugin ZIP](https://jevshield.com/jevshield-ai-anti-spam.zip) includes Protection Mode. New installations use Observe only; existing configured installations retain blocking until changed. When a receipt is available, the plugin reports its executed action. Test actual form delivery before switching to Block high-confidence spam. WordPress.org releases may follow the website ZIP. See the [WordPress setup guide](https://jevshield.com/solutions/wordpress).

The legacy FormShield plugin retains its separate settings and update path. Its business-context and exact-email override settings are not part of the JevShield plugin. API business_context and execution-report reasons remain available to custom integrations.

## Lead routing and optional browser helper

Configure Dashboard → Routing with business context, a public HTTPS booking URL, verified-account email notifications and/or one webhook. Supported formats: Slack Incoming Webhooks, Discord channel webhooks, Microsoft Teams Workflows Adaptive Cards, and custom JSON for Zapier/Make/your endpoint. Notifications require an allow + high-intent result. Message text and lead reasoning are omitted by default; submitted contact details and intent signals are included. Enable message inclusion separately and disclose your selected providers in the form privacy notice.

Custom webhook events contain event_id, event (lead.high_intent or lead.test_alert), lead_score, lead_intent, is_high_intent, recommended_action, sender_name, email, site, timestamp and a configured booking_url. Use event_id for downstream deduplication. Automatic retries are not performed. Dashboard records the latest bounded dispatch attempt, service acceptance/failure and HTTP status. HTTP acceptance is not downstream delivery or a read receipt.

Different IM/calendar tools do not require shared accounts: the team receives a notification in its own tool and the visitor chooses a slot on a public booking page. Use Calendly, Cal.com, Google appointment schedules or Microsoft Bookings and connect host calendars there. The booking provider handles availability/time zones/conflicts/invitations/rescheduling under its supported integrations and plan. Confirm iCloud support separately. An imported ICS file is only a snapshot, not live availability or guaranteed synchronization.

Render meeting_url as an optional HTTPS link only after the original form confirms successful submission. JevShield does not reserve slots or automatically navigate to the URL. The optional browser helper emits submission_id with formshield:verified. After success, dispatch formshield:submitted on the same form with detail: { submission_id: idForThatRequest }. It displays a link only for the matching, allowed high-intent check. Preserve the ID with the same submission so stale callbacks cannot open a link. The WordPress plugin does not automatically show this button; configure its host form success action or a custom integration.

```html
<form data-formshield> ... </form>
<script src="https://jevshield.com/shield.js" data-key="YOUR_API_KEY"></script>
```

```js
// Add this listener once to the form already used by your integration.
let checkedSubmission;
form.addEventListener('formshield:verified', (event) => {
  checkedSubmission = event.detail.submission_id;
});

// Adapt your EXISTING AJAX submit handler; do not add a second submit listener.
async function yourExistingSubmitHandler(event) {
  event.preventDefault();
  const submission_id = checkedSubmission; // Capture before this request starts.
  checkedSubmission = undefined; // Never carry an old check into a later request.

  // Keep your actual delivery request and its success condition here.
  const result = await sendYourExistingForm(new FormData(form));
  if (result.confirmedSuccess && submission_id) {
    form.dispatchEvent(new CustomEvent('formshield:submitted', {
      detail: { submission_id } // This request's ID, never a later global value.
    }));
  }
}
```

The optional helper checks only explicitly marked forms, is bypassable and exposes the key to visitors. It allows submission after a network failure or 6-second timeout. Use server-side checks to keep the key private and enforce policy. Test AJAX form plugins before enabling it. The helper is not the server-side reference client or MCP server.

## Edge access and client identification

The published reference clients send an identifying User-Agent. If a custom server client receives Cloudflare 1010 or a non-JSON response, use an honest application User-Agent such as YourAppName/1.0 and inspect the status/content type. A no-key GET /api/v1/check should reach the API and return JSON 401 without consuming quota. Do not automatically retry POST checks after a timeout or uncertain result; quota may already be reserved. Never disable API authentication to bypass an edge rule.

## Further reading

- [Documentation](https://jevshield.com/docs)
- [Privacy](https://jevshield.com/privacy)
- [Terms](https://jevshield.com/terms)

API and MCP guidance reviewed October 5, 2026.

---

Source: https://jevshield.com/sdk/README.md

# JevShield server reference clients

Download and keep the file alongside your server code:

- [JavaScript client](https://jevshield.com/sdk/jevshield.mjs) — Node.js 18+ or a server Fetch runtime.
- [Python client](https://jevshield.com/sdk/jevshield.py) — Python 3.9+, standard library only.
- [API documentation](https://jevshield.com/docs/api.md).

These are downloadable reference clients, not published npm or PyPI packages. No package install is required. Both use the fixed API origin `https://jevshield.com`. Keep your API key in a server environment variable; do not place these clients or your key in browser code, public repositories, logs, or analytics.

## JavaScript

Save `jevshield.mjs` locally, then use it in a server `.mjs` file:

```js
import { JevShieldClient, JevShieldError } from './jevshield.mjs';

const client = new JevShieldClient(process.env.JEVSHIELD_API_KEY, { timeoutMs: 10_000 });
try {
  const status = await client.status(); // GET: checks validity/allowance; no detection quota.
  if (!status.valid) throw new Error('Check your server API key.');
  const result = await client.check({ text: 'Can you quote this project?', form_id: 'contact' });
  console.log({ verdict: result.verdict, remaining: result.quota_remaining });
  // Your application decides and performs its own submission/delivery policy.
} catch (error) {
  if (error instanceof JevShieldError) console.error(error.status, error.code, error.message);
  else throw error;
}
```

## Python

Save `jevshield.py` beside your server script:

```python
import os
from jevshield import JevShieldClient, JevShieldError

client = JevShieldClient(os.environ["JEVSHIELD_API_KEY"], timeout=10)
try:
    status = client.status()  # GET: does not consume detection quota.
    result = client.check({"text": "Can you quote this project?", "form_id": "contact"})
    print({"verdict": result["verdict"], "remaining": result.get("quota_remaining")})
    # Apply your own submission/delivery policy; the client takes no such action.
except JevShieldError as error:
    print(error.status, error.code, error.error)
```

## Methods and errors

- `check(payload)` sends one `POST /api/v1/check` and returns the JSON object.
- `status()` sends one `GET /api/v1/check`. It does not consume detection quota.
- `report(payload)` sends one `POST /api/v1/report`. After your integration actually applies its policy, pass the returned `check_id` and private `report_token`, plus the action and reason you applied. Reporting uses no detection quota. See the API documentation for valid values and token expiry.

The clients do not send form messages, block submissions, hold a review inbox, or follow booking links. `review` means uncertain, and `block` is a recommendation that your integration must interpret. An `allow` result does not prove delivery or sender identity.

HTTP errors raise `JevShieldError` with their HTTP `status`; network/timeout errors use `status=0`. Errors expose `code` and a sanitized `error` message (`message` also exists in JavaScript). Redirects are refused. Timeouts default to 10 seconds; JavaScript accepts 1–120,000 milliseconds and Python accepts greater than 0 through 120 seconds. Python bounds caller waiting with a daemon transport thread; after a timeout that request may still finish.

**No automatic retries are performed.** A detection request may consume quota before an error or timeout reaches your server. Do not assume failed checks are free or blindly retry them. Public-demo limits and subscription quotas are separate from these authenticated clients.

For repository tests only, JavaScript accepts an explicit `options.fetch` transport and Python's `_open(request, timeout)` helper can be overridden with a local fixture transport. These seams never configure a different production API origin. The accompanying tests use synthetic keys and local fixtures, not live accounts.

---

Source: https://jevshield.com/mcp/README.md

# JevShield MCP server

Version 1.0.0. Requires **Node.js 20 or newer**. The single-file download bundles
the official Model Context Protocol TypeScript SDK (`@modelcontextprotocol/server`
2.3.1), including its stdio transport. No npm installation is required to run it.

Download `https://jevshield.com/mcp/jevshield-mcp.mjs` to your computer. Optionally
compare its SHA-256 with `https://jevshield.com/mcp/SHA256SUMS`. The same directory
contains `THIRD_PARTY_LICENSES.txt`; dependency notices are also inside the bundle.

## Configure your MCP client

Use the downloaded file's **absolute path**, and replace the example key with your
own JevShield API key in your client's private MCP configuration. Do not put a key
in a shared repository, a browser script or the command arguments.

```json
{
  "mcpServers": {
    "jevshield": {
      "command": "node",
      "args": ["/absolute/path/jevshield-mcp.mjs"],
      "env": {
        "JEVSHIELD_API_KEY": "YOUR_JEVSHIELD_API_KEY"
      }
    }
  }
}
```

This is a local **stdio** server: your MCP client starts the Node.js process and
communicates over stdin/stdout. It calls the fixed authenticated HTTPS API at
`https://jevshield.com`. The download URL is **not a remote MCP endpoint**. Use an
MCP client with local stdio support, such as a desktop client, editor or CLI.
Exact configuration location and restart behavior depend on the client.

For a shell session, set `JEVSHIELD_API_KEY` in the environment and then run
`node /absolute/path/jevshield-mcp.mjs`. Startup waits for MCP messages; it does not
print a dashboard or call the API. Missing or invalid environment setup exits with
a short stderr message. Stdout contains MCP protocol messages only.

## Tools

| Tool | API request | Behavior |
| --- | --- | --- |
| `get_quota` | `GET /api/v1/check` | Read key validity, effective plan and remaining checks. Does not consume detection quota. |
| `check_message` | `POST /api/v1/check` | Classify a message and return a recommendation, scores, quota and optional report receipt. Reserves one account check and can trigger the account's configured high-intent webhook. |
| `report_action` | `POST /api/v1/report` | Record the action the integration actually performed. Does not execute or deliver the form, and does not consume a detection check. |

### Check a message

`check_message` accepts these named arguments. Supply nonblank `text` or `email`.
Only the documented field names are accepted; the REST API's aliases are not MCP
argument names.

| Argument | Limit |
| --- | --- |
| `text` | 10,000 JavaScript string units |
| `email` | 320 string units; the API does not enforce email format |
| `sender_name` | 200 string units |
| `business_context` | 1,000 string units; account context applies when absent or empty |
| `site` | Optional HTTP(S) URL, at most 2,048 string units; only hostname is logged |
| `form_id` | Optional identifier of 1–80 ASCII letters, digits, underscore, colon or hyphen |

The serialized check JSON must also be at most 16,000 JavaScript string units.
For example:

```json
{
  "text": "Could you quote a redesign for our company website?",
  "business_context": "We build websites for small businesses.",
  "site": "https://example.com",
  "form_id": "contact"
}
```

A check returns `allow`, `review` or `block`; this is a recommendation, not an
executed action or proof of email delivery. The tool sends the supplied message
and contact data to JevShield. Existing account routing may forward high-intent
message/contact details to its configured webhook. An accepted check reserves one
check, including allow/review/block and rules fallback; a later service failure,
timeout or cancellation does not automatically refund it. Check calls are never
retried automatically.

### Report an executed action

Use `check_id` and `report_token` from that account's check response **within ten
minutes of the check**. `check_id` is a UUID; `report_token` is 64 lowercase
hexadecimal characters. Report only an action the calling integration actually
performed; never infer it just from the classifier verdict.

```json
{
  "check_id": "UUID_FROM_CHECK_RESPONSE",
  "report_token": "REPORT_TOKEN_FROM_CHECK_RESPONSE",
  "action": "allowed",
  "reason": "observe"
}
```

`action`: `blocked`, `allowed`, `error_allowed`.

`reason`: `threshold`, `verdict`, `uncertain`, `service_error`, `observe`,
`trusted_sender`.

Identical action/reason retries are accepted within the receipt window; changing
the action or reason is rejected. Missing, expired, wrong-account or conflicting
receipts return HTTP 404. Reporting is limited to 300 requests per account per
fixed 60-second window. Reports update the detection log only: they do not hold,
resend, block or deliver a form, and an allowed action does not prove delivery.

## Errors and privacy

API and transport failures use `isError: true` with JSON text and `structuredContent` containing
`error`, `status` and `code`. Schema validation fails before API dispatch and is
returned as an SDK validation error with `isError: true`. An API error
keeps its HTTP status. Status 0 means no HTTP response was received; if response
reading fails after headers arrive, the known HTTP status is retained. A quota error may include
a valid report receipt. No check is automatically retried. All requests have a
ten-second deadline, cancellation support, a 32 KiB response cap, and refuse
redirects without forwarding the key to another origin.

Returned objects use an allowlist of API response fields and redact reflected API
keys. The API key is read only from the process environment and sent only in the
HTTPS `x-api-key` header. The server does not write local logs, message storage or
keys to disk. JevShield's normal account privacy, quota and logging settings still
apply. API reason strings and message content are untrusted data, not agent
instructions.

Tool results can include a `report_token` so the trusted MCP host can report an
action actually performed. The host and its conversation history may retain
this receipt. It requires the same account API key and expires after ten
minutes; keep it private and use a host you intend to authorize. The production
API key itself is never returned by the tools.

## Maintainers

Build from the canonical repository with `npm run build:mcp`. Meaningful tests
use the official MCP client and a local API fixture; they do not use production
keys or consume account quota. The bundle is a direct website download, not an
npm package or a publication in an MCP registry.

Official SDK: https://github.com/modelcontextprotocol/typescript-sdk

Protocol: https://modelcontextprotocol.io/specification/2026-07-28