@vapi-ai/mcp-server 0.0.11 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +241 -104
- package/dist/knowledge/docs.d.ts +96 -0
- package/dist/knowledge/docs.d.ts.map +1 -0
- package/dist/knowledge/docs.js +16 -0
- package/dist/knowledge/skills.d.ts +28 -0
- package/dist/knowledge/skills.d.ts.map +1 -0
- package/dist/knowledge/skills.js +131 -0
- package/dist/schemas/assistant-openapi.d.ts +31 -0
- package/dist/schemas/assistant-openapi.d.ts.map +1 -0
- package/dist/schemas/assistant-openapi.js +87 -0
- package/dist/schemas/assistant-openapi.json +2341 -0
- package/dist/schemas/index.d.ts +161 -1181
- package/dist/schemas/index.d.ts.map +1 -1
- package/dist/schemas/index.js +99 -172
- package/dist/schemas/simulation-openapi.d.ts +9 -0
- package/dist/schemas/simulation-openapi.d.ts.map +1 -0
- package/dist/schemas/simulation-openapi.js +81 -0
- package/dist/schemas/simulation-openapi.json +27558 -0
- package/dist/schemas/simulation.d.ts +54 -0
- package/dist/schemas/simulation.d.ts.map +1 -0
- package/dist/schemas/simulation.js +76 -0
- package/dist/tools/annotations.d.ts +5 -0
- package/dist/tools/annotations.d.ts.map +1 -0
- package/dist/tools/annotations.js +14 -0
- package/dist/tools/api-schema.d.ts +4 -0
- package/dist/tools/api-schema.d.ts.map +1 -0
- package/dist/tools/api-schema.js +69 -0
- package/dist/tools/assistant.d.ts.map +1 -1
- package/dist/tools/assistant.js +33 -17
- package/dist/tools/call.d.ts.map +1 -1
- package/dist/tools/call.js +20 -11
- package/dist/tools/docs.d.ts +3 -0
- package/dist/tools/docs.d.ts.map +1 -0
- package/dist/tools/docs.js +27 -0
- package/dist/tools/index.d.ts.map +1 -1
- package/dist/tools/index.js +8 -0
- package/dist/tools/input-schema.d.ts +5 -0
- package/dist/tools/input-schema.d.ts.map +1 -0
- package/dist/tools/input-schema.js +59 -0
- package/dist/tools/list.d.ts +34 -0
- package/dist/tools/list.d.ts.map +1 -0
- package/dist/tools/list.js +47 -0
- package/dist/tools/phone-number.d.ts.map +1 -1
- package/dist/tools/phone-number.js +17 -10
- package/dist/tools/simulation.d.ts +4 -0
- package/dist/tools/simulation.d.ts.map +1 -0
- package/dist/tools/simulation.js +146 -0
- package/dist/tools/skills.d.ts +3 -0
- package/dist/tools/skills.d.ts.map +1 -0
- package/dist/tools/skills.js +31 -0
- package/dist/tools/tool.d.ts.map +1 -1
- package/dist/tools/tool.js +31 -14
- package/dist/tools/validation.d.ts +24 -0
- package/dist/tools/validation.d.ts.map +1 -0
- package/dist/tools/validation.js +94 -0
- package/dist/transformers/index.d.ts +3 -3
- package/dist/transformers/index.d.ts.map +1 -1
- package/dist/transformers/index.js +52 -31
- package/package.json +9 -6
package/README.md
CHANGED
|
@@ -1,103 +1,47 @@
|
|
|
1
1
|
# Vapi MCP Server
|
|
2
2
|
|
|
3
|
-
[
|
|
3
|
+
Build AI voice assistants and phone agents with [Vapi](https://vapi.ai) from any agent or app that speaks the [Model Context Protocol](https://modelcontextprotocol.com/).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Connect to the hosted server
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
<img width="380" height="200" src="https://glama.ai/mcp/servers/@VapiAI/mcp-server/badge" alt="Vapi Server MCP server" />
|
|
9
|
-
</a>
|
|
7
|
+
**You don't need to clone, install or run anything.** Vapi hosts this server for you:
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
- **URL:** `https://mcp.vapi.ai/mcp` (Streamable HTTP)
|
|
10
|
+
- **Header:** `Authorization: Bearer YOUR_VAPI_API_KEY`
|
|
12
11
|
|
|
13
|
-
|
|
12
|
+
Get an API key from the [Vapi dashboard](https://dashboard.vapi.ai/org/api-keys).
|
|
14
13
|
|
|
15
|
-
|
|
14
|
+
👉 **[Step-by-step setup for Codex, Claude Code, Cursor, VS Code, Hermes and Claude Desktop](https://docs.vapi.ai/sdk/mcp-server#connect-your-agent)**
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
The two most common setups:
|
|
18
17
|
|
|
19
|
-
|
|
20
|
-
npx -y @vapi-ai/mcp-server
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
Set `VAPI_TOKEN` in the server environment. MCP client configuration formats vary, but the server definition generally looks like this:
|
|
18
|
+
**Claude Code**
|
|
24
19
|
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
"args": ["-y", "@vapi-ai/mcp-server"],
|
|
31
|
-
"env": {
|
|
32
|
-
"VAPI_TOKEN": "<your_vapi_token>"
|
|
33
|
-
}
|
|
34
|
-
}
|
|
35
|
-
}
|
|
36
|
-
}
|
|
20
|
+
```bash
|
|
21
|
+
export VAPI_API_KEY="YOUR_VAPI_API_KEY"
|
|
22
|
+
claude mcp add --transport http --scope user vapi \
|
|
23
|
+
https://mcp.vapi.ai/mcp \
|
|
24
|
+
--header 'Authorization: Bearer ${VAPI_API_KEY}'
|
|
37
25
|
```
|
|
38
26
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
Clients that support remote MCP servers can connect directly:
|
|
42
|
-
|
|
43
|
-
- URL: `https://mcp.vapi.ai/mcp`
|
|
44
|
-
- Header: `Authorization: Bearer your_vapi_api_key_here`
|
|
45
|
-
|
|
46
|
-
### Client-Specific Examples
|
|
47
|
-
|
|
48
|
-
#### Claude Code
|
|
27
|
+
**Codex**
|
|
49
28
|
|
|
50
29
|
```bash
|
|
51
|
-
|
|
30
|
+
export VAPI_API_KEY="YOUR_VAPI_API_KEY"
|
|
31
|
+
codex mcp add vapi --url https://mcp.vapi.ai/mcp \
|
|
32
|
+
--bearer-token-env-var VAPI_API_KEY
|
|
52
33
|
```
|
|
53
34
|
|
|
54
|
-
|
|
35
|
+
Keep `VAPI_API_KEY` set whenever you launch your agent. Start a new session, then try:
|
|
55
36
|
|
|
56
|
-
Use the local server configuration above in the Claude Desktop configuration file. To connect to the hosted server through an stdio bridge instead:
|
|
57
|
-
|
|
58
|
-
```json
|
|
59
|
-
{
|
|
60
|
-
"mcpServers": {
|
|
61
|
-
"vapi": {
|
|
62
|
-
"command": "npx",
|
|
63
|
-
"args": [
|
|
64
|
-
"mcp-remote",
|
|
65
|
-
"https://mcp.vapi.ai/mcp",
|
|
66
|
-
"--header",
|
|
67
|
-
"Authorization: Bearer ${VAPI_TOKEN}"
|
|
68
|
-
],
|
|
69
|
-
"env": {
|
|
70
|
-
"VAPI_TOKEN": "<your_vapi_token>"
|
|
71
|
-
}
|
|
72
|
-
}
|
|
73
|
-
}
|
|
74
|
-
}
|
|
75
37
|
```
|
|
76
|
-
|
|
77
|
-
### Optional Agent Skill
|
|
78
|
-
|
|
79
|
-
The [`skill`](./skill) directory contains reusable instructions for AI coding agents that support Agent Skills. Install it using your host's skill installation process.
|
|
80
|
-
|
|
81
|
-
For Claude Code:
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
mkdir -p ~/.claude/skills/vapi
|
|
85
|
-
curl -o ~/.claude/skills/vapi/SKILL.md https://raw.githubusercontent.com/VapiAI/mcp-server/main/skill/SKILL.md
|
|
38
|
+
List my Vapi assistants.
|
|
86
39
|
```
|
|
87
40
|
|
|
88
|
-
---
|
|
89
|
-
|
|
90
|
-
## Example Usage
|
|
91
|
-
|
|
92
|
-
### Create a Voice Assistant
|
|
93
|
-
|
|
94
|
-
Ask your MCP-enabled agent:
|
|
95
41
|
```
|
|
96
|
-
I want to build a voice assistant that can schedule appointments
|
|
42
|
+
I want to build a voice assistant that can schedule appointments.
|
|
97
43
|
```
|
|
98
44
|
|
|
99
|
-
### Make an Outbound Call
|
|
100
|
-
|
|
101
45
|
```
|
|
102
46
|
Call +1234567890 using my appointment reminder assistant with these details:
|
|
103
47
|
- Customer name: Sarah Johnson
|
|
@@ -105,25 +49,34 @@ Call +1234567890 using my appointment reminder assistant with these details:
|
|
|
105
49
|
- Appointment time: 2:30 PM
|
|
106
50
|
```
|
|
107
51
|
|
|
108
|
-
### Schedule a Future Call
|
|
109
|
-
|
|
110
52
|
```
|
|
111
53
|
Schedule a call with my support assistant for next Tuesday at 3:00 PM to +1555123456
|
|
112
54
|
```
|
|
113
55
|
|
|
114
|
-
|
|
56
|
+
> The legacy SSE endpoint (`https://mcp.vapi.ai/sse`) is deprecated. Move existing remote configurations to `https://mcp.vapi.ai/mcp`.
|
|
57
|
+
|
|
58
|
+
### Optional: add the Vapi agent skill
|
|
59
|
+
|
|
60
|
+
The [`skill`](./skill) directory contains reusable instructions for AI coding agents that support Agent Skills. Install it using your host's skill installation process.
|
|
61
|
+
|
|
62
|
+
For Claude Code:
|
|
115
63
|
|
|
116
|
-
|
|
64
|
+
```bash
|
|
65
|
+
mkdir -p ~/.claude/skills/vapi
|
|
66
|
+
curl -o ~/.claude/skills/vapi/SKILL.md https://raw.githubusercontent.com/VapiAI/mcp-server/main/skill/SKILL.md
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Using Variable Values in Assistant Prompts
|
|
117
70
|
|
|
118
71
|
The `create_call` action supports passing dynamic variables through `assistantOverrides.variableValues`. Use double curly braces in your assistant's prompts: `{{variableName}}`.
|
|
119
72
|
|
|
120
|
-
|
|
73
|
+
#### Example Prompt with Variables
|
|
121
74
|
|
|
122
75
|
```
|
|
123
76
|
Hello {{customerName}}, this is a reminder about your appointment on {{appointmentDate}} at {{appointmentTime}} with {{doctorName}}.
|
|
124
77
|
```
|
|
125
78
|
|
|
126
|
-
|
|
79
|
+
#### Default Variables
|
|
127
80
|
|
|
128
81
|
These are automatically available (no need to pass):
|
|
129
82
|
|
|
@@ -139,56 +92,155 @@ See [Vapi documentation](https://docs.vapi.ai/assistants/dynamic-variables#defau
|
|
|
139
92
|
|
|
140
93
|
---
|
|
141
94
|
|
|
142
|
-
##
|
|
95
|
+
## Oh, you're still here?
|
|
96
|
+
|
|
97
|
+
You must want to [leave feedback](#leave-feedback), [run a local server yourself](#run-a-local-server) or [peek under the hood](#peek-under-the-hood). Read on.
|
|
143
98
|
|
|
144
|
-
|
|
99
|
+
### Leave feedback
|
|
100
|
+
|
|
101
|
+
- **Found a bug or want a tool we don't have?** [Open an issue](https://github.com/VapiAI/mcp-server/issues).
|
|
102
|
+
- **Have a question or want to talk it through?** Join the [Vapi Discord](https://discord.gg/v5Ee6FhAZt).
|
|
103
|
+
- **Want to fix it yourself?** Pull requests are welcome. See [Development](#development) for how to build and test.
|
|
104
|
+
|
|
105
|
+
### Run a local server
|
|
106
|
+
|
|
107
|
+
Run the server on your own machine if your client only supports local stdio servers or you want to try unreleased changes. It uses the same tools as the hosted server.
|
|
108
|
+
|
|
109
|
+
Configure your MCP client to run:
|
|
110
|
+
|
|
111
|
+
```text
|
|
112
|
+
npx -y @vapi-ai/mcp-server
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Set `VAPI_TOKEN` to your Vapi API key in the server environment. MCP client configuration formats vary, but the server definition generally looks like this:
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{
|
|
119
|
+
"mcpServers": {
|
|
120
|
+
"vapi": {
|
|
121
|
+
"command": "npx",
|
|
122
|
+
"args": ["-y", "@vapi-ai/mcp-server"],
|
|
123
|
+
"env": {
|
|
124
|
+
"VAPI_TOKEN": "<your_vapi_token>"
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
```
|
|
145
130
|
|
|
146
|
-
|
|
131
|
+
For Claude Code:
|
|
147
132
|
|
|
148
|
-
|
|
149
|
-
-
|
|
133
|
+
```bash
|
|
134
|
+
claude mcp add -e VAPI_TOKEN=your_vapi_token vapi -- npx -y @vapi-ai/mcp-server
|
|
135
|
+
```
|
|
150
136
|
|
|
151
|
-
|
|
137
|
+
For Claude Desktop, add the configuration above to the Claude Desktop configuration file.
|
|
152
138
|
|
|
153
|
-
|
|
154
|
-
- Header: `Authorization: Bearer your_vapi_api_key_here`
|
|
139
|
+
To run a build from this repository instead, see [Local Development Config](#local-development-config).
|
|
155
140
|
|
|
156
141
|
---
|
|
157
142
|
|
|
158
|
-
##
|
|
143
|
+
## Peek under the hood
|
|
159
144
|
|
|
160
|
-
###
|
|
145
|
+
### Available Tools
|
|
146
|
+
|
|
147
|
+
#### Documentation
|
|
148
|
+
| Tool | Description |
|
|
149
|
+
|------|-------------|
|
|
150
|
+
| `ask_vapi_docs` | Query the Fern docs MCP for current documentation passages and source URLs |
|
|
151
|
+
|
|
152
|
+
`ask_vapi_docs({"question":"How do assistant hooks work?","topK":8})` forwards to
|
|
153
|
+
`searchDocs` at `https://docs.vapi.ai/_mcp/server`. The result preserves Fern's
|
|
154
|
+
content, source links and error flag. This endpoint currently returns passages
|
|
155
|
+
for the calling agent to synthesize, rather than a generated answer. `topK`
|
|
156
|
+
defaults to 8 (maximum 20). Each request owns its MCP connection, supports caller
|
|
157
|
+
cancellation, times out after 30 seconds and closes the connection afterwards.
|
|
158
|
+
|
|
159
|
+
This tool needs outbound HTTPS to the Fern endpoint. It makes no Vapi API calls
|
|
160
|
+
and sends no Vapi credentials upstream. The server still requires `VAPI_TOKEN`
|
|
161
|
+
at startup. Discovery through `tools/list` makes no network requests; upstream
|
|
162
|
+
failures are returned as tool errors. No extra MCP connection is needed. Do not
|
|
163
|
+
include secrets or private customer data in docs questions.
|
|
164
|
+
|
|
165
|
+
#### Assistants
|
|
161
166
|
| Tool | Description |
|
|
162
167
|
|------|-------------|
|
|
163
|
-
| `list_assistants` | List
|
|
168
|
+
| `list_assistants` | List assistants in pages of up to 10 |
|
|
164
169
|
| `get_assistant` | Get assistant by ID |
|
|
165
170
|
| `create_assistant` | Create new assistant |
|
|
166
171
|
| `update_assistant` | Update assistant |
|
|
167
172
|
|
|
168
|
-
|
|
173
|
+
#### Calls
|
|
169
174
|
| Tool | Description |
|
|
170
175
|
|------|-------------|
|
|
171
|
-
| `list_calls` | List call history |
|
|
176
|
+
| `list_calls` | List call history in pages of up to 10 |
|
|
172
177
|
| `get_call` | Get call details |
|
|
173
178
|
| `create_call` | Start outbound call (immediate or scheduled) |
|
|
174
179
|
|
|
175
|
-
|
|
180
|
+
#### Phone Numbers
|
|
176
181
|
| Tool | Description |
|
|
177
182
|
|------|-------------|
|
|
178
|
-
| `list_phone_numbers` | List phone numbers |
|
|
183
|
+
| `list_phone_numbers` | List phone numbers in pages of up to 10 |
|
|
179
184
|
| `get_phone_number` | Get phone number details |
|
|
180
185
|
|
|
181
|
-
|
|
186
|
+
#### Tools (Function Calling)
|
|
182
187
|
| Tool | Description |
|
|
183
188
|
|------|-------------|
|
|
184
|
-
| `list_tools` | List custom tools |
|
|
189
|
+
| `list_tools` | List custom tools in pages of up to 10 |
|
|
185
190
|
| `get_tool` | Get tool details |
|
|
186
191
|
| `create_tool` | Create tool for API integration |
|
|
187
192
|
| `update_tool` | Update tool |
|
|
188
193
|
|
|
189
|
-
|
|
194
|
+
#### Public Skills
|
|
195
|
+
| Tool | Description |
|
|
196
|
+
|------|-------------|
|
|
197
|
+
| `search_skills` | Search public Vapi skills by keywords; omit `query` to browse |
|
|
198
|
+
| `load_skill` | Read a skill's `SKILL.md` or a supporting file |
|
|
199
|
+
|
|
200
|
+
For example, call `search_skills({"query":"simulations"})`, then
|
|
201
|
+
`load_skill({"name":"simulations"})`. The load result includes a `files` list;
|
|
202
|
+
read a supporting file with `load_skill({"name":"simulations","path":"references/example.md"})`,
|
|
203
|
+
using an exact path from that list. Loading returns instructions for the current
|
|
204
|
+
task; it does not install skills or run scripts.
|
|
205
|
+
|
|
206
|
+
Skills come directly from the public [VapiAI/skills](https://github.com/VapiAI/skills)
|
|
207
|
+
repository, including experimental skills. Discovery uses its GitHub tree rather
|
|
208
|
+
than the proposed skills manifest. Each server caches a commit-pinned snapshot
|
|
209
|
+
for five minutes, so file reads within that snapshot use the same revision. Search
|
|
210
|
+
matches names, descriptions and instruction text; it returns at most `limit`
|
|
211
|
+
results (default 10, maximum 30) and the total match count. `load_skill` returns
|
|
212
|
+
one text file at a time, up to 512 KB, with its source URL and revision.
|
|
213
|
+
|
|
214
|
+
The skills tools need outbound HTTPS to public GitHub. They make no Vapi API
|
|
215
|
+
calls and send no Vapi credentials upstream. The server still requires
|
|
216
|
+
`VAPI_TOKEN` at startup. Discovery through `tools/list` makes no network requests;
|
|
217
|
+
upstream failures are returned as tool errors. No GitHub token is needed for this
|
|
218
|
+
public content. GitHub's unauthenticated API rate limits apply.
|
|
219
|
+
|
|
220
|
+
#### Simulations
|
|
190
221
|
|
|
191
|
-
|
|
222
|
+
| Tool | Description |
|
|
223
|
+
|------|-------------|
|
|
224
|
+
| `list_simulation_personalities` | List simulated callers |
|
|
225
|
+
| `create_simulation_personality` | Create a simulated caller with a tester assistant |
|
|
226
|
+
| `list_simulation_scenarios` | List tester scripts and evaluations |
|
|
227
|
+
| `create_simulation_scenario` | Create a tester script and evaluations |
|
|
228
|
+
| `list_simulations` | List scenario/personality pairs |
|
|
229
|
+
| `create_simulation` | Pair a scenario with a personality |
|
|
230
|
+
| `list_simulation_suites` | List groups of simulations |
|
|
231
|
+
| `create_simulation_suite` | Group simulations into a suite |
|
|
232
|
+
| `run_simulations` | Run simulations or suites against an assistant or squad |
|
|
233
|
+
| `list_simulation_runs` | List runs and filter by status or target |
|
|
234
|
+
| `get_simulation_run` | Get run status and item summaries |
|
|
235
|
+
| `get_simulation_run_item` | Get a full item including transcript and results |
|
|
236
|
+
|
|
237
|
+
The catalog contains 29 tools. Simulation lists default to 50 results.
|
|
238
|
+
`get_simulation_run` returns the first 100 item summaries, with API pagination
|
|
239
|
+
metadata in `itemsMetadata` and `itemsTruncated: true` when more items exist.
|
|
240
|
+
Legacy array responses are also supported. Use `get_simulation_run_item` for
|
|
241
|
+
the full details of a known item.
|
|
242
|
+
|
|
243
|
+
### Development
|
|
192
244
|
|
|
193
245
|
```bash
|
|
194
246
|
# Install dependencies
|
|
@@ -201,7 +253,7 @@ npm run build
|
|
|
201
253
|
npm run inspector
|
|
202
254
|
```
|
|
203
255
|
|
|
204
|
-
|
|
256
|
+
#### Local Development Config
|
|
205
257
|
|
|
206
258
|
```json
|
|
207
259
|
{
|
|
@@ -217,7 +269,7 @@ npm run inspector
|
|
|
217
269
|
}
|
|
218
270
|
```
|
|
219
271
|
|
|
220
|
-
|
|
272
|
+
#### Testing
|
|
221
273
|
|
|
222
274
|
```bash
|
|
223
275
|
# Safe default suite (build, mocked execution, contract, and stdio compatibility)
|
|
@@ -247,6 +299,91 @@ export VAPI_TOKEN=your_test_org_token_here
|
|
|
247
299
|
npm run test:live:mutating
|
|
248
300
|
```
|
|
249
301
|
|
|
302
|
+
#### Input validation from OpenAPI
|
|
303
|
+
|
|
304
|
+
All 21 parameterized MCP tools use imported OpenAPI constraints through
|
|
305
|
+
Zod's experimental `z.fromJSONSchema()`, pinned to Zod 4.6.7. This covers
|
|
306
|
+
assistant names/LLMs/voices/transcribers, call schedules and customer numbers,
|
|
307
|
+
lookup/update IDs, function parameters, transfer destinations, HTTP methods,
|
|
308
|
+
timeouts and retry plans, plus all 12 simulation tools. The four original list
|
|
309
|
+
tools have local empty input schemas.
|
|
310
|
+
|
|
311
|
+
`src/schemas/assistant-openapi.json` is the compact projection for the original
|
|
312
|
+
tool surfaces (the filename is retained from the initial assistant cutover). It
|
|
313
|
+
records the [public API spec](https://api.vapi.ai/api-json) source SHA-256 and
|
|
314
|
+
includes the recursive JSON-schema definitions needed for function parameters
|
|
315
|
+
and request bodies. Builds and installs use it without network access. Refresh
|
|
316
|
+
explicitly with `npm run schemas:snapshot`, or pass a saved spec with
|
|
317
|
+
`npm run schemas:snapshot -- /path/spec.json`.
|
|
318
|
+
|
|
319
|
+
`src/schemas/simulation-openapi.json` bundles the full simulation DTOs and their
|
|
320
|
+
referenced definitions from the same public spec. The same refresh command
|
|
321
|
+
updates both snapshots. Simulation validation includes names, folder paths,
|
|
322
|
+
UUIDs, instructions, evaluations, nested tester assistants and structured
|
|
323
|
+
outputs. Scenario/suite `additionalFields` are validated after merging, so they
|
|
324
|
+
cannot override an API constraint. Large nested assistant and structured-output
|
|
325
|
+
objects have compact advertised envelopes; their full API contracts are checked
|
|
326
|
+
at runtime. The shared summary projection omits long documentation and recursive
|
|
327
|
+
definitions from simulation discovery. The 25-tool catalog is about 28 KB.
|
|
328
|
+
No runtime schema fetch or
|
|
329
|
+
`get_api_schema` tool is required.
|
|
330
|
+
|
|
331
|
+
Simulation aliases remain local adapters: `run_simulations` takes exactly one
|
|
332
|
+
assistant/squad target and at least one simulation/suite ID, then builds the API
|
|
333
|
+
request. Integer iterations and integer page sizes of 1–100 are MCP policies;
|
|
334
|
+
API iteration bounds and parameter formats come from the snapshot. The item
|
|
335
|
+
lookup endpoint publishes plain strings for its IDs, so those are not assigned
|
|
336
|
+
UUID constraints from a different endpoint.
|
|
337
|
+
|
|
338
|
+
The shared normalizer also represents empty preset enums as always-failing
|
|
339
|
+
branches and preserves property names such as `oneOf` and `default` when walking
|
|
340
|
+
JSON Schema definitions.
|
|
341
|
+
|
|
342
|
+
When upgrading `@vapi-ai/server-sdk`, refresh and review the bundled schema in
|
|
343
|
+
the same PR, then run `npm run typecheck`, `npm test`, and `npm run test:package`.
|
|
344
|
+
Check changes against the SDK's request types and the MCP adapters below. The
|
|
345
|
+
public endpoint serves the current API spec, not a spec version tied to the SDK
|
|
346
|
+
release, so refreshing does not by itself guarantee compatibility. Keep the
|
|
347
|
+
reviewed schema bundled with the release; do not refresh it during installation
|
|
348
|
+
or startup.
|
|
349
|
+
|
|
350
|
+
The adapter documents published contract corrections: overlapping enum/string
|
|
351
|
+
`oneOf` alternatives become `anyOf`; duplicate enum values and JavaScript regex
|
|
352
|
+
delimiters are removed; the contradictory object/string-enum annotation on
|
|
353
|
+
`BackoffPlan.type` is corrected. Provider variants reject undeclared fields.
|
|
354
|
+
Spec defaults do not inject request fields; MCP defaults remain separate.
|
|
355
|
+
For the original compact assistant tools, variants requiring fields outside
|
|
356
|
+
the current interface remain excluded: custom
|
|
357
|
+
voice, Neuphonic voice, custom transcriber, Speechmatics transcriber, and custom
|
|
358
|
+
LLM. Adding their required fields needs an explicit interface extension.
|
|
359
|
+
|
|
360
|
+
MCP wrappers preserve field aliases and sparse updates. URL checks and
|
|
361
|
+
string-valued header maps remain explicit transport rules because the spec only
|
|
362
|
+
describes a string/object. API-request header maps and SMS metadata retain legacy MCP representations;
|
|
363
|
+
they are explicit compatibility adapters, not claimed to be full API DTO
|
|
364
|
+
validation. SMS metadata is not described in the published DTO. Response summaries also remain
|
|
365
|
+
local: they are transformed MCP representations, not raw API DTOs.
|
|
366
|
+
|
|
367
|
+
Validation failures return `isError: true`, concise text and structured
|
|
368
|
+
`validationError` details: tool name, issue code, field path, message and allowed
|
|
369
|
+
choices where relevant. Errors select the supplied provider's union branch,
|
|
370
|
+
include at most 12 issues and 8 allowed choices per issue, and indicate
|
|
371
|
+
truncation. Submitted values and credential contents are not echoed. Agents
|
|
372
|
+
should correct the listed fields and retry; a validation failure never invokes
|
|
373
|
+
the API handler. Tests exercise this correction loop through a real MCP client.
|
|
374
|
+
|
|
375
|
+
`tools/list` advertises a compact input summary derived from the same validators:
|
|
376
|
+
field names, basic types, required fields, defaults, and short constraints. It
|
|
377
|
+
omits provider/model catalogs, lengthy API documentation, and recursive schema
|
|
378
|
+
definitions. The full OpenAPI-derived validator still runs before any API call;
|
|
379
|
+
the advertised summary is intentionally broader. Catalog tests cap the
|
|
380
|
+
original 13-tool list at 20 KB, the 12 simulation tools at 10 KB, and the complete
|
|
381
|
+
25-tool list at 30 KB to prevent unexpected agent-context growth.
|
|
382
|
+
|
|
383
|
+
`npm test` includes schema contract tests, independent Ajv parity cases, and
|
|
384
|
+
validation-feedback tests. The existing live compatibility
|
|
385
|
+
suites cover read-only resources and disposable assistants/custom tools.
|
|
386
|
+
|
|
250
387
|
---
|
|
251
388
|
|
|
252
389
|
## References
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
|
|
2
|
+
export declare const DOCS_MCP_URL = "https://docs.vapi.ai/_mcp/server";
|
|
3
|
+
export declare function askVapiDocs(question: string, topK: number, signal?: AbortSignal, transport?: Transport): Promise<{
|
|
4
|
+
[x: string]: unknown;
|
|
5
|
+
content: ({
|
|
6
|
+
type: "text";
|
|
7
|
+
text: string;
|
|
8
|
+
annotations?: {
|
|
9
|
+
audience?: ("user" | "assistant")[] | undefined;
|
|
10
|
+
priority?: number | undefined;
|
|
11
|
+
lastModified?: string | undefined;
|
|
12
|
+
} | undefined;
|
|
13
|
+
_meta?: Record<string, unknown> | undefined;
|
|
14
|
+
} | {
|
|
15
|
+
type: "image";
|
|
16
|
+
data: string;
|
|
17
|
+
mimeType: string;
|
|
18
|
+
annotations?: {
|
|
19
|
+
audience?: ("user" | "assistant")[] | undefined;
|
|
20
|
+
priority?: number | undefined;
|
|
21
|
+
lastModified?: string | undefined;
|
|
22
|
+
} | undefined;
|
|
23
|
+
_meta?: Record<string, unknown> | undefined;
|
|
24
|
+
} | {
|
|
25
|
+
type: "audio";
|
|
26
|
+
data: string;
|
|
27
|
+
mimeType: string;
|
|
28
|
+
annotations?: {
|
|
29
|
+
audience?: ("user" | "assistant")[] | undefined;
|
|
30
|
+
priority?: number | undefined;
|
|
31
|
+
lastModified?: string | undefined;
|
|
32
|
+
} | undefined;
|
|
33
|
+
_meta?: Record<string, unknown> | undefined;
|
|
34
|
+
} | {
|
|
35
|
+
type: "resource";
|
|
36
|
+
resource: {
|
|
37
|
+
uri: string;
|
|
38
|
+
text: string;
|
|
39
|
+
mimeType?: string | undefined;
|
|
40
|
+
_meta?: Record<string, unknown> | undefined;
|
|
41
|
+
} | {
|
|
42
|
+
uri: string;
|
|
43
|
+
blob: string;
|
|
44
|
+
mimeType?: string | undefined;
|
|
45
|
+
_meta?: Record<string, unknown> | undefined;
|
|
46
|
+
};
|
|
47
|
+
annotations?: {
|
|
48
|
+
audience?: ("user" | "assistant")[] | undefined;
|
|
49
|
+
priority?: number | undefined;
|
|
50
|
+
lastModified?: string | undefined;
|
|
51
|
+
} | undefined;
|
|
52
|
+
_meta?: Record<string, unknown> | undefined;
|
|
53
|
+
} | {
|
|
54
|
+
uri: string;
|
|
55
|
+
name: string;
|
|
56
|
+
type: "resource_link";
|
|
57
|
+
description?: string | undefined;
|
|
58
|
+
mimeType?: string | undefined;
|
|
59
|
+
size?: number | undefined;
|
|
60
|
+
annotations?: {
|
|
61
|
+
audience?: ("user" | "assistant")[] | undefined;
|
|
62
|
+
priority?: number | undefined;
|
|
63
|
+
lastModified?: string | undefined;
|
|
64
|
+
} | undefined;
|
|
65
|
+
_meta?: {
|
|
66
|
+
[x: string]: unknown;
|
|
67
|
+
} | undefined;
|
|
68
|
+
icons?: {
|
|
69
|
+
src: string;
|
|
70
|
+
mimeType?: string | undefined;
|
|
71
|
+
sizes?: string[] | undefined;
|
|
72
|
+
theme?: "light" | "dark" | undefined;
|
|
73
|
+
}[] | undefined;
|
|
74
|
+
title?: string | undefined;
|
|
75
|
+
})[];
|
|
76
|
+
_meta?: {
|
|
77
|
+
[x: string]: unknown;
|
|
78
|
+
progressToken?: string | number | undefined;
|
|
79
|
+
"io.modelcontextprotocol/related-task"?: {
|
|
80
|
+
taskId: string;
|
|
81
|
+
} | undefined;
|
|
82
|
+
} | undefined;
|
|
83
|
+
structuredContent?: Record<string, unknown> | undefined;
|
|
84
|
+
isError?: boolean | undefined;
|
|
85
|
+
} | {
|
|
86
|
+
[x: string]: unknown;
|
|
87
|
+
toolResult: unknown;
|
|
88
|
+
_meta?: {
|
|
89
|
+
[x: string]: unknown;
|
|
90
|
+
progressToken?: string | number | undefined;
|
|
91
|
+
"io.modelcontextprotocol/related-task"?: {
|
|
92
|
+
taskId: string;
|
|
93
|
+
} | undefined;
|
|
94
|
+
} | undefined;
|
|
95
|
+
}>;
|
|
96
|
+
//# sourceMappingURL=docs.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/knowledge/docs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE/E,eAAO,MAAM,YAAY,qCAAqC,CAAC;AAI/D,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,EACpB,SAAS,GAAE,SAAoE;;;;;mBAW44f,CAAC;oBAA4B,CAAC;oBAAgE,CAAC;wBAAkD,CAAC;;aAAkE,CAAC;;;;;mBAA+J,CAAC;oBAA4B,CAAC;oBAAgE,CAAC;wBAAkD,CAAC;;aAAkE,CAAC;;;;;mBAA+J,CAAC;oBAA4B,CAAC;oBAAgE,CAAC;wBAAkD,CAAC;;aAAkE,CAAC;;;;;;oBAA8L,CAAC;iBAA2C,CAAC;;;;oBAA4I,CAAC;iBAA2C,CAAC;;mBAA6E,CAAC;oBAA4B,CAAC;oBAAgE,CAAC;wBAAkD,CAAC;;aAAkE,CAAC;;;;;mBAAkK,CAAC;gBAA0C,CAAC;YAAsC,CAAC;mBAA6C,CAAC;oBAA4B,CAAC;oBAAgE,CAAC;wBAAkD,CAAC;;aAAkE,CAAC;;;aAAsF,CAAC;;oBAAyD,CAAC;iBAA2C,CAAC;iBAA6C,CAAC;;aAA8E,CAAC;;;;qBAAiH,CAAC;8CAAiF,CAAC;;;;;;;;;;;qBAAgV,CAAC;8CAAiF,CAAC;;;;GADv/lB"}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
2
|
+
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
|
|
3
|
+
export const DOCS_MCP_URL = 'https://docs.vapi.ai/_mcp/server';
|
|
4
|
+
// A separate connection per request avoids sharing a failed session or leaking
|
|
5
|
+
// concurrent calls across each other. No Vapi credentials are sent upstream.
|
|
6
|
+
export async function askVapiDocs(question, topK, signal, transport = new StreamableHTTPClientTransport(new URL(DOCS_MCP_URL))) {
|
|
7
|
+
const client = new Client({ name: 'vapi-mcp-docs', version: '1.0.0' });
|
|
8
|
+
const options = { signal: AbortSignal.any([AbortSignal.timeout(30_000), ...(signal ? [signal] : [])]), timeout: 30_000 };
|
|
9
|
+
try {
|
|
10
|
+
await client.connect(transport, options);
|
|
11
|
+
return await client.callTool({ name: 'searchDocs', arguments: { query: question, topK } }, undefined, options);
|
|
12
|
+
}
|
|
13
|
+
finally {
|
|
14
|
+
await client.close().catch(() => undefined);
|
|
15
|
+
}
|
|
16
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
export declare class PublicSkills {
|
|
2
|
+
private readonly fetcher;
|
|
3
|
+
private cached?;
|
|
4
|
+
constructor(fetcher?: typeof fetch);
|
|
5
|
+
private read;
|
|
6
|
+
private snapshot;
|
|
7
|
+
private content;
|
|
8
|
+
private skill;
|
|
9
|
+
search(query: string, limit: number): Promise<{
|
|
10
|
+
repository: string;
|
|
11
|
+
revision: string;
|
|
12
|
+
total: number;
|
|
13
|
+
skills: {
|
|
14
|
+
name: string;
|
|
15
|
+
description: string;
|
|
16
|
+
sourceUrl: string;
|
|
17
|
+
}[];
|
|
18
|
+
}>;
|
|
19
|
+
load(name: string, path: string): Promise<{
|
|
20
|
+
name: string;
|
|
21
|
+
path: string;
|
|
22
|
+
revision: string;
|
|
23
|
+
sourceUrl: string;
|
|
24
|
+
content: string;
|
|
25
|
+
files: string[];
|
|
26
|
+
}>;
|
|
27
|
+
}
|
|
28
|
+
//# sourceMappingURL=skills.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/knowledge/skills.ts"],"names":[],"mappings":"AAwBA,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,MAAM,CAAC,CAAoD;gBAEtC,OAAO,GAAE,OAAO,KAAa;YAE5C,IAAI;IA6BlB,OAAO,CAAC,QAAQ;IAiBhB,OAAO,CAAC,OAAO;YAWD,KAAK;IAQb,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;;;;;;;;;;IAyBnC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;;;;;;;;CAatC"}
|