@baichen_yu/mcp-guard 0.3.0

package/dist/tests/contract/list_tools.js

@@ -0,0 +1,14 @@
+export async function runListToolsTest(client) {
+    const start = Date.now();
+    const listed = (await client.request('tools/list')).tools;
+    const passed = Array.isArray(listed) && listed.length > 0;
+    return {
+        result: {
+            name: 'list_tools',
+            passed,
+            durationMs: Date.now() - start,
+            details: passed ? `Listed ${listed.length} tools` : 'No tools returned'
+        },
+        tools: listed
+    };
+}

package/dist/tests/contract/timeout.d.ts

@@ -0,0 +1,2 @@
+import { RpcClient, TestResult } from '../../mcp/types.js';
+export declare function runTimeoutTest(client: RpcClient): Promise<TestResult>;

package/dist/tests/contract/timeout.js

@@ -0,0 +1,25 @@
+export async function runTimeoutTest(client) {
+    const start = Date.now();
+    try {
+        await client.request('tools/call', {
+            name: 'sleep',
+            arguments: { ms: 300 }
+        }, 30);
+        return {
+            name: 'deterministic_timeout',
+            passed: false,
+            durationMs: Date.now() - start,
+            details: 'Expected timeout did not occur'
+        };
+    }
+    catch (error) {
+        const normalized = client.normalizeError(error);
+        const passed = /timed out|aborted|abort/i.test(normalized.message);
+        return {
+            name: 'deterministic_timeout',
+            passed,
+            durationMs: Date.now() - start,
+            details: normalized.message
+        };
+    }
+}

package/dist/validate/schema_lints.d.ts

@@ -0,0 +1,2 @@
+import { Finding, Profile, ToolDescriptor } from '../mcp/types.js';
+export declare function runSchemaLints(tools: ToolDescriptor[], profile: Profile): Finding[];

package/dist/validate/schema_lints.js

@@ -0,0 +1,65 @@
+function asObject(input) {
+    return typeof input === 'object' && input !== null ? input : {};
+}
+export function runSchemaLints(tools, profile) {
+    const findings = [];
+    for (const tool of tools) {
+        const schema = asObject(tool.inputSchema);
+        const properties = asObject(schema.properties);
+        if (!tool.description && profile !== 'default') {
+            findings.push({
+                severity: 'low',
+                ruleId: 'schema.missing_description',
+                message: `Tool ${tool.name} is missing a description`,
+                evidence: tool.name,
+                remediation: 'Add a concise description for tooling and reviewers.',
+                toolName: tool.name
+            });
+        }
+        if (Object.keys(properties).length === 0) {
+            findings.push({
+                severity: 'medium',
+                ruleId: 'schema.empty_properties',
+                message: `Tool ${tool.name} does not declare input properties`,
+                evidence: JSON.stringify(tool.inputSchema),
+                remediation: 'Add explicit JSON Schema properties and constraints.',
+                toolName: tool.name
+            });
+        }
+        for (const [name, raw] of Object.entries(properties)) {
+            const prop = asObject(raw);
+            if (prop.type === 'string' && !('maxLength' in prop) && !('enum' in prop) && !('pattern' in prop)) {
+                const severity = profile === 'strict' || profile === 'paranoid' ? 'medium' : 'low';
+                findings.push({
+                    severity,
+                    ruleId: 'schema.unbounded_string',
+                    message: `Parameter ${name} on tool ${tool.name} is an unconstrained string`,
+                    evidence: JSON.stringify(prop),
+                    remediation: 'Add maxLength, enum, or pattern constraints.',
+                    toolName: tool.name
+                });
+            }
+            if (prop.type === 'array' && !('maxItems' in prop)) {
+                findings.push({
+                    severity: 'medium',
+                    ruleId: 'schema.unbounded_array',
+                    message: `Parameter ${name} on tool ${tool.name} is an unbounded array`,
+                    evidence: JSON.stringify(prop),
+                    remediation: 'Add maxItems and constrain item values.',
+                    toolName: tool.name
+                });
+            }
+            if ((profile === 'strict' || profile === 'paranoid') && /(mode|type|kind|format)/i.test(name) && !('enum' in prop)) {
+                findings.push({
+                    severity: 'low',
+                    ruleId: 'schema.categorical_missing_enum',
+                    message: `Categorical field ${name} on tool ${tool.name} should use enum`,
+                    evidence: JSON.stringify(prop),
+                    remediation: 'Declare explicit enum values for categorical fields.',
+                    toolName: tool.name
+                });
+            }
+        }
+    }
+    return findings;
+}

package/docs/assets/demo.gif

@@ -0,0 +1 @@
+This is a placeholder. Record a terminal demo (asciinema or GIF) and replace this file.

package/docs/cli.md

@@ -0,0 +1,38 @@
+# CLI Reference
+
+## Install
+
+```bash
+npm i -g @baichen_yu/mcp-guard
+# or
+npx @baichen_yu/mcp-guard --help
+```
+
+Installed command remains:
+
+```bash
+mcp-guard --help
+```
+
+## Core commands
+
+- `mcp-guard validate --stdio <cmd>|--http <url> [--profile default|strict|paranoid] [--out reports] [--timeout-ms 30000]`
+- `mcp-guard test --stdio <cmd>|--http <url> [--out reports] [--timeout-ms 30000]`
+- `mcp-guard audit --stdio <cmd>|--http <url> [--profile ...] [--fail-on off|low|medium|high] [--sarif reports/report.sarif]`
+
+## Scan and registry commands
+
+- `mcp-guard scan [--repo <path>] [--path <file>] [--format md|json|sarif] [--out reports]`
+- `mcp-guard registry lint <file>`
+- `mcp-guard registry score <file>`
+- `mcp-guard registry verify <file> --sample 5`
+
+## Exit codes
+
+- `0`: clean run (or below policy threshold)
+- `1`: findings exist, but not policy-failing
+- `2`: contract failure, policy failure, or invalid command/config
+
+## Remote transport support
+
+`--http` supports HTTP JSON-RPC (POST) only. SSE is not supported.

package/docs/github-action.md

@@ -0,0 +1,23 @@
+# GitHub Action
+
+Use the local composite action to run audits and upload SARIF.
+
+```yaml
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: ./.github/actions/mcp-guard
+        with:
+          stdio_command: node fixtures/servers/hello-mcp-server/server.cjs
+          out_dir: reports
+          sarif_path: reports/report.sarif
+          fail_on: high
+          timeout_ms: 30000
+```
+
+SARIF is always uploaded before policy enforcement runs.

package/docs/index.md

@@ -0,0 +1,75 @@
+---
+layout: home
+
+hero:
+  name: "mcp-guard"
+  text: "Practical security gating for MCP servers"
+  tagline: "Deterministic MCP validation, contract tests, and audit reporting for local workflows and CI."
+  image:
+    src: /brand-mark.svg
+    alt: mcp-guard
+  actions:
+    - theme: brand
+      text: 30-second quickstart
+      link: /quickstart
+    - theme: alt
+      text: CLI reference
+      link: /cli
+    - theme: alt
+      text: GitHub Action
+      link: /github-action
+
+features:
+  - icon: 🧪
+    title: Deterministic contracts
+    details: Fixed checks for tools/list, tool call behavior, invalid shapes, cancellation behavior, large payload handling, and timeouts.
+  - icon: 🛡️
+    title: Policy gate built-in
+    details: Use profiles and --fail-on thresholds to enforce guardrails in CI without custom glue code.
+  - icon: 📄
+    title: Reproducible outputs
+    details: Markdown + JSON + SARIF reports designed for review, snapshots, and code-scanning pipelines.
+  - icon: 🚦
+    title: Two transport modes
+    details: Local stdio and remote HTTP JSON-RPC support with bounded retries and timeouts.
+---
+
+> [!IMPORTANT]
+> Remote mode currently supports **HTTP JSON-RPC only** (`--http`). SSE is not implemented.
+
+<div class="stats-grid">
+  <div class="stat-card"><h4>Profiles</h4><p><code>default</code> · <code>strict</code> · <code>paranoid</code></p></div>
+  <div class="stat-card"><h4>Outputs</h4><p><code>report.md</code> · <code>report.json</code> · <code>report.sarif</code></p></div>
+  <div class="stat-card"><h4>Policy</h4><p><code>--fail-on off|low|medium|high</code></p></div>
+</div>
+
+## Report preview
+
+<div class="report-preview">
+<strong>MCP Guard Report</strong><br/>
+Risk score: <code>100/100</code><br/>
+Key findings: <code>0</code><br/>
+Contract tests: <code>6/6</code><br/>
+Target: <code>node fixtures/servers/hello-mcp-server/server.cjs (stdio)</code>
+</div>
+
+## Architecture
+
+```mermaid
+graph LR
+  CLI[mcp-guard CLI] --> T[Transports: stdio/http]
+  T --> RPC[JSON-RPC]
+  RPC --> RULES[Rules + Profiles]
+  RULES --> REP[Reports: md/json/sarif]
+  REP --> GATE[Policy Gate (--fail-on)]
+  GATE --> CI[CI / Code Scanning]
+```
+
+## Ship checklist
+
+1. Run `mcp-guard audit` in CI with `--fail-on` policy.
+2. Upload SARIF so findings show in security dashboards.
+3. Gate merges on reproducible report output.
+
+- GitHub: https://github.com/TomAs-1226/MCP-shariff
+- npm: https://www.npmjs.com/package/@baichen_yu/mcp-guard

package/docs/quickstart.md

@@ -0,0 +1,34 @@
+# Quickstart
+
+## No install (npx)
+
+```bash
+npx @baichen_yu/mcp-guard audit --stdio "node fixtures/servers/hello-mcp-server/server.cjs" --out reports --fail-on off
+```
+
+## Global install
+
+```bash
+npm i -g @baichen_yu/mcp-guard
+mcp-guard --help
+```
+
+## Package note
+
+The npm package is scoped as `@baichen_yu/mcp-guard` to avoid name collisions, while the runtime CLI command stays `mcp-guard`.
+
+For first publish of the scoped package, use:
+
+```bash
+npm publish --access public
+```
+
+## GitHub Pages docs
+
+1. Enable **Settings → Pages → Source → GitHub Actions** once.
+2. Docs deploy from `.github/workflows/deploy-pages.yml`.
+3. Expected URL: `https://<owner>.github.io/MCP-shariff/`.
+
+## Remote mode note
+
+Remote mode supports **HTTP JSON-RPC only** (`--http`). SSE is not supported yet.

package/docs/releasing.md

@@ -0,0 +1,39 @@
+# Releasing
+
+## Prerequisites
+
+- npm account has access to `@baichen_yu` scope
+- GitHub Pages source is set to **GitHub Actions**
+
+## First publish (scoped package)
+
+```bash
+npm login
+npm run fixtures:gen
+npm run lint
+npm test
+npm run build
+npm run docs:build
+npm pack --dry-run
+npm publish --access public
+```
+
+Why `--access public`?
+Scoped packages default to private on first publish. Explicitly setting public avoids that surprise.
+
+## Publishing troubleshooting
+
+- Run `npm publish` from the project root (the directory that contains `package.json`).
+- If you see `ENOENT` about missing `package.json`, you are in the wrong directory.
+
+## Tag + GitHub Release
+
+```bash
+git tag v0.3.0
+git push origin v0.3.0
+```
+
+Then create a GitHub Release and include:
+- key highlights
+- migration note (formerly mcp-doctor)
+- limitation note (HTTP JSON-RPC only, SSE not supported)

package/docs/rules.md

@@ -0,0 +1,18 @@
+# Rules and Profiles
+
+## Rules
+
+- `schema.empty_properties`: tool schema has no declared properties.
+- `schema.unbounded_string`: string input without maxLength/enum/pattern.
+- `schema.unbounded_array`: array input without maxItems.
+- `schema.missing_description` (strict/paranoid): tool description missing.
+- `schema.categorical_missing_enum` (strict/paranoid): categorical field lacks enum.
+- `security.path_traversal`: path/file parameters without allowlist constraints.
+- `security.shell_injection`: raw command/shell arguments accepted as strings.
+- `security.raw_args`: unbounded argv/flags arrays.
+
+## Profiles
+
+- `default`: baseline rule set.
+- `strict`: enables additional schema hygiene checks and heavier scoring.
+- `paranoid`: escalates shell/argv findings to high severity and uses strongest score penalties.

package/docs/security-model.md

@@ -0,0 +1,14 @@
+# Security Model
+
+`mcp-guard` is designed for deterministic, bounded checks.
+
+- Contract tests are fixed and do not execute arbitrary tool payloads.
+- Every request has a timeout; transports enforce bounded retries.
+- Child processes are terminated on shutdown.
+- Config scan redacts token-like values in output.
+- Registry verify is offline-only and never executes remote servers.
+
+## Known limitations
+
+- HTTP mode currently supports JSON-RPC over POST, not SSE.
+- `scan` reports discovered configurations and metadata, but does not execute every discovered server by default.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@baichen_yu/mcp-guard",
+  "version": "0.3.0",
+  "description": "Security auditing and policy gating for MCP servers (STDIO/HTTP) with Markdown + SARIF reports",
+  "type": "module",
+  "bin": {
+    "mcp-guard": "dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "fixtures:gen": "tsx scripts/gen-fixtures.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "vitepress": "^1.6.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "RELEASE.md",
+    "docs/*.md",
+    "docs/assets/demo.gif"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TomAs-1226/MCP-shariff.git"
+  },
+  "homepage": "https://tomas-1226.github.io/MCP-shariff/",
+  "bugs": {
+    "url": "https://github.com/TomAs-1226/MCP-shariff/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/cli.js",
+  "types": "dist/cli.d.ts",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "security",
+    "audit",
+    "sarif",
+    "cli",
+    "lint"
+  ]
+}