Shellward

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:

{
  "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.