npm package: @keypost/wrapper
Description: Lightweight wrapper for local stdio MCP servers with Keypost policy enforcement
Author: Keypost Team
Latest version: 0.1.0

# @keypost/wrapper

Lightweight Node.js wrapper for local stdio MCP servers with Keypost policy enforcement.

## Overview

The Keypost Wrapper enables you to apply Keypost policies to local stdio MCP servers (like filesystem, local databases, system tools) while maintaining low latency and a simple user experience.

## How It Works

```
AI Agent (Claude Desktop, etc.)
    ↓ (spawns keypost-wrapper)
Keypost Wrapper
    ↓ (HTTP) → Keypost Cloud (evaluates request policies)
    ↓ (stdio) → Local MCP Server
    ↓ (HTTP) → Keypost Cloud (evaluates response policies)
    ↓ (stdio) → AI Agent
```

The wrapper:
1. Receives MCP requests from AI agents via stdin
2. Evaluates request policies via Keypost cloud API
3. Forwards allowed requests to local stdio servers
4. Evaluates response policies via Keypost cloud API
5. Returns modified/allowed responses via stdout

## Installation

### Using npx (Recommended)

No installation needed - just use `npx`:

```bash
npx @keypost/wrapper --keypost my-fs -- npx @modelcontextprotocol/server-filesystem /tmp
```

### Global Installation

```bash
npm install -g @keypost/wrapper
```

Then use directly:

```bash
keypost-wrapper --keypost my-fs -- npx @modelcontextprotocol/server-filesystem /tmp
```

## Usage

### Basic Usage

Replace your stdio server command with the wrapper:

**Before:**
```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/Users/me/Documents"]
    }
  }
}
```

**After:**
```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@keypost/wrapper",
        "--keypost", "my-fs",
        "--",
        "npx", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"
      ]
    }
  }
}
```

### CLI Arguments

```bash
npx @keypost/wrapper --keypost <SLUG_OR_URL> -- <SERVER_COMMAND>
```

**Options:**
- `--keypost <SLUG_OR_URL>` (or `-k`) - Keypost slug or full URL (required).
  - Slug: `my-fs` (defaults to `https://my-fs.keypost.ai`)
  - Full URL: `http://localhost:5001/my-fs` (for local development)
- `-- <COMMAND>` - Local stdio server command and args (everything after `--`)

**Environment Variables:**
- `DEBUG=keypost:*` - Enable debug logging

### Examples

**Filesystem Server (Production):**
```bash
npx @keypost/wrapper --keypost my-fs -- npx @modelcontextprotocol/server-filesystem /tmp
```

**GitHub Server (Production):**
```bash
npx @keypost/wrapper --keypost my-github -- npx @modelcontextprotocol/server-github
```

**Custom Server (Local Development):**
```bash
npx @keypost/wrapper --keypost http://localhost:5001/my-server -- python3 my_mcp_server.py
```

## Configuration

### 1. Create Keypost in Dashboard

1. Go to https://app.keypost.ai
2. Click "Add Keypost"
3. Select type: **Stdio**
4. Enter name and slug (e.g., "My Filesystem", "my-fs")
5. Configure policies

### 2. Update AI Agent Config

Add the wrapper to your AI agent's MCP server configuration (see Usage above).

### 3. Use Normally

Your AI agent will now enforce Keypost policies on all tool calls to the local server.

## Policy Examples

### Block Write Operations

```yaml
- tool: write_file
  access: deny
```

### Restrict File Paths

```yaml
- tool: read_file
  param:
    path:
      must_match: "^/Users/me/Documents/public/"
```

### DLP on Responses

```yaml
- tool: read_file
  response:
    dlp:
      block_patterns:
        ssn: "\\d{3}-\\d{2}-\\d{4}"
        api_key: "sk-[a-zA-Z0-9]{32}"
      action: redact
```

### Rate Limiting

```yaml
- tool: query_database
  throttle:
    max: 100
    per: hour
```

## Rust Alternative

If you prefer a compiled binary with faster startup time, we also provide a Rust version:

```bash
cargo install keypost-wrapper
```

See [keypost-wrapper](../keypost-wrapper) for details.

## Troubleshooting

### Debug Logging

Enable verbose logging to see what's happening:

```bash
DEBUG=keypost:* npx @keypost/wrapper --keypost my-fs -- npx @modelcontextprotocol/server-filesystem /tmp
```

### Wrapper Not Starting

Check that the server command after `--` is correct:
```bash
# Test the server command directly first
npx @modelcontextprotocol/server-filesystem /tmp
```

### Authentication Errors

Ensure your Keypost is configured with type "stdio" in the dashboard.

### Process Not Cleaning Up

The wrapper handles SIGTERM/SIGINT to ensure stdio servers are terminated when the wrapper exits.

## Requirements

- Node.js 18+
- npm or npx

## License

MIT