@talqing/mcp 0.6.0 → 0.8.0

package/README.md

@@ -10,9 +10,8 @@ the CoPilot can build, your coding agent can build.
 ## What you get
 
 One operation for everything a workspace is built out of. Agents and agent
-tasks, tools and their operation trees, integrations and triggers, knowledge
-bases from crawl to ready, carrier accounts and phone numbers, secrets, provider
-keys and webhooks; then placing outbound calls, running call and email batches,
+tasks, tools and their operation trees, integrations and triggers, carrier
+accounts and phone numbers, secrets, provider keys and webhooks; then placing outbound calls, running call and email batches,
 talking to text agents, and reading back transcripts, cost and latency. Each one
 maps to a Talqing API endpoint, and its arguments mirror that HTTP call: path and
 query parameters at the top level, request body under `body`.
@@ -107,9 +106,9 @@ Four things are deliberately out of reach:
   where a human is in the loop.
 - **Buying credits.** Reading the balance would be harmless; starting a payment
   spends the workspace's money, and neither belongs on a coding agent's surface.
-- **Streaming endpoints**, which are not tool-shaped. Every one has a polling
-  equivalent here — `list_conversation_items` for a conversation, `get_kb` for a
-  knowledge build — so nothing is unreachable.
+- **Streaming endpoints**, which are not tool-shaped. Each has a polling
+  equivalent here — `list_conversation_items` for a conversation — so nothing is
+  unreachable.
 - **Deleting a call or its recording.** Every other `delete_*` removes
   configuration you could write again; this one destroys the record of something
   that happened, and can take a contact's memory of past calls with it.

package/SKILL.md

@@ -3,9 +3,9 @@ name: talqing
 description: >-
   Build, publish and operate Talqing AI voice, video and text agents — agent
   config and model stack, custom tools and their operation trees, MCP and
-  messaging integrations, knowledge bases, phone numbers, secrets and webhooks,
-  plus placing calls and reading back transcripts, cost and latency. Use
-  whenever working against a Talqing workspace through the talqing MCP server.
+  messaging integrations, phone numbers, secrets and webhooks, plus placing
+  calls and reading back transcripts, cost and latency. Use whenever working
+  against a Talqing workspace through the talqing MCP server.
 ---
 
 <!-- Generated by openapi/export.py from backend/services/copilot/skill.md. Edit that file, then re-run the export. -->
@@ -14,7 +14,7 @@ description: >-
 
 Talqing is a no-code builder for AI voice, video and text agents. Everything you
 can build here you could otherwise have written as a LiveKit agent by hand: a
-model stack, a system prompt, callable tools, knowledge, and lifecycle hooks.
+model stack, a system prompt, callable tools, and lifecycle hooks.
 The same machinery also runs **agent tasks** — an agent nobody talks to, which
 takes named inputs and returns a typed result.
 
@@ -156,13 +156,17 @@ An agent is a single object, `config`, plus what you attach to it:
   create it, publish v1 and store `{"tool_id": "..."}` in its place, so the
   agent and its tools can be built in one request. Use it for exactly that.
   Attaching an existing tool is still `tool_id`.
-- **`kb_ids`** — ready knowledge bases for grounded answers.
 - **`mcps`** — external MCP servers whose tools the agent may call, each
   `{"integration_id": "..."}` naming an active, MCP-capable integration. Which
   of a server's tools may be called is the integration's own `allowed_tools`,
   not this list. As with `tools`, an entry may instead carry `{"mcp": {name,
   url, headers, allowed_tools, tools_namespace}}`, which is created as a
   `custom_mcp` integration and replaced by its id.
+- **`faqs`** — FAQs the agent answers from, each `{"faq_id": "..."}`, up to ten
+  (see FAQs below). As with `tools`, an entry may instead carry `{"faq": {name,
+  entries: [{question, answer}]}}`, which `create_agent` and `update_agent`
+  create as a stored FAQ and replace by its id — so an agent and its FAQ can be
+  built in one request.
 - **`tasks`** — jobs this agent can enter and come back from, each
   `{"name": "collect_shipping_address", "task_id": "...", "description": "...",
   "message": "..."}`. Each becomes one ordinary tool the model can call: the
@@ -337,9 +341,8 @@ starts that object over, so send its `voice` and settings with it. Unknown field
 
 The config is validated on every write. Unknown models, a model that does not
 support the channel, a language the model does not offer, a speed outside the
-model's range, an unpublished tool, a knowledge base that is not ready — all are
-refused with an explanation. Read the error and correct it; that is faster than
-guessing.
+model's range, an unpublished tool — all are refused with an explanation. Read
+the error and correct it; that is faster than guessing.
 
 Some fields are normalized for you. Switching to `text` clears `stt`, `tts`,
 `greeting`, `turn_handling` and `avatar`. Switching to `video` fills in an
@@ -579,7 +582,7 @@ of whatever the models cost.
 A tool is one capability the agent's LLM can call mid-conversation. It has:
 
 - **`name`** — the function name the LLM sees. A valid identifier, snake_case,
-  describing the capability. `knowledge_fetch` is reserved.
+  describing the capability.
 - **`description`** — tells the LLM *when* to call it. This matters as much as
   the implementation.
 - **`json_schema`** — the arguments the LLM supplies. Declare only values the
@@ -871,9 +874,9 @@ Each hook points at a **published tool id**, or null.
 ## Agent tasks
 
 An **agent task** takes named inputs, does some work, and returns a **typed
-structured output**. Same prompt, same model, same tools, same MCP servers, same
-knowledge and same lifecycle hooks as an agent — minus everything that belongs
-to a *session*, because a task never owns one.
+structured output**. Same prompt, same model, same tools, same MCP servers and
+same lifecycle hooks as an agent — minus everything that belongs to a
+*session*, because a task never owns one.
 
 **It runs two ways, and declares nothing that ties it to either.** On its own —
 `POST /v1/tasks/{task_id}/runs`, or an email batch drafting a row — it is an LLM
@@ -901,7 +904,7 @@ message, draft an opening line, take a shipping address mid-call.
   a step rather than as one, so it costs no steps and real seconds. It is the
   one media slot a task keeps, because an LLM is stateless per request and
   swapping one in rebuilds nothing.
-- **`kb_ids`**, **`on_enter`**, **`on_exit`**, **`on_user_turn_completed`** —
+- **`on_enter`**, **`on_exit`**, **`on_user_turn_completed`** —
   exactly an agent's. `on_user_turn_completed` only ever fires when an agent
   entered the task; a standalone run has nobody to take a turn.
 - There is no `stt`, `tts`, `realtime`, `language`, `turn_handling`, `channel`,
@@ -913,6 +916,7 @@ message, draft an opening line, take a shipping address mid-call.
 - **`tools`** / **`mcps`** — exactly an agent's, attached by id or defined
   inline, and pinned by publish exactly as an agent's are: republishing a tool
   does not change a published task until that task is published again.
+- **`faqs`** — exactly an agent's.
 - **`vars`** — the task's **inputs**, declared exactly as an agent's variables
   are: a `name`, a `description`, an optional `default` and `required`. A run
   supplies values by name; one it omits falls back to the `default`, and a
@@ -1048,14 +1052,42 @@ tell apart.
 Task runs are **not** in the Observability charts, which are built on calls and
 conversations. `list_task_runs` is where a task's own history lives.
 
+## FAQs
+
+An FAQ is a named list of question/answer pairs the business wrote. Attached
+through `faqs`, its **questions** are added to the agent's prompt and the agent
+gets one generated tool, `get_faq_answers`, that returns the written **answers**
+for the questions it picks — so what the agent says is the business's own text.
+Do not create a tool with that name; it is reserved.
+
+- **Use one for stable facts people ask often and the business wants answered
+  exactly**: opening hours, refund policy, delivery areas, pricing. Behaviour,
+  tone and what to do next belong in the prompt; anything that changes per
+  caller or needs a live lookup belongs in a tool.
+- **Edits are live.** Changing a question or an answer reaches every agent using
+  the FAQ from its next session, with no republish. Attaching or detaching an
+  FAQ is a config change and does take a publish.
+- **Phrase each question the way a caller would ask it** — "Do you deliver on
+  Sundays?", not "Sunday delivery policy". The model matches what was asked
+  against the question text, so paraphrases need no extra entries.
+- **Keep answers short and speakable on a voice agent**: one or two sentences,
+  no lists, links or markdown, since the agent will say it aloud.
+- **Add many at once with `create_faq_entries`** (up to 500 per FAQ, all or
+  nothing), and fix one with `update_faq_entry` rather than recreating the FAQ.
+  A question may appear only once per FAQ.
+- Do not also paste the answers into the prompt, and do not tell the agent to
+  refuse what the FAQ lacks unless the user asks for that.
+
+`delete_faq` is refused with 409 while an agent or task attaches it; detach it
+there first.
+
 ## Integrations
 
 Integrations are external services, and they come in two shapes.
 
 **MCP integrations** give an agent tools from an external server. Attach them
-in the agent's own config, as `mcps` — the same place as `tools` and
-`kb_ids`, written by `create_agent` or `update_agent`, and frozen at publish
-like the rest of it. So attaching one **takes a publish** before a call sees it.
+in the agent's own config, as `mcps` — the same place as `tools`, written by
+`create_agent` or `update_agent`, and frozen at publish like the rest of it. So attaching one **takes a publish** before a call sees it.
 `list_integration_mcp_tools` connects to the server and lists everything it
 offers, which also proves the connection works.
 
@@ -1144,8 +1176,16 @@ overrides of anything else — one batch is one agent, one number, one clock.
 weekdays it may dial in, so a list uploaded at 23:00 can start at 11:00
 tomorrow, stop at 18:00 and resume at 10:00 on the next weekday untouched. A
 window may cross midnight; the days then name the evening it starts on.
-`next_dial_at` on the batch says when it will dial next, which is how you tell
-"waiting for Monday" apart from "stuck".
+`next_dial_at` on the batch says when it will dial next and `next_dial_reason`
+why (`start`, `window`, `daily_cap`), which is how you tell "waiting for Monday"
+apart from "stuck".
+
+**Pace.** `dial_gap_seconds` is the minimum wait between starting two calls (0,
+the default, dials as slots free). `dial_daily_cap` limits calls placed per
+local day, retries included: `{kind: "fixed", limit}` or a ramp, `{kind: "ramp",
+start, end, step, interval_days}`, which rises by `step` every `interval_days`
+days the batch actually dialled. For a new caller ID suggest a ramp rather than
+a flat limit. `dialed_today` is measured against `dial_daily_cap_today`.
 
 **Say these two things before creating one**, because a user who discovers
 either from an invoice will not forgive us:
@@ -1242,7 +1282,10 @@ row. `create_email_send` takes a `scope` and returns a **send** you can steer:
 - `start_at` schedules it, `window` (on its own `timezone`) holds it to business
   hours, `send_gap_seconds` is the minimum wait between two emails of the
   **batch** (1 second to 1 hour) and `send_daily_cap` bounds how many the batch
-  may send per local day. Anything omitted comes from the batch.
+  may send per local day: `{kind: "fixed", limit}`, or a ramp, `{kind: "ramp",
+  start, end, step, interval_days}`, which rises by `step` every `interval_days`
+  days the batch actually sent (a weekend or a pause earns nothing). Anything
+  omitted comes from the batch.
 - A draft a live send covers reads `queued`, and is still a draft: it can be
   edited, skipped or redrafted until the send takes it.
 - `pause_email_send` stops on the next email; `resume_email_send` carries on.
@@ -1254,9 +1297,10 @@ row. `create_email_send` takes a `scope` and returns a **send** you can steer:
   within five minutes, so raising a spent cap or removing a window needs no
   cancel.
 
-**The safeguard here is a RATE, not a row count.** `send_daily_cap` (200 by
-default, per batch, `null` for uncapped) is what stands between a 5 000-row list
-and a sending domain nobody trusts again. Before creating a send, say how many
+**The safeguard here is a RATE, not a row count.** `send_daily_cap` (a fixed
+200 by default, per batch, `null` for uncapped) is what stands between a
+5 000-row list and a sending domain nobody trusts again. For a new sending
+domain, suggest a ramp (say 10 rising to 50) rather than a flat cap. Before creating a send, say how many
 emails it is and roughly how long it will take at the pace it has — and if the
 user asks to raise or remove the cap, say what it is for rather than just doing
 it.
@@ -1301,7 +1345,7 @@ ours — Resend keeps one and auto-suppresses hard bounces and complaints.
 
 `get_email_batch` carries live counts, `skips` (why rows were skipped),
 `draft_failures` (why drafts failed, most common first), `failure_reason`,
-`sent_today` (against `send_daily_cap`), `drafted_versions`,
+`sent_today` (against `send_daily_cap_today`), `drafted_versions`,
 `stale_redraftable` / `stale_sent` and the drafting cost so far. Measure
 progress against what can be reached: `unfillable` rows are never drafted, and
 skipped, failed or cancelled rows are never sent.
@@ -1325,7 +1369,9 @@ gives a sender's approved templates — header, body, footer, buttons and variab
 names; one with `unsupported_reason` cannot be used.
 `create_whatsapp_batch` maps `to_column` and every variable onto CSV columns. A
 row with a bad or repeated phone, or a blank mapped cell, is kept and skipped
-with the reason, so read the returned `counts`.
+with the reason, so read the returned `counts`. `send_daily_cap` takes the same
+object an email batch's does (a fixed 250 by default); for a new sender suggest
+a ramp.
 
 **Say these before creating one:**
 
@@ -1343,33 +1389,6 @@ Replies are answered by the agent on the sender's
 `{{userdata.<column>}}` and the whole template, buttons included, as its own
 first message — so write that agent's prompt against the CSV's column names.
 
-## Knowledge bases
-
-A knowledge base gives an agent grounded answers over crawled content. Attach
-it through the agent's `kb_ids`. A call reads only `ready` ones, so one still
-building can be attached now and is used once it finishes.
-
-Building one runs in three stages and takes minutes, not seconds:
-
-1. `create_kb` with the site URLs starts the crawl. It returns immediately at
-   `discovering` — poll `get_kb` until `status` is `review`.
-2. At `review`, `discovered` holds every URL the crawl found. Choose the ones
-   worth indexing and pass them to `build_kb`. This choice decides the quality
-   of the whole knowledge base: prefer pages that answer real questions over
-   everything the crawl happened to reach.
-3. The KB moves through `transcribing` and `generating` to `ready`. Keep
-   polling `get_kb`; `progress` says what stage it is in and `error` says if it
-   stopped.
-
-Once ready, `get_kb_prompt` is the table of contents exactly as the agent
-receives it — read it to judge what the agent will actually be able to find,
-since a vague entry is one it will never fetch. `list_pages` shows which URLs
-failed to transcribe, `patch_node` corrects an entry by hand, and
-`regenerate_toc` rebuilds the structure without crawling again.
-
-Tell the user a build is running rather than waiting silently through it, and
-never poll a build in a tight loop.
-
 ## Secrets, keys and webhooks
 
 **Secrets** are workspace values referenced as `{{secrets.NAME}}` from tool
@@ -1482,8 +1501,8 @@ and the final `userdata` usually name the cause.
   connected channel is a message they receive. Both are irreversible. Test
   against a number or thread the user has named, never one you picked.
 - **Delete only on an explicit request naming the target.** Agents, tools,
-  knowledge bases, carrier accounts, integrations, triggers, secrets, webhooks
-  and tokens are all permanent. Taking a phone number out of service stops real
+  carrier accounts, integrations, triggers, secrets, webhooks and tokens are
+  all permanent. Taking a phone number out of service stops real
   callers from reaching anyone — treat it the same way.
 - **Never echo a secret back.** Personal access tokens, webhook signing secrets
   and provider keys are shown once; repeating one puts it in the conversation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talqing/mcp",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "MCP server for building Talqing AI voice, video and text agents from Claude Code, Codex, or any MCP client.",
   "license": "MIT",
   "homepage": "https://talqing.com",

package/tools.json

@@ -591,156 +591,114 @@
       "role": "write"
     },
     {
-      "description": "List the workspace's knowledge bases with their build status.",
+      "description": "List the workspace's FAQs by name, with how many questions each holds.",
       "method": "GET",
-      "name": "list_kbs",
+      "name": "list_faqs",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('list_kbs').",
+        "description": "Arguments not inlined: call describe_function('list_faqs').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/knowledge",
+      "path": "/v1/faqs",
       "read_only": true,
       "role": "read"
     },
     {
-      "description": "Start a knowledge base by crawling one or more websites.",
+      "description": "Create an FAQ, optionally with its first question/answer entries.",
       "method": "POST",
-      "name": "create_kb",
+      "name": "create_faq",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('create_kb').",
+        "description": "Arguments not inlined: call describe_function('create_faq').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/knowledge",
+      "path": "/v1/faqs",
       "read_only": false,
       "role": "write"
     },
     {
-      "description": "Read one knowledge base: build status, progress and content tree.",
+      "description": "Get one FAQ with every entry, in the order they were added.",
       "method": "GET",
-      "name": "get_kb",
+      "name": "get_faq",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('get_kb').",
+        "description": "Arguments not inlined: call describe_function('get_faq').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/knowledge/{kb_id}",
+      "path": "/v1/faqs/{faq_id}",
       "read_only": true,
       "role": "read"
     },
     {
-      "description": "Index the chosen pages, then write the table of contents.",
-      "method": "POST",
-      "name": "build_kb",
+      "description": "Rename an FAQ.",
+      "method": "PATCH",
+      "name": "update_faq",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('build_kb').",
+        "description": "Arguments not inlined: call describe_function('update_faq').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/knowledge/{kb_id}/build",
+      "path": "/v1/faqs/{faq_id}",
       "read_only": false,
       "role": "write"
     },
     {
-      "description": "Rewrite the table of contents from the pages already indexed.",
-      "method": "POST",
-      "name": "regenerate_toc",
+      "description": "Delete an FAQ and its entries. Refused with 409 while an agent or task still attaches it.",
+      "method": "DELETE",
+      "name": "delete_faq",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('regenerate_toc').",
+        "description": "Arguments not inlined: call describe_function('delete_faq').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/knowledge/{kb_id}/toc",
+      "path": "/v1/faqs/{faq_id}",
       "read_only": false,
       "role": "write"
     },
     {
-      "description": "List the crawled pages and how each one transcribed.",
-      "method": "GET",
-      "name": "list_pages",
-      "parameters": {
-        "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('list_pages').",
-        "properties": {},
-        "type": "object"
-      },
-      "path": "/v1/knowledge/{kb_id}/pages",
-      "read_only": true,
-      "role": "read"
-    },
-    {
-      "description": "The table of contents exactly as an agent using this KB is given it.",
-      "method": "GET",
-      "name": "get_kb_prompt",
-      "parameters": {
-        "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('get_kb_prompt').",
-        "properties": {},
-        "type": "object"
-      },
-      "path": "/v1/knowledge/{kb_id}/prompt",
-      "read_only": true,
-      "role": "read"
-    },
-    {
-      "description": "Read one entry of the table of contents, with its full content.",
-      "method": "GET",
-      "name": "get_node",
-      "parameters": {
-        "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('get_node').",
-        "properties": {},
-        "type": "object"
-      },
-      "path": "/v1/knowledge/{kb_id}/nodes/{node_id}",
-      "read_only": true,
-      "role": "read"
-    },
-    {
-      "description": "Correct one entry's title, summary or content by hand \u2014 the way to fix a fact the crawl got wrong without rebuilding.",
-      "method": "PATCH",
-      "name": "patch_node",
+      "description": "Append question/answer entries to an FAQ, all or nothing. Live at once: agents using the FAQ read them from their next session.",
+      "method": "POST",
+      "name": "create_faq_entries",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('patch_node').",
+        "description": "Arguments not inlined: call describe_function('create_faq_entries').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/knowledge/{kb_id}/nodes/{node_id}",
+      "path": "/v1/faqs/{faq_id}/entries",
       "read_only": false,
       "role": "write"
     },
     {
-      "description": "Drop one entry from the table of contents, permanently.",
-      "method": "DELETE",
-      "name": "delete_node",
+      "description": "Change one entry's question, answer or both. Live from the next session.",
+      "method": "PATCH",
+      "name": "update_faq_entry",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('delete_node').",
+        "description": "Arguments not inlined: call describe_function('update_faq_entry').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/knowledge/{kb_id}/nodes/{node_id}",
+      "path": "/v1/faqs/{faq_id}/entries/{entry_id}",
       "read_only": false,
       "role": "write"
     },
     {
-      "description": "Delete a knowledge base and everything crawled into it, permanently.",
+      "description": "Delete one entry from an FAQ.",
       "method": "DELETE",
-      "name": "delete_kb",
+      "name": "delete_faq_entry",
       "parameters": {
         "additionalProperties": true,
-        "description": "Arguments not inlined: call describe_function('delete_kb').",
+        "description": "Arguments not inlined: call describe_function('delete_faq_entry').",
         "properties": {},
         "type": "object"
       },
-      "path": "/v1/knowledge/{kb_id}",
+      "path": "/v1/faqs/{faq_id}/entries/{entry_id}",
       "read_only": false,
       "role": "write"
     },