@baichen_yu/mcp-guard 0.3.0 → 0.3.2

package/README.md

@@ -1,58 +1,115 @@
 # mcp-guard
 
-[![CI](https://img.shields.io/github/actions/workflow/status/TomAs-1226/MCP-shariff/ci.yml?label=CI)](./.github/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/%40baichen_yu%2Fmcp-guard)](https://www.npmjs.com/package/@baichen_yu/mcp-guard)
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+<div align="center">
 
-Security auditing and policy gating for MCP servers (local + CI), with deterministic tests and Markdown/SARIF outputs.
+![mcp-guard logo](docs/public/brand-mark.svg)
 
-> Formerly **mcp-doctor**.
+**Security auditing and policy gating for MCP servers (local + CI).**  
+Deterministic checks. Actionable findings. Reproducible reports.
+
+[![CI](https://img.shields.io/github/actions/workflow/status/TomAs-1226/mcp-guard/ci.yml?label=CI&style=for-the-badge)](./.github/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/%40baichen_yu%2Fmcp-guard?style=for-the-badge)](https://www.npmjs.com/package/@baichen_yu/mcp-guard)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
+[![Node >=20](https://img.shields.io/badge/node-%3E%3D20-3C873A?style=for-the-badge)](./package.json)
+[![Docs](https://img.shields.io/badge/docs-github%20pages-7C3AED?style=for-the-badge)](https://tomas-1226.github.io/mcp-guard/)
+
+</div>
+
+---
 
 > [!IMPORTANT]
-> Remote mode supports **HTTP JSON-RPC only** (`--http`). SSE is not implemented.
+> Remote mode supports **HTTP JSON-RPC** (`--http`) and **SSE** (`--sse`, optional `--sse-post`).
+
+## Why people use mcp-guard
+
+- ✅ **Deterministic contract tests** (no fuzzy behavior, no mystery calls)
+- ✅ **Policy gate in CI** (`--fail-on off|low|medium|high`)
+- ✅ **Security-focused rule packs** with profile controls (`default`, `strict`, `paranoid`)
+- ✅ **Review-friendly output formats** (`report.md`, `report.json`, `report.sarif`)
+- ✅ **Config discovery + redaction** for common MCP client config layouts
+
+### Quick stats
 
-## Package name
+| Signal | Value |
+|---|---:|
+| Transports | STDIO + HTTP JSON-RPC + SSE |
+| Report formats | Markdown, JSON, SARIF |
+| Rule profiles | 3 |
+| Contract scenarios | list, call, error shape, cancellation behavior, large payload, timeout |
+| Registry modes | lint, verify, score |
 
-- npm package: `@baichen_yu/mcp-guard` (scoped to avoid name collisions)
-- CLI command after install: `mcp-guard`
-- first scoped publish: `npm publish --access public`
+---
 
 ## 30-second quickstart
 
-### A) No install (npx)
+### 1) No install (`npx`)
+
+```bash
+npx @baichen_yu/mcp-guard audit \
+  --stdio "node /absolute/path/to/your-mcp-server.cjs" \
+  --out reports \
+  --fail-on off
+```
+
+> [!TIP]
+> `--stdio` runs in your **current working directory**. Use an absolute path or `cd` into the project that contains your server first.
+
+### Local demo (from this repo root)
 
 ```bash
-npx @baichen_yu/mcp-guard audit --stdio "node fixtures/servers/hello-mcp-server/server.cjs" --out reports --fail-on off
+npm run fixtures:gen
+npx @baichen_yu/mcp-guard audit \
+  --stdio "node fixtures/servers/hello-mcp-server/server.cjs" \
+  --out reports \
+  --fail-on off
 ```
 
-### B) Global install
+### 2) Global install
 
 ```bash
 npm i -g @baichen_yu/mcp-guard
 mcp-guard --help
 ```
 
-### C) GitHub Action (paste into workflow)
+### 3) Package + command naming
 
-```yaml
-jobs:
-  mcp-audit:
-    runs-on: ubuntu-latest
-    permissions:
-      security-events: write
-      actions: read
-      contents: read
-    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
-          fail_on: high
+- npm package: **`@baichen_yu/mcp-guard`**
+- runtime CLI command: **`mcp-guard`**
+- first scoped publish command: **`npm publish --access public`**
+
+---
+
+## Architecture
+
+```mermaid
+flowchart LR
+  CLI[mcp-guard CLI] --> T[Transport layer\nSTDIO HTTP SSE]
+  T --> RPC[JSON-RPC client]
+  RPC --> TESTS[Contract tests]
+  RPC --> RULES[Rules and profiles]
+  TESTS --> REPORTS[Reports\nMD JSON SARIF]
+  RULES --> REPORTS
+  REPORTS --> GATE[Policy gate fail-on]
+  GATE --> CI[CI and code scanning]
 ```
 
+### Audit pipeline
+
+```mermaid
+flowchart TD
+  A[Start audit] --> B[Initialize session]
+  B --> C[List tools]
+  C --> D[Run contract suite]
+  C --> E[Run schema and security rules]
+  D --> F[Apply profile tuning]
+  E --> F
+  F --> G[Compute score]
+  G --> H[Emit reports]
+  H --> I[Exit by policy threshold]
+```
+
+---
+
 ## Report preview
 
 ```text
@@ -63,67 +120,122 @@ jobs:
 - Target: node fixtures/servers/hello-mcp-server/server.cjs (stdio)
 ```
 
-## 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]
-```
+---
 
 ## Commands
 
 ```bash
+# Validate / Test / Audit
 mcp-guard validate --stdio "node server.cjs" --profile default --out reports
 mcp-guard test --stdio "node server.cjs" --out reports
 mcp-guard audit --stdio "node server.cjs" --profile strict --fail-on medium --sarif reports/report.sarif
+
+# Remote audit (HTTP JSON-RPC)
 mcp-guard audit --http "http://127.0.0.1:4010" --timeout-ms 30000 --fail-on off
+
+# Remote audit (SSE stream + POST endpoint)
+mcp-guard audit --sse "http://127.0.0.1:4013/sse" --sse-post "http://127.0.0.1:4013/message" --timeout-ms 30000 --fail-on off
+
+# Config scan
 mcp-guard scan --repo . --format md --out reports
+
+# Registry checks
 mcp-guard registry lint registry/servers.yaml
 mcp-guard registry verify registry/servers.yaml --sample 5
 mcp-guard registry score registry/servers.yaml
 ```
 
-## Docs site (GitHub Pages)
+---
 
-- Docs URL pattern: `https://<owner>.github.io/MCP-shariff/`
-- One-time setup: GitHub repo **Settings → Pages → Source → GitHub Actions**
-- Deploy workflow: `.github/workflows/deploy-pages.yml`
+## CI integration (drop-in)
 
-## Links
+```yaml
+jobs:
+  mcp-audit:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      actions: read
+      contents: read
+    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
+          fail_on: high
+```
 
-- Docs: https://tomas-1226.github.io/MCP-shariff/
-- GitHub: https://github.com/TomAs-1226/MCP-shariff
-- npm: https://www.npmjs.com/package/@baichen_yu/mcp-guard
+---
+
+## Automated releases
+
+- On each push to `main`, `.github/workflows/release.yml` now:
+  - runs lint/test/build
+  - computes the next available version above local and npm latest
+  - builds release assets (package tarball + compiled `dist` archive)
+  - creates/updates a GitHub Release with GitHub generated (auto/AI-style) release notes + uploaded assets
+  - publishes the new package to npm (requires `NPM_TOKEN`)
+- For npm publishing in CI, set `NPM_TOKEN` to an **npm Automation token** (no interactive password/OTP required).
+
+## Docs site (GitHub Pages)
+
+- URL pattern: `https://<owner>.github.io/mcp-guard/`
+- Current docs: https://tomas-1226.github.io/mcp-guard/
+- One-time setup: **Settings → Pages → Source → GitHub Actions**
+
+---
 
 ## Troubleshooting
 
-- Node `>=20` required
-- On Windows, wrap `--stdio` command in double quotes
-- If startup is slow, increase `--timeout-ms`
-- HTTP target must accept JSON-RPC over POST
+<details>
+<summary><strong>Publishing ENOENT / package.json not found</strong></summary>
+
+Run `npm publish` from the project root (the directory containing `package.json`).
+
+</details>
+
+<details>
+<summary><strong>HTTP target fails</strong></summary>
+
+Confirm endpoint supports JSON-RPC via HTTP POST and increase `--timeout-ms` if startup is slow.
 
-## Releasing
+</details>
 
-See [`docs/releasing.md`](docs/releasing.md) and [`RELEASE.md`](RELEASE.md).
+<details>
+<summary><strong>Windows command quoting</strong></summary>
 
-### Local release bundle script
+Wrap `--stdio` values in double quotes.
 
-Use this helper to generate a release-ready tarball locally:
+</details>
+
+---
+
+## Release helper
+
+Build release artifacts locally/offline (after one online `npm ci`):
 
 ```bash
-./scripts/build-release-local.sh
+npm run release:offline
 ```
 
-### Publishing troubleshooting
+---
 
-Run `npm publish` from the project root that contains `package.json`.
-If you hit `ENOENT` for `package.json`, you are publishing from the wrong directory.
+## Links
+
+- Docs: https://tomas-1226.github.io/mcp-guard/
+- GitHub: https://github.com/TomAs-1226/mcp-guard
+- npm: https://www.npmjs.com/package/@baichen_yu/mcp-guard
 
 ## License
 
-MIT. See [`LICENSE`](LICENSE).
+MIT. See [LICENSE](LICENSE).
+
+
+### npm package run check
+
+```bash
+npm run npm:test-run
+```

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { mkdir, readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { Command } from 'commander';
-import { HttpJsonRpcClient, StdioJsonRpcClient } from './mcp/jsonrpc.js';
+import { HttpJsonRpcClient, SseJsonRpcClient, StdioJsonRpcClient } from './mcp/jsonrpc.js';
 import { StdioTransport } from './mcp/transport_stdio.js';
 import { writeJsonReport } from './report/json.js';
 import { writeMarkdownReport } from './report/markdown.js';
@@ -40,19 +40,27 @@ function shouldFailByPolicy(findings, failOn) {
     return findings.some((finding) => severityRank[finding.severity] >= rank[failOn]);
 }
 async function buildClient(options) {
-    if (!options.stdio && !options.http)
-        throw new Error('One of --stdio or --http is required.');
-    if (options.stdio && options.http)
-        throw new Error('Use only one transport: --stdio or --http.');
+    const selected = [options.stdio, options.http, options.sse].filter(Boolean).length;
+    if (selected === 0)
+        throw new Error('One of --stdio, --http, or --sse is required.');
+    if (selected > 1)
+        throw new Error('Use only one transport: --stdio, --http, or --sse.');
     if (options.stdio) {
         const transport = new StdioTransport();
         await transport.start({ stdioCommand: options.stdio, silent: options.silent });
         return { client: new StdioJsonRpcClient(transport, options.timeoutMs), target: options.stdio, transport: 'stdio' };
     }
-    return { client: new HttpJsonRpcClient(options.http, options.timeoutMs), target: options.http, transport: 'http' };
+    if (options.http) {
+        return { client: new HttpJsonRpcClient(options.http, options.timeoutMs), target: options.http, transport: 'http' };
+    }
+    return {
+        client: new SseJsonRpcClient(options.sse, options.timeoutMs, options.ssePost ?? options.sse),
+        target: options.sse,
+        transport: 'sse'
+    };
 }
 async function executeSuite(params) {
-    const { client, target, transport } = await buildClient({ stdio: params.stdio, http: params.http, timeoutMs: params.timeoutMs, silent: false });
+    const { client, target, transport } = await buildClient({ stdio: params.stdio, http: params.http, sse: params.sse, ssePost: params.ssePost, timeoutMs: params.timeoutMs, silent: false });
     const findings = [];
     let tools = [];
     const tests = [];
@@ -110,13 +118,15 @@ async function executeSuite(params) {
 }
 program
     .name('mcp-guard')
-    .description('Validate, test, and security-audit MCP servers over STDIO or HTTP JSON-RPC')
+    .description('Validate, test, and security-audit MCP servers over STDIO, HTTP JSON-RPC, or SSE + JSON-RPC')
     .showHelpAfterError();
 for (const commandName of ['validate', 'test', 'audit']) {
     program.command(commandName)
         .description(`${commandName} an MCP server`)
         .option('--stdio <cmd>', 'Command used to launch MCP server over stdio')
         .option('--http <url>', 'HTTP JSON-RPC endpoint URL')
+        .option('--sse <url>', 'SSE endpoint URL for responses')
+        .option('--sse-post <url>', 'HTTP POST URL used to send JSON-RPC requests (defaults to --sse)')
         .option('--out <dir>', 'Output directory', 'reports')
         .option('--sarif <file>', 'SARIF output file (mainly for audit)', 'reports/report.sarif')
         .option('--profile <profile>', 'Rule profile: default|strict|paranoid', parseProfile, 'default')
@@ -128,6 +138,8 @@ for (const commandName of ['validate', 'test', 'audit']) {
         const code = await executeSuite({
             stdio: options.stdio,
             http: options.http,
+            sse: options.sse,
+            ssePost: options.ssePost,
             outDir: options.out,
             runTests: doTests,
             runAudit: doAudit,

package/dist/mcp/jsonrpc.d.ts

@@ -20,4 +20,20 @@ export declare class HttpJsonRpcClient implements RpcClient {
     normalizeError(error: unknown): NormalizedError;
     close(): Promise<void>;
 }
+export declare class SseJsonRpcClient implements RpcClient {
+    private readonly streamUrl;
+    private readonly timeoutMs;
+    private readonly postUrl;
+    private nextId;
+    private pending;
+    private streamController?;
+    private readerPromise?;
+    constructor(streamUrl: string, timeoutMs?: number, postUrl?: string);
+    request<T>(method: string, params?: unknown, timeoutOverrideMs?: number): Promise<T>;
+    normalizeError(error: unknown): NormalizedError;
+    close(): Promise<void>;
+    private ensureStream;
+    private openAndReadStream;
+    private resolvePending;
+}
 export declare function normalizeError(error: unknown): NormalizedError;

package/dist/mcp/jsonrpc.js

@@ -101,6 +101,134 @@ export class HttpJsonRpcClient {
         await Promise.resolve();
     }
 }
+export class SseJsonRpcClient {
+    streamUrl;
+    timeoutMs;
+    postUrl;
+    nextId = 1;
+    pending = new Map();
+    streamController;
+    readerPromise;
+    constructor(streamUrl, timeoutMs = 5000, postUrl = streamUrl) {
+        this.streamUrl = streamUrl;
+        this.timeoutMs = timeoutMs;
+        this.postUrl = postUrl;
+    }
+    async request(method, params, timeoutOverrideMs) {
+        await this.ensureStream();
+        const id = this.nextId++;
+        const payload = { jsonrpc: '2.0', id, method, params };
+        return new Promise(async (resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Request timed out: ${method}`));
+            }, timeoutOverrideMs ?? this.timeoutMs);
+            this.pending.set(id, { resolve: resolve, reject, timer });
+            try {
+                const response = await fetch(this.postUrl, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify(payload)
+                });
+                if (!response.ok) {
+                    throw new Error(`SSE POST failed: ${response.status}`);
+                }
+                const contentType = response.headers.get('content-type') ?? '';
+                if (contentType.includes('application/json')) {
+                    const parsed = (await response.json());
+                    this.resolvePending(parsed);
+                }
+            }
+            catch (error) {
+                const pending = this.pending.get(id);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pending.delete(id);
+                    pending.reject(error);
+                }
+            }
+        });
+    }
+    normalizeError(error) {
+        return normalizeError(error);
+    }
+    async close() {
+        this.streamController?.abort();
+        await this.readerPromise?.catch(() => undefined);
+        for (const [id, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('SSE client closed'));
+            this.pending.delete(id);
+        }
+    }
+    async ensureStream() {
+        if (this.readerPromise)
+            return;
+        this.streamController = new AbortController();
+        this.readerPromise = this.openAndReadStream(this.streamController.signal).catch((error) => {
+            for (const [id, pending] of this.pending) {
+                clearTimeout(pending.timer);
+                pending.reject(error);
+                this.pending.delete(id);
+            }
+            this.readerPromise = undefined;
+        });
+    }
+    async openAndReadStream(signal) {
+        const response = await fetch(this.streamUrl, {
+            method: 'GET',
+            headers: { Accept: 'text/event-stream' },
+            signal
+        });
+        if (!response.ok || !response.body) {
+            throw new Error(`Failed to open SSE stream: ${response.status}`);
+        }
+        const decoder = new TextDecoder();
+        const reader = response.body.getReader();
+        let buffer = '';
+        let dataLines = [];
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let idx = buffer.indexOf('\n');
+            while (idx >= 0) {
+                const line = buffer.slice(0, idx).replace(/\r$/, '');
+                buffer = buffer.slice(idx + 1);
+                if (line.startsWith('data:')) {
+                    dataLines.push(line.slice(5).trimStart());
+                }
+                else if (line === '') {
+                    if (dataLines.length > 0) {
+                        const payload = dataLines.join('\n');
+                        dataLines = [];
+                        try {
+                            const parsed = JSON.parse(payload);
+                            this.resolvePending(parsed);
+                        }
+                        catch {
+                            // ignore malformed events
+                        }
+                    }
+                }
+                idx = buffer.indexOf('\n');
+            }
+        }
+    }
+    resolvePending(parsed) {
+        const pending = this.pending.get(parsed.id);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.pending.delete(parsed.id);
+        if ('error' in parsed) {
+            pending.reject(parsed.error);
+            return;
+        }
+        pending.resolve(parsed.result);
+    }
+}
 export function normalizeError(error) {
     if (typeof error === 'object' && error !== null && 'code' in error && 'message' in error) {
         const err = error;

package/dist/mcp/types.d.ts

@@ -29,6 +29,8 @@ export interface ToolDescriptor {
 export interface ServerConfig {
     stdioCommand?: string;
     httpUrl?: string;
+    sseUrl?: string;
+    ssePostUrl?: string;
     cwd?: string;
     env?: Record<string, string>;
     timeoutMs?: number;
@@ -52,7 +54,7 @@ export interface TestResult {
 export interface Report {
     server: {
         target: string;
-        transport: 'stdio' | 'http';
+        transport: 'stdio' | 'http' | 'sse';
         protocolVersion?: string;
     };
     tools: ToolDescriptor[];

package/dist/scan/scanner.d.ts

@@ -2,7 +2,7 @@ export interface DiscoveredServer {
     source: 'claude_desktop' | 'cursor';
     path: string;
     name: string;
-    transport: 'stdio' | 'http' | 'unknown';
+    transport: 'stdio' | 'http' | 'sse' | 'unknown';
     command?: string;
     rawCommand?: string;
     permissions?: string[];

package/dist/scan/scanner.js

@@ -23,6 +23,8 @@ function redact(text) {
 function detectTransport(server) {
     if (typeof server.command === 'string')
         return 'stdio';
+    if (typeof server.sseUrl === 'string' || typeof server.sse === 'string')
+        return 'sse';
     if (typeof server.url === 'string' || typeof server.httpUrl === 'string')
         return 'http';
     return 'unknown';

package/docs/cli.md

@@ -16,9 +16,9 @@ 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]`
+- `mcp-guard validate --stdio <cmd>|--http <url>|--sse <url> [--sse-post <url>] [--profile default|strict|paranoid] [--out reports] [--timeout-ms 30000]`
+- `mcp-guard test --stdio <cmd>|--http <url>|--sse <url> [--sse-post <url>] [--out reports] [--timeout-ms 30000]`
+- `mcp-guard audit --stdio <cmd>|--http <url>|--sse <url> [--sse-post <url>] [--profile ...] [--fail-on off|low|medium|high] [--sarif reports/report.sarif]`
 
 ## Scan and registry commands
 
@@ -35,4 +35,6 @@ mcp-guard --help
 
 ## Remote transport support
 
-`--http` supports HTTP JSON-RPC (POST) only. SSE is not supported.
+`--http` supports HTTP JSON-RPC (POST).
+
+`--sse` supports SSE response streams (GET) with request POSTs sent to `--sse-post` (or to `--sse` when omitted).

package/docs/index.md

@@ -3,39 +3,39 @@ 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."
+  text: "Security gating for MCP servers, from local dev to CI"
+  tagline: "Validate protocol contracts, test runtime behavior, and enforce policy with reproducible reports."
   image:
     src: /brand-mark.svg
     alt: mcp-guard
   actions:
     - theme: brand
-      text: 30-second quickstart
+      text: Start in 30 seconds
       link: /quickstart
+    - theme: alt
+      text: Run tests
+      link: /testing
     - 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.
+    title: Deterministic contract checks
+    details: Fixed checks for tools/list, tool-call behavior, malformed payloads, cancellation behavior, large responses, and timeout boundaries.
   - icon: 🛡️
     title: Policy gate built-in
-    details: Use profiles and --fail-on thresholds to enforce guardrails in CI without custom glue code.
+    details: Use profile severity 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.
+    details: Generate Markdown + JSON + SARIF artifacts designed for pull-request review and code scanning.
   - icon: 🚦
-    title: Two transport modes
-    details: Local stdio and remote HTTP JSON-RPC support with bounded retries and timeouts.
+    title: Three transport modes
+    details: Local stdio plus remote HTTP JSON-RPC and SSE support with bounded retries and timeouts.
 ---
 
 > [!IMPORTANT]
-> Remote mode currently supports **HTTP JSON-RPC only** (`--http`). SSE is not implemented.
+> Remote mode supports **HTTP JSON-RPC** (`--http`) and **SSE** (`--sse`).
 
 <div class="stats-grid">
   <div class="stat-card"><h4>Profiles</h4><p><code>default</code> · <code>strict</code> · <code>paranoid</code></p></div>
@@ -43,21 +43,31 @@ features:
   <div class="stat-card"><h4>Policy</h4><p><code>--fail-on off|low|medium|high</code></p></div>
 </div>
 
-## Report preview
+## Typical workflow
 
-<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 class="workflow-grid">
+  <div class="workflow-card">
+    <h4>1) Validate quickly</h4>
+    <p>Run checks locally against your MCP server before opening a PR.</p>
+    <code>mcp-guard validate --stdio "node server.cjs"</code>
+  </div>
+  <div class="workflow-card">
+    <h4>2) Test behavior</h4>
+    <p>Execute deterministic test probes and emit machine-readable reports.</p>
+    <code>mcp-guard test --stdio "node server.cjs"</code>
+  </div>
+  <div class="workflow-card">
+    <h4>3) Gate in CI</h4>
+    <p>Use <code>audit</code> with SARIF and severity thresholds to block risky changes.</p>
+    <code>mcp-guard audit --fail-on medium --sarif reports/report.sarif</code>
+  </div>
 </div>
 
 ## Architecture
 
 ```mermaid
 graph LR
-  CLI[mcp-guard CLI] --> T[Transports: stdio/http]
+  CLI[mcp-guard CLI] --> T[Transports: stdio/http/sse]
   T --> RPC[JSON-RPC]
   RPC --> RULES[Rules + Profiles]
   RULES --> REP[Reports: md/json/sarif]
@@ -71,5 +81,5 @@ graph LR
 2. Upload SARIF so findings show in security dashboards.
 3. Gate merges on reproducible report output.
 
-- GitHub: https://github.com/TomAs-1226/MCP-shariff
+- GitHub: https://github.com/TomAs-1226/mcp-guard
 - npm: https://www.npmjs.com/package/@baichen_yu/mcp-guard

package/docs/quickstart.md

@@ -27,8 +27,23 @@ npm publish --access public
 
 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/`.
+3. Expected URL after repo rename to `mcp-guard`: `https://<owner>.github.io/mcp-guard/`.
+4. If the site renders as plain text or a blank page, confirm docs base path is set to `/<repo-name>/`.
 
 ## Remote mode note
 
-Remote mode supports **HTTP JSON-RPC only** (`--http`). SSE is not supported yet.
+Remote mode supports **HTTP JSON-RPC** (`--http`) and **SSE** (`--sse`, optional `--sse-post`).
+
+
+## SSE quick check
+
+```bash
+node fixtures/servers/sse-mcp-server/server.cjs
+# in another shell
+npx @baichen_yu/mcp-guard audit --sse "http://127.0.0.1:4013/sse" --sse-post "http://127.0.0.1:4013/message" --out reports --fail-on off
+```
+
+
+## Release auth note
+
+For automatic npm releases in GitHub Actions, create an **npm Automation token** and store it as repository secret `NPM_TOKEN`. This avoids interactive password/OTP prompts during CI publish.

package/docs/releasing.md

@@ -36,4 +36,49 @@ 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)
+- transport note (HTTP JSON-RPC + SSE supported)
+
+
+## Automated release pipeline
+
+On pushes to `main`, `.github/workflows/release.yml` will:
+
+1. Run `npm run lint`, `npm test`, and `npm run build`.
+2. Compute the next available version above both local `package.json` and npm latest, then bump to that version.
+3. Push commit + tag back to GitHub.
+4. Build release assets (`npm pack` tarball + compiled `dist` archive).
+5. Publish to npm with provenance.
+6. Create/update a GitHub Release with generated release notes and uploaded assets.
+
+Required secret: `NPM_TOKEN` with publish permission for `@baichen_yu/mcp-guard`.
+
+Use an **npm Automation token** (recommended) so the workflow can publish without interactive password/OTP prompts.
+
+- npm: create token at <https://www.npmjs.com/settings/tokens>
+- GitHub: add it as repository secret `NPM_TOKEN`
+- workflow preflight runs `npm whoami` to confirm auth before version bump/publish
+
+
+## Offline release package build
+
+After dependencies are installed once (`npm ci` while online), you can build the release tarball completely offline:
+
+```bash
+npm run release:offline
+```
+
+If `node_modules` is missing, the script exits with guidance.
+
+## npm package test-run command
+
+Use this to verify the published package entrypoint works:
+
+```bash
+npm run npm:test-run
+```
+
+
+The workflow also supports manual trigger via `workflow_dispatch` in GitHub Actions.
+
+
+If a release tag already exists (for example, from a re-run), the workflow updates that release and re-uploads assets with `--clobber` instead of failing.

package/docs/testing.md

@@ -0,0 +1,67 @@
+# Testing options
+
+Use these commands depending on what you want to verify.
+
+## 1) Unit/integration test suite (Vitest)
+
+```bash
+npm test
+```
+
+Runs the project test suite and regenerates fixtures first (`pretest`).
+
+## 2) TypeScript compile checks (no emit)
+
+```bash
+npm run lint
+```
+
+Confirms the codebase type-checks cleanly.
+
+## 3) Production build
+
+```bash
+npm run build
+```
+
+Compiles CLI sources to `dist/`.
+
+## 4) Docs build (GitHub Pages artifact parity)
+
+```bash
+npm run docs:build
+```
+
+Builds the VitePress static site exactly like the Pages workflow.
+
+## 5) Example end-to-end CLI run
+
+```bash
+npx tsx src/cli.ts audit --stdio "node fixtures/servers/hello-mcp-server/server.cjs" --out reports --fail-on off
+```
+
+This is a practical smoke test that exercises transport, rules, and report generation.
+
+## Minimal local validation flow
+
+```bash
+npm run lint && npm test && npm run build && npm run docs:build
+```
+
+
+## SSE smoke test
+
+```bash
+node fixtures/servers/sse-mcp-server/server.cjs
+# new terminal
+node dist/cli.js audit --sse "http://127.0.0.1:4013/sse" --sse-post "http://127.0.0.1:4013/message" --out reports --fail-on off
+```
+
+
+## Published npm package smoke test
+
+```bash
+npm run npm:test-run
+```
+
+This executes the package from npm and prints CLI help to verify install/entrypoint integrity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baichen_yu/mcp-guard",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Security auditing and policy gating for MCP servers (STDIO/HTTP) with Markdown + SARIF reports",
   "type": "module",
   "bin": {
@@ -11,13 +11,18 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
     "dev": "tsx src/cli.ts",
+    "pretest": "npm run fixtures:gen",
     "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"
+    "docs:preview": "vitepress preview docs",
+    "prepublishOnly": "npm run lint && npm test",
+    "release:offline": "bash scripts/build-release-local.sh",
+    "npm:test-run": "PKG=$(npm pack --silent | tail -n 1) && npx --yes --package \"./$PKG\" mcp-guard --help && rm -f \"$PKG\""
   },
   "dependencies": {
     "commander": "^12.1.0",
@@ -41,11 +46,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/TomAs-1226/MCP-shariff.git"
+    "url": "https://github.com/TomAs-1226/mcp-guard.git"
   },
-  "homepage": "https://tomas-1226.github.io/MCP-shariff/",
+  "homepage": "https://tomas-1226.github.io/mcp-guard/",
   "bugs": {
-    "url": "https://github.com/TomAs-1226/MCP-shariff/issues"
+    "url": "https://github.com/TomAs-1226/mcp-guard/issues"
   },
   "publishConfig": {
     "access": "public"