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.
Files changed (2) hide show
  1. package/README.md +48 -12
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,7 +1,11 @@
1
1
  # mcp-behave
2
2
 
3
- [![mcp-behave MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/navid72m/mcp-behave/badges/score.svg)](https://glama.ai/mcp/servers/navid72m/mcp-behave)
3
+ [![CI](https://github.com/navid72m/mcp-behave/actions/workflows/ci.yml/badge.svg)](https://github.com/navid72m/mcp-behave/actions/workflows/ci.yml)
4
+ [![PyPI version](https://img.shields.io/pypi/v/mcp-behave.svg)](https://pypi.org/project/mcp-behave/)
4
5
  [![PyPI Downloads](https://static.pepy.tech/personalized-badge/mcp-behave?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/mcp-behave)
6
+ [![npm version](https://img.shields.io/npm/v/mcp-behave.svg)](https://www.npmjs.com/package/mcp-behave)
7
+ [![mcp-behave MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/navid72m/mcp-behave/badges/score.svg)](https://glama.ai/mcp/servers/navid72m/mcp-behave)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](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
  ![mcp-behave demo](demo.gif)
15
19
 
16
- > See [`ARCHITECTURE.md`](ARCHITECTURE.md) for module dependency, data-flow, and
17
- > sequence diagrams of the audit pipeline.
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 Python (pip / uv)
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 (npx)
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 `![...](https://...)` 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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-behave",
3
- "version": "0.1.9",
3
+ "version": "0.2.0",
4
4
  "description": "Runtime behavioral auditor for MCP servers — scope-violation detection via native interposition & syscall tracing",
5
5
  "main": "bin/mcp-behave.js",
6
6
  "bin": "./bin/mcp-behave.js",