Metadata-Version: 2.1
Name: langprotect-vector
Version: 1.4.0
Summary: LangProtect Vector Gateway for protected MCP access across local AI hosts
Author-email: LangProtect Security Team <security@langprotect.com>
License: MIT
Project-URL: Homepage, https://www.langprotect.com/
Project-URL: Documentation, https://www.langprotect.com/docs
Project-URL: Repository, https://github.com/langprotect/mcp-gateway
Project-URL: Issues, https://github.com/langprotect/mcp-gateway/issues
Keywords: mcp,security,ai-security,langprotect,model-context-protocol
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi >=0.110.0
Requires-Dist: httpx >=0.27.0
Requires-Dist: pydantic >=2.6.0
Requires-Dist: requests >=2.31.0
Requires-Dist: sse-starlette >=2.0.0
Requires-Dist: uvicorn >=0.29.0
Provides-Extra: dev
Requires-Dist: black >=23.0.0 ; extra == 'dev'
Requires-Dist: mypy >=1.0.0 ; extra == 'dev'
Requires-Dist: pytest >=7.0.0 ; extra == 'dev'

# LangProtect Vector Gateway

🛡️ **Security gateway for Model Context Protocol (MCP)** - Protect your AI tool interactions from security threats.

[![PyPI version](https://badge.fury.io/py/langprotect-vector.svg)](https://pypi.org/project/langprotect-vector/)

## 🆕 What's New in v1.3.0

### Layer 2: Output Scanning 🔍
- **Automatic secret masking** in AI-generated responses
- **30+ secret types detected**: AWS, Google Cloud, Azure, Stripe, GitHub, JWTs, DB credentials, private keys
- **Non-blocking warnings** - never interrupts workflow
- **Preserves structure** - masks secrets while keeping code/content readable

### Enhanced Security Controls 🔐
- **Fail-closed mode** - Block requests on scan failures (optional)
- **Configurable timeouts** - Control scan performance
- **High-entropy detection** - Catch unknown secret formats

### Example

**Before** (v1.2.6):
```bash
AI: Here's your AWS deployment script:
export AWS_ACCESS_KEY_ID="AKIAIOSFODNN7EXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/K7MDENG..."
```

**After** (v1.3.0):
```bash
AI: Here's your AWS deployment script:
export AWS_ACCESS_KEY_ID="<REDACTED:AWS_ACCESS_KEY:1a5d44a2>"
export AWS_SECRET_ACCESS_KEY="<REDACTED:AWS_SECRET_KEY:73ec276f>"
```
✅ **Secrets masked** | 🔒 **Code structure preserved** | 📝 **Audit trail maintained**

---

## Features

✅ **Two-Layer Protection**
- **Layer 1 (Input)**: Blocks dangerous requests before sending to MCP server
- **Layer 2 (Output)**: Masks secrets in AI responses

✅ **Automatic Threat Detection** - Scans all MCP requests for security risks  
✅ **Access Control** - Whitelist/blacklist MCP servers and tools  
✅ **Full Audit Trail** - Logs all AI interactions for compliance  
✅ **IDE Support** - Works with VS Code, Cursor, and all MCP-compatible IDEs  
✅ **Easy Setup** - 30-second installation
✅ **Fail-Open Design** - Won't block your workflow if backend is unavailable

## Quick Start

### 1. Installation

The gateway runs as a global CLI tool. We recommend using `pipx` to manage the installation.

```bash
# Recommended: Install via pipx
pipx install langprotect-vector
```

### 2. Automatic Setup (Recommended) 🚀

Run the one-time setup command to sign in, configure supported local hosts, and start the shared local gateway:

```bash
langprotect-vector setup --backend-url http://localhost:8000 --email you@example.com
```

**What happens:**
- 🔐 **Prompts for credentials** interactively (password hidden)
- ✅ **Validates credentials** in real-time against your backend
- 🔄 **Retries on failure** with helpful error messages
- 📝 **Stores a local Vector profile** under `~/.config/langprotect-vector/`
- ⚙️ **Configures supported local hosts** such as VS Code / Copilot, Cursor, and JetBrains
- 🧩 **Writes MCP config/snippets** so hosts point at the shared Vector gateway
- 🚀 **Starts the shared local gateway** and enables autostart where supported

**Example:**
```bash
$ langprotect-vector setup --backend-url http://localhost:8000 --email your.email@company.com

🚀 Setting up LangProtect Vector Gateway...

═══════════════════════════════════════════════════════════════
         🔐 Enter Your LangProtect Credentials
═══════════════════════════════════════════════════════════════

Backend URL [http://localhost:8000]: http://localhost:8000
Email: your.email@company.com
Password: ●●●●●●●●●●

      Validating credentials...
      ✓ Credentials validated successfully!

⚙️  Configuring hosts...
   ✅ Updated: ~/.config/Code/User/mcp.json
   ✅ Updated: ~/.cursor/mcp.json
   ✅ Generated: ~/.config/langprotect-vector/hosts/jetbrains.mcp.json

✅ Setup complete!
```

**Alternative: Pre-set credentials via environment variables**
```bash
export LANGPROTECT_URL="http://localhost:8000"
export LANGPROTECT_EMAIL="your.email@company.com"
export LANGPROTECT_PASSWORD="your-password"
langprotect-vector setup --backend-url "$LANGPROTECT_URL" --email "$LANGPROTECT_EMAIL" --password "$LANGPROTECT_PASSWORD"
```

### 3. Reload VS Code

Press `Ctrl+Shift+P` → `Developer: Reload Window`

**That's it!** ✅ Vector will now protect all configured local hosts.

On each IDE reopen, MCP servers configured with auto-start are started automatically when your first chat request needs MCP tools.

Note: current VS Code MCP auto-start modes are limited to `never`, `onlyNew`, and `newAndOutdated`; it does not provide a built-in `always-run-on-launch` mode for all servers.

---

## ⚙️ Configuration Options (v1.3.0+)

Configure security behavior with environment variables in your wrapper script:

```bash
# Security Controls
export LANGPROTECT_ENABLE_MASKING=true      # Enable output masking (default: true)
export LANGPROTECT_FAIL_CLOSED=false        # Block on scan errors (default: false = fail-open)
export LANGPROTECT_SCAN_TIMEOUT=5.0         # Scan timeout in seconds (default: 5.0)
export LANGPROTECT_ENTROPY_DETECTION=true   # Detect unknown secrets via entropy (default: true)
export LANGPROTECT_SOURCE="vscode-copilot"  # Optional global source override
export LANGPROTECT_INPUT_SOURCE="custom-input-source"     # Legacy per-scan override
export LANGPROTECT_OUTPUT_SOURCE="custom-output-source"   # Legacy per-scan override

# Backend Connection
export LANGPROTECT_URL="http://localhost:8000"
export LANGPROTECT_EMAIL="your.email@company.com"
export LANGPROTECT_PASSWORD="your-password"
```

**Source labels are auto-detected by default** (no env var required):
- `vscode-codex`
- `vscode-copilot`
- `vscode-cline`
- `cursor-codex`
- `cursor-copilot`
- `cursor-cline`
- `claude-desktop-claude`

If the AI tool cannot be detected reliably, the source falls back to IDE-only:
- `vscode`
- `cursor`
- `claude-desktop`

### Security Modes

**Fail-Open (Default)** - Recommended for development:
```bash
export LANGPROTECT_FAIL_CLOSED=false
```
- If scan times out or fails → **Allow request** (log warning)
- Won't block your workflow
- Best for development environments

**Fail-Closed** - Recommended for production:
```bash
export LANGPROTECT_FAIL_CLOSED=true
```
- If scan times out or fails → **Block request**
- Maximum security
- Best for production/sensitive environments

### Output Masking

Control how AI-generated secrets are handled:

```bash
# Enable masking (default)
export LANGPROTECT_ENABLE_MASKING=true

# Disable masking (see secrets in plain text - not recommended)
export LANGPROTECT_ENABLE_MASKING=false
```

**Masked format**: `<REDACTED:SECRET_TYPE:hash>`
- Example: `<REDACTED:AWS_ACCESS_KEY:1a5d44a2>`
- Hash allows deduplication across logs
- Preserves code structure

---

## Vector Gateway CLI Scaffold

The repo now also includes a separate Vector-oriented client CLI:

```bash
langprotect-vector setup --backend-url http://localhost:8000 --email you@example.com
langprotect-vector login
langprotect-vector host install --host vscode
langprotect-vector start
langprotect-vector mcp-stdio --host vscode
```

Recommended local-machine flow:

```bash
langprotect-vector setup --backend-url http://localhost:8000 --email you@example.com
```

What `setup` does:
- logs in and stores the local Vector profile
- installs working host MCP config for `vscode`, `cursor`, and `jetbrains`
- installs OS-level autostart for the local gateway where supported
- starts the shared local gateway immediately so hosts can connect without a separate per-host start

What the CLI does now:
- stores a local Vector login profile
- writes a local gateway `.env` file
- writes working local host MCP config for:
  - VS Code / Copilot
  - Cursor
- writes a JetBrains MCP JSON snippet for import into the JetBrains MCP settings UI
- creates a per-host install manifest for local hosts such as `vscode`, `copilot`, `cursor`, `jetbrains`, `cline`, and `continue`
- starts the local `vector_gateway_service`
- exposes a stdio MCP adapter for local hosts that bridges:
  - `tools/list`
  - `tools/call`
  into the local Vector gateway runtime

Manual local host flow:

```bash
langprotect-vector login --backend-url http://localhost:8000 --email you@example.com
langprotect-vector host install --host vscode
langprotect-vector start
```

The installed host config launches:

```bash
python -m langprotect_mcp_gateway.vector_cli mcp-stdio --host vscode --profile ~/.config/langprotect-vector/profile.json --gateway-url http://127.0.0.1:8090
```

The stdio adapter talks to the shared local gateway HTTP service. Start the gateway once before using MCP tools from any configured host.

---

## 🏗️ Manual Host Setup

If you prefer not to use the one-shot setup command, you can sign in first and then configure each local host explicitly:

```bash
langprotect-vector login --backend-url http://localhost:8000 --email you@example.com
langprotect-vector host install --host vscode
langprotect-vector host install --host cursor
langprotect-vector host install --host jetbrains
langprotect-vector start
```

Host-specific notes:
- VS Code / Copilot: writes `~/.config/Code/User/mcp.json`
- Cursor: writes `~/.cursor/mcp.json`
- JetBrains: writes `~/.config/langprotect-vector/hosts/jetbrains.mcp.json` for import into the JetBrains MCP settings UI
- All configured hosts point to the same shared local Vector gateway process, so you only start it once

## How It Works

```
┌─────────────┐     ┌────────────────────┐     ┌──────────────────┐
│   VS Code   │────▶│ LangProtect Gateway│────▶│  Filesystem MCP  │
│  (Copilot)  │     │   (Security Scan)  │     │    Server        │
└─────────────┘     └────────────────────┘     └──────────────────┘
                              │
                              ▼
                    ┌────────────────────┐
                    │ LangProtect Backend│
                    │  (Policy Check)    │
                    └────────────────────┘
```

1. **Intercepts** all MCP tool calls from your AI assistant
2. **Sends** each request to LangProtect backend for security scanning
3. **Blocks** requests that violate your security policies
4. **Forwards** allowed requests to the actual MCP server
5. **Logs** everything for audit trail
         ↓
LangProtect Gateway (this package)
         ↓
    [Security Scan]
         ↓
MCP Servers (filesystem, github, etc.)
```

Every request is:
1. Intercepted by the gateway
2. Scanned for security threats
3. Logged to LangProtect backend
4. Forwarded to actual MCP server (if safe)
5. Response returned to AI

## Dashboard

Monitor all activity at your LangProtect dashboard:
- View all AI interactions
- See security threats blocked
- Track IDE usage
- Generate compliance reports

## Security

The gateway protects against:
- 🚫 Sensitive file access (`.env`, SSH keys, etc.)
- 🚫 Dangerous commands (`rm -rf`, data exfiltration)
- 🚫 SQL injection patterns
- 🚫 Hardcoded credentials in suggestions
- 🚫 Prompt injection attacks

## Troubleshooting

**"externally-managed-environment" error on Linux:**
- Modern Linux systems protect system Python. Use `pipx` instead:
  ```bash
  sudo apt install pipx -y
  pipx install langprotect-vector
  ```

**Authentication failed:**
- Check `LANGPROTECT_URL`, `LANGPROTECT_EMAIL`, `LANGPROTECT_PASSWORD` are correct
- Ensure LangProtect backend is accessible

**Gateway not starting:**
- Check Python version: `python3 --version` (need 3.8+)
- Check package installed: `pipx list | grep langprotect`
- Verify path: `which langprotect-vector`

**Tools not working:**
- Check MCP servers are configured under `"servers"` section
- Restart IDE completely

**Command not found after install:**
- Run `pipx ensurepath` and restart your terminal
- Or add `~/.local/bin` to your PATH manually

## For Team Leads

### Quick Team Rollout:

1. **Share credentials** with each team member:
   ```
   Email: user@company.com
   Password: secure-password
   Server: http://langprotect.company.com:8000
   ```

2. **Team members install:**
   ```bash
   # Linux/macOS
   sudo apt install pipx -y  # or: brew install pipx
   pipx install langprotect-vector
   langprotect-vector setup --backend-url http://langprotect.company.com:8000 --email user@company.com
   ```

3. **Monitor dashboard:** See all team activity in real-time

## Updates

```bash
# Upgrade with pipx
pipx upgrade langprotect-vector

# Or reinstall specific version
pipx install langprotect-vector==1.4.0 --force
```

## Support

- **Documentation:** https://www.langprotect.com/docs
- **Issues:** https://github.com/langprotect/mcp-gateway/issues
- **Security:** security@langprotect.com

## License

MIT License - see LICENSE file for details

## Links

- **Homepage:** https://www.langprotect.com/
- **GitHub:** https://github.com/langprotect/mcp-gateway
- **Documentation:** https://www.langprotect.com/docs
