Performs deterministic preflight linting for SMS and iMessage to prevent silent carrier filtering and segment blowups.
Also known as abryfs/willitsend
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Oct 4, 2026
- License
- MIT
What is willitsend MCP?
willitsend performs deterministic preflight linting for SMS and iMessage to prevent silent carrier filtering and segment blowups.
Summary generated from the project's README
About willitsend MCP server
willitsend provides a deterministic preflight check for outbound SMS and iMessage to prevent messages from being silently filtered by carriers. It acts as a verification layer between an AI agent and a messaging API, catching issues like missing opt-out instructions, brand identification failures, and unexpected segment blowups caused by special characters. This tool is designed for developers building autonomous agents that send text messages at scale.
The server can be used locally via a CLI or integrated into MCP clients like Claude Code. It is stateless and does not store message content. While it runs offline by default, providing an AGENTPHONE_API_KEY enables live lookups for phone-number destinations. It uses a verdict system to return pass, warn, block, or needs_context statuses, helping agents correct drafts before they are sent to the carrier.
What you can do with it
- 1Prevent silent carrier filteringVerify that a first message includes required opt-out instructions to avoid being dropped by carriers without an API error.
- 2Calculate message segments accuratelyCheck if adding an emoji or special character will cause a message to expand into multiple billable segments.
- 3Automate compliance correctionsUse the returned fix strings to automatically update a message draft that failed a compliance check.
Written from the project's README. Every use case is checked against a quote from it.
How to install willitsend MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall willitsend MCP in Claude Code
$ claude mcp add --env 'AGENTPHONE_API_KEY=<YOUR_AGENTPHONE_API_KEY>' willitsend -- npx -y willitsendInstall willitsend MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"willitsend": {
"command": "npx",
"args": [
"-y",
"willitsend"
],
"env": {
"AGENTPHONE_API_KEY": "<YOUR_AGENTPHONE_API_KEY>"
}
}
}
}Install willitsend MCP in VS Code
.vscode/mcp.json
{
"servers": {
"willitsend": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"willitsend"
],
"env": {
"AGENTPHONE_API_KEY": "<YOUR_AGENTPHONE_API_KEY>"
}
}
}
}Install willitsend MCP in VS Code CLI
$ code --add-mcp '{"name":"willitsend","type":"stdio","command":"npx","args":["-y","willitsend"],"env":{"AGENTPHONE_API_KEY":"<YOUR_AGENTPHONE_API_KEY>"}}'Install willitsend MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"willitsend": {
"command": "npx",
"args": [
"-y",
"willitsend"
],
"env": {
"AGENTPHONE_API_KEY": "<YOUR_AGENTPHONE_API_KEY>"
}
}
}
}Install willitsend MCP in Codex
$ codex mcp add willitsend --env 'AGENTPHONE_API_KEY=<YOUR_AGENTPHONE_API_KEY>' -- npx -y willitsendInstall willitsend MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.willitsend] command = "npx" args = ["-y", "willitsend"] [mcp_servers.willitsend.env] AGENTPHONE_API_KEY = "<YOUR_AGENTPHONE_API_KEY>"
Install willitsend MCP in Gemini CLI
$ gemini mcp add -s user -e 'AGENTPHONE_API_KEY=<YOUR_AGENTPHONE_API_KEY>' willitsend npx -- -y willitsendInstall willitsend MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"willitsend": {
"command": "npx",
"args": [
"-y",
"willitsend"
],
"env": {
"AGENTPHONE_API_KEY": "<YOUR_AGENTPHONE_API_KEY>"
}
}
}
}Configuration
AGENTPHONE_API_KEYSecretOptional API key for live carrier/capabilities lookup. The linter runs fully offline without it.
| Name | Description | |
|---|---|---|
| AGENTPHONE_API_KEY | Optional API key for live carrier/capabilities lookup. The linter runs fully offline without it. | Secret |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableabryfs/willitsend is public and reachablegithub.com/abryfs/willitsend ↗Pass
- Package names this repository as its sourcewillitsend names abryfs/willitsend as sourcenpmjs.com/package/willitsend ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-04github.com/abryfs/willitsend ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from willitsendPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubwillitsend
Your AI agent sends texts. Carriers silently drop the non-compliant ones, and the API never tells you. willitsend is the missing check between the model and the carrier: a deterministic preflight for outbound SMS/iMessage that catches silent filtering, segment blowups, and dropped iMessage features before you spend the send.
Try it in the browser: runs client-side, nothing leaves the page.
npx -y -p github:abryfs/willitsend willitsend-cli "Hey! Your appointment is tomorrow at 2pm." --first-message
Verdict: BLOCK
Segments: 1 (gsm7, 41 septets)
Channel: unknown
[BLOCK] first-message.opt-out: First message doesn't include opt-out instructions (e.g. "Reply STOP
to unsubscribe"). Carriers may silently filter first messages that lack one, with no API error.
Fix: Append "Reply STOP to unsubscribe." to the message body.
Source: https://docs.agentphone.ai/documentation/reference/messaging-rate-limits#first-message-requirements
[WARN] first-message.opt-in: No opt-in acknowledgment language found …
[INFO] first-message.brand: No brand_name was provided …
The problem
Messaging APIs report "sent" when a message reaches the downstream carrier, not when it reaches a phone. AgentPhone's rate-limit docs spell out the consequence: first messages that skip brand identification, opt-in acknowledgment, or opt-out instructions "may be silently filtered by carriers. The API will not return an error."
AI agents now send texts autonomously, and nothing sits between the model and the carrier. An agent that drops the opt-out line gets no error and no delivery. An agent that adds one emoji turns a 160-character message into three billable segments and never notices.
willitsend is the missing check: a deterministic, stateless lint for a draft message. Text and context in, verdict and evidence out. It sends nothing and stores nothing.
sequenceDiagram
participant A as AI agent
participant W as willitsend
participant API as Messaging API
participant C as Carrier
participant P as Phone
rect rgba(255,69,58,0.08)
note over A,P: without preflight
A->>API: send_message (no opt-out language)
API-->>A: "sent" ✓
C--xP: silently filtered. no error, no delivery
end
rect rgba(52,199,89,0.08)
note over A,P: with preflight
A->>W: preflight_message(draft, context)
W-->>A: BLOCK · missing opt-out · fix + citation
A->>W: preflight_message(fixed draft)
W-->>A: PASS
A->>API: send_message
API-->>A: "sent" ✓
C->>P: delivered
end
Why not just prompt the rules into your agent?
A fair question: AgentPhone's docs are agent-readable, so you could feed them into every generation call and ask the model to comply. Two things break, and one gets expensive:
- Generation is probabilistic; verification is deterministic. A model with the rules in context complies usually. This checker returns the same verdict every time, and its failure mode is a visible finding rather than a silently filtered message. Compose-time guidance and pre-send verification are complements — this repo ships both (the agent skill is the compose-time half).
- Models can't do segment math. Septet counting, GSM-7 extension characters, encoding flips from one smart quote, placement-aware packing — token-based models are structurally bad at exactly this arithmetic. No amount of prompting fixes it; a 300-line deterministic function does.
- The token math, measured (char-count/4 heuristic on the actual pages, July 2026):
| Approach | Tokens per message | 10,000 msgs/day at $3/M input |
|---|---|---|
| Feed both AgentPhone doc pages into each generation call | ~7,700 | |
preflight_message call result (default) |
~250 (+ ~1,450 once per session for the tool definition) | ~$7.50/day |
preflight_message with response_format: "concise" |
~4 on pass, ~44 on block (measured) | ~$0.35/day at a 90% pass rate |
Roughly 30× fewer tokens per message in default mode — several hundred× in concise mode — and the checker's own compute rounds to zero (~4µs locally, no API). If you compress the rules into your system prompt instead — our skill file does, at ~950 tokens — you keep the compose-time benefit but still have no verifier and no segment math. Bulk senders feel this most: the tool exists precisely for AI agents sending texts at volume.
Quickstart
As an MCP tool (Claude Code):
claude mcp add willitsend -- npx -y -p github:abryfs/willitsend willitsend-mcp
or in any MCP client config:
{
"mcpServers": {
"willitsend": {
"command": "npx",
"args": ["-y", "-p", "github:abryfs/willitsend", "willitsend-mcp"]
}
}
}
For AI agents — paste this block into your agent (or point it at this README):
Install the willitsend MCP server (pre-send SMS/iMessage lint, no API key needed):
- Claude Code: run `claude mcp add willitsend -- npx -y -p github:abryfs/willitsend willitsend-mcp`
- Any other MCP client: add {"command": "npx", "args": ["-y", "-p", "github:abryfs/willitsend", "willitsend-mcp"]} to its MCP server config.
Then, before every send_message (or equivalent) call, call preflight_message with the
draft body, is_first_message_to_contact (true/false when known), and brand_name.
Treat verdict "block" as do-not-send: apply the returned fix strings and re-run until
pass. Treat "needs_context" as a signal to determine whether this is a first message
(check conversation history), never as permission to send. For high-volume loops pass
response_format: "concise" (~4 tokens on pass).
No API key required. Set AGENTPHONE_API_KEY if you want a live iMessage/SMS capabilities lookup for phone-number destinations; without it the tool runs offline. The config above installs straight from this repo (a prepare script builds on install) — nothing to sign up for. willitsend also publishes to npm and the MCP Registry under the server name io.github.abryfs/willitsend; once a release is cut, registry-aware clients can add it by name and npx -y willitsend starts the server directly. See docs/publishing.md for the release runbook.
As a library (npm install github:abryfs/willitsend):
import { preflight } from "willitsend";
const report = preflight({
body: "Acme: thanks for signing up. Your order shipped. Reply STOP to unsubscribe.",
is_first_message_to_contact: true,
brand_name: "Acme",
});
report.verdict; // "pass" | "warn" | "block" | "needs_context"
report.findings; // each with severity, fix, and a citation URL
report.trace.segments; // { encoding, units, segments, perSegment, ... }
As a CLI: npx -y -p github:abryfs/willitsend willitsend-cli --help (or npx -y -p willitsend willitsend-cli once installed from npm). Exit codes: 0 pass/warn, 1 block, 2 needs context, 3 usage error. It drops into CI or a shell pipeline as-is.
What it checks
| Rule | Severity | Source |
|---|---|---|
first-message.opt-out: first message to a contact must carry opt-out instructions |
block | AgentPhone docs |
first-message.brand: first message must identify the brand (checked only against a brand_name you provide, never guessed) |
block | AgentPhone docs |
first-message.opt-in: first message should acknowledge how the contact opted in |
warn | AgentPhone docs |
first-message.media-only: compliance text can't ride in an image |
warn | AgentPhone docs |
segments.unicode-blowup: one non-GSM character re-encodes the whole message as UCS-2 |
warn | AgentPhone docs |
imessage.feature-fallback: send_style, threaded replies, and carousels drop without a trace on SMS fallback |
warn | AgentPhone docs |
imessage.invalid-send-style, imessage.carousel-count: invalid effect names, carousels outside the documented 2-20 range |
block | AgentPhone docs |
imessage.new-contact-cap: iMessage caps new-contact sends at 50/day per line |
info | AgentPhone docs |
destination.invalid, destination.voip: malformed destinations; known-VoIP lines (line type is never guessed from the number) |
block / warn | send API / AgentPhone docs |
content.shaft: sex/alcohol/firearms/tobacco terms carriers filter (hate speech has no keyword rule: word lists can't detect it and we don't pretend) |
warn | Twilio guidelines |
content.url-shortener: shared public shorteners (bit.ly, tinyurl, …) conflict with CTIA dedicated-shortener guidance |
warn | CTIA MP&BP (PDF) |
content.spam-patterns: ALL-CAPS runs, $$$, !!! |
info | heuristic |
Rules come in two labeled tiers. Rules sourced from AgentPhone's own documentation can block. Industry-sourced rules warn at most, because a keyword heuristic has no business vetoing your send.
The verdict model
A finding that depends on context you didn't supply doesn't pretend to be certain. If you never say whether this is the first message to a contact, the opt-out rule reports conditionally and the verdict is needs_context. You get no fake pass and no fake block.
flowchart LR
F[findings] --> B{any block finding<br/>with known context?}
B -- yes --> BLOCK
B -- no --> C{any block finding<br/>waiting on context?}
C -- yes --> NC[NEEDS_CONTEXT]
C -- no --> W{any warning?}
W -- yes --> WARN
W -- no --> PASS
Every report also carries a send trace: destination classification, assumed channel (iMessage/SMS/MMS), full segment math (encoding, septet and code-unit counts, placement-aware per-segment packing), and, given a 10DLC campaign tier, what this message costs against published daily segment caps.
Benchmarks
Reproduce every number here from the repo; none of them require an account.
- Segment-math parity: agrees with Twilio's reference segment calculator on encoding and segment count across a frozen 126-vector corpus: GSM-7/UCS-2 boundaries, extension characters, emoji, ZWJ sequences, and a deterministic fuzz sweep. The corpus and suite live in
test/parity.test.ts; runnpm test. - Latency: median ~4µs per message, ~100,000 messages/second on one thread (Node 22, Apple Silicon laptop; single-pass code-point tables, zero per-character allocation). Run
npm run benchon yours. Preflighting every outbound message is cheaper than logging it. - Worked cost example, from published caps: a sole-proprietor 10DLC campaign gets 1,000 T-Mobile segments/day (≈3,000 total US, per AgentPhone's published estimate). One stray emoji that flips a 2-segment GSM-7 message to 4 UCS-2 segments halves the number of messages that quota buys. Same text, same recipients, half the reach.
You will find no delivery-rate improvement claims here. That claim needs send data we don't have.
What this can't do
Carriers filter with systems whose rules they don't publish. The policy layer is public (conduct codes, content categories, volume caps); the runtime filtering decisions are deliberately opaque, and only part of the outcome is observable (some blocks return explicit filter errors, some messages are accepted and silently never delivered). This tool covers the deterministic, documented layer, and nothing else:
- A
passis not a delivery guarantee. It means nothing documented will kill the message. - The opt-in check verifies language presence, not that consent exists. Consent lives in your records, not in message text.
- Detection is English-only in v1 (findings carry a
localefield). - Quota math is a static illustration from published caps, not your account's live state.
- The tool never infers line type (VoIP/mobile) from a phone number. Pass
destination_line_typefrom a lookup service if you have one; libphonenumber-js gives a free approximation, with known limits for US numbers.
Prior art
- TwilioDevEd/message-segment-calculator is the reference for segment math. This library is tested for parity against it rather than competing with it.
- sms_policy_checker covers similar compliance ground for Ruby/Rails with an LLM layer; willitsend is the deterministic, zero-network counterpart.
- Web checkers (10dlccheck.com, Calilio) cover overlapping rules as human-facing forms. willitsend makes those checks embeddable: a library an agent can call a hundred thousand times a second, with citations.
- As far as we can tell, this is the first MCP tool for pre-send SMS content compliance. Corrections welcome.
Privacy
No telemetry. No network calls, except the optional capabilities lookup you enable with an API key. The tool never logs, stores, or echoes message bodies in its output. The playground runs in your browser and sends nothing anywhere.
Future
- The engine's natural home is server-side: a
dry_runparameter on the send endpoint itself. The library is written to drop in, as a pure function with no state and a dependency-free core. - Close the loop: correlate preflight verdicts with delivery-status webhooks, so rule precision is measured against real outcomes instead of assumed. Filtering is partially observable (explicit filter errors on some blocks, silence on others), which is exactly enough signal to grade a deterministic ruleset honestly. Learning the opaque layer itself takes aggregate send data across many senders; that belongs to platforms, not to a stateless client tool.
- A rendered deliverability report card via the MCP Apps extension.
- Locale packs beyond English.
Developing
git clone https://github.com/abryfs/willitsend && cd willitsend
npm install # builds via prepare
npm test # 191 tests: unit, Twilio parity, held-out acceptance
npm run bench
License
MIT
willitsend MCP questions
How do I add willitsend MCP to Claude Code?
Run claude mcp add --env 'AGENTPHONE_API_KEY=<YOUR_AGENTPHONE_API_KEY>' willitsend -- npx -y willitsend in your terminal. Add --scope user to make it available in every project.
How do I add willitsend MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does willitsend require an API key?
No API key is required for basic use. You can set AGENTPHONE_API_KEY if you want live iMessage/SMS capabilities lookup for phone-number destinations.
How does it handle first messages to a contact?
It checks for mandatory compliance elements like brand identification, opt-in acknowledgment, and opt-out instructions to prevent silent filtering.
Can it calculate message segments?
Yes, it performs deterministic segment math, including GSM-7 extension characters and encoding flips, to prevent unexpected billable segment increases.