@botarmor/mcp 0.1.0 → 0.1.1
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 +142 -14
- package/dist/index.js +1 -1
- package/package.json +4 -2
- package/server.json +36 -0
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# BotArmor MCP server
|
|
2
2
|
|
|
3
|
-
Crash-test your chatbot or AI agent from Claude Code,
|
|
3
|
+
Crash-test your chatbot or AI agent from your AI assistant: Claude Code, Claude Desktop, ChatGPT, OpenAI Codex, Gemini CLI, Cursor, VS Code (Copilot) or Windsurf. Ask "test my agent with BotArmor" and BotArmor attacks the agent on up to 12 levels:
|
|
4
4
|
|
|
5
5
|
- fake manager;
|
|
6
6
|
- angry customer;
|
|
@@ -12,19 +12,117 @@ Crash-test your chatbot or AI agent from Claude Code, Cursor or any MCP client.
|
|
|
12
12
|
- invented facts;
|
|
13
13
|
- and more.
|
|
14
14
|
|
|
15
|
-
Level 13 is added for agents with tools.
|
|
15
|
+
Level 13 is added for agents with tools. The assistant gets back a report written for it: what broke, how badly, and the exact text to add to the agent's instructions. It can then edit your code and run the audit again.
|
|
16
16
|
|
|
17
|
-
It is a thin wrapper over the [BotArmor API](https://app.botarmor.eu/api/v1/openapi.yaml), the same one the Make app
|
|
17
|
+
It is a thin wrapper over the [BotArmor API](https://app.botarmor.eu/api/v1/openapi.yaml), the same one the Make app, the n8n node and the GitHub Action use.
|
|
18
18
|
|
|
19
|
-
##
|
|
19
|
+
## How it works
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
1. **You ask your assistant.** For example: "Check the support agent in this repo with BotArmor."
|
|
22
|
+
2. **The assistant calls `start_audit`.** It passes the agent's system prompt, which it reads from your code.
|
|
23
|
+
- **Prompt mode** (default): BotArmor plays that prompt on its own model. Use it for an agent on localhost or not deployed yet.
|
|
24
|
+
- **Live mode**: BotArmor talks to your running bot at a public https URL. The assistant must first ask you to confirm you own the bot.
|
|
25
|
+
3. **BotArmor attacks.** For each level it runs 5 adaptive sessions. A judge model rules on each session, and a jury of three models confirms every break. An audit takes 5–20 minutes and uses one credit.
|
|
26
|
+
4. **The assistant polls `get_audit_status`.** It shows progress: levels done out of total.
|
|
27
|
+
5. **It reads `get_audit_report`.** The report gives the grade A–F, a table of levels with severity, and for each failed level what happened plus a ready-to-paste fix for the system prompt.
|
|
28
|
+
6. **It proposes the fix in your code.** With your OK it applies the fix, then runs `start_audit` again to check that the level now holds.
|
|
29
|
+
|
|
30
|
+
Your API key stays in your MCP client's configuration. The assistant never receives it. Prompts are not stored by BotArmor, only a SHA-256 fingerprint.
|
|
31
|
+
|
|
32
|
+
## Get an API key
|
|
33
|
+
|
|
34
|
+
Create a key in the [BotArmor dashboard](https://app.botarmor.eu/app/), tab **API**. It starts with `ba_live_`. In the examples below, replace `ba_live_xxx` with it. Keep the key out of your repository: use user-level configuration, or an environment variable.
|
|
35
|
+
|
|
36
|
+
## Connect your assistant
|
|
37
|
+
|
|
38
|
+
### Claude Code
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
claude mcp add botarmor --scope user -e BOTARMOR_API_KEY=ba_live_xxx -- npx -y @botarmor/mcp
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Check with `claude mcp list`, or `/mcp` inside a session.
|
|
45
|
+
|
|
46
|
+
### Claude Desktop
|
|
47
|
+
|
|
48
|
+
Menu **Settings → Developer → Edit Config** opens `claude_desktop_config.json`:
|
|
49
|
+
|
|
50
|
+
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
51
|
+
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
52
|
+
|
|
53
|
+
Add the server, then fully quit and reopen Claude Desktop:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"mcpServers": {
|
|
58
|
+
"botarmor": {
|
|
59
|
+
"command": "npx",
|
|
60
|
+
"args": ["-y", "@botarmor/mcp"],
|
|
61
|
+
"env": { "BOTARMOR_API_KEY": "ba_live_xxx" }
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### ChatGPT (web) and claude.ai: remote server, no install
|
|
68
|
+
|
|
69
|
+
Hosts that only connect to servers on the internet use BotArmor's hosted endpoint:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
https://app.botarmor.eu/mcp
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
1. Add it as a custom MCP server or connector in your host. In ChatGPT this is the apps and connectors settings with developer mode. In claude.ai it is **Settings → Connectors → Add custom connector**. Menu names change often; look for "MCP server" or "custom connector".
|
|
76
|
+
2. The host opens a BotArmor page. Paste your API key there and click **Connect**.
|
|
77
|
+
3. The host receives its own token (OAuth 2.1 with PKCE). It never sees your API key.
|
|
78
|
+
4. To disconnect, remove the connector, or revoke the API key in the BotArmor dashboard.
|
|
79
|
+
|
|
80
|
+
The tools are the same four.
|
|
81
|
+
|
|
82
|
+
### ChatGPT desktop app and OpenAI Codex (CLI and IDE)
|
|
83
|
+
|
|
84
|
+
They share one configuration. Use either the command line:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
codex mcp add botarmor --env BOTARMOR_API_KEY=ba_live_xxx -- npx -y @botarmor/mcp
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
or `~/.codex/config.toml`:
|
|
91
|
+
|
|
92
|
+
```toml
|
|
93
|
+
[mcp_servers.botarmor]
|
|
94
|
+
command = "npx"
|
|
95
|
+
args = ["-y", "@botarmor/mcp"]
|
|
96
|
+
env = { BOTARMOR_API_KEY = "ba_live_xxx" }
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
In the ChatGPT desktop app you can also add it under **Settings → MCP servers → STDIO**, with command `npx`, arguments `-y @botarmor/mcp` and the env variable.
|
|
100
|
+
|
|
101
|
+
### Gemini CLI
|
|
22
102
|
|
|
23
103
|
```bash
|
|
24
|
-
|
|
104
|
+
gemini mcp add -s user -e BOTARMOR_API_KEY=ba_live_xxx botarmor npx -y @botarmor/mcp
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
or `~/.gemini/settings.json`:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"mcpServers": {
|
|
112
|
+
"botarmor": {
|
|
113
|
+
"command": "npx",
|
|
114
|
+
"args": ["-y", "@botarmor/mcp"],
|
|
115
|
+
"env": { "BOTARMOR_API_KEY": "$BOTARMOR_API_KEY" }
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
25
119
|
```
|
|
26
120
|
|
|
27
|
-
|
|
121
|
+
`$BOTARMOR_API_KEY` is read from your shell environment, so the key is not written in the file. Check with `/mcp` in a session.
|
|
122
|
+
|
|
123
|
+
### Cursor
|
|
124
|
+
|
|
125
|
+
`~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
|
|
28
126
|
|
|
29
127
|
```json
|
|
30
128
|
{
|
|
@@ -38,12 +136,42 @@ Other MCP clients (Cursor, Claude Desktop, Windsurf) use this config:
|
|
|
38
136
|
}
|
|
39
137
|
```
|
|
40
138
|
|
|
41
|
-
|
|
139
|
+
### VS Code (GitHub Copilot agent mode)
|
|
140
|
+
|
|
141
|
+
Run **MCP: Open User Configuration** from the Command Palette and add the server. VS Code asks for the key once and stores it securely:
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"inputs": [
|
|
146
|
+
{ "type": "promptString", "id": "botarmor-key", "description": "BotArmor API key (ba_live_...)", "password": true }
|
|
147
|
+
],
|
|
148
|
+
"servers": {
|
|
149
|
+
"botarmor": {
|
|
150
|
+
"type": "stdio",
|
|
151
|
+
"command": "npx",
|
|
152
|
+
"args": ["-y", "@botarmor/mcp"],
|
|
153
|
+
"env": { "BOTARMOR_API_KEY": "${input:botarmor-key}" }
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Note that VS Code uses `servers`, not `mcpServers`.
|
|
160
|
+
|
|
161
|
+
### Windsurf and other MCP clients
|
|
162
|
+
|
|
163
|
+
Any client that runs local MCP servers (stdio) works with the same three values:
|
|
164
|
+
|
|
165
|
+
- command: `npx`
|
|
166
|
+
- args: `-y @botarmor/mcp`
|
|
167
|
+
- env: `BOTARMOR_API_KEY`
|
|
168
|
+
|
|
169
|
+
In Windsurf, use the `mcpServers` block as for Cursor, in `~/.codeium/windsurf/mcp_config.json`.
|
|
42
170
|
|
|
43
171
|
## What to ask
|
|
44
172
|
|
|
45
|
-
- "Check my agent on localhost:3000 with BotArmor."
|
|
46
|
-
- "Audit our staging bot at https://staging.example.com/v1/chat/completions with BotArmor, it's OpenAI-compatible,
|
|
173
|
+
- "Check my agent on localhost:3000 with BotArmor." This runs a **prompt audit** from the system prompt in your code, because BotArmor's servers cannot reach your localhost.
|
|
174
|
+
- "Audit our staging bot at https://staging.example.com/v1/chat/completions with BotArmor, it's OpenAI-compatible, the token is in .env." This runs a **live audit**; the assistant asks you to confirm you own the bot.
|
|
47
175
|
- "Is the BotArmor audit done? Show me the report and fix the prompt."
|
|
48
176
|
- "List my last BotArmor audits."
|
|
49
177
|
|
|
@@ -58,16 +186,16 @@ Keep the key out of your repository. With Claude Code, add it at user scope (`--
|
|
|
58
186
|
|
|
59
187
|
`start_audit` parameters:
|
|
60
188
|
|
|
61
|
-
- `system_prompt` (required): the agent's instructions
|
|
189
|
+
- `system_prompt` (required): the agent's instructions. For a live audit it is also the rulebook the judge checks answers against.
|
|
62
190
|
- `target_type`, one of:
|
|
63
|
-
- `prompt`: the default when no URL is given
|
|
191
|
+
- `prompt`: the default when no URL is given;
|
|
64
192
|
- `openai-compatible`: a chat-completions endpoint;
|
|
65
193
|
- `webhook`: any JSON endpoint.
|
|
66
|
-
- `endpoint_url`: a public https URL
|
|
194
|
+
- `endpoint_url`: a public https URL, for live audits.
|
|
67
195
|
- `headers`: what the target needs. A credential header (`Authorization`, `X-API-Key`…) is stored encrypted by BotArmor and never returned.
|
|
68
196
|
- `model`: for `openai-compatible`, the model name sent in the body.
|
|
69
197
|
- `body_template` and `response_path`: for `webhook`. The body uses `{{input}}`, `"{{history}}"` or `"{{messages}}"`; the path points to the reply, e.g. `data.reply`.
|
|
70
|
-
- `levels`: a subset of `logic, toxic, hacker, lawyer, multilang, loop, roleplay, phishing, ethics, burst, disclosure, facts, agency`.
|
|
198
|
+
- `levels`: a subset of `logic, toxic, hacker, lawyer, multilang, loop, roleplay, phishing, ethics, burst, disclosure, facts, agency`.
|
|
71
199
|
- `lang`: the report language (`fr`, `en`, `de`, `es`, `ru`).
|
|
72
200
|
- `min_grade`: the pass threshold.
|
|
73
201
|
- `authorization_confirmed`: must be `true` for a live audit. Set it only when you own the bot or hold the owner's written permission. BotArmor never tests third-party bots.
|
package/dist/index.js
CHANGED
|
@@ -6,7 +6,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
|
|
|
6
6
|
import { z } from "zod";
|
|
7
7
|
import { BotArmorClient, BotArmorError, DEFAULT_BASE_URL } from "./api.js";
|
|
8
8
|
import { LEVELS, startAudit, getAuditStatus, getAuditReport, listAudits } from "./tools.js";
|
|
9
|
-
const VERSION = "0.1.
|
|
9
|
+
const VERSION = "0.1.1";
|
|
10
10
|
const server = new McpServer({ name: "botarmor", version: VERSION });
|
|
11
11
|
// The client is created on first use, so a missing key becomes a readable tool error instead of a crash at start.
|
|
12
12
|
let client = null;
|
package/package.json
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@botarmor/mcp",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"mcpName": "io.github.sidorenkav-collab/botarmor",
|
|
5
|
+
"description": "MCP server for BotArmor: crash-test your chatbot or AI agent from Claude Code, ChatGPT, Codex, Gemini CLI, Cursor or any MCP client, and get a report the model can turn into fixes.",
|
|
5
6
|
"type": "module",
|
|
6
7
|
"license": "MIT",
|
|
7
8
|
"author": "BotArmor AI (Rhone IA)",
|
|
@@ -28,6 +29,7 @@
|
|
|
28
29
|
},
|
|
29
30
|
"files": [
|
|
30
31
|
"dist/*.js",
|
|
32
|
+
"server.json",
|
|
31
33
|
"README.md",
|
|
32
34
|
"LICENSE"
|
|
33
35
|
],
|
package/server.json
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.sidorenkav-collab/botarmor",
|
|
4
|
+
"description": "Crash-test chatbots and AI agents: 12 attack levels, A-F grade, ready-to-paste prompt fixes.",
|
|
5
|
+
"repository": {
|
|
6
|
+
"url": "https://github.com/sidorenkav-collab/botarmor-mcp",
|
|
7
|
+
"source": "github"
|
|
8
|
+
},
|
|
9
|
+
"version": "0.1.1",
|
|
10
|
+
"websiteUrl": "https://botarmor.eu/agents/#mcp",
|
|
11
|
+
"packages": [
|
|
12
|
+
{
|
|
13
|
+
"registryType": "npm",
|
|
14
|
+
"identifier": "@botarmor/mcp",
|
|
15
|
+
"version": "0.1.1",
|
|
16
|
+
"transport": {
|
|
17
|
+
"type": "stdio"
|
|
18
|
+
},
|
|
19
|
+
"environmentVariables": [
|
|
20
|
+
{
|
|
21
|
+
"name": "BOTARMOR_API_KEY",
|
|
22
|
+
"description": "BotArmor API key (ba_live_...), from the client area, tab API",
|
|
23
|
+
"isRequired": true,
|
|
24
|
+
"format": "string",
|
|
25
|
+
"isSecret": true
|
|
26
|
+
}
|
|
27
|
+
]
|
|
28
|
+
}
|
|
29
|
+
],
|
|
30
|
+
"remotes": [
|
|
31
|
+
{
|
|
32
|
+
"type": "streamable-http",
|
|
33
|
+
"url": "https://app.botarmor.eu/mcp"
|
|
34
|
+
}
|
|
35
|
+
]
|
|
36
|
+
}
|