agent-mcp-gateway 0.2.1__py3-none-any.whl

agent_mcp_gateway-0.2.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+src/CONFIG_README.md,sha256=RDrVI5aP5Wld0_HsHoc8tdyC1IO_JzhFee_3yuLhBwo,9201
+src/__init__.py,sha256=_xMCrvLcZjUcPIDAoeorVOwswrLgrKtrf_g1178faM8,55
+src/audit.py,sha256=P_YMhSifH66Fm_HXt6wFuFRmk0ekzXXzJOAc9zTinwQ,3034
+src/config.py,sha256=_Q0Fo5Nc22OnqubGJyZi92QMaMF38QH7SXVQYN-0-IU,32793
+src/config_watcher.py,sha256=z8MsOexNEEsmCtk7NBcKpkaLyYLbDfJF10euh3pAvIk,11603
+src/gateway.py,sha256=phk1dyCq3l-ZLbtEXCCaa_CE6vM2tZGrGnyDwt0OHK8,22205
+src/main.py,sha256=4ReyFFmXTl6OdMEiJ4UEiG_gVHsACAQeF8EJ6rSvvYU,24326
+src/metrics.py,sha256=SD4e5zo4Gtd1Gqp7SIHo7DBZTrvqaY-iKtf4qAPTy_k,9896
+src/middleware.py,sha256=iaHxe7lW0nSz3k-ieNyO4n5MtPKSGChEg_qRlHr3X8Q,7257
+src/policy.py,sha256=6jjWjExkr5DsFsmxCdxUq5Is8f1HV_x-KEJxNM1LM9s,19308
+src/proxy.py,sha256=ueSEm5t5AOYVuB24DAvnhdduEmiDmpvLqhnGyoJtsD8,24949
+src/config/.mcp-gateway-rules.json.example,sha256=UNfIVbtvHddWhWmWJ6Om-iaoPXNSDkzsUKtA59gi7ac,1289
+src/config/.mcp.json.example,sha256=_Gy7bflSOw15A2LfXpprSf29gGcve4zjDka-vuPVN2c,842
+agent_mcp_gateway-0.2.1.dist-info/METADATA,sha256=g2zqAYeFQQbalxwbjemR6xf09JU4u3Ab7agHGg20PW8,47901
+agent_mcp_gateway-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+agent_mcp_gateway-0.2.1.dist-info/entry_points.txt,sha256=Rb9I44QKFEI6-38dCb1sPwSAzQlAzUBZKDQqjb-FHTI,52
+agent_mcp_gateway-0.2.1.dist-info/licenses/LICENSE,sha256=XPIqCRndYgq7mXJ2NlfnvN0IoqQGXpK2gnHIqyvuPws,1078
+agent_mcp_gateway-0.2.1.dist-info/RECORD,,

agent_mcp_gateway-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_mcp_gateway-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-mcp-gateway = src.main:main

agent_mcp_gateway-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rodrigo Franken Dutra
+
+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.

src/CONFIG_README.md

@@ -0,0 +1,351 @@
+# Configuration Module
+
+The configuration module (`src/config.py`) provides robust loading, validation, and management of configuration files for the Agent MCP Gateway.
+
+## Features
+
+- **MCP Server Configuration**: Load and validate MCP server definitions (stdio and HTTP transports)
+- **Gateway Rules**: Load and validate agent policy configurations
+- **Environment Variable Substitution**: Automatic `${VAR}` pattern replacement
+- **Comprehensive Validation**: Type checking, required field validation, and cross-validation
+- **Clear Error Messages**: Helpful, actionable error messages for all validation failures
+- **Path Expansion**: Automatic `~/` home directory expansion
+
+## Functions
+
+### `load_mcp_config(path: str) -> dict`
+
+Loads and validates MCP server configuration from a JSON file.
+
+**Features:**
+- Validates stdio transport (command, args, env)
+- Validates HTTP transport (url, headers)
+- Performs environment variable substitution
+- Validates required fields per transport type
+- Expands user paths (`~/`)
+
+**Example:**
+```python
+from src.config import load_mcp_config
+
+config = load_mcp_config("./config/.mcp.json")
+servers = config["mcpServers"]
+```
+
+### `load_gateway_rules(path: str) -> dict`
+
+Loads and validates gateway rules configuration from a JSON file.
+
+**Features:**
+- Validates agent policy structure
+- Supports hierarchical agent names (`team.role`)
+- Validates wildcard patterns (`*`, `get_*`, `*_query`)
+- Validates allow/deny rules
+- Expands user paths (`~/`)
+
+**Example:**
+```python
+from src.config import load_gateway_rules
+
+rules = load_gateway_rules(".mcp-gateway-rules.json")
+agents = rules["agents"]
+```
+
+### `validate_rules_against_servers(rules: dict, mcp_config: dict) -> list[str]`
+
+Cross-validates that all servers referenced in rules exist in the MCP configuration.
+
+**Returns:** List of warning messages (empty if all valid)
+
+**Example:**
+```python
+from src.config import load_mcp_config, load_gateway_rules, validate_rules_against_servers
+
+mcp_config = load_mcp_config("./config/.mcp.json")
+rules = load_gateway_rules(".mcp-gateway-rules.json")
+
+warnings = validate_rules_against_servers(rules, mcp_config)
+for warning in warnings:
+    print(f"Warning: {warning}")
+```
+
+### `get_config_path(env_var: str, default: str) -> str`
+
+Gets configuration file path from environment variable or uses default.
+
+**Example:**
+```python
+from src.config import get_config_path
+
+mcp_config_path = get_config_path(
+    "GATEWAY_MCP_CONFIG",
+    "./config/.mcp.json"
+)
+```
+
+## Configuration File Formats
+
+### MCP Servers Configuration
+
+**File:** `config/.mcp.json`
+
+**Structure:**
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "package-name"],
+      "env": {
+        "VAR_NAME": "${ENV_VAR}"
+      }
+    }
+  }
+}
+```
+
+**Stdio Transport:**
+```json
+{
+  "server-name": {
+    "command": "npx",           // Required
+    "args": ["--flag", "value"], // Optional
+    "env": {"KEY": "value"}     // Optional
+  }
+}
+```
+
+**HTTP Transport:**
+```json
+{
+  "server-name": {
+    "url": "https://example.com/mcp",  // Required
+    "headers": {                        // Optional
+      "Authorization": "Bearer token"
+    }
+  }
+}
+```
+
+### Gateway Rules Configuration
+
+**File:** `.mcp-gateway-rules.json`
+
+**Structure:**
+```json
+{
+  "agents": {
+    "agent-id": {
+      "allow": {
+        "servers": ["server1", "server2"],
+        "tools": {
+          "server1": ["tool1", "tool2", "get_*"],
+          "server2": ["*"]
+        }
+      },
+      "deny": {
+        "tools": {
+          "server1": ["drop_*", "delete_*"]
+        }
+      }
+    }
+  },
+  "defaults": {
+    "deny_on_missing_agent": true
+  }
+}
+```
+
+**Wildcard Patterns:**
+- `*` - Matches all (must be alone)
+- `get_*` - Matches prefix
+- `*_query` - Matches suffix
+- Middle wildcards NOT supported (`get_*_all` is invalid)
+
+**Hierarchical Agent Names:**
+- `researcher` - Simple name
+- `team.researcher` - Hierarchical (team.role)
+- `company.team.developer` - Multi-level hierarchy
+
+## Environment Variables
+
+### Configuration Paths
+
+- `GATEWAY_MCP_CONFIG` - Path to MCP servers config (default: `./config/.mcp.json`)
+- `GATEWAY_RULES` - Path to gateway rules config (default: `.mcp-gateway-rules.json`, fallback: `./config/.mcp-gateway-rules.json`)
+
+### Variable Substitution
+
+Environment variables in configuration files are substituted using `${VAR}` syntax:
+
+```json
+{
+  "env": {
+    "API_KEY": "${BRAVE_API_KEY}",
+    "DATABASE_URL": "${POSTGRES_URL}"
+  }
+}
+```
+
+**Important:** All referenced environment variables MUST be set before loading the configuration, or a `ValueError` will be raised with a clear error message.
+
+## Error Handling
+
+The configuration module provides clear, actionable error messages for all validation failures:
+
+### Missing File
+```
+FileNotFoundError: MCP server configuration file not found: /path/to/config.json
+```
+
+### Invalid JSON
+```
+JSONDecodeError: Invalid JSON in MCP server configuration: Expecting ',' delimiter
+```
+
+### Missing Environment Variable
+```
+ValueError: Environment variable "BRAVE_API_KEY" referenced in configuration but not set. 
+Please set this variable before starting the gateway.
+```
+
+### Invalid Transport
+```
+ValueError: Server "my-server" must specify either "command" (stdio) or "url" (HTTP) transport
+```
+
+### Invalid Wildcard
+```
+ValueError: Agent "test" allow.tools["server"][0]: wildcard in pattern "get_*_all" 
+must be at start, end, or alone
+```
+
+## Validation Script
+
+Use the included validation script to check your configurations:
+
+```bash
+# Validate with default paths
+python validate_config.py
+
+# Validate with custom paths
+GATEWAY_MCP_CONFIG=./my-config.json \
+GATEWAY_RULES=./.mcp-gateway-rules.json \
+python validate_config.py
+
+# Validate with required environment variables
+BRAVE_API_KEY=your_key \
+POSTGRES_URL=postgresql://localhost/db \
+python validate_config.py
+```
+
+## Testing
+
+Run the test suite to verify the configuration module:
+
+```bash
+python test_config.py
+```
+
+**Tests cover:**
+- Valid configuration loading
+- Environment variable substitution
+- Missing environment variables
+- HTTP and stdio transports
+- Invalid transport specifications
+- Gateway rules validation
+- Hierarchical agent names
+- Wildcard pattern validation
+- Cross-validation between rules and servers
+- Config path resolution
+- File not found errors
+- Invalid JSON handling
+
+## Usage Example
+
+```python
+import os
+from src.config import (
+    load_mcp_config,
+    load_gateway_rules,
+    validate_rules_against_servers,
+    get_config_path
+)
+
+# Set required environment variables
+os.environ["BRAVE_API_KEY"] = "your_api_key"
+os.environ["POSTGRES_URL"] = "postgresql://localhost/db"
+
+# Get config paths
+mcp_config_path = get_config_path(
+    "GATEWAY_MCP_CONFIG",
+    "./config/.mcp.json"
+)
+rules_path = get_config_path(
+    "GATEWAY_RULES",
+    ".mcp-gateway-rules.json"
+)
+
+# Load configurations
+try:
+    mcp_config = load_mcp_config(mcp_config_path)
+    rules = load_gateway_rules(rules_path)
+    
+    # Cross-validate
+    warnings = validate_rules_against_servers(rules, mcp_config)
+    if warnings:
+        for warning in warnings:
+            print(f"Warning: {warning}")
+    
+    print(f"Loaded {len(mcp_config['mcpServers'])} servers")
+    print(f"Loaded {len(rules['agents'])} agent policies")
+    
+except FileNotFoundError as e:
+    print(f"Configuration file not found: {e}")
+except ValueError as e:
+    print(f"Configuration validation error: {e}")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+## Best Practices
+
+1. **Use `.env.example`**: Document all required environment variables in `.env.example`
+2. **Validate Early**: Run `validate_config.py` before starting the gateway
+3. **Cross-Validate**: Always run `validate_rules_against_servers()` to catch undefined server references
+4. **Secure Secrets**: Never commit actual API keys or credentials to version control
+5. **Clear Naming**: Use descriptive server and agent names
+6. **Wildcard Safety**: Use specific patterns (e.g., `get_*`) instead of `*` when possible
+7. **Deny-Before-Allow**: Place deny rules before allow rules for clarity (enforced at runtime)
+
+## Implementation Details
+
+### Environment Variable Substitution
+
+The `_substitute_env_vars()` function recursively processes all strings in the configuration:
+
+- **Pattern:** `${VARIABLE_NAME}`
+- **Behavior:** Replaces with `os.environ["VARIABLE_NAME"]`
+- **Error:** Raises `ValueError` if variable not set
+- **Recursive:** Processes nested dicts and lists
+
+### Validation Order
+
+1. **File existence** - Check file exists
+2. **JSON parsing** - Parse JSON structure
+3. **Structure validation** - Validate top-level keys
+4. **Type validation** - Check all field types
+5. **Transport validation** - Validate stdio/HTTP requirements
+6. **Pattern validation** - Validate wildcards
+7. **Environment substitution** - Replace ${VAR} patterns
+8. **Cross-validation** - Validate references between configs
+
+### Path Handling
+
+All file paths are:
+1. Expanded (`~/` → home directory)
+2. Resolved to absolute paths
+3. Validated for existence
+4. Reported in error messages with full paths
+
+This ensures consistent behavior across different execution contexts and clear error reporting.

src/__init__.py

@@ -0,0 +1 @@
+"""Agent MCP Gateway - Core implementation package."""

src/audit.py

@@ -0,0 +1,94 @@
+"""Audit logging for Agent MCP Gateway."""
+
+import json
+import sys
+import time
+from datetime import datetime, timezone
+from functools import wraps
+from pathlib import Path
+from typing import Any, Callable
+
+
+class AuditLogger:
+    """Logs gateway operations for security auditing and debugging."""
+
+    def __init__(self, log_path: str = "~/.cache/agent-mcp-gateway/logs/audit.jsonl"):
+        """Initialize audit logger with log file path.
+
+        Args:
+            log_path: Path to audit log file (JSONL format)
+        """
+        self.log_path = Path(log_path).expanduser()
+        # Create log directory if it doesn't exist
+        self.log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def log(
+        self,
+        agent_id: str,
+        operation: str,
+        decision: str,
+        latency_ms: float,
+        metadata: dict[str, Any] | None = None
+    ):
+        """Log an audit entry to the log file.
+
+        Args:
+            agent_id: Agent making the request
+            operation: Operation name (list_servers, execute_tool, etc.)
+            decision: ALLOW, DENY, or ERROR
+            latency_ms: Operation latency in milliseconds
+            metadata: Additional context (server, tool, error, etc.)
+        """
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "agent_id": agent_id,
+            "operation": operation,
+            "decision": decision,
+            "latency_ms": round(latency_ms, 2),
+            "metadata": metadata or {}
+        }
+
+        try:
+            with open(self.log_path, 'a') as f:
+                f.write(json.dumps(entry) + "\n")
+                f.flush()  # Ensure immediate write
+        except Exception as e:
+            # Log to stderr if file logging fails
+            # Don't raise - logging failures shouldn't crash the gateway
+            print(f"WARNING: Failed to write audit log: {e}", file=sys.stderr)
+
+
+def audit_operation(operation: str, audit_logger: AuditLogger):
+    """Decorator to automatically audit an operation.
+
+    Args:
+        operation: Operation name
+        audit_logger: AuditLogger instance
+
+    Returns:
+        Decorated function that logs operation timing and outcome
+    """
+    def decorator(func: Callable):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            start_time = time.time()
+            agent_id = kwargs.get("agent_id", "unknown")
+
+            try:
+                result = await func(*args, **kwargs)
+                latency_ms = (time.time() - start_time) * 1000
+                audit_logger.log(agent_id, operation, "ALLOW", latency_ms)
+                return result
+            except Exception as e:
+                latency_ms = (time.time() - start_time) * 1000
+                audit_logger.log(
+                    agent_id,
+                    operation,
+                    "ERROR",
+                    latency_ms,
+                    metadata={"error": str(e)}
+                )
+                raise
+
+        return wrapper
+    return decorator

src/config/.mcp-gateway-rules.json.example

@@ -0,0 +1,59 @@
+{
+  "agents": {
+    "default": {
+      "deny": {
+        "servers": ["*"]
+      }
+    },
+    "researcher": {
+      "allow": {
+        "servers": ["brave-search", "context7"],
+        "tools": {
+          "brave-search": ["brave_web_search"]
+        }
+      }
+    },
+    "backend": {
+      "allow": {
+        "servers": ["postgres", "laravel-boost"],
+        "tools": {
+          "postgres": ["query", "list_tables", "list_schemas"],
+          "laravel-boost": ["get_*", "list_*", "read_*", "database_*", "search_*"]
+        }
+      },
+      "deny": {
+        "tools": {
+          "postgres": ["drop_*", "delete_*"],
+          "laravel-boost": ["database_query", "tinker"]
+        }
+      }
+    },
+    "admin": {
+      "allow": {
+        "servers": ["*"],
+        "tools": {
+          "brave-search": ["brave_web_search"]
+        }
+      },
+      "deny": {
+        "servers": ["notion"],
+        "tools": {
+          "playwright": ["browser_type"]
+        }
+      }
+    },
+    "claude-desktop": {
+      "allow": {
+        "servers": ["context7", "brave-search", "notion", "playwright"]
+      },
+      "deny": {
+        "tools": {
+          "playwright": ["browser_type", "browser_close_all", "launch_*"]
+        }
+      }
+    }
+  },
+  "defaults": {
+    "deny_on_missing_agent": false
+  }
+}

src/config/.mcp.json.example

@@ -0,0 +1,30 @@
+{
+  "mcpServers": {
+    "brave-search": {
+      "description": "Web search via Brave Search API",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+      }
+    },
+    "postgres": {
+      "description": "PostgreSQL database access and query execution",
+      "command": "uvx",
+      "args": ["mcp-server-postgres"],
+      "env": {
+        "POSTGRES_URL": "${POSTGRES_URL}"
+      }
+    },
+    "filesystem": {
+      "description": "Read and write files in /workspace directory",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
+    },
+    "notion": {
+      "description": "Access and manage Notion workspaces",
+      "url": "https://mcp.notion.com/mcp",
+      "transport": "http"
+    }
+  }
+}