Metadata-Version: 2.4
Name: cognito-mcp-proxy
Version: 0.1.1
Summary: Cognito OAuth stdio proxy for AWS Bedrock AgentCore Runtimes
Project-URL: repository, https://github.com/your-org/cognito-mcp-proxy
Author: Charter BI Team
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: truststore>=0.9.0
Description-Content-Type: text/markdown

# cognito-mcp-proxy

**Cognito OAuth stdio proxy for AWS Bedrock AgentCore Runtimes**

A lightweight, `uvx`-installable package that bridges MCP clients (Kiro IDE, Claude Desktop)
with AgentCore Runtimes secured by Cognito/EntraID OAuth. No `.env` files, no AWS CLI needed.

## Architecture

```
Kiro IDE <--stdio (JSON-RPC)--> cognito-mcp-proxy <--HTTPS + Bearer JWT--> AgentCore Runtime
                                       |
                                 Cognito OAuth PKCE
                                 (browser sign-in)
```

## How It Works

1. On startup, opens your browser for Cognito/EntraID sign-in (OAuth PKCE)
2. After auth, reads JSON-RPC messages from stdin (from Kiro)
3. For each request: refreshes the JWT, sends it as Bearer token to the AgentCore runtime
4. Parses the SSE/JSON response and writes JSON-RPC back to stdout

## Installation & Usage

### Option 1: uvx (Recommended)

Add to your MCP config (`~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json`):

```json
{
  "mcpServers": {
    "redshift-secure": {
      "command": "uvx",
      "args": ["cognito-mcp-proxy@latest"],
      "env": {
        "AGENTCORE_REGION": "us-east-1",
        "AGENTCORE_RUNTIME_ID": "arn:aws:bedrock-agentcore:us-east-1:123456789:runtime/YourRuntime-AbcXyz",
        "COGNITO_DOMAIN": "https://your-pool.auth.us-east-1.amazoncognito.com",
        "COGNITO_CLIENT_ID": "your_cognito_client_id"
      },
      "disabled": false,
      "autoApprove": ["whoami"]
    }
  }
}
```

### Option 2: Direct Python (Fallback)

```json
{
  "mcpServers": {
    "redshift-secure": {
      "command": "python",
      "args": ["-m", "cognito_mcp_proxy"],
      "env": {
        "AGENTCORE_REGION": "us-east-1",
        "AGENTCORE_RUNTIME_ID": "arn:aws:bedrock-agentcore:...",
        "COGNITO_DOMAIN": "https://...",
        "COGNITO_CLIENT_ID": "..."
      },
      "disabled": false
    }
  }
}
```

## Environment Variables

All configuration is via environment variables set in the `env` block of your mcp.json:

### AgentCore Runtime (Option A — recommended: components)

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AGENTCORE_REGION` | Yes* | Extracted from ARN | AWS region (e.g., `us-east-1`) |
| `AGENTCORE_RUNTIME_ID` | Yes* | — | Runtime ARN (e.g., `arn:aws:bedrock-agentcore:us-east-1:123456:runtime/MyRuntime-Abc`) |
| `AGENTCORE_QUALIFIER` | No | `DEFAULT` | Runtime qualifier/alias |

### AgentCore Runtime (Option B — advanced: full URL)

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `AGENTCORE_RUNTIME_URL` | Yes* | — | Full invocation URL (overrides region/ID/qualifier) |

*One of Option A or Option B must be provided.

The proxy builds the URL as:
```
https://bedrock-agentcore.{REGION}.amazonaws.com/runtimes/{URL_ENCODED_ARN}/invocations?qualifier={QUALIFIER}
```

### Cognito OAuth

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `COGNITO_DOMAIN` | **Yes** | — | Cognito User Pool domain (with or without `https://`) |
| `COGNITO_CLIENT_ID` | **Yes** | — | Cognito App Client ID |
| `COGNITO_REDIRECT_URI` | No | `http://localhost:22553/oauth/callback` | OAuth callback URI |
| `COGNITO_SCOPE` | No | `openid email` | OAuth scopes |
| `COGNITO_CALLBACK_PORT` | No | `22553` | Local port for OAuth callback server |
| `COGNITO_REQUEST_TIMEOUT` | No | `120` | HTTP timeout in seconds for runtime calls |

## First-Time Setup

1. Add the MCP configuration to your mcp.json (see above)
2. Restart Kiro (or reconnect MCP servers)
3. On first request, your browser opens for Cognito/Microsoft sign-in
4. Complete sign-in — you'll see "Authentication complete"
5. Return to Kiro and test: ask "run whoami using redshift-secure"

## Connecting to Different Runtimes

Since all config is via env vars, you can have multiple entries pointing to different runtimes:

```json
{
  "mcpServers": {
    "redshift-secure": {
      "command": "uvx",
      "args": ["cognito-mcp-proxy@latest"],
      "env": {
        "AGENTCORE_REGION": "us-east-1",
        "AGENTCORE_RUNTIME_ID": "arn:aws:bedrock-agentcore:us-east-1:123456:runtime/Redshift-Prod",
        "COGNITO_DOMAIN": "https://my-pool.auth.us-east-1.amazoncognito.com",
        "COGNITO_CLIENT_ID": "abc123"
      }
    },
    "another-runtime": {
      "command": "uvx",
      "args": ["cognito-mcp-proxy@latest"],
      "env": {
        "AGENTCORE_REGION": "us-west-2",
        "AGENTCORE_RUNTIME_ID": "arn:aws:bedrock-agentcore:us-west-2:123456:runtime/Other-Runtime",
        "COGNITO_DOMAIN": "https://other-pool.auth.us-west-2.amazoncognito.com",
        "COGNITO_CLIENT_ID": "xyz789"
      }
    }
  }
}
```

## Key Differences from tester_bundle

| Feature | tester_bundle (old) | cognito-mcp-proxy (new) |
|---------|--------------------|-----------------------|
| Installation | Manual copy + `pip install truststore` | `uvx cognito-mcp-proxy@latest` (zero setup) |
| Configuration | Edit `.env` file | Set env vars in `mcp.json` |
| Path management | User must locate Python and script path | Automatic via uvx |
| Upgrades | Manual file replacement | `@latest` auto-updates |
| Reuse | One config per .env file | Different env vars per mcp.json entry |
| Multi-runtime | Copy entire folder per runtime | Just add another mcp.json entry |

## Development

```bash
# Clone and build
cd cognito_mcp_proxy
uv venv
uv pip install -e .

# Run directly
cognito_mcp_proxy

# Test with MCP Inspector
npx @modelcontextprotocol/inspector cognito_mcp_proxy
```

### Build & Publish

```bash
uv build
uv publish  # to PyPI
```

## Troubleshooting

**Browser doesn't open:**
- Check your default browser is set
- Ensure VPN is connected (corporate network required)

**"Invalid grant" error:**
- Disconnect and reconnect the MCP server in Kiro

**Timeout errors:**
- Ensure VPN is active
- Increase `COGNITO_REQUEST_TIMEOUT` if runtime is slow

**"Required environment variable X is not set":**
- Check your mcp.json `env` block has all required variables

**"AgentCore runtime not configured":**
- Set either `AGENTCORE_RUNTIME_ID` (+ optional `AGENTCORE_REGION`) or `AGENTCORE_RUNTIME_URL`

## Notes

- No AWS CLI or `aws sso login` needed
- No credentials saved to disk — tokens live in memory only
- Token auto-refreshes (valid ~30 days)
- If already signed into Microsoft, auth completes with zero clicks
- Corporate SSL handled via `truststore` package
- Works with any AgentCore runtime — not limited to Redshift
