Metadata-Version: 2.4
Name: opsguide-mcp
Version: 0.1.2
Summary: MCP Server proxy for Amazon Bedrock AgentCore Runtime
Author-email: Ekky Armandi <me@ekky.dev>
License-Expression: MIT
Keywords: ai,bedrock,mcp,opsguide,proxy
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# OpsGuide MCP Proxy

A **stateless** Model Context Protocol (MCP) server proxy for OpsGuide's Amazon Bedrock AgentCore Runtime. This proxy creates fresh connections for each request, ensuring no sessions are maintained.

## Overview

This stateless proxy server acts as a bridge between:
- **MCP clients** (like Claude Desktop, Cursor) that communicate via stdio
- **Amazon Bedrock AgentCore Runtime** that hosts your MCP server via HTTP

```
Claude Desktop ↔ opsguide-mcp (stateless proxy) ↔ Fresh HTTP Connection ↔ Bedrock AgentCore ↔ Your Tools
```

### Key Features
- ✅ **Stateless Design**: No persistent connections or sessions
- ✅ **Fresh Connections**: Each request creates a new connection to Bedrock
- ✅ **Tool Proxying**: Forwards `list_tools` and `call_tool` requests
- ✅ **Simple Configuration**: Only requires API_KEY

## Features

- **Protocol Bridge**: Converts between stdio (MCP client) and HTTP (Bedrock AgentCore)
- **Tool Proxying**: Forwards all tool calls to your Bedrock-hosted MCP server
- **Resource Access**: Proxies resource reading and listing
- **Prompt Support**: Forwards prompt operations
- **uvx Compatible**: Easy installation and usage with `uvx`
- **Environment Configuration**: Uses standard environment variables

## Prerequisites

- Python 3.10 or higher
- `uv` package manager
- Amazon Bedrock AgentCore Runtime with deployed MCP server
- Valid API key and agent ARN

## Installation

### For Claude Code

Add this configuration to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "opsguide-mcp": {
      "command": "uvx",
      "args": ["opsguide-mcp@latest"],
      "env": {
        "API_KEY": "your-bearer-token"
      }
    }
  }
}
```

### Direct Installation

```bash
# Install with uvx (recommended)
uvx opsguide-mcp

# Or install with pip
pip install opsguide-mcp
```

## Environment Variables

Only one environment variable is required:

- `API_KEY`: The bearer token for authentication

**Hardcoded Configuration:**
- `AGENT_ARN`: `arn:aws:bedrock-agentcore:us-east-1:654654574429:runtime/opsguide_mcp_server_example-feNooQ7JbB` 
- `AWS_REGION`: `us-east-1`

### Example .env file

```env
API_KEY=eyJraWQiOiI3RG1ZaXlQbnpoUXR6cmRXNmtvWEd5anhaZU9FaitXcHBpck1rcDlvbHFjPSIsImFsZyI6IlJTMjU2In0...
```

## Usage

### With Claude Code

1. Configure the MCP server in Claude Code settings (see installation section)
2. Restart Claude Code
3. Your Bedrock-hosted MCP tools will be available in Claude Code

### Command Line

```bash
# Run directly
opsguide-mcp

# Run with uvx
uvx opsguide-mcp

# Run with environment variable
API_KEY="your-bearer-token" opsguide-mcp
```

## How It Works

1. **Startup**: The proxy server reads your environment variables
2. **Connection**: Establishes HTTP connection to Bedrock AgentCore Runtime
3. **Discovery**: Lists available tools, resources, and prompts from your MCP server
4. **Proxying**: Forwards all MCP requests from Claude Code to Bedrock AgentCore
5. **Response**: Returns results back to Claude Code via stdio

## Troubleshooting

### Common Issues

**Connection Failed**
- Verify your `API_KEY` is correct and not expired
- Check that your Bedrock AgentCore runtime is running
- Ensure you have network access to bedrock-agentcore.us-east-1.amazonaws.com

**No Tools Available**
- Check that your MCP server is properly deployed in Bedrock AgentCore
- Verify the runtime is in "DEFAULT" qualifier state
- Check logs for connection errors

**Authentication Errors**
- Ensure your API_KEY (bearer token) is valid and not expired
- Verify the token has permission to invoke the specified runtime

### Debug Mode

Run with debug logging:

```bash
PYTHONPATH=. python -m bedrock_mcp_proxy.server
```

## Development

### Local Development

```bash
# Clone the repository
git clone https://github.com/your-username/opsguide-mcp
cd opsguide-mcp

# Install dependencies
uv sync

# Run locally
uv run opsguide-mcp
```

### Testing

```bash
# Test the connection
python test_connection.py
```

## Security Considerations

- **API Keys**: Store API keys securely using environment variables or secure credential management
- **Network Access**: The proxy requires outbound HTTPS access to AWS Bedrock AgentCore
- **Authentication**: Bearer tokens should be rotated regularly
- **Logging**: Be careful not to log sensitive information

## License

MIT License - see LICENSE file for details.

## Support

For issues related to:
- **This proxy**: Open an issue on this repository
- **Bedrock AgentCore**: Consult AWS documentation
- **Claude Code**: Check Claude Code documentation