# jnMetaCode/shellward [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/jnMetaCode/shellward  
**GitHub Stars:** 139  
**npm Downloads (last month):** 973  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/jnmetacode-shellward

## Description
AI Agent Security Middleware & MCP Server with 8-layer defense including prompt injection detection, DLP data flow tracking, command blocking, and PII detection. 7 MCP tools, zero dependencies.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "shellward": {
    "command": "npx",
    "args": ["-y","shellward"],
    "env": {
      "SHELLWARD_MODE": "",
      "SHELLWARD_LOCALE": "",
      "SHELLWARD_THRESHOLD": "",
      "SHELLWARD_BASELINE_PATH": ""
    }
  }
}
```

**Requires environment variables:** `SHELLWARD_MODE`, `SHELLWARD_LOCALE`, `SHELLWARD_THRESHOLD`, `SHELLWARD_BASELINE_PATH` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What jnMetaCode/shellward MCP server does

The jnMetaCode/shellward MCP server acts as a local security layer for AI agents and MCP clients. It evaluates agent inputs, tool definitions, commands, paths, responses, and outbound actions instead of providing business-system integrations. The implementation is described as dependency-free and runs locally over stdio, so the MCP checks do not require a hosted service or API credential.

Its detection coverage is aimed at both English and Chinese content. The project includes rules for prompt injection, Chinese identity cards and mobile numbers, UnionPay cards, common API keys, JWTs, passwords, credit cards, and US Social Security numbers. Sensitive data is audited rather than automatically redacted. When sensitive data has recently been accessed, outbound email, HTTP, or shell-based transfer attempts can be denied.

The repository also provides a command-line compliance scanner. It reports findings with file and line locations, checks items such as hardcoded secrets, exposed environment files, Chinese PII, and overseas LLM endpoints or SDKs, and can emit JSON or HTML reports.

## How it works

The jnMetaCode/shellward MCP server exposes checks through JSON-RPC over stdio. A client starts the published executable with `npx`, then registers it in the client’s MCP configuration. The default mode is enforcement; an audit mode is also available. Detection thresholds and locale behavior can be adjusted through environment variables.

The runtime design contains eight named defense layers: prompt guard, input auditor, tool blocker, output scanner, security gate, outbound guard, data-flow guard, and session guard. Tool definitions can be inspected for concealed instructions, invisible characters, secret-file access, and exfiltration hints. The server can also remember an initial tool description fingerprint and identify later changes.

For project assessment, `npx shellward scan` performs a read-only local scan. Optional modes open a report in a browser, serve it locally, produce CI-oriented JSON, or fail a build when critical findings are present. A web mode can scan a public repository URL, while the local web mode reads a local path.

## Setup and configuration

Add the following MCP entry to Claude Desktop, Cursor, or another stdio-compatible MCP client:

```json
{
  "mcpServers": {
    "shellward": {
      "command": "npx",
      "args": ["-y", "-p", "shellward", "shellward-mcp"]
    }
  }
}
```

The jnMetaCode/shellward MCP server supports these settings:

- `SHELLWARD_MODE`: `enforce` or `audit`; enforcement is the default.
- `SHELLWARD_LOCALE`: `auto`, `zh`, or `en`.
- `SHELLWARD_THRESHOLD`: a value from `0` to `100`, defaulting to `40`.
- `SHELLWARD_BASELINE_PATH`: the baseline file location used for tool fingerprints.

The package can also be installed as an SDK with `npm install shellward`, or used through the documented OpenClaw plugin installation.

## Tools and capabilities

The documented MCP interface includes:

- `check_command` for dangerous shell commands and bypass patterns.
- `check_injection` for Chinese and English prompt-injection rules.
- `scan_data` for PII and credential detection.
- `check_path` for sensitive paths such as `.env`, `.ssh`, and credential files.
- `check_tool` for disallowed tool names, including payment or transfer tools.
- `check_response` for canary leaks and PII exposure.
- `scan_mcp_tool` for tool poisoning and description changes.
- `security_status` for the active security configuration.
- `compliance_check` for a China-focused compliance health check.

## Limitations and notes

The material documents security analysis and blocking, not authorization for external systems or guaranteed regulatory compliance. PII findings are returned in an audit result and are not automatically masked. The project’s compliance scan is specifically oriented toward Chinese regulatory concepts and overseas-model data-transfer risks. Client compatibility depends on MCP stdio support and the client’s configuration format.

_Full upstream README: https://allmcps.com/mcp/jnmetacode-shellward/readme_