mcp-behave 0.1.9 → 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 +48 -12
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
# mcp-behave
|
|
2
2
|
|
|
3
|
-
[](https://github.com/navid72m/mcp-behave/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/mcp-behave/)
|
|
4
5
|
[](https://pepy.tech/projects/mcp-behave)
|
|
6
|
+
[](https://www.npmjs.com/package/mcp-behave)
|
|
7
|
+
[](https://glama.ai/mcp/servers/navid72m/mcp-behave)
|
|
8
|
+
[](LICENSE)
|
|
5
9
|
|
|
6
10
|
**Runtime behavioral auditor for MCP servers.** Runs an MCP server under
|
|
7
11
|
a runtime tracer (macOS dylib, Linux `LD_PRELOAD`, or `strace`), exercises
|
|
@@ -13,8 +17,9 @@ Static scanners read tool descriptions. `mcp-behave` watches behavior.
|
|
|
13
17
|
|
|
14
18
|

|
|
15
19
|
|
|
16
|
-
>
|
|
17
|
-
>
|
|
20
|
+
> 📖 **Read the research article**: [Auditing Real-World MCP Servers with mcp-behave](https://www.navidmirnouri.com/blog/auditing-mcp-servers-with-mcp-behave.html) for an empirical audit comparing real-world packages and investigating known MCP vulnerability classes.
|
|
21
|
+
>
|
|
22
|
+
> 🏗️ **Architecture & Systems Internals**: See [`ARCHITECTURE.md`](ARCHITECTURE.md) for module dependency, data-flow, and sequence diagrams of the audit pipeline.
|
|
18
23
|
|
|
19
24
|
## The idea in one contrast
|
|
20
25
|
|
|
@@ -33,17 +38,25 @@ A static scanner reads two harmless tools. `mcp-behave` sees the difference:
|
|
|
33
38
|
The honest server producing **zero** findings matters as much as the leaky one
|
|
34
39
|
tripping two — false positives would kill credibility.
|
|
35
40
|
|
|
36
|
-
## Install
|
|
41
|
+
## Install & Quickstart
|
|
42
|
+
|
|
43
|
+
Run directly without manual installation:
|
|
37
44
|
|
|
38
45
|
```bash
|
|
39
|
-
# Via
|
|
46
|
+
# Via npx (Node.js ecosystem — zero install)
|
|
47
|
+
npx mcp-behave <server-command>
|
|
48
|
+
|
|
49
|
+
# Via uvx (Python ecosystem — zero install)
|
|
50
|
+
uvx mcp-behave <server-command>
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Or install into your local environment:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# Via pip
|
|
40
57
|
pip install mcp-behave
|
|
41
|
-
# or run directly with uv:
|
|
42
|
-
uvx mcp-behave
|
|
43
58
|
|
|
44
|
-
# Via npm
|
|
45
|
-
npx mcp-behave
|
|
46
|
-
# or install globally:
|
|
59
|
+
# Via npm
|
|
47
60
|
npm install -g mcp-behave
|
|
48
61
|
```
|
|
49
62
|
|
|
@@ -106,15 +119,28 @@ Exit codes: `0` clean, `3` findings at or above `--fail-on` threshold,
|
|
|
106
119
|
|
|
107
120
|
```bash
|
|
108
121
|
# Start MCP server over stdio
|
|
109
|
-
mcp-behave serve
|
|
122
|
+
npx mcp-behave serve
|
|
110
123
|
# or
|
|
111
124
|
uvx mcp-behave serve
|
|
112
125
|
```
|
|
113
126
|
|
|
114
|
-
### Claude Desktop / Cursor Configuration
|
|
127
|
+
### Claude Desktop / Cursor / Cline Configuration
|
|
115
128
|
|
|
116
129
|
Add to your `claude_desktop_config.json` or Cursor MCP settings:
|
|
117
130
|
|
|
131
|
+
**Option A: Using `npx` (No Python virtualenv setup needed)**
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"mcpServers": {
|
|
135
|
+
"mcp-behave": {
|
|
136
|
+
"command": "npx",
|
|
137
|
+
"args": ["-y", "mcp-behave", "serve"]
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**Option B: Using `uvx`**
|
|
118
144
|
```json
|
|
119
145
|
{
|
|
120
146
|
"mcpServers": {
|
|
@@ -169,6 +195,16 @@ and prints the response body to stderr.
|
|
|
169
195
|
- **Rug-pull** — the declared manifest hash changes between runs of the same
|
|
170
196
|
server (e.g. a tool's description silently changes after the user trusts it).
|
|
171
197
|
Hashes persist under `$XDG_DATA_HOME/mcp-behave/manifests/`.
|
|
198
|
+
- **Covert Channel & Metadata Injection** (CSA TTP: Tool Description Poisoning) — ANSI
|
|
199
|
+
terminal escape codes (`\x1b`), invisible zero-width Unicode (`\u200B`, `\u200C`,
|
|
200
|
+
`\u200D`, `\uFEFF`, `\u2060`), BiDi overrides (`\u202A`–`\u202E`, `\u2066`–`\u2069`),
|
|
201
|
+
Unicode tag characters, and prompt injection directive patterns (`Ignore previous instructions`,
|
|
202
|
+
`SYSTEM PROMPT:`, `<system>`, etc.) embedded in tool/parameter descriptions, resource URIs,
|
|
203
|
+
or prompt metadata.
|
|
204
|
+
- **Tool Output Safety & Markdown Exfiltration** (CSA TTP: Output Prompt Injection / Data Exfiltration) —
|
|
205
|
+
captures runtime tool responses during probe execution and flags client-side HTTP GET
|
|
206
|
+
exfiltration vectors (such as external Markdown images `` and HTML `<img src="...">` tags),
|
|
207
|
+
as well as ANSI escapes, invisible Unicode, and prompt injection payloads returned in tool outputs.
|
|
172
208
|
|
|
173
209
|
Findings are framed as observations ("does X, undeclared"), never accusations.
|
|
174
210
|
|
package/package.json
CHANGED