Metadata-Version: 2.4
Name: aws-s3-explorer-mcp
Version: 0.1.0
Summary: An open-source Model Context Protocol (MCP) server for Amazon S3.
Author-email: Kyle Bates <kylembates97@gmail.com>
License: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp
Requires-Dist: aiobotocore

# AWS S3 Explorer - MCP Server

An open-source Model Context Protocol (MCP) server built in Python that securely connects AI assistants to Amazon S3. 

This server provides Large Language Models (LLMs) with the ability to list buckets, inspect dataset structures, and read file schemas directly without requiring massive data downloads. It is engineered for ML infrastructure pipelines, featuring fully asynchronous I/O and defensive error handling.

## Features

* **Asynchronous I/O:** Utilizes `aiobotocore` for non-blocking concurrent requests, ensuring the server doesn't fall over under heavy LLM workloads.
* **Defensive Error Handling:** Catch-and-return patterns for AWS exceptions (including missing credentials) that allow AI agents to cleanly self-correct.
* **Strict Typing:** Heavily typed Python interfaces using the `FastMCP` wrapper to automatically generate robust JSON schemas for the client.
* **Mocked CI/CD:** Fully automated test suites using `pytest` and `pytest-asyncio`, integrated into a GitHub Action pipeline.

## Tools Exposed to the LLM

This server exposes three specific primitives:

1. `list_s3_buckets()`: Lists all S3 buckets accessible by the current AWS credentials.
2. `list_s3_objects(bucket_name, prefix, max_keys)`: Lists objects inside a specific bucket. Limits results by default to prevent LLM context window overflow.
3. `read_s3_file_head(bucket_name, object_key, byte_limit)`: Reads the first few kilobytes of an S3 object to inspect its contents (e.g., CSV headers, JSON structures) without downloading the entire file.

## Installation and Setup

### Prerequisites
* Python 3.11+
* AWS credentials configured locally (e.g., `aws configure` or `~/.aws/credentials`)

### Option 1: User Setup
Install the package with pip directly from GitHub:
```bash
pip install git+https://github.com/kbates97/AWS_S3_Explorer_MCP.git
```
You can start the MCP server by running:
```bash
aws-s3-mcp
```

### Option 2: Developer Setup
Clone the repository and install the required dependencies:

```bash
git clone https://github.com/kbates97/AWS_S3_Explorer_MCP.git
cd AWS_S3_Explorer_MCP
python -m venv venv

# Windows: .\venv\Scripts\activate
# Mac/Linux: source venv/bin/activate

pip install -r requirements.txt
```
