Metadata-Version: 2.4
Name: agentcore-mcp-proxy
Version: 0.1.0
Summary: MCP server for any AWS AgenCore Gateway endpoint with Cognito authentication and hardware-bound token encryption
Project-URL: Homepage, https://github.com/sameerbattoo/socialmediatracker_proxy_mcp_server
Project-URL: Repository, https://github.com/sameerbattoo/socialmediatracker_proxy_mcp_server
Project-URL: Issues, https://github.com/sameerbattoo/socialmediatracker_proxy_mcp_server/issues
Author-email: Sameer Battoo <sbattoo@amazon.com>
License: MIT
License-File: LICENSE
Keywords: agentcore,aws,cognito,mcp,model-context-protocol,social-media
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: cryptography>=41.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: strands-agents>=1.26.0
Description-Content-Type: text/markdown

# Social Media Tracker MCP Server

An MCP (Model Context Protocol) server that bridges Kiro IDE with the Social Media Tracker AgentCore Gateway. It provides secure, authenticated access to customer intelligence tools including activity tracking, hashtag analytics, geographic distribution, and territory management.

## Architecture

```
┌─────────┐       stdio        ┌──────────┐      HTTPS       ┌──────────────────┐
│  Kiro   │◀──────────────────▶│   MCP    │◀────────────────▶│   AgentCore      │
│   IDE   │                    │  Server  │                   │   Gateway        │
└─────────┘                    └──────────┘                   └──────────────────┘
                                    │                                  │
                                    │                                  │
                               ┌────┴────┐                    ┌───────┴────────┐
                               │ Cognito │                    │  Social Media  │
                               │  OAuth  │                    │  Tracker API   │
                               └─────────┘                    └────────────────┘
```

1. Kiro IDE communicates with the MCP server over stdio
2. MCP server authenticates via Cognito OAuth (browser-based)
3. Authenticated requests are forwarded to AgentCore Gateway over HTTPS
4. Tools are dynamically discovered from the gateway (no hardcoding)

### Key Components

| File | Purpose |
|------|---------|
| `server.py` | MCP server with stdio transport, tool discovery, and error handling |
| `auth_manager.py` | Dual auth (Federate + Cognito User), OAuth flow, token caching |
| `token_encryption.py` | Hardware-bound AES-256 encryption using machine UUID |
| `gateway_client.py` | Strands MCPClient integration with Bearer token auth |
| `config.py` | Environment-based configuration with validation |

## Features

- 🔐 Dual Authentication: Amazon Corporate SSO (Federate) or Cognito User Pool
- 🔄 Automatic Token Refresh: 30-day validity with transparent refresh
- 🔒 Hardware-Bound Encryption: Tokens encrypted with machine-specific UUID (non-portable)
- 🛠️ Dynamic Tool Discovery: Tools auto-discovered from AgentCore Gateway
- 🌐 Cross-Platform: macOS, Linux, and Windows
- 📦 Easy Installation: `uvx` or `pip`

## Available Tools

| Tool | Description |
|------|-------------|
| `list_territories` | List all territories with company counts |
| `list_customers` | List customers with optional search and insights |
| `get_customer` | Get detailed customer information |
| `get_activities_by_customer` | Get activities for specific customers |
| `get_activities_by_source` | Get activities from a specific source (X, LinkedIn, news, blog) |
| `get_activity_frequency` | Time-series activity frequency data |
| `get_activity_heatmap` | Activity counts by customer and source |
| `get_activity_velocity` | Activity percentage change between periods |
| `get_geo_distribution` | Geographic distribution of activities |
| `get_hashtag_analytics` | Hashtag distribution with engagement metrics |
| `authenticate_with_federate` | Initiate Amazon Corporate SSO authentication |
| `authenticate_with_cognito_user` | Initiate Cognito User Pool authentication |

## Security Overview

The server implements multi-layered security:

- OAuth 2.0 Authorization Code Flow with AWS Cognito
- Hardware-bound token encryption (AES-256, non-portable across machines)
- ID Token used for gateway authorization (contains user identity claims)
- Automatic token refresh with 30-day validity
- Tokens stored encrypted at `~/.agentcore_mcp_proxy/tokens.enc`

For the full security architecture, threat model, and cryptographic details, see [SECURITY.md](SECURITY.md).

---


## Kiro IDE Configuration

### Option 1: Using `uvx` (Recommended — after PyPI publishing)

Add to `~/.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "agentcore_mcp_proxy": {
      "command": "uvx",
      "args": ["agentcore_mcp_proxy@latest"],
      "env": {
        "AGENTCORE_GATEWAY_URL": "https://your-gateway.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
        "COGNITO_USER_POOL_ID": "us-west-2_XXXXXXXXX",
        "COGNITO_CLIENT_ID": "your_client_id_here",
        "COGNITO_DOMAIN": "your-domain.auth.us-west-2.amazoncognito.com"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Option 2: Using local Python (Development)

```json
{
  "mcpServers": {
    "agentcore_mcp_proxy": {
      "command": "/path/to/your/.venv/bin/python3",
      "args": ["/path/to/proxy_mcp_server/src/agentcore_mcp_proxy/server.py"],
      "env": {
        "AGENTCORE_GATEWAY_URL": "https://your-gateway.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
        "COGNITO_USER_POOL_ID": "us-west-2_XXXXXXXXX",
        "COGNITO_CLIENT_ID": "your_client_id_here",
        "COGNITO_DOMAIN": "your-domain.auth.us-west-2.amazoncognito.com"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Option 3: Using `uvx` with local source

```json
{
  "mcpServers": {
    "agentcore_mcp_proxy": {
      "command": "uvx",
      "args": ["--from", "/path/to/proxy_mcp_server", "agentcore_mcp_proxy"],
      "env": {
        "AGENTCORE_GATEWAY_URL": "https://your-gateway.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
        "COGNITO_USER_POOL_ID": "us-west-2_XXXXXXXXX",
        "COGNITO_CLIENT_ID": "your_client_id_here",
        "COGNITO_DOMAIN": "your-domain.auth.us-west-2.amazoncognito.com"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Environment Variables

All configuration is via environment variables (set in `env` block above or via `.env` file):

| Variable | Required | Description |
|----------|----------|-------------|
| `AGENTCORE_GATEWAY_URL` | Yes | AgentCore Gateway endpoint URL |
| `COGNITO_USER_POOL_ID` | Yes | Cognito User Pool ID |
| `COGNITO_CLIENT_ID` | Yes | Cognito App Client ID |
| `COGNITO_DOMAIN` | Yes | Cognito Domain (without `https://`) |
| `AMAZON_IDP_NAME` | No | Identity provider name (default: `federate`) |
| `PROXY_HOST` | No | Callback host (default: `localhost`) |
| `PROXY_PORT` | No | Callback port (default: `8080`) |

See `.env.sample` for a template.

### First-Time Setup

1. Add the MCP configuration to `~/.kiro/settings/mcp.json`
2. Restart Kiro IDE
3. On first tool call, a browser window opens for Cognito authentication
4. Complete login (Amazon SSO or username/password)
5. Tokens are cached encrypted for 30 days with automatic refresh

### Verifying Connection

After configuration, the MCP server appears in Kiro's MCP panel. Verify by asking Kiro to "list my territories" or "list customers".

---

## Building and Testing Locally

### Prerequisites

- Python 3.10+
- `uv` package manager ([install guide](https://docs.astral.sh/uv/getting-started/installation/))
- `npx` (for MCP Inspector testing)

### Quick Start

```bash
# Clone and setup
git clone <repo-url>
cd proxy_mcp_server
uv venv
source .venv/bin/activate

# Install in development mode
uv pip install -e .

# Configure environment
cp .env.sample .env
# Edit .env with your values

# Run the server
agentcore_mcp_proxy
```

### Build, Test & Deploy Script

The repository includes `Build_Test_Deploy.sh` which automates the full pipeline:

```bash
chmod +x Build_Test_Deploy.sh
./Build_Test_Deploy.sh
```

The script performs these steps:

1. Cleans previous builds
2. Builds the package with `uv build`
3. Installs in editable mode for testing
4. Verifies the installation (import check + entry point)
5. Opens MCP Inspector for interactive testing (`http://localhost:6274`)
6. Guides you through Kiro testing
7. Deploys to TestPyPI or PyPI

### Manual Build Steps

```bash
# Clean
rm -rf dist/ build/ *.egg-info

# Build
uv build

# Install locally
uv pip install -e . --force-reinstall --no-deps

# Verify
python -c "from agentcore_mcp_proxy import main; print('OK')"
which agentcore_mcp_proxy
```

### Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector $(which agentcore_mcp_proxy)
```

Opens a browser at `http://localhost:6274` where you can interactively test tools.

### Publishing to PyPI

```bash
# TestPyPI (recommended first)
uv publish --publish-url https://test.pypi.org/legacy/

# Production PyPI
uv publish
```

After publishing, users can install with:
```bash
uvx agentcore_mcp_proxy@latest
# or
pip install agentcore-mcp-proxy
```

---

## Troubleshooting

### Port 8080 Already in Use

The server automatically kills blocking processes. If that fails:
```bash
lsof -ti :8080 | xargs kill -9
```

### "Encryption key mismatch"

Tokens were copied from another machine or hardware changed:
```bash
rm -rf ~/.agentcore_mcp_proxy/
# Re-authenticate on next use
```

### "Missing required environment variables"

Ensure all required env vars are set. See [Environment Variables](#environment-variables) above.

### No Midway Session (Federate only)

```bash
mwinit
# Or use Cognito User authentication instead
```

### Gateway 401 Unauthorized

Delete cached tokens and re-authenticate:
```bash
rm -rf ~/.agentcore_mcp_proxy/
```

## License

MIT License — See [LICENSE](LICENSE) file.
