@spekoai/mcp-calls 0.4.0 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spekoai/mcp-calls",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "description": "Place real, disclosed phone calls to businesses straight from your coding agent — the Speko \"AI calls for devs\" MCP. Single self-contained package: `npx @spekoai/mcp-calls init` to set up.",
   "mcpName": "ai.speko/mcp-calls",
   "type": "module",

package/server.json

@@ -4,13 +4,13 @@
   "title": "Speko — AI Calls for Devs",
   "description": "Place real, disclosed outbound phone calls to businesses straight from your coding agent.",
   "repository": { "url": "https://github.com/SpekoAI/mcp-dev-calls", "source": "github" },
-  "version": "0.4.0",
+  "version": "0.4.3",
   "websiteUrl": "https://speko.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@spekoai/mcp-calls",
-      "version": "0.4.0",
+      "version": "0.4.3",
       "transport": { "type": "stdio" },
       "environmentVariables": [
         {

package/skills/speko-calls/SKILL.md

@@ -1,67 +1,88 @@
 ---
 name: speko-calls
 description: >-
-  Use when the user wants to place a REAL outbound phone call to a BUSINESS via the
-  Speko Calls MCP — e.g. "call <place> and ask <question>", book a reservation, check
-  hours/availability/pricing, or chase an order. Teaches the lookup → dial_token →
-  make_call workflow, the mandatory AI disclosure, the business-lines-only + quiet-hours
-  rails, and how to report the call OUTCOME honestly. Not for personal/consumer calls.
+  Use when the user wants to place a REAL outbound phone call via the Speko Calls MCP — e.g.
+  "call <place> and ask <question>", "find the best <X> near me and call them", book a
+  reservation, check hours/availability/pricing, or place/chase an order. Covers calling a
+  number you have or found via web search (call_number) and Speko's verified business lookup
+  (lookup_business → make_call), the mandatory AI disclosure, the quiet-hours + no-spam rails,
+  and reporting the call OUTCOME honestly.
 ---
 
-# Speko Calls — placing real, disclosed business calls
+# Speko Calls — placing real, disclosed phone calls
 
-The Speko Calls MCP places **real, disclosed** outbound phone calls to **businesses** and
-returns the result as text. Every call opens with a non-removable AI disclosure
-(*"Hi, this is an AI assistant calling on behalf of …"*). You drive it through three tools
-and **never dial a raw number directly**.
+The Speko Calls MCP places **real, disclosed** outbound phone calls and returns the result as
+text. Every call opens with a non-removable AI disclosure — the callee hears
+*"Hey! Quick heads up — I'm \<your-name\>'s AI assistant, \<your-name\> asked me to give you a
+call…"* before anything else.
 
-## Workflow — always in this order
-1. **`check_call_readiness()`** — read-only preflight (auth, credit balance, outbound
-   caller-ID). Run first if unsure the account can dial. Never dials.
-2. **`lookup_business(name, location?, phone_number?, utc_offset_minutes?)`** — resolves the business
-   to dialable candidates, each with a **signed, single-use `dial_token`**. This is the ONLY thing that
-   can authorize a call. If you can find the business's official phone number via web search, pass it as
-   `phone_number` (E.164) to skip the directory lookup — it's still carrier-verified as a business line.
-   If the number's region isn't auto-recognized for quiet-hours, also pass `utc_offset_minutes`
-   (e.g. -300 US Eastern) — you know the business's city from your search.
-3. **`make_call(dial_token, objective, caller_name, context?)`** — places the disclosed
-   call, waits while it rings, returns the `OUTCOME:` line + transcript.
+There are **two ways to dial**:
+- **`call_number`** — dial a number you already have, or one you found via web search. Works
+  with just the user's Speko key, no extra setup. **This is the hero path for "find a place and
+  call it."**
+- **`lookup_business` → `make_call`** — let Speko find the business in a directory and
+  carrier-verify it's a real business line, then dial. Use when you want that verification (the
+  server must have directory/carrier keys configured).
 
-`make_call` is impossible without a fresh `dial_token` from `lookup_business`. There is no
-way to pass a raw phone number — that's a safety boundary, not a limitation.
+## Find the number yourself (the hero flow)
+When the user names a *kind* of place ("the best taco spot in the Bay Area"), don't ask them
+for a number — find it and call it. **Be decisive — don't stall the user with options.**
+1. **Web-search** and pick the SINGLE best match; don't make the user choose from a list. Read
+   its official site/listing for the full phone number and its city.
+2. **`call_number(phone_number=<+E.164>, objective, caller_name)`** places the disclosed call.
+   Use a full international number with a leading `+` and country code (`+14152857117`, not
+   `(415) 285-7117`). The destination timezone auto-derives from common area codes; if the tool
+   says it couldn't determine the timezone (an unusual area code, or a toll-free
+   800/888/877/866 number), re-run with `utc_offset_minutes` for the business's city
+   (US Pacific is `-420` in summer / `-480` in winter, US Eastern `-240`/`-300`, UK `+60`/`0`).
+3. One quick inline confirm ("calling La Taqueria, +1 415-285-7117, to ask if they have carnitas
+   — go?"), then dial. A call is a real-world action, so keep the gate to a single yes/no.
 
-## Before dialing — confirm with the human
-- **Confirm the business and the objective with the user.** A call is a real-world action.
-- Pass the user's name as `caller_name` (the disclosure says "on behalf of `<caller_name>`").
-- Write `objective` as ONE clear transactional goal:
-  *"Ask if there's a table for 4 at 8pm tonight and book it under John."*
+Example: *"find the best taco place in the Bay Area and ask if they're open and have carnitas"*
+→ search → pick La Taqueria → `call_number(...)` → relay the `OUTCOME`.
+
+## Writing the objective
+One plain, transactional goal in everyday words:
+- **reservation:** *"Ask if there's a table for 4 at 8pm tonight and book it under John."*
+- **order:** *"Order 2 carnitas tacos and a Coke Zero for pickup, and ask when it'll be ready."*
+- **info:** *"Ask if they're open now and how long the wait is for a table for 2."*
+
+Pass the user's name as `caller_name` (the disclosure says *"I'm \<caller_name\>'s AI assistant"*).
+Avoid words the no-spam screen refuses — they match as substrings (e.g. "promot" catches
+"promotion"): *sell, sales pitch, promote, discount, sponsor, advertise, marketing, survey,
+donate, fundraise, vote, campaign, debt, warranty, crypto, investment.* Just say it plainly
+("order…", "ask if…", "book…", "check the price of…"). ("deal" is fine.)
+
+## The verified directory path — `lookup_business` → `make_call`
+1. **`check_call_readiness()`** — read-only preflight (auth, credit, outbound caller-ID). Run
+   first if unsure the account can dial. Never dials.
+2. **`lookup_business(name, location?, phone_number?, utc_offset_minutes?)`** — resolves the
+   business to candidates, each with a **signed, single-use `dial_token`** (the only thing that
+   can authorize `make_call`). Needs the server's directory/carrier keys; without them, use
+   `call_number` with a number you found instead.
+3. **`make_call(dial_token, objective, caller_name, context?)`** — places the disclosed call,
+   waits while it rings, and returns the `OUTCOME:` line + transcript.
 
 ## The rails (enforced server-side — you cannot override them)
-- **Business lines only** — mobiles are blocked (carrier line-type check).
-- **Transactional objectives only** — reservations, availability, hours, pricing, order
-  status. **Refused:** selling, promotion, surveys, fundraising, political campaigning.
-- **Quiet hours** — 08:00–21:00 in the destination's local time (fail-closed if unknown).
 - **AI disclosure** — hard-coded; cannot be removed or reworded.
+- **Transactional objectives only** — reservations, availability, hours, pricing, orders.
+  **Refused:** selling, promotion, surveys, fundraising, political campaigning.
+- **Quiet hours** — 08:00–21:00 in the destination's local time; calls outside are rejected
+  (fail-closed if the timezone is unknown — pass `utc_offset_minutes`).
+- **Business-line verification** applies on the `lookup_business` path (mobiles blocked there).
 
-If an objective trips a rail, `make_call` returns a rejection with a reason. Rewrite the
-objective as a single transactional question and retry, or tell the user it isn't allowed.
+If an objective trips a rail, the tool returns a rejection with a reason. Fix the objective (or
+pass `utc_offset_minutes`) and retry, or tell the user it isn't allowed.
 
 ## Reading the result — honestly
-- `connected` / `answered` are reported truthfully. If the platform never put a real call
-  on the wire (no telephony leg), it returns **`not_connected`** — do **not** report that
-  as success. Run `check_call_readiness` and tell the user the deployment's outbound
-  trunk / caller-ID may need setup.
-- The `OUTCOME:` line is the answer (e.g. *"table for 4 at 8pm, booked under John"*).
-  Relay it plainly and offer the transcript.
-
-## Personal calls — `call_number`
-If the user wants to call a **specific number they give you** (e.g. a friend), use
-`call_number(phone_number, objective, caller_name, recipient_name?)` — not the business
-flow. It works by default. Mobiles are allowed here; the AI disclosure, quiet hours, and
-no-spam screen still apply. Only ever call a number the user **explicitly provides and has
-consent to call** — never one you guessed. For businesses, use `lookup_business` instead.
+- `connected` / `answered` are reported truthfully. If the platform never put a real call on
+  the wire, it returns **`not_connected`** — do **not** report that as success; run
+  `check_call_readiness` and tell the user the deployment's outbound trunk/caller-ID may need setup.
+- The `OUTCOME:` line is the answer (e.g. *"table for 4 at 8pm, booked under John"*). Relay it
+  plainly and offer the transcript.
 
 ## Don't
-- Don't invent or guess phone numbers — `make_call` dials only a server-minted `dial_token`; `call_number` dials only a number the user explicitly gave you.
-- Don't retry after a pre-dial rejection without fixing the objective first.
+- Don't invent or guess phone numbers — only dial a number the user gave you or one you found
+  from the business's own official listing.
+- Don't retry after a pre-dial rejection without fixing the objective/timezone first.
 - Don't promise a call will connect — report what actually happened.