@aiclude/mcp-guard 0.2.0 → 0.2.2

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 AIclude Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,209 +1,401 @@
-<p align="center">
-  <img src="https://aiclude.com/assets/mcp-guard-logo.svg" alt="MCP Guard" width="120" />
-</p>
+# MCP Guard
 
-<h1 align="center">MCP Guard</h1>
+**Real-time security firewall for AI agents**
 
-<p align="center">
-  <strong>AI 에이전트를 위한 실시간 보안 방화벽</strong><br/>
-  MCP(Model Context Protocol) 통신을 실시간으로 검사하고, 악성 도구 호출을 사전에 차단합니다.
-</p>
+MCP Guard is an inline security proxy that sits between MCP clients and servers. It inspects every message in real-time and blocks malicious tool calls before they reach the server.
 
-<p align="center">
-  <a href="#왜-mcp-guard인가">왜 필요한가</a> ·
-  <a href="#핵심-기능">핵심 기능</a> ·
-  <a href="#빠른-시작">빠른 시작</a> ·
-  <a href="USAGE.md">사용 가이드</a> ·
-  <a href="LICENSE.md">라이선스</a>
-</p>
+[![npm version](https://img.shields.io/npm/v/@aiclude/mcp-guard.svg)](https://www.npmjs.com/package/@aiclude/mcp-guard)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 
 ---
 
-## 왜 MCP Guard인가?
+## Why MCP Guard?
 
-AI 에이전트 시대, **MCP(Model Context Protocol)** 는 사실상의 표준이 되었습니다. Claude, Cursor, Copilot 등 주요 AI 도구가 MCP를 통해 외부 시스템과 연동합니다.
+In 2026, **MCP (Model Context Protocol)** has become the de facto standard for AI agents to interact with external systems. Claude, Cursor, Copilot, and other major AI tools use MCP to connect to databases, APIs, file systems, and cloud services.
 
-**그러나 MCP 통신은 무방비 상태입니다.**
+**But MCP communication is unprotected.**
 
-- 2026년 1~2월, MCP 관련 CVE **30건 이상** 발생
-- MCP 플러그인 10개만 설치해도 **92%의 익스플로잇 확률** (VentureBeat)
-- **OWASP MCP Top 10** 발표 — Tool Poisoning, Prompt Injection, Context Spoofing 등 실제 공격 확인
+- **30+ CVEs** reported in Jan–Feb 2026 alone
+- **92% exploit probability** with just 10 MCP plugins installed ([VentureBeat](https://venturebeat.com))
+- **OWASP MCP Top 10** published — Tool Poisoning, Prompt Injection, Context Spoofing confirmed as real attack vectors
 
-기존 보안 도구(WAF, SAST, DAST)는 MCP 프로토콜 레벨에서 동작하지 않습니다. HTTP 요청이 아닌 **JSON-RPC 메시지 스트림** 위에서 벌어지는 공격은 기존 도구로 탐지할 수 없습니다.
+Existing security tools (WAF, SAST, DAST) don't operate at the MCP protocol level. Attacks happening inside **JSON-RPC message streams** over stdio pipes or SSE are invisible to traditional security tools.
 
-> **MCP Guard**는 MCP 클라이언트와 서버 사이에 인라인으로 위치하여, 모든 메시지를 실시간으로 검사하고 위험한 도구 호출을 **서버에 도달하기 전에 차단**합니다.
+> **MCP Guard** inspects all messages in real-time and **blocks dangerous tool calls before they reach the server**.
 
 ---
 
-## 핵심 기능
+## Quick Start
 
-### 실시간 양방향 메시지 검사
+### Install
 
-MCP 클라이언트 → 서버, 서버 → 클라이언트 **양방향 모든 메시지**를 실시간으로 검사합니다. 단순한 사후 분석이 아닌, 위험이 실행되기 전에 차단하는 **인라인 보안 프록시**입니다.
+```bash
+npm install -g @aiclude/mcp-guard
+```
 
-### 3대 보안 룰 엔진
+### stdio mode — Protect a local MCP server
 
-| 보안 룰 | 검사 대상 | 대응 위협 |
-|---------|----------|----------|
-| **Tool Poisoning Detection** | 서버가 노출하는 도구 목록 | 제로폭 스테가노그래피, 프롬프트 인젝션, 도구명 사칭, 호모글리프 위장 |
-| **Argument Injection Detection** | 클라이언트의 도구 호출 인자 | SQL/Command/XSS/Path Traversal/Template 인젝션 |
-| **Data Exfiltration Detection** | 서버의 도구 실행 결과 | 민감 데이터 노출, 시스템 경로 유출, 명령어 실행 증거 |
+```bash
+mcp-guard -- npx @modelcontextprotocol/server-fetch
+```
 
-### 다국어 위협 탐지
+### HTTP mode — Protect a remote MCP server
 
-영어뿐 아니라 **한국어, 중국어, 일본어** 프롬프트 인젝션 구절을 탐지합니다. 시릴릭/그리스 문자를 이용한 호모글리프 우회 공격도 정규화하여 차단합니다.
+```bash
+mcp-guard http --upstream http://mcp-server:8080/mcp --port 9090
+```
 
-### 듀얼 프로토콜 지원
+### Claude Desktop Integration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "fetch-guarded": {
+      "command": "npx",
+      "args": ["-y", "@aiclude/mcp-guard", "--", "npx", "-y", "@modelcontextprotocol/server-fetch"]
+    }
+  }
+}
+```
 
-| 모드 | 용도 | 대상 |
-|------|------|------|
-| **stdio** | 로컬 MCP 서버 프로세스 래핑 | Claude Desktop, Cursor 등 |
-| **HTTP** | 원격 MCP 서버 리버스 프록시 | Streamable HTTP + Legacy SSE |
+### Cursor IDE Integration
 
-### 제로 설정, 즉시 보호
+Add to `.cursor/mcp.json`:
 
-정책 파일 없이도 빌트인 기본 정책으로 즉시 보호를 시작합니다. 필요 시 YAML 정책 파일로 세부 조정이 가능합니다.
+```json
+{
+  "mcpServers": {
+    "my-server-guarded": {
+      "command": "npx",
+      "args": ["-y", "@aiclude/mcp-guard", "--", "npx", "-y", "@some/mcp-server"]
+    }
+  }
+}
+```
 
 ---
 
-## 한눈에 보는 보호 범위
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                        MCP Guard 보호 범위                           │
-├─────────────────────┬───────────────────────┬───────────────────────┤
-│   도구 정의 검사     │   도구 호출 검사       │   도구 응답 검사       │
-│   (server → client) │   (client → server)   │   (server → client)   │
-├─────────────────────┼───────────────────────┼───────────────────────┤
-│ ✓ 제로폭 스테가노그래피 │ ✓ SQL Injection       │ ✓ 민감 데이터 노출     │
-│ ✓ 프롬프트 인젝션     │ ✓ Command Injection   │ ✓ 시스템 경로 유출     │
-│ ✓ 호모글리프 위장     │ ✓ Path Traversal      │ ✓ 스택 트레이스 노출   │
-│ ✓ HTML 주석 은닉     │ ✓ XSS                 │ ✓ 명령어 실행 증거     │
-│ ✓ Base64 인코딩 은닉 │ ✓ Template Injection  │ ✓ 템플릿 인젝션 결과   │
-│ ✓ 도구명 사칭        │ ✓ 프롬프트 인젝션      │ ✓ 자격 증명 유출       │
-│ ✓ 다국어 인젝션      │ ✓ 다국어 인젝션        │                       │
-│ ✓ 에이전트 조작 패턴  │ ✓ 제로폭 문자 은닉     │                       │
-│ ✓ InputSchema 검사   │                       │                       │
-├─────────────────────┴───────────────────────┴───────────────────────┤
-│  CWE: CWE-22, CWE-78, CWE-79, CWE-89, CWE-94, CWE-200, CWE-209  │
-│  OWASP MCP Top 10: Tool Poisoning, Prompt Injection 등 다수 대응    │
-└─────────────────────────────────────────────────────────────────────┘
-```
+## Key Features
+
+### 3 Security Rule Engines
+
+| Rule | Inspects | Threats Addressed |
+|------|----------|-------------------|
+| **Tool Poisoning Detection** | Tool definitions from server | Zero-width steganography, prompt injection, homoglyph spoofing, name shadowing |
+| **Argument Injection Detection** | Tool call arguments from client | SQL / Command / XSS / Path Traversal / Template injection (21+ patterns) |
+| **Data Exfiltration Detection** | Tool responses from server | Credential leaks, system path exposure, stack trace disclosure |
+
+### Multilingual Threat Detection
+
+Detects prompt injection phrases in **English, Korean, Chinese, and Japanese**. Normalizes Cyrillic/Greek homoglyphs to block character-disguise bypass attacks.
+
+### Dual Protocol Support
+
+| Mode | Use Case | Target |
+|------|----------|--------|
+| **stdio** | Wrap local MCP server processes | Claude Desktop, Cursor, etc. |
+| **HTTP** | Reverse proxy for remote MCP servers | Streamable HTTP + Legacy SSE |
+
+### Zero Configuration
+
+Works out of the box with built-in default policies. Customize with YAML policy files when needed.
 
 ---
 
-## 동작 원리
+## Protection Coverage
+
+| Tool Definitions (server → client) | Tool Call Arguments (client → server) | Tool Responses (server → client) |
+|:-----------------------------------|:--------------------------------------|:---------------------------------|
+| Zero-width steganography | SQL Injection | Credential exposure |
+| Prompt injection phrases | Command Injection | System path leaks |
+| Homoglyph spoofing | Path Traversal | Stack trace exposure |
+| HTML comment hiding | XSS | Command exec evidence |
+| Base64 encoding hiding | Template Injection | Template injection results |
+| Name shadowing | Prompt injection | Credential leaks |
+| Multilingual injection | Multilingual injection | |
+| Agent manipulation patterns | Zero-width char hiding | |
+| InputSchema validation | | |
+
+**CWE Coverage:** CWE-22, CWE-78, CWE-79, CWE-89, CWE-94, CWE-200, CWE-209
+
+**OWASP MCP Top 10:** Tool Poisoning, Prompt Injection, and more
+
+---
+
+## How It Works
+
+MCP Guard operates as a **transparent proxy** between client and server.
+
+### stdio Mode
+
+> **MCP Client** → *stdio* → **MCP Guard (Proxy)** → *stdio* → **MCP Server (Local)**
+>
+> All messages pass through the **Rule Engine** for real-time inspection.
 
-MCP Guard는 클라이언트와 서버 사이에서 **투명 프록시**로 동작합니다.
+### HTTP Mode
 
-### stdio 모드 — 로컬 MCP 서버
+> **MCP Client** → *HTTP POST* → **MCP Guard (:9090)** → *HTTP POST* → **MCP Server (Remote)**
+>
+> Responses (JSON or SSE stream) are inspected before forwarding back to the client.
 
+**Default behavior: Fail-Close.** If the policy engine errors, all traffic is blocked for safety.
+
+---
+
+## CLI Reference
+
+### stdio mode (default)
+
+```bash
+mcp-guard [options] -- <server-command> [server-args...]
 ```
-┌──────────────┐     stdio      ┌──────────────┐     stdio      ┌──────────────┐
-│  MCP Client  │ ────────────→ │  MCP Guard   │ ────────────→ │  MCP Server  │
-│ (Claude 등)  │ ←──────────── │   (Proxy)    │ ←──────────── │  (로컬)       │
-└──────────────┘                └──────┬───────┘                └──────────────┘
-                                       │
-                                ┌──────┴───────┐
-                                │  Rule Engine │
-                                └──────────────┘
+
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--config <path>` | `-c` | YAML policy file path | Built-in defaults |
+| `--verbose` | `-v` | Enable debug-level logging | `false` |
+| `--fail-open` | | Allow traffic on policy engine error (not recommended) | `false` |
+| `--dry-run` | | Log violations without blocking | `false` |
+| `--version` | `-V` | Print version | |
+| `--help` | `-h` | Print help | |
+
+### HTTP mode
+
+```bash
+mcp-guard http [options] --upstream <url>
 ```
 
-### HTTP 모드 — 원격 MCP 서버
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--upstream <url>` | `-u` | Upstream MCP server URL **(required)** | |
+| `--port <number>` | `-p` | Listen port | `9090` |
+| `--host <host>` | `-H` | Bind host | `127.0.0.1` |
+| `--config <path>` | `-c` | YAML policy file path | Built-in defaults |
+| `--verbose` | `-v` | Enable debug-level logging | `false` |
+| `--fail-open` | | Allow traffic on policy engine error | `false` |
+| `--dry-run` | | Log violations without blocking | `false` |
+
+---
+
+## Policy File
+
+Policy files are written in YAML. Without a policy file, built-in defaults apply.
+
+### Basic Structure
 
+```yaml
+version: 1
+failMode: closed    # closed (recommended) | open
+
+logging:
+  level: info       # debug | info | warn | error
+  destination: stderr
+
+rules:
+  - id: tool-poisoning
+    enabled: true
+    severity: critical
+    action: block       # block | warn
+    type: tool-poisoning
+
+  - id: argument-injection
+    enabled: true
+    severity: critical
+    action: block
+    type: argument-injection
+
+  - id: data-exfiltration
+    enabled: true
+    severity: high
+    action: warn        # warn recommended — blocking may break normal flow
+    type: data-exfiltration
 ```
-┌──────────────┐   HTTP POST    ┌──────────────┐   HTTP POST    ┌──────────────┐
-│  MCP Client  │ ────────────→ │  MCP Guard   │ ────────────→ │  MCP Server  │
-│              │ ←──SSE/JSON── │  (:9090)     │ ←──SSE/JSON── │  (원격)       │
-└──────────────┘                └──────┬───────┘                └──────────────┘
-                                       │
-                                ┌──────┴───────┐
-                                │  Rule Engine │
-                                └──────────────┘
+
+### Tool Poisoning Config
+
+```yaml
+config:
+  checkZeroWidth: true
+  checkInjectionPhrases: true
+  checkHtmlComments: true
+  checkBase64: true
+  checkShadowing: true
+  checkInstructionPatterns: true
+  maxDescriptionLength: 5000
+```
+
+### Argument Injection Config
+
+```yaml
+config:
+  checkPromptInjection: true
 ```
 
-**기본 동작: Fail-Close.** 정책 엔진에 오류가 발생하면 안전을 위해 모든 트래픽을 차단합니다.
+SQL, Command, Path Traversal, XSS, and Template Injection checks are always active.
+
+### Data Exfiltration Config
+
+```yaml
+config:
+  checkCredentials: true
+  checkPathExposure: true
+  checkStackTraces: true
+```
 
 ---
 
-## 빠른 시작
+## Usage Scenarios
+
+### Evaluate a new MCP server safely
 
 ```bash
-# 설치
-npm install -g mcp-guard
+# Step 1: Dry-run to observe
+mcp-guard --dry-run --verbose -- npx @unknown/mcp-server 2>guard.log
 
-# stdio 모드: 로컬 MCP 서버 보호
-mcp-guard -- npx @modelcontextprotocol/server-fetch
+# Step 2: Review findings
+cat guard.log | grep "DRY-RUN"
 
-# HTTP 모드: 원격 MCP 서버 보호
-mcp-guard http --upstream http://mcp-server:8080/mcp --port 9090
+# Step 3: Enable blocking if clean
+mcp-guard -- npx @unknown/mcp-server
 ```
 
-### Claude Desktop 연동
+### Protect multiple servers in Claude Desktop
 
 ```json
 {
   "mcpServers": {
     "fetch-guarded": {
       "command": "npx",
-      "args": ["-y", "mcp-guard", "--", "npx", "-y", "@modelcontextprotocol/server-fetch"]
+      "args": ["-y", "@aiclude/mcp-guard", "--", "npx", "-y", "@modelcontextprotocol/server-fetch"]
+    },
+    "github-guarded": {
+      "command": "npx",
+      "args": ["-y", "@aiclude/mcp-guard", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
     }
   }
 }
 ```
 
-> 자세한 설치, 설정, 정책 작성법은 **[사용 가이드(USAGE.md)](USAGE.md)** 를 참고하세요.
+### HTTP security gateway
+
+```bash
+mcp-guard http \
+  -u http://internal-mcp:8080/mcp \
+  -p 9090 -H 0.0.0.0 \
+  -c /etc/mcp-guard/policy.yaml
+```
+
+### Custom policy with selective rules
+
+```bash
+mcp-guard -c my-policy.yaml -- npx @some/mcp-server
+```
 
 ---
 
-## 제품 특장점
+## Understanding Logs
+
+All logs are written to **stderr** in JSON format. stdout is reserved for MCP JSON-RPC communication.
 
-| 특장점 | 설명 |
-|--------|------|
-| **마이크로초 검사** | 동기적 패턴 매칭으로 메시지당 마이크로초 수준 지연. 사용자 경험 영향 없음 |
-| **46KB 초경량** | 의존성 3개, 단일 파일 번들. 공급망 공격 표면 최소화 |
-| **Node.js 단독** | 별도 데몬/컨테이너 불필요. 어디서나 즉시 배포 |
-| **YAML 정책** | 룰별 활성화/비활성화, 심각도 조정, 차단/경고 세밀 제어 |
-| **Dry-Run** | 차단 없이 관찰 모드. 새 MCP 서버 안전 테스트 |
+### Startup
+
+```json
+{"ts":"...","level":"info","msg":"mcp-guard starting","rules":["tool-poisoning","argument-injection","data-exfiltration"],"failMode":"closed"}
+```
+
+### Blocked
+
+```json
+{"ts":"...","level":"warn","msg":"BLOCKED server->client","rule":"tool-poisoning","severity":"critical","reason":"Tool \"search\": Zero-width characters detected in description"}
+```
+
+### Warning
+
+```json
+{"ts":"...","level":"warn","msg":"WARNING server->client","rule":"data-exfiltration","severity":"critical","reason":"Sensitive Data Exposure in tool response (CWE-200)"}
+```
+
+### Dry-Run
+
+```json
+{"ts":"...","level":"warn","msg":"DRY-RUN WOULD BLOCK client->server","rule":"argument-injection","severity":"critical","reason":"SQL Injection detected (CWE-89)"}
+```
 
 ---
 
-## 기술 사양
+## Troubleshooting
 
-| 항목 | 내용 |
-|------|------|
-| Language | TypeScript (strict mode, ESM-only) |
-| Runtime | Node.js 20+ |
-| Bundle Size | 46KB (단일 파일) |
-| Dependencies | 3개 |
-| Transport | stdio + HTTP (Streamable HTTP, Legacy SSE) |
-| 보안 룰 | 3종, 탐지기 7개 모듈 |
-| 인젝션 패턴 | 21개+, 프롬프트 인젝션 구절 33개+ (영/한/중/일) |
-| CWE 커버리지 | 7개 (CWE-22, 78, 79, 89, 94, 200, 209) |
-| OS | macOS, Linux, Windows |
+**"Failed to spawn MCP server"**
+— Verify the command after `--` runs independently: `npx @some/mcp-server`
+
+**Legitimate tools being blocked**
+1. Run with `--dry-run --verbose` to identify which rule triggers
+2. Disable the specific check in a policy file, or change the rule action to `warn`
+
+**No logs visible**
+— Logs go to stderr. Redirect: `mcp-guard --verbose -- ... 2>/tmp/guard.log`
+
+**HTTP "Upstream connection failed"**
+— Verify upstream is reachable: `curl -v http://mcp-server:8080/mcp`
+
+**SSE stream disconnecting**
+— If behind nginx, disable buffering:
+```nginx
+proxy_buffering off;
+proxy_cache off;
+```
 
 ---
 
-## 관련 프로젝트
+## FAQ
+
+**Does it affect MCP communication speed?**
+Barely. Synchronous pattern matching adds microsecond-level latency per message.
+
+**Can I use it without a policy file?**
+Yes. Built-in defaults apply: tool-poisoning (block), argument-injection (block), data-exfiltration (warn).
+
+**What is fail-close?**
+If the policy engine itself errors, all traffic is blocked for safety. Use `--fail-open` to override (not recommended).
+
+**Does it work on Windows?**
+Yes. Uses `cross-spawn` for Windows compatibility.
+
+**Does it support HTTP/SSE MCP servers?**
+Yes. Both Streamable HTTP and Legacy HTTP+SSE are supported since v0.2.0.
 
-- **[AIclude ASVS](https://vs.aiclude.com)** — AI Agent 보안 취약점 종합 진단 플랫폼
-- **[OWASP MCP Top 10](https://owasp.org/www-project-mcp-top-10/)** — MCP 보안 위협 분류 체계
+**How is authentication handled in HTTP mode?**
+`Authorization` headers are forwarded to upstream as-is. MCP Guard does not store or modify tokens.
 
 ---
 
-## 문서
+## Technical Specifications
 
-| 문서 | 내용 |
-|------|------|
-| **[사용 가이드 (USAGE.md)](USAGE.md)** | 설치, 설정, CLI 옵션, 정책 작성법, 연동 가이드, FAQ |
-| **[라이선스 (LICENSE.md)](LICENSE.md)** | AICLUDE Proprietary License |
+| Spec | Details |
+|------|---------|
+| Language | TypeScript (strict mode, ESM-only) |
+| Runtime | Node.js 20+ |
+| Bundle Size | ~60KB (single file) |
+| Dependencies | 3 (commander, cross-spawn, yaml) |
+| Transport | stdio + HTTP (Streamable HTTP, Legacy SSE) |
+| Security Rules | 3 engines, 7 detector modules |
+| Injection Patterns | 21+ fuzz patterns, 33+ prompt injection phrases (EN/KO/ZH/JA) |
+| CWE Coverage | CWE-22, CWE-78, CWE-79, CWE-89, CWE-94, CWE-200, CWE-209 |
+| OS | macOS, Linux, Windows |
 
 ---
 
-## 라이선스
+## Related
+
+- **[AIclude ASVS](https://vs.aiclude.com)** — AI Agent Security Vulnerability Scanner platform
+- **[OWASP MCP Top 10](https://owasp.org/www-project-mcp-top-10/)** — MCP security threat classification
+
+---
 
-MCP Guard는 **AICLUDE Proprietary License**에 의해 보호됩니다. AIclude Inc.의 명시적 서면 허가 없이 복제, 수정, 배포, 상업적 사용이 금지됩니다.
+## License
 
-자세한 내용은 [LICENSE.md](LICENSE.md)를 참고하세요.
+Apache License 2.0 — see [LICENSE](LICENSE) for details.
 
-Copyright © 2026 AIclude Inc. All rights reserved.
+Copyright 2026 AIclude Inc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiclude/mcp-guard",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "MCP runtime security proxy — intercepts and enforces security policies on MCP tool calls",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,9 +25,10 @@
   ],
   "license": "Apache-2.0",
   "author": "AIclude <dev@aiclude.com>",
+  "homepage": "https://vs.aiclude.com/mcp-guard",
   "repository": {
     "type": "git",
-    "url": "https://github.com/aiclude/mcp-guard"
+    "url": "https://github.com/mastergear4824/mcp-guard"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -38,7 +39,7 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE.md"
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --shims",

package/LICENSE.md

@@ -1,64 +0,0 @@
-# AICLUDE Proprietary License
-
-**Version 1.0 — Effective Date: January 1, 2026**
-
-Copyright © 2026 AIclude Inc. All rights reserved.
-
----
-
-## 1. 정의
-
-- **"소프트웨어"** 란 MCP Guard의 소스 코드, 바이너리, 문서, 관련 파일 일체를 의미합니다.
-- **"라이선서"** 란 AIclude Inc.를 의미합니다.
-- **"라이선시"** 란 본 라이선스에 동의하고 소프트웨어를 사용하는 개인 또는 법인을 의미합니다.
-
-## 2. 라이선스 부여
-
-라이선서는 라이선시에게 다음 조건 하에 소프트웨어의 비독점적, 양도 불가능한, 제한적 사용 권한을 부여합니다.
-
-### 2.1 허용되는 사용
-
-- **평가 목적**: 비상업적 환경에서 소프트웨어의 기능을 평가하기 위한 사용
-- **허가된 상업적 사용**: 라이선서와 별도의 상업적 라이선스 계약을 체결한 경우에 한하여 상업적 목적으로 사용 가능
-
-### 2.2 금지되는 행위
-
-명시적 서면 허가 없이 다음 행위는 엄격히 금지됩니다:
-
-- 소프트웨어의 전부 또는 일부를 **복제, 수정, 병합, 배포, 재라이선스, 판매**하는 행위
-- 소프트웨어를 기반으로 **파생 저작물**을 작성하는 행위
-- 소프트웨어의 **역컴파일, 역어셈블, 리버스 엔지니어링** 행위
-- 소프트웨어를 **제3자에게 서브라이선스**하는 행위
-- 본 라이선스의 저작권 표시, 상표, 또는 기타 권리 고지를 **제거하거나 변경**하는 행위
-
-## 3. 지적 재산권
-
-소프트웨어에 대한 모든 지적 재산권(저작권, 특허, 상표, 영업비밀 포함)은 라이선서에게 독점적으로 귀속됩니다. 본 라이선스는 라이선시에게 소프트웨어에 대한 소유권을 부여하지 않습니다.
-
-## 4. 보증 부인
-
-소프트웨어는 **"있는 그대로(AS-IS)"** 제공되며, 상품성, 특정 목적에의 적합성, 비침해에 대한 보증을 포함하여 명시적이든 묵시적이든 어떠한 종류의 보증도 제공하지 않습니다.
-
-## 5. 책임 제한
-
-어떠한 경우에도 라이선서는 소프트웨어의 사용 또는 사용 불능으로 인해 발생하는 직접적, 간접적, 우발적, 특수적, 징벌적 또는 결과적 손해에 대하여 책임을 지지 않습니다.
-
-## 6. 라이선스 종료
-
-- 라이선시가 본 라이선스의 조건을 위반할 경우, 라이선스는 자동으로 종료됩니다.
-- 라이선스 종료 시, 라이선시는 소프트웨어의 모든 사본을 즉시 삭제해야 합니다.
-
-## 7. 준거법
-
-본 라이선스는 대한민국 법률에 의해 규율되며, 관련 분쟁은 서울중앙지방법원을 전속 관할 법원으로 합니다.
-
-## 8. 상업적 라이선스
-
-상업적 사용을 위한 라이선스 문의: **license@aiclude.com**
-
----
-
-**AIclude Inc.**
-서울특별시 강남구 | https://aiclude.com
-
-> [← README로 돌아가기](README.md)