mcp-behave 0.0.0-stage → 0.1.9

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Navid Mirnoori Langeroudi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,219 @@
1
- # Temporary Holding Version
1
+ # mcp-behave
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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)
4
+ [![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)
5
+
6
+ **Runtime behavioral auditor for MCP servers.** Runs an MCP server under
7
+ a runtime tracer (macOS dylib, Linux `LD_PRELOAD`, or `strace`), exercises
8
+ every tool / resource / prompt it advertises, and then compares what it
9
+ *declared* against what it actually *did* — file reads, network egress, subprocess
10
+ execution.
11
+
12
+ Static scanners read tool descriptions. `mcp-behave` watches behavior.
13
+
14
+ ![mcp-behave demo](demo.gif)
15
+
16
+ > See [`ARCHITECTURE.md`](ARCHITECTURE.md) for module dependency, data-flow, and
17
+ > sequence diagrams of the audit pipeline.
18
+
19
+ ## The idea in one contrast
20
+
21
+ `targets/leaky_server.py` and `targets/honest_server.py` advertise the
22
+ **identical** tool:
23
+
24
+ > `format_note` — "Formats a markdown note. Purely local text formatting."
25
+
26
+ A static scanner reads two harmless tools. `mcp-behave` sees the difference:
27
+
28
+ | Target | network egress | sensitive file read | findings |
29
+ |-----------------|---------------------|----------------------------|----------|
30
+ | `honest_server` | none | none | **0** |
31
+ | `leaky_server` | `93.184.216.34:80` | `~/.ssh/id_rsa` (a canary) | **2 HIGH** |
32
+
33
+ The honest server producing **zero** findings matters as much as the leaky one
34
+ tripping two — false positives would kill credibility.
35
+
36
+ ## Install
37
+
38
+ ```bash
39
+ # Via Python (pip / uv)
40
+ pip install mcp-behave
41
+ # or run directly with uv:
42
+ uvx mcp-behave
43
+
44
+ # Via npm (npx)
45
+ npx mcp-behave
46
+ # or install globally:
47
+ npm install -g mcp-behave
48
+ ```
49
+
50
+ ### Tracer Requirements
51
+ - **macOS**: Works natively without `strace` or root using an injected dylib (`DYLD_INSERT_LIBRARIES`). Built automatically on first use with `cc` (Xcode Command Line Tools).
52
+ - **Linux**: Works natively without `strace` or `SYS_PTRACE` using an `LD_PRELOAD` shared library. Built automatically on first use with `cc` (e.g. `gcc`). If no compiler is available, `strace` is used as a fallback if installed on `PATH`.
53
+ - **Untraced mode**: Run on any platform with `--no-trace` for manifest inspection and rug-pull checks without any runtime tracer.
54
+
55
+ ## Use
56
+
57
+ ```bash
58
+ # Audit any stdio MCP server -- pass its launch command:
59
+ mcp-behave python -m mcp_server_fetch
60
+ mcp-behave npx -y @modelcontextprotocol/server-filesystem /tmp
61
+ mcp-behave uvx mcp-server-git
62
+
63
+ # Run untraced (manifest & rug-pull analysis only, no tracer needed):
64
+ mcp-behave --no-trace python -m mcp_server_fetch
65
+
66
+ # Machine-readable output for CI:
67
+ mcp-behave --json --fail-on high python -m mcp_server_fetch
68
+
69
+ # Connect to an already-running remote server (manifest analysis only,
70
+ # no syscall trace possible):
71
+ mcp-behave --transport sse http://localhost:8000/sse
72
+ ```
73
+
74
+ Exit codes: `0` clean, `3` findings at or above `--fail-on` threshold,
75
+ `2` tracer setup failed, `1` other error.
76
+
77
+ ### Useful flags
78
+
79
+ - `--no-trace` — skip syscall tracing and run manifest analysis only.
80
+ - `--tracer {auto,preload,dylib,strace,none}` — choose tracer backend explicitly (default `auto`).
81
+ - `--json` — emit findings as JSON on stdout.
82
+ - `--fail-on {never,info,high}` — severity that triggers exit code 3 (default `high`).
83
+ - `--no-dns` — skip reverse-DNS lookups (faster, offline-safe).
84
+ - `--timeout SECONDS` — per-call timeout (default 15).
85
+ - `--transport {stdio,sse,streamable-http}` — remote transports skip syscall tracing.
86
+ - `--out-dir PATH` — where `manifest.json` and `trace.log` are written.
87
+
88
+ ### Environment Variables
89
+
90
+ | Variable | Default | Description |
91
+ | :--- | :--- | :--- |
92
+ | `OUT_DIR` | `/tmp/mcp_behave_out` | Directory where probe output (`manifest.json` and `trace.log`) is stored. |
93
+ | `TRACE_FILE` | `$OUT_DIR/trace.log` | Path to the raw syscall trace log file. |
94
+ | `MCP_BEHAVE_CALL_TIMEOUT` | `15` | Timeout in seconds per individual tool, resource, or prompt call during exercise. |
95
+ | `MCP_BEHAVE_STATE_DIR` | `$XDG_DATA_HOME/mcp-behave/manifests` | Storage location for historical manifest hashes used in rug-pull detection. |
96
+ | `MCP_BEHAVE_DEBUG` | *(unset)* | Set to `1` to print full Python tracebacks on probe failures. |
97
+ | `PROBE_NOISE_EXTRA` | *(empty)* | Colon-separated path substrings to filter out as benign noise during trace analysis. |
98
+ | `MCP_BEHAVE_DASHBOARD_URL` | *(unset)* | Target dashboard URL for `mcp-behave push`. |
99
+ | `MCP_BEHAVE_TOKEN` | *(unset)* | API bearer token for `mcp-behave push`. |
100
+
101
+ ## Run as an MCP Server (Glama, Claude Desktop, Cursor)
102
+
103
+ `mcp-behave` can run as an MCP server exposing behavioral security tools to AI agents:
104
+ - `audit_server`: Probes and dynamically audits another MCP server's behavioral footprint.
105
+ - `inspect_manifest`: Safely fetches and inspects advertised tools, resources, and prompts, and checks for rug-pulls.
106
+
107
+ ```bash
108
+ # Start MCP server over stdio
109
+ mcp-behave serve
110
+ # or
111
+ uvx mcp-behave serve
112
+ ```
113
+
114
+ ### Claude Desktop / Cursor Configuration
115
+
116
+ Add to your `claude_desktop_config.json` or Cursor MCP settings:
117
+
118
+ ```json
119
+ {
120
+ "mcpServers": {
121
+ "mcp-behave": {
122
+ "command": "uvx",
123
+ "args": ["mcp-behave", "serve"]
124
+ }
125
+ }
126
+ }
127
+ ```
128
+
129
+ ### Glama & Registry Listing
130
+
131
+ `mcp-behave` is compatible with [Glama](https://glama.ai/mcp/servers) and includes a root `glama.json` manifest. AI models can invoke `audit_server` to verify untrusted third-party MCP servers before interacting with them.
132
+
133
+ ## Push results to a dashboard
134
+
135
+ `mcp-behave push` uploads a JSON audit result to an
136
+ [mcp-behave dashboard](https://github.com/navid72m/mcp-behave-dashboard).
137
+
138
+ ```bash
139
+ # 1. Sign in at https://<your-dashboard>.vercel.app/settings and mint a token.
140
+ export MCP_BEHAVE_DASHBOARD_URL=https://<your-dashboard>.vercel.app
141
+ export MCP_BEHAVE_TOKEN=mcpb_...
142
+
143
+ # 2. Audit something with --json and pipe it to push.
144
+ mcp-behave --json python -m mcp_server_fetch \
145
+ | mcp-behave push --server-name server-fetch --category network
146
+
147
+ # Or save to a file first, then push.
148
+ mcp-behave --json python -m mcp_server_fetch > audit.json
149
+ mcp-behave push audit.json --server-name server-fetch --category network
150
+ ```
151
+
152
+ Flags worth knowing:
153
+
154
+ - `--server-name NAME` — canonical name on the dashboard. Defaults to the joined
155
+ server command from the audit JSON; usually you want to set this.
156
+ - `--description TEXT` — used the first time this server is submitted.
157
+ - `--github-url URL`, `--npm-package PKG`, `--author NAME` — optional server metadata.
158
+ - `--category {local,network,database,other}` — defaults to `other`.
159
+ - `--dry-run` — print the JSON payload that would be POSTed and exit.
160
+
161
+ The endpoint is rate-limited per token (20 req/min); `push` exits 1 on HTTP error
162
+ and prints the response body to stderr.
163
+
164
+ ## What it detects
165
+
166
+ - **Undeclared network egress** — IP:port destinations reached during tool calls
167
+ (reverse-DNS resolved in findings when available).
168
+ - **Sensitive-path reads** — `~/.ssh/*`, `~/.aws/*`, `~/.env`, `~/.netrc`, etc.
169
+ - **Rug-pull** — the declared manifest hash changes between runs of the same
170
+ server (e.g. a tool's description silently changes after the user trusts it).
171
+ Hashes persist under `$XDG_DATA_HOME/mcp-behave/manifests/`.
172
+
173
+ Findings are framed as observations ("does X, undeclared"), never accusations.
174
+
175
+ ## Docker (works on macOS / Windows hosts)
176
+
177
+ ```bash
178
+ docker build -t mcp-behave .
179
+ # default: runs the bundled leaky target so you can see findings immediately
180
+ docker run --rm mcp-behave
181
+ # point at a real server
182
+ docker run --rm mcp-behave python -m mcp_server_fetch
183
+ ```
184
+
185
+ The container automatically compiles and runs the native `LD_PRELOAD` tracer
186
+ without needing `--cap-add=SYS_PTRACE`. If you explicitly use `--tracer strace`,
187
+ `--cap-add=SYS_PTRACE` is required.
188
+
189
+ The image bundles Node.js (for `npx` servers), `uv` (for `uvx` servers), and
190
+ sandbox canary files (`sandbox_home/`) mounted as `$HOME` so credential reads
191
+ are detectable.
192
+
193
+ ## Development
194
+
195
+ ```bash
196
+ pip install -e ".[test]"
197
+ pytest -v
198
+ ```
199
+
200
+ CI tests across Ubuntu and macOS; see `.github/workflows/ci.yml`.
201
+
202
+ ## Known limits
203
+
204
+ - **Runtime tracing requires macOS (DYLD interposition) or Linux (LD_PRELOAD / strace).**
205
+ Windows and other platforms can run with `--no-trace` for manifest and rug-pull checks.
206
+ An eBPF backend for system-wide capture is on the roadmap — see [ROADMAP.md](ROADMAP.md).
207
+ - **stdio is the only transport with syscall tracing.** `sse` and
208
+ `streamable-http` connect to a remote server we cannot trace; only manifest
209
+ analysis and rug-pull detection apply there.
210
+ - **Input synthesis is heuristic** — JSON Schema `format`, key-name hints, and
211
+ type defaults. Schema-coverage fuzzing (hypothesis-jsonschema) is roadmap.
212
+ - **AF_UNIX egress** isn't matched — a server exfiltrating over a unix domain
213
+ socket would slip past the current network detection.
214
+ - **Single call per capability** — servers that misbehave only on specific
215
+ inputs or after N calls may not be triggered.
216
+
217
+ ## License
218
+
219
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,109 @@
1
+ #!/usr/bin/env node
2
+
3
+ const { spawn, spawnSync } = require('child_process');
4
+ const path = require('path');
5
+ const fs = require('fs');
6
+ const os = require('os');
7
+
8
+ const PKG_NAME = 'mcp-behave';
9
+ const args = process.argv.slice(2);
10
+
11
+ function commandExists(cmd) {
12
+ try {
13
+ const res = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
14
+ return res.status === 0;
15
+ } catch {
16
+ return false;
17
+ }
18
+ }
19
+
20
+ function findPython() {
21
+ for (const cmd of ['python3', 'python']) {
22
+ try {
23
+ const res = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
24
+ if (res.status === 0) return cmd;
25
+ } catch {}
26
+ }
27
+ return null;
28
+ }
29
+
30
+ function runCommand(command, cmdArgs) {
31
+ const child = spawn(command, cmdArgs, {
32
+ stdio: 'inherit',
33
+ env: process.env,
34
+ });
35
+
36
+ child.on('error', (err) => {
37
+ console.error(`[mcp-behave] Failed to start '${command}':`, err.message);
38
+ process.exit(1);
39
+ });
40
+
41
+ child.on('close', (code, signal) => {
42
+ if (signal) {
43
+ process.kill(process.pid, signal);
44
+ } else {
45
+ process.exit(code ?? 0);
46
+ }
47
+ });
48
+
49
+ process.on('SIGINT', () => child.kill('SIGINT'));
50
+ process.on('SIGTERM', () => child.kill('SIGTERM'));
51
+ }
52
+
53
+ function main() {
54
+ // 1. Prefer uvx if available (fastest, isolated)
55
+ if (commandExists('uvx')) {
56
+ return runCommand('uvx', [PKG_NAME, ...args]);
57
+ }
58
+
59
+ // 2. Try pipx if available
60
+ if (commandExists('pipx')) {
61
+ return runCommand('pipx', ['run', PKG_NAME, ...args]);
62
+ }
63
+
64
+ // 3. Fallback to python3 / python
65
+ const pythonCmd = findPython();
66
+ if (!pythonCmd) {
67
+ console.error('[mcp-behave] Error: Python 3 is required to run mcp-behave.');
68
+ console.error('Please install Python 3 (https://www.python.org) or uv (https://astral.sh/uv).');
69
+ process.exit(1);
70
+ }
71
+
72
+ // Check if mcp_behave is already installed in the active Python environment
73
+ const importCheck = spawnSync(pythonCmd, ['-c', 'import mcp_behave'], { stdio: 'ignore' });
74
+ if (importCheck.status === 0) {
75
+ return runCommand(pythonCmd, ['-m', 'mcp_behave.cli', ...args]);
76
+ }
77
+
78
+ // If not installed, use an isolated cache venv so we don't mutate system packages
79
+ const cacheBase = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
80
+ const venvDir = path.join(cacheBase, 'mcp-behave', 'npm-venv');
81
+ const venvBin = process.platform === 'win32'
82
+ ? path.join(venvDir, 'Scripts', 'mcp-behave.exe')
83
+ : path.join(venvDir, 'bin', 'mcp-behave');
84
+
85
+ if (!fs.existsSync(venvBin)) {
86
+ console.error('[mcp-behave] First-time setup: preparing environment in ~/.cache/mcp-behave/npm-venv...');
87
+ fs.mkdirSync(path.dirname(venvDir), { recursive: true });
88
+
89
+ const venvCreate = spawnSync(pythonCmd, ['-m', 'venv', venvDir], { stdio: 'inherit' });
90
+ if (venvCreate.status !== 0) {
91
+ console.error('[mcp-behave] Warning: could not create venv, falling back to direct run.');
92
+ return runCommand(pythonCmd, ['-m', 'mcp_behave.cli', ...args]);
93
+ }
94
+
95
+ const pipBin = process.platform === 'win32'
96
+ ? path.join(venvDir, 'Scripts', 'pip.exe')
97
+ : path.join(venvDir, 'bin', 'pip');
98
+
99
+ const pipInstall = spawnSync(pipBin, ['install', '--upgrade', PKG_NAME], { stdio: 'inherit' });
100
+ if (pipInstall.status !== 0) {
101
+ console.error('[mcp-behave] Error: failed to install mcp-behave.');
102
+ process.exit(1);
103
+ }
104
+ }
105
+
106
+ return runCommand(venvBin, args);
107
+ }
108
+
109
+ main();
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "mcp-behave",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.9",
4
+ "description": "Runtime behavioral auditor for MCP servers — scope-violation detection via native interposition & syscall tracing",
5
+ "main": "bin/mcp-behave.js",
6
+ "bin": "./bin/mcp-behave.js",
7
+ "files": [
8
+ "bin/",
9
+ "README.md",
10
+ "LICENSE"
11
+ ],
12
+ "keywords": [
13
+ "mcp",
14
+ "model-context-protocol",
15
+ "security",
16
+ "auditing",
17
+ "agents",
18
+ "tracer",
19
+ "sandbox"
20
+ ],
21
+ "author": "Navid Mirnoori Langeroudi <navid72m@gmail.com>",
22
+ "license": "MIT",
23
+ "repository": {
24
+ "type": "git",
25
+ "url": "git+https://github.com/navid72m/mcp-behave.git"
26
+ },
27
+ "bugs": {
28
+ "url": "https://github.com/navid72m/mcp-behave/issues"
29
+ },
30
+ "homepage": "https://github.com/navid72m/mcp-behave#readme",
31
+ "engines": {
32
+ "node": ">=16.0.0"
33
+ }
34
+ }