agent-mcp-gateway 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

{agent_mcp_gateway-0.1.0.dist-info → agent_mcp_gateway-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-mcp-gateway
-Version: 0.1.0
+Version: 0.1.1
 Summary: An MCP gateway that aggregates your existing MCP servers and lets you define which servers and individual tools each agent or subagent can access. Solves Claude Code's MCP context window waste where all tool definitions load upfront instead of being discovered when actually needed.
 Project-URL: Homepage, https://github.com/roddutra/agent-mcp-gateway
 Project-URL: Documentation, https://github.com/roddutra/agent-mcp-gateway#readme
@@ -37,7 +37,10 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) gateway that a
 ## Table of Contents
 
 - [Overview](#overview)
+- [Installation](#installation)
 - [Quick Start](#quick-start)
+- [Command-Line Options](#command-line-options)
+- [Configuration File Discovery](#configuration-file-discovery)
 - [Configuration](#configuration)
 - [Usage](#usage)
 - [Gateway Tools](#gateway-tools)
@@ -74,11 +77,11 @@ The Agent MCP Gateway acts as a single MCP server that proxies to multiple downs
 
 ### How It Works
 
-![Agent MCP Gateway Architecture](docs/diagram-snippet.png)
+![Agent MCP Gateway Architecture](https://raw.githubusercontent.com/roddutra/agent-mcp-gateway/main/docs/diagram-snippet.png)
 
 The gateway sits between agents and downstream MCP servers, exposing only 3 lightweight tools. When an agent needs specific functionality, it discovers available servers and tools through the gateway, which filters visibility based on policy rules - agents only see servers and tools they have access to. This reduces each agent's context window to only relevant tools, while the gateway handles proxying authorized requests to downstream servers.
 
-**[View detailed diagram with examples →](docs/diagram-full.png)** (includes downstream servers, tools, and gateway rules examples)
+**[View detailed diagram with examples →](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/diagram-full.png)** (includes downstream servers, tools, and gateway rules examples)
 
 ### Key Features
 
@@ -95,48 +98,138 @@ The gateway sits between agents and downstream MCP servers, exposing only 3 ligh
 - ✅ **Thread-Safe Operations** - Safe concurrent access during reloads
 - ✅ **Diagnostic Tools** - Health monitoring via `get_gateway_status` (debug mode only)
 
-## Quick Start
+## Installation
+
+### For End Users (Recommended)
+
+Install via `uvx` for on-demand usage without persistent installation:
+
+```bash
+# Run directly without installing
+uvx agent-mcp-gateway --help
+
+# First-time setup - create config directory
+uvx agent-mcp-gateway --init
+
+# Run the gateway (uses configs from ~/.config/agent-mcp-gateway/)
+GATEWAY_MCP_CONFIG=~/.config/agent-mcp-gateway/mcp.json \
+GATEWAY_RULES=~/.config/agent-mcp-gateway/mcp-gateway-rules.json \
+uvx agent-mcp-gateway
+```
+
+Or install persistently with `uv tool`:
+
+```bash
+# Install once
+uv tool install agent-mcp-gateway
+
+# Run anytime
+agent-mcp-gateway --help
 
-### Prerequisites
+# Update to latest version
+uv tool upgrade agent-mcp-gateway
+```
 
-- Python 3.12+
-- [uv](https://docs.astral.sh/uv/) (Python package manager)
+### For Developers
 
-### 1. Install Dependencies
+Clone and install in development mode:
 
 ```bash
-# Clone the repository
-git clone <repository-url>
+# Clone repository
+git clone https://github.com/roddutra/agent-mcp-gateway.git
 cd agent-mcp-gateway
 
-# Install dependencies with uv
+# Install dependencies
 uv sync
+
+# Run locally
+uv run python main.py --help
 ```
 
-This installs:
-- `fastmcp >= 2.13.0.1` - MCP server framework
-- `pytest`, `pytest-cov`, `pytest-asyncio` - Testing tools (dev)
+## Quick Start
+
+**Note:** This guide assumes you've installed the gateway. See [Installation](#installation) above.
+
+### 1. Set Up Configuration Files
+
+The gateway requires two configuration files to operate. Choose your setup method:
 
-### 2. Set Up Configuration Files
+**Method A: For PyPI Installation (uvx/uv tool)**
 
 ```bash
+# Initialize config directory and create template files
+uvx agent-mcp-gateway --init
+# or
+agent-mcp-gateway --init  # if installed with uv tool
+
+# Edit configs with your servers and rules
+nano ~/.config/agent-mcp-gateway/mcp.json
+nano ~/.config/agent-mcp-gateway/mcp-gateway-rules.json
+```
+
+**Method B: For Local Development**
+
+```bash
+# Copy example files to your project directory
 cp config/.mcp.json.example .mcp.json
 cp config/.mcp-gateway-rules.json.example .mcp-gateway-rules.json
 
-# Edit configs with your servers and rules...
-# Note: .mcp.json is the standard MCP config format used by Claude Code
+# Edit configs with your servers and rules
+# Note: mcp.json is the standard MCP config format used by Claude Code
 ```
 
-### 3. Add Gateway to Your MCP Client
+See [Configuration File Discovery](#configuration-file-discovery) below for details on where the gateway searches for configuration files.
+
+### 2. Add Gateway to Your MCP Client
+
+**For PyPI Installation (uvx):**
 
-**Claude Code CLI:**
 ```bash
-claude mcp add agent-mcp-gateway \
-  uv run --directory /path/to/agent-mcp-gateway python main.py
+# Claude Code CLI
+claude mcp add agent-mcp-gateway uvx agent-mcp-gateway
+
+# Or manual configuration (Claude Desktop, etc.)
+# Add to your MCP client config:
+{
+  "mcpServers": {
+    "agent-mcp-gateway": {
+      "command": "uvx",
+      "args": ["agent-mcp-gateway"],
+      "env": {
+        "GATEWAY_MCP_CONFIG": "~/.config/agent-mcp-gateway/mcp.json",
+        "GATEWAY_RULES": "~/.config/agent-mcp-gateway/mcp-gateway-rules.json",
+        "GATEWAY_DEFAULT_AGENT": "developer"
+      }
+    }
+  }
+}
 ```
 
-**Manual MCP Client Configuration** (Claude Desktop, etc.):
+**For PyPI Installation (uv tool):**
+
 ```json
+{
+  "mcpServers": {
+    "agent-mcp-gateway": {
+      "command": "agent-mcp-gateway",
+      "env": {
+        "GATEWAY_MCP_CONFIG": "~/.config/agent-mcp-gateway/mcp.json",
+        "GATEWAY_RULES": "~/.config/agent-mcp-gateway/mcp-gateway-rules.json",
+        "GATEWAY_DEFAULT_AGENT": "developer"
+      }
+    }
+  }
+}
+```
+
+**For Local Development:**
+
+```bash
+# Claude Code CLI
+claude mcp add agent-mcp-gateway \
+  uv run --directory /path/to/agent-mcp-gateway python main.py
+
+# Or manual configuration
 {
   "mcpServers": {
     "agent-mcp-gateway": {
@@ -150,9 +243,9 @@ claude mcp add agent-mcp-gateway \
 }
 ```
 
-Replace `/path/to/agent-mcp-gateway` with the actual path to your gateway installation.
+Replace `/path/to/agent-mcp-gateway` with the actual path to your gateway clone.
 
-**Note:** The `--directory` flag tells `uv run` to change to the project directory before running, ensuring it finds `pyproject.toml` and the gateway configuration files.
+**Note:** For local development, the `--directory` flag tells `uv run` to change to the project directory before running, ensuring it finds `pyproject.toml` and the gateway configuration files.
 
 **Verify Gateway Connection:**
 
@@ -177,19 +270,7 @@ Gateway initialized successfully
   - 3 gateway tools available
 ```
 
-### 4. Development Usage (Optional)
-
-For local development and testing:
-
-```bash
-# Run gateway directly
-uv run python main.py
-
-# Test with MCP Inspector
-npx @modelcontextprotocol/inspector uv run python main.py
-```
-
-### 5. Configure Your Agents
+### 3. Configure Your Agents
 
 The gateway's tool descriptions are self-documenting, but for proper access control you should configure how your agents identify themselves.
 
@@ -252,7 +333,49 @@ When you need to use tools from downstream MCP servers:
 
 Replace `YOUR_AGENT_NAME` with your agent's identifier (e.g., "researcher", "backend", "admin").
 
-**Examples:** See [`.claude/agents/researcher.md`](.claude/agents/researcher.md) and [`.claude/agents/mcp-developer.md`](.claude/agents/mcp-developer.md) for complete configuration examples.
+**Examples:** See [`.claude/agents/researcher.md`](https://github.com/roddutra/agent-mcp-gateway/blob/main/.claude/agents/researcher.md) and [`.claude/agents/mcp-developer.md`](https://github.com/roddutra/agent-mcp-gateway/blob/main/.claude/agents/mcp-developer.md) for complete configuration examples.
+
+## Command-Line Options
+
+```bash
+# Show version
+agent-mcp-gateway --version
+
+# Initialize config directory (first-time setup)
+agent-mcp-gateway --init
+
+# Enable debug mode (exposes get_gateway_status diagnostic tool)
+agent-mcp-gateway --debug
+
+# Show help
+agent-mcp-gateway --help
+```
+
+**For local development:**
+```bash
+uv run python main.py --version
+uv run python main.py --init
+uv run python main.py --debug
+uv run python main.py --help
+```
+
+## Configuration File Discovery
+
+The gateway searches for configuration files in this order:
+
+### MCP Server Config (mcp.json)
+1. `GATEWAY_MCP_CONFIG` environment variable (if set)
+2. `.mcp.json` in current directory
+3. `~/.config/agent-mcp-gateway/mcp.json` (home directory)
+4. `./config/.mcp.json` (fallback)
+
+### Gateway Rules (mcp-gateway-rules.json)
+1. `GATEWAY_RULES` environment variable (if set)
+2. `.mcp-gateway-rules.json` in current directory
+3. `~/.config/agent-mcp-gateway/mcp-gateway-rules.json` (home directory)
+4. `./config/.mcp-gateway-rules.json` (fallback)
+
+**Tip:** Use `agent-mcp-gateway --init` to create the home directory configs on first run.
 
 ## Configuration
 
@@ -260,9 +383,9 @@ The gateway requires two configuration files:
 
 ### 1. MCP Servers Configuration
 
-**File:** `.mcp.json` (or `config/.mcp.json`)
+**File:** `mcp.json` (searched in [multiple locations](#configuration-file-discovery))
 
-Defines the downstream MCP servers the gateway will proxy to. Uses the standard `.mcp.json` format compatible with Claude Code and other coding agents:
+Defines the downstream MCP servers the gateway will proxy to. Uses the standard MCP config format compatible with Claude Code and other coding agents:
 
 ```json
 {
@@ -329,7 +452,7 @@ If you use `${VAR_NAME}` syntax in `.mcp.json`, note that macOS GUI applications
 
 ### 2. Gateway Rules Configuration
 
-**File:** `.mcp-gateway-rules.json` (or `config/.mcp-gateway-rules.json`)
+**File:** `mcp-gateway-rules.json` (searched in [multiple locations](#configuration-file-discovery))
 
 Defines per-agent access policies using deny-before-allow precedence:
 
@@ -420,7 +543,7 @@ uv run python main.py
 
 ### 3. OAuth Support for Downstream Servers
 
-OAuth-protected downstream servers (Notion, GitHub) are automatically supported via auto-detection when servers return HTTP 401. The gateway uses FastMCP's OAuth support to handle authentication flows transparently - browser opens once for initial authentication, then tokens are cached for future use. See [OAuth User Guide](docs/oauth-user-guide.md) for detailed setup and troubleshooting.
+OAuth-protected downstream servers (Notion, GitHub) are automatically supported via auto-detection when servers return HTTP 401. The gateway uses FastMCP's OAuth support to handle authentication flows transparently - browser opens once for initial authentication, then tokens are cached for future use. See [OAuth User Guide](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/oauth-user-guide.md) for detailed setup and troubleshooting.
 
 ### 4. Environment Variables Reference
 
@@ -856,7 +979,7 @@ The `deny_on_missing_agent` setting controls this behavior:
 
 **Debug Mode:** The `get_gateway_status` tool exposes gateway internals and is only available when `GATEWAY_DEBUG=true`. Disable in production environments.
 
-**For comprehensive security guidance:** See [Security Guide](docs/security-guide.md) for detailed information on rules file security, debug mode considerations, agent impersonation risks, and production best practices.
+**For comprehensive security guidance:** See [Security Guide](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/security-guide.md) for detailed information on rules file security, debug mode considerations, agent impersonation risks, and production best practices.
 
 ## Troubleshooting
 
@@ -896,7 +1019,7 @@ The `deny_on_missing_agent` setting controls this behavior:
 
 **Symptom:** Browser doesn't open or OAuth flow fails
 
-See detailed troubleshooting in [OAuth User Guide](docs/oauth-user-guide.md).
+See detailed troubleshooting in [OAuth User Guide](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/oauth-user-guide.md).
 
 Quick fixes:
 - **Clear token cache:** `rm -rf ~/.fastmcp/oauth-mcp-client-cache/`
@@ -913,7 +1036,7 @@ Quick fixes:
 - **Manual reload:** Send SIGHUP signal or restart gateway
 - **Debug mode:** Use `get_gateway_status` to check last reload timestamps
 
-**For additional help:** See [Security Guide](docs/security-guide.md), [OAuth User Guide](docs/oauth-user-guide.md), or open a GitHub issue.
+**For additional help:** See [Security Guide](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/security-guide.md), [OAuth User Guide](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/oauth-user-guide.md), or open a GitHub issue.
 
 ## Testing
 
@@ -1075,41 +1198,41 @@ open htmlcov/index.html
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│                    Agent / Client                        │
+│                    Agent / Client                       │
 └─────────────────────┬───────────────────────────────────┘
                       │
                       ▼
 ┌─────────────────────────────────────────────────────────┐
-│              Agent MCP Gateway                           │
+│              Agent MCP Gateway                          │
 │  ┌───────────────────────────────────────────────────┐  │
-│  │  Gateway Tools (3 tools, ~400 tokens)            │  │
+│  │  Gateway Tools (3 tools, ~400 tokens)             │  │
 │  │  • list_servers                                   │  │
 │  │  • get_server_tools                               │  │
 │  │  • execute_tool                                   │  │
 │  └───────────────────────────────────────────────────┘  │
-│                      │                                   │
+│                      │                                  │
 │  ┌─────────────────────────────────────────────────┐    │
-│  │  AgentAccessControl Middleware                   │    │
-│  │  • Extract agent_id                              │    │
-│  │  • Validate permissions                          │    │
+│  │  AgentAccessControl Middleware                  │    │
+│  │  • Extract agent_id                             │    │
+│  │  • Validate permissions                         │    │
 │  └─────────────────────────────────────────────────┘    │
-│                      │                                   │
+│                      │                                  │
 │  ┌─────────────────────────────────────────────────┐    │
-│  │  PolicyEngine                                    │    │
+│  │  PolicyEngine                                   │    │
 │  │  • Deny-before-allow precedence                 │    │
 │  │  • Wildcard matching                            │    │
 │  └─────────────────────────────────────────────────┘    │
-│                      │                                   │
+│                      │                                  │
 │  ┌─────────────────────────────────────────────────┐    │
-│  │  ProxyManager                                    │    │
-│  │  • Session isolation                             │    │
-│  │  • Connection pooling                            │    │
+│  │  ProxyManager                                   │    │
+│  │  • Session isolation                            │    │
+│  │  • Connection pooling                           │    │
 │  └─────────────────────────────────────────────────┘    │
-│                      │                                   │
+│                      │                                  │
 │  ┌─────────────────────────────────────────────────┐    │
-│  │  AuditLogger & MetricsCollector                  │    │
+│  │  AuditLogger & MetricsCollector                 │    │
 │  └─────────────────────────────────────────────────┘    │
-└──────────────────────┬───────────────────────────────────┘
+└──────────────────────┬──────────────────────────────────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼              ▼
@@ -1192,19 +1315,19 @@ docker run -v ./config:/config agent-mcp-gateway
 
 ## Documentation
 
-- [Product Requirements Document](docs/specs/PRD.md)
-- [M0: Foundation Spec](docs/specs/m0-foundation.md)
-- [M0: Success Report](docs/milestones/m0-success-report.md)
-- [M1: Core Spec](docs/specs/m1-core.md)
-- [M1: Success Report](docs/milestones/m1-success-report.md)
-- [FastMCP Implementation Guide](docs/fastmcp-implementation-guide.md)
-- [Claude Code Subagent Limitations](docs/claude-code-subagent-mcp-limitations.md)
+- [Product Requirements Document](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/specs/PRD.md)
+- [M0: Foundation Spec](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/specs/m0-foundation.md)
+- [M0: Success Report](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/milestones/m0-success-report.md)
+- [M1: Core Spec](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/specs/m1-core.md)
+- [M1: Success Report](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/milestones/m1-success-report.md)
+- [FastMCP Implementation Guide](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/fastmcp-implementation-guide.md)
+- [Claude Code Subagent Limitations](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/claude-code-subagent-mcp-limitations.md)
 
 ## Contributing
 
 Contributions welcome! Please:
 
-1. Read the [PRD](docs/specs/PRD.md) and relevant milestone specs
+1. Read the [PRD](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/specs/PRD.md) and relevant milestone specs
 2. Follow the existing code style and patterns
 3. Write tests for all new functionality
 4. Ensure all tests pass: `uv run pytest`
@@ -1213,13 +1336,13 @@ Contributions welcome! Please:
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/roddutra/agent-mcp-gateway/blob/main/LICENSE) file for details.
 
 ## Support
 
 For issues and questions:
-- GitHub Issues: [Create an issue](link-to-issues)
-- Documentation: [docs/specs/](docs/specs/)
+- GitHub Issues: [Create an issue](https://github.com/roddutra/agent-mcp-gateway/issues)
+- Documentation: [docs/](https://github.com/roddutra/agent-mcp-gateway/blob/main/docs/)
 - MCP Specification: https://modelcontextprotocol.io
 
 ## Acknowledgments

{agent_mcp_gateway-0.1.0.dist-info → agent_mcp_gateway-0.1.1.dist-info}/RECORD

@@ -11,8 +11,8 @@ src/policy.py,sha256=aJGPWOBQoQlR_hAodY6nGXiqq8k2m0tO8Ped0VF7d7c,19051
 src/proxy.py,sha256=eIZuHBJoZRmnm4lcXId3xIvxhl5Z1drmGHBEu88KvMg,24912
 src/config/.mcp-gateway-rules.json.example,sha256=t53srRy_JPHojDonjhVtkB_WhLTg_oTLqxLq5i6m_ww,855
 src/config/.mcp.json.example,sha256=_Gy7bflSOw15A2LfXpprSf29gGcve4zjDka-vuPVN2c,842
-agent_mcp_gateway-0.1.0.dist-info/METADATA,sha256=6eGMIReCnv46cuNGnonUZ4P9mycW0u6bDMmeXiHg1fk,42547
-agent_mcp_gateway-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-agent_mcp_gateway-0.1.0.dist-info/entry_points.txt,sha256=Rb9I44QKFEI6-38dCb1sPwSAzQlAzUBZKDQqjb-FHTI,52
-agent_mcp_gateway-0.1.0.dist-info/licenses/LICENSE,sha256=XPIqCRndYgq7mXJ2NlfnvN0IoqQGXpK2gnHIqyvuPws,1078
-agent_mcp_gateway-0.1.0.dist-info/RECORD,,
+agent_mcp_gateway-0.1.1.dist-info/METADATA,sha256=ZqueQoFLB2Y2KaJ3zc9zvIU2Jc08GH14xjpyssVBrTg,46962
+agent_mcp_gateway-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+agent_mcp_gateway-0.1.1.dist-info/entry_points.txt,sha256=Rb9I44QKFEI6-38dCb1sPwSAzQlAzUBZKDQqjb-FHTI,52
+agent_mcp_gateway-0.1.1.dist-info/licenses/LICENSE,sha256=XPIqCRndYgq7mXJ2NlfnvN0IoqQGXpK2gnHIqyvuPws,1078
+agent_mcp_gateway-0.1.1.dist-info/RECORD,,