@purplesquirrel/guardrails-mcp-server 1.0.0

package/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(ci)"

package/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint --if-present
+
+      - name: Run tests
+        run: npm test --if-present
+
+      - name: Build
+        run: npm run build --if-present

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Purple Squirrel Media
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,257 @@
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
+[![Security](https://img.shields.io/badge/AI-Security-green)](https://github.com/PurpleSquirrelMedia/guardrails-mcp-server)
+[![CI](https://github.com/PurpleSquirrelMedia/guardrails-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/PurpleSquirrelMedia/guardrails-mcp-server/actions/workflows/ci.yml)
+
+# AI Guardrails MCP Server
+
+MCP server providing security guardrails for Claude Code and AI agents. Implements input validation, output filtering, policy enforcement, and audit logging.
+
+## Features
+
+- **Input Validation** - Sanitize and validate all inputs before processing
+- **Output Filtering** - Redact sensitive data from responses
+- **Policy Enforcement** - Enforce custom security policies
+- **Audit Logging** - Complete audit trail of all requests
+- **Rate Limiting** - Protect against abuse and overuse
+
+## Architecture
+
+```
+User Request
+     │
+     ▼
+┌─────────────────────────────────────┐
+│       Guardrails Engine             │
+├─────────────────────────────────────┤
+│  ┌─────────┐  ┌──────────────────┐  │
+│  │  Rate   │  │     Input        │  │
+│  │ Limiter │──▶   Validator      │  │
+│  └─────────┘  └────────┬─────────┘  │
+│                        │            │
+│               ┌────────▼─────────┐  │
+│               │     Policy       │  │
+│               │     Engine       │  │
+│               └────────┬─────────┘  │
+│                        │            │
+│               ┌────────▼─────────┐  │
+│               │     Output       │  │
+│               │     Filter       │  │
+│               └────────┬─────────┘  │
+│                        │            │
+│  ┌─────────────────────▼─────────┐  │
+│  │        Audit Logger           │  │
+│  └───────────────────────────────┘  │
+└─────────────────────────────────────┘
+     │
+     ▼
+  Response
+```
+
+## Components
+
+### GuardrailsEngine (`src/engine/GuardrailsEngine.js`)
+
+Core orchestration engine that coordinates all security components:
+
+```javascript
+import { GuardrailsEngine } from './src/engine/GuardrailsEngine.js';
+
+const engine = new GuardrailsEngine({
+  enableInputValidation: true,
+  enableOutputFiltering: true,
+  enablePolicyEnforcement: true,
+  enableAuditLogging: true,
+  enableRateLimiting: true,
+  maxRequestsPerMinute: 60,
+});
+
+// Process incoming request
+const result = await engine.processInput(request, { userId: 'user123' });
+
+// Filter outgoing response
+const filtered = await engine.processOutput(response, context);
+```
+
+### InputValidator (`src/validators/InputValidator.js`)
+
+Validates and sanitizes incoming requests:
+
+- Pattern matching for blocked content
+- Size and token limits
+- Character encoding validation
+- SQL injection detection
+- XSS prevention
+
+### OutputFilter (`src/filters/OutputFilter.js`)
+
+Filters and redacts sensitive information from outputs:
+
+- PII detection and redaction (SSN, credit cards, emails)
+- API key/secret detection
+- Custom pattern redaction
+- Configurable replacement text
+
+### PolicyEngine (`src/policies/PolicyEngine.js`)
+
+Enforces custom security policies:
+
+- Allow/deny lists for operations
+- Domain restrictions
+- Resource access controls
+- Custom policy rules
+
+### AuditLogger (`src/audit/AuditLogger.js`)
+
+Comprehensive audit logging:
+
+- Request/response logging
+- Policy violation tracking
+- Rate limit events
+- Searchable log queries
+
+## Configuration
+
+```javascript
+const config = {
+  // Feature toggles
+  enableInputValidation: true,
+  enableOutputFiltering: true,
+  enablePolicyEnforcement: true,
+  enableAuditLogging: true,
+  enableRateLimiting: true,
+
+  // Rate limiting
+  maxRequestsPerMinute: 60,
+  maxTokensPerRequest: 100000,
+
+  // Security patterns
+  blockedPatterns: [
+    /password\s*[:=]/i,
+    /api[_-]?key/i,
+  ],
+
+  // Domain restrictions
+  allowedDomains: ['api.example.com'],
+
+  // Sensitive data patterns for redaction
+  sensitiveDataPatterns: [
+    { pattern: /\b\d{3}-\d{2}-\d{4}\b/, replacement: '[SSN REDACTED]' },
+    { pattern: /\b\d{16}\b/, replacement: '[CARD REDACTED]' },
+  ],
+};
+```
+
+## Installation
+
+```bash
+cd ~/guardrails-mcp-server
+npm install
+```
+
+## Usage with Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "guardrails": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/guardrails-mcp-server/index.js"]
+    }
+  }
+}
+```
+
+## Use Cases
+
+### Enterprise AI Deployments
+
+- Ensure all AI interactions comply with security policies
+- Prevent data leakage through output filtering
+- Maintain audit trails for compliance
+
+### Multi-Tenant Systems
+
+- Rate limiting per user/tenant
+- Policy isolation between tenants
+- Usage tracking and billing
+
+### Regulated Industries
+
+- Healthcare: HIPAA compliance with PHI detection
+- Finance: PCI-DSS with card number redaction
+- Government: Data classification enforcement
+
+## API
+
+### processInput(request, context)
+
+Process and validate an incoming request.
+
+**Returns:**
+```javascript
+{
+  allowed: boolean,
+  requestId: string,
+  request: object,  // Sanitized request
+  processingTime: number,
+  // If blocked:
+  reason: string,
+  code: 'RATE_LIMIT' | 'VALIDATION_ERROR' | 'POLICY_VIOLATION',
+  violations: array,
+}
+```
+
+### processOutput(response, context)
+
+Filter and redact sensitive data from a response.
+
+**Returns:**
+```javascript
+{
+  filtered: boolean,
+  response: object,  // Filtered response
+  redactions: array, // List of redactions applied
+  processingTime: number,
+}
+```
+
+### getStats()
+
+Get current engine statistics.
+
+### getAuditLogs(filter)
+
+Query audit logs with optional filtering.
+
+## Files
+
+```
+guardrails-mcp-server/
+├── package.json
+├── README.md
+├── src/
+│   ├── engine/
+│   │   └── GuardrailsEngine.js    # Core engine
+│   ├── validators/
+│   │   └── InputValidator.js      # Input validation
+│   ├── filters/
+│   │   └── OutputFilter.js        # Output filtering
+│   ├── policies/
+│   │   └── PolicyEngine.js        # Policy enforcement
+│   └── audit/
+│       └── AuditLogger.js         # Audit logging
+├── tests/
+└── docs/
+```
+
+## Author
+
+Matthew Karsten - Purple Squirrel Media
+
+## License
+
+MIT

package/TROUBLESHOOTING.md

@@ -0,0 +1,299 @@
+# Troubleshooting Guide
+
+Common issues and solutions for the AI Guardrails MCP Server.
+
+## Rate Limiting Issues
+
+### `RATE_LIMIT` - Request blocked
+
+**Cause**: Too many requests in the time window.
+
+**Solutions**:
+1. Increase `maxRequestsPerMinute` in config
+2. Add delays between rapid requests
+3. Check if legitimate usage or potential abuse
+
+**Example config adjustment**:
+```javascript
+const engine = new GuardrailsEngine({
+  maxRequestsPerMinute: 120,  // Increase from default 60
+});
+```
+
+### Rate limits applying to wrong users
+
+**Cause**: User context not being passed correctly.
+
+**Solution**: Always include `userId` in context:
+```javascript
+const result = await engine.processInput(request, {
+  userId: 'unique-user-id',
+  tenantId: 'tenant-123'  // For multi-tenant setups
+});
+```
+
+## Input Validation Issues
+
+### `VALIDATION_ERROR` - Request rejected
+
+**Cause**: Input matched a blocked pattern.
+
+**Solutions**:
+1. Check which pattern triggered the block
+2. Review `blockedPatterns` configuration
+3. Add exceptions for legitimate use cases
+
+**Checking violation details**:
+```javascript
+if (!result.allowed) {
+  console.log('Violations:', result.violations);
+  // [{pattern: '...', message: '...'}]
+}
+```
+
+### False positives on valid content
+
+**Cause**: Pattern too broad.
+
+**Solutions**:
+1. Make patterns more specific
+2. Add word boundaries: `\bpassword\b` instead of `password`
+3. Use negative lookahead for exceptions
+
+**Example**:
+```javascript
+blockedPatterns: [
+  // Too broad - blocks "password reset"
+  /password/i,
+
+  // Better - only blocks password disclosure
+  /password\s*[:=]\s*\S+/i,
+]
+```
+
+### Token limit exceeded
+
+**Cause**: Request too large.
+
+**Solution**: Adjust `maxTokensPerRequest`:
+```javascript
+const engine = new GuardrailsEngine({
+  maxTokensPerRequest: 200000,  // Increase limit
+});
+```
+
+## Output Filtering Issues
+
+### Sensitive data not being redacted
+
+**Cause**: Pattern doesn't match the format.
+
+**Solutions**:
+1. Check regex pattern syntax
+2. Test patterns with sample data
+3. Add additional patterns for variations
+
+**Common patterns**:
+```javascript
+sensitiveDataPatterns: [
+  // SSN variations
+  { pattern: /\b\d{3}-\d{2}-\d{4}\b/, replacement: '[SSN]' },
+  { pattern: /\b\d{9}\b/, replacement: '[SSN]' },
+
+  // Credit cards (13-19 digits)
+  { pattern: /\b\d{13,19}\b/, replacement: '[CARD]' },
+  { pattern: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/, replacement: '[CARD]' },
+
+  // Email addresses
+  { pattern: /\b[\w.+-]+@[\w.-]+\.\w{2,}\b/g, replacement: '[EMAIL]' },
+
+  // API keys (common formats)
+  { pattern: /\b(sk|pk|api)[_-][a-zA-Z0-9]{20,}\b/g, replacement: '[API_KEY]' },
+]
+```
+
+### Over-redaction of content
+
+**Cause**: Patterns too aggressive.
+
+**Solutions**:
+1. Use more specific patterns
+2. Add context requirements
+3. Use word boundaries
+
+### Performance slow on large outputs
+
+**Cause**: Many regex patterns or large text.
+
+**Solutions**:
+1. Compile regex patterns once (use RegExp objects)
+2. Use simpler patterns where possible
+3. Consider chunking large outputs
+
+## Policy Engine Issues
+
+### `POLICY_VIOLATION` - Action blocked
+
+**Cause**: Request violates a configured policy.
+
+**Check policy details**:
+```javascript
+if (!result.allowed && result.code === 'POLICY_VIOLATION') {
+  console.log('Policy violated:', result.reason);
+  console.log('Violations:', result.violations);
+}
+```
+
+### Domain restrictions not working
+
+**Cause**: URL parsing or matching issue.
+
+**Solution**: Check domain format:
+```javascript
+// Correct
+allowedDomains: ['api.example.com', 'cdn.example.com']
+
+// Wrong - don't include protocol
+allowedDomains: ['https://api.example.com']
+```
+
+### Custom policies not executing
+
+**Cause**: Policy syntax or registration issue.
+
+**Solution**: Verify policy structure:
+```javascript
+const customPolicy = {
+  name: 'my-policy',
+  description: 'Custom validation',
+  evaluate: (request, context) => {
+    if (/* violation condition */) {
+      return {
+        allowed: false,
+        reason: 'Policy violation description',
+      };
+    }
+    return { allowed: true };
+  }
+};
+```
+
+## Audit Logging Issues
+
+### Logs not being written
+
+**Cause**: Audit logging disabled or path issue.
+
+**Solutions**:
+1. Verify `enableAuditLogging: true`
+2. Check log file path permissions
+3. Ensure disk has space
+
+### Log queries returning empty
+
+**Cause**: Filter too restrictive or no matching logs.
+
+**Solution**: Broaden filter:
+```javascript
+// Start with no filter
+const logs = await engine.getAuditLogs({});
+
+// Then narrow down
+const logs = await engine.getAuditLogs({
+  startTime: new Date(Date.now() - 3600000),  // Last hour
+  userId: 'user123',
+});
+```
+
+### Log file growing too large
+
+**Solutions**:
+1. Implement log rotation
+2. Set up external log aggregation
+3. Configure retention policy
+
+## Configuration Issues
+
+### Engine not initializing
+
+**Cause**: Invalid configuration object.
+
+**Solution**: Check all required fields:
+```javascript
+const engine = new GuardrailsEngine({
+  enableInputValidation: true,
+  enableOutputFiltering: true,
+  enablePolicyEnforcement: true,
+  enableAuditLogging: true,
+  enableRateLimiting: true,
+  maxRequestsPerMinute: 60,
+});
+```
+
+### Hot reload not working
+
+**Cause**: Config changes not detected.
+
+**Solution**: Implement reload:
+```javascript
+// Reload configuration
+engine.updateConfig(newConfig);
+
+// Or recreate engine
+engine = new GuardrailsEngine(newConfig);
+```
+
+## MCP Server Issues
+
+### Server not appearing in Claude Code
+
+**Solutions**:
+1. Verify `~/.claude.json` syntax
+2. Check path to `index.js`
+3. Restart Claude Code
+4. Test: `node /path/to/guardrails-mcp-server/index.js`
+
+### Module not found errors
+
+**Solution**:
+```bash
+cd ~/guardrails-mcp-server
+npm install
+```
+
+## Debugging
+
+### Enable debug mode
+
+```javascript
+const engine = new GuardrailsEngine({
+  // ... other config
+  debug: true,  // Verbose logging
+});
+```
+
+### Test individual components
+
+```javascript
+// Test input validator
+const validator = new InputValidator(config);
+const result = validator.validate(testInput);
+
+// Test output filter
+const filter = new OutputFilter(config);
+const result = filter.filter(testOutput);
+```
+
+### View engine statistics
+
+```javascript
+const stats = engine.getStats();
+console.log('Requests processed:', stats.totalRequests);
+console.log('Requests blocked:', stats.blockedRequests);
+console.log('Rate limit hits:', stats.rateLimitHits);
+```
+
+## Getting Help
+
+- [GitHub Issues](https://github.com/PurpleSquirrelMedia/guardrails-mcp-server/issues)
+- [OWASP Input Validation](https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html)

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@purplesquirrel/guardrails-mcp-server",
+  "version": "1.0.0",
+  "description": "AI Agent Guardrails MCP Server - Security layer for Claude Code and AI agents",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "start": "node index.js",
+    "test": "node --test tests/",
+    "dev": "node --watch index.js"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "guardrails",
+    "ai-safety",
+    "security",
+    "validation",
+    "filtering"
+  ],
+  "author": "Purple Squirrel Media",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}