Metadata-Version: 2.4
Name: socialmediatracker-mcp
Version: 0.1.0
Summary: MCP server for Social Media Tracker 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

Stdio-based MCP server that provides access to Social Media Tracker tools through Cognito authentication.

## Features

- 🔐 **Secure Authentication**: Cognito OAuth flow with browser-based login
- 🔒 **Hardware-Bound Encryption**: Tokens encrypted with machine-specific hardware UUID (non-portable)
- 🔄 **Automatic Token Refresh**: 30-day token validity with automatic refresh
- 🛠️ **Dynamic Tool Discovery**: Automatically discovers tools from AgentCore Gateway
- 🌐 **Cross-Platform**: Supports macOS, Linux, and Windows
- 📦 **Easy Installation**: Install with `uvx` or `pip`

## Quick Start

### Installation

Install via `uvx` (recommended) or `pip`:

```bash
# Using uvx (no installation needed)
uvx socialmediatracker-mcp@latest

# Or using pip
pip install socialmediatracker-mcp
```

### Configuration

You need to configure the following environment variables with your AWS resources:

- `AGENTCORE_GATEWAY_URL` - Your AgentCore Gateway endpoint
- `COGNITO_USER_POOL_ID` - Your Cognito User Pool ID
- `COGNITO_CLIENT_ID` - Your Cognito App Client ID
- `COGNITO_DOMAIN` - Your Cognito Domain

**Option 1: MCP Configuration (Recommended)**

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

```json
{
  "mcpServers": {
    "socialmediatracker": {
      "command": "uvx",
      "args": ["socialmediatracker-mcp@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"
      }
    }
  }
}
```

**Option 2: Environment File**

Create a `.env` file in your working directory:

```bash
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
```

See `.env.sample` in the repository for a template.

### First-Time Setup

1. **Configure Environment**: Set up your AWS resource configuration (see above)
2. **Ensure Midway Authentication**: Run `mwinit` to authenticate with Midway
3. **Connect MCP Server**: The server will automatically open a browser for Cognito authentication
4. **Authenticate**: Complete the OAuth flow in your browser
5. **Done**: Tokens are encrypted and cached locally for 30 days

## Available Tools

The server provides 10 tools for social media tracking:

- `get_activities_by_customer` - Get social media activities for specific customers
- `get_activities_by_source` - Get activities from a specific source (X, LinkedIn, news, blog)
- `get_activity_frequency` - Get time-series activity frequency data
- `get_activity_heatmap` - Get activity counts by customer and source
- `get_activity_velocity` - Get activity percentage change between periods
- `get_geo_distribution` - Get geographic distribution of activities
- `get_hashtag_analytics` - Get hashtag distribution with engagement metrics
- `get_customer` - Get detailed customer information
- `list_customers` - List all customers with optional search
- `list_territories` - List all territories with company counts

## Security

### Hardware-Bound Encryption

Tokens are encrypted using a key derived from your machine's hardware UUID, making them non-portable:
- **macOS**: IOPlatformUUID from `ioreg -rd1 -c IOPlatformExpertDevice`
- **Linux**: Product UUID from `/sys/class/dmi/id/product_uuid`
- **Windows**: Machine GUID from `wmic csproduct get UUID`

**Why this matters:**
- Tokens cannot be copied to another machine
- Even if someone steals both `.key` and `tokens.enc` files, they won't work on a different computer
- Provides defense-in-depth security for your credentials

### Token Storage

- **Encrypted tokens**: `~/.socialmediatracker/tokens.enc` (AES-256 encryption)
- **Encryption key**: `~/.socialmediatracker/.key` (600 permissions, hardware-derived)
- **Automatic refresh**: Tokens refresh automatically before expiration (30-day validity)
- **Key verification**: On startup, the stored key is verified against hardware UUID

### OAuth Flow Security

- Browser-based authentication with Cognito
- Temporary callback server on localhost:8080 (automatically cleans up port conflicts)
- Authorization code exchange (not implicit flow)
- Tokens never exposed in URLs or logs

## Development

### Local Installation

```bash
# Clone the repository
git clone https://github.com/sameerbattoo/socialmediatracker_proxy_mcp_server.git
cd socialmediatracker_proxy_mcp_server

# Create virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# Configure environment
cp .env.sample .env
# Edit .env with your AWS resource values
```

### Testing

```bash
# Test the server directly
python -m socialmediatracker_mcp.server

# Or use the installed command
socialmediatracker-mcp
```

## Troubleshooting

### Port 8080 Already in Use

The OAuth callback server uses port 8080. The server automatically detects and kills any process using this port before starting. If you see port-related messages in the logs, this is normal behavior.

**What happens:**
1. Server checks if port 8080 is available
2. If occupied, automatically kills the blocking process
3. Starts the OAuth callback server
4. Falls back to socket reuse if cleanup fails

### Configuration Error

If you see "Missing required environment variables", ensure you've configured all required environment variables:
- `AGENTCORE_GATEWAY_URL`
- `COGNITO_USER_POOL_ID`
- `COGNITO_CLIENT_ID`
- `COGNITO_DOMAIN`

See the Configuration section above for setup instructions.

### Token Mismatch Error

If you see "Encryption key mismatch", this means:
- Tokens were copied from another machine (not supported due to hardware-bound encryption)
- Hardware UUID changed (rare, usually after motherboard replacement)
- Username changed

**Solution:** Delete `~/.socialmediatracker/` and re-authenticate.

### Authentication Required

Ensure you have run `mwinit` to authenticate with Midway before using the MCP server. The server reads your Midway cookies to identify your user account.

## Architecture

```
Kiro IDE (stdio) → MCP Server → AgentCore Gateway (HTTP)
                    ↓
                    ├─ Cognito OAuth authentication (browser-based)
                    ├─ Hardware-bound token encryption (AES-256)
                    ├─ Automatic port cleanup (kills blocking processes)
                    ├─ Dynamic tool discovery (no hardcoding)
                    └─ Token refresh (30-day validity)
```

### Key Components

1. **Authentication Manager** (`auth_manager.py`)
   - Cognito OAuth flow with browser
   - Midway cookie integration for user identification
   - Automatic port 8080 cleanup
   - Token encryption and caching

2. **Token Encryption** (`token_encryption.py`)
   - Hardware UUID extraction (cross-platform)
   - AES-256 encryption with PBKDF2 key derivation
   - Key verification on startup

3. **Gateway Client** (`gateway_client.py`)
   - Strands MCPClient integration
   - Dynamic tool discovery with pagination
   - Bearer token authentication

4. **MCP Server** (`server.py`)
   - Stdio transport for Kiro
   - Tool name cleaning (removes API prefixes)
   - Error handling and logging

## License

MIT License - See LICENSE file for details
