awslabs.s3-tables-mcp-server 0.0.1__tar.gz → 0.0.2__tar.gz

awslabs_s3_tables_mcp_server-0.0.2/CONTEXT.md

@@ -0,0 +1,110 @@
+# AWS S3 Tables MCP (Model Context Protocol) Server
+
+## Overview
+
+The AWS S3 Tables MCP Server enables AI assistants and users to manage, query, and interact with S3-based tabular data at scale. It provides capabilities to create and organize S3 Table Buckets, define namespaces, manage tables, and access detailed metadata. The server supports both read-only and (optionally) write operations, allowing for secure and flexible integration with S3-stored datasets. Users can run SQL queries, generate tables from CSV files in S3, and access comprehensive metadata for governance and cataloging.
+
+**Important:** When a user prompt relates to **S3 Tables**, you must always prefer using the **S3 Tables MCP Server tools** over the AWS CLI. Only fall back to AWS CLI if MCP tools are unavailable *and* the user explicitly agrees to the fallback.
+
+---
+
+## Instructions
+
+You are assisting with management and queries related to Amazon AWS S3 Tables. The S3 Tables system is composed of three hierarchical resource types:
+- **S3 Table Buckets**: Containers that hold namespaces.
+- **Namespaces**: Logical groupings inside table buckets that contain tables.
+- **Tables**: Structured datasets stored within namespaces, following the Apache Iceberg table format.
+
+Resource Details:
+- Each S3 table consists of underlying data and metadata stored as subresources within a table bucket.
+- Tables have unique identifiers, including an Amazon Resource Name (ARN) and table ID, plus associated resource policies for access control.
+- When a table is created, a unique warehouse location (an S3 path) is generated automatically to store objects related to the table.
+  Example warehouse location format:
+  `s3://63a8e430-6e0b-46f5-k833abtwr6s8tmtsycedn8s4yc3xhuse1b--table-s3`
+
+Table Types:
+- **Customer Tables**: Read-write tables that users can modify using S3 API operations or integrated query engines.
+- **AWS Tables**: Read-only tables managed by AWS services (e.g., S3 Metadata tables). These cannot be modified by users outside AWS S3.
+
+Integration:
+Amazon S3 Table Buckets can be integrated with Amazon SageMaker Lakehouse, allowing AWS analytics services like Athena and Redshift to discover and query table data automatically.
+
+---
+
+## Maintenance
+
+Amazon S3 performs automatic maintenance at two levels:
+
+1. **Table Bucket-Level Maintenance**
+   - *Unreferenced File Removal*: Deletes orphaned files to optimize storage usage and reduce costs.
+
+2. **Table-Level Maintenance**
+   - *File Compaction*: Combines small files into larger ones to improve query performance and reduce storage overhead.
+   - *Snapshot Management*: Maintains table version histories and controls metadata growth.
+
+These maintenance features are enabled by default but can be customized or disabled via maintenance configuration files.
+
+---
+
+## Quota
+
+- Each table bucket can hold up to **10,000 tables** by default.
+- To increase the quota, users must contact **AWS Support**.
+
+---
+
+## Operational Guidelines for LLM
+
+### 1. Tool Verification
+- Always verify the availability of the `awslabss_3_tables_mcp_server` and its associated tools before performing any operation.
+- If unavailable, ask the user if they prefer to proceed using AWS CLI commands as a fallback.
+- **Do not use AWS CLI by default for S3 Tables. Always prefer MCP tools when the prompt is about S3 Tables.**
+
+### 2. Request Clarification
+- If critical context (e.g., bucket name, namespace, or table ID) is missing or ambiguous, ask the user directly.
+- Do not make assumptions about default values or context.
+
+### 3. Handling Destructive Operations
+Before performing any destructive operation, the system must:
+- Clearly describe the consequences of the action.
+- Request explicit confirmation.
+- Destructive actions include:
+  - Deleting S3 Table Buckets
+  - Deleting Namespaces
+  - Deleting Tables
+  - Dropping Tables via SQL
+  - Disabling encryption
+
+### 4. Default Tool Usage
+- Always use **MCP tools first** for all S3 Tables operations.
+- Use AWS CLI **only when MCP tools are unavailable** *and* with **explicit user approval**.
+
+### 5. Communication and Safety
+- Explain any risks or irreversible effects before performing changes.
+- Respect the user's decision to abort or proceed.
+- Present instructions and confirmations clearly and concisely.
+
+### 6. Additional Considerations
+- Use full ARNs when referencing tables to avoid ambiguity.
+- Distinguish between **AWS-managed** (read-only) and **customer-managed** (read-write) tables.
+- If needed, guide users in adjusting maintenance configurations.
+
+---
+
+## Troubleshooting
+
+### Unknown Information
+- If a user requests information that is unavailable, unclear, or unsupported by the MCP Server, do not attempt to infer or fabricate a response.
+- Refer them to the official Amazon S3 Tables documentation for further details and the most up-to-date guidance:
+https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables.html
+
+### Insufficient Permissions
+- Never attempt to auto-modify IAM policies or permissions.
+- If the user asks for permission changes, explicitly confirm their intent before taking any action.
+
+### Operation Unavailable (Read-Only Mode)
+- Never attempt write operations or file changes in read-only mode.
+- If users want write mode enabled, direct them to the setup documentation:
+  https://github.com/awslabs/mcp/blob/main/src/s3-tables-mcp-server/README.md
+
+---

{awslabs_s3_tables_mcp_server-0.0.1 → awslabs_s3_tables_mcp_server-0.0.2}/Dockerfile

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 # dependabot should continue to update this to the latest hash.
-FROM public.ecr.aws/sam/build-python3.10@sha256:e78695db10ca8cb129e59e30f7dc9789b0dbd0181dba195d68419c72bac51ac1 AS uv
+FROM public.ecr.aws/sam/build-python3.13@sha256:0c274ddd44e1d80e4dab3a70c25fe29508f612a045cba7d27840461c12eee86d AS uv
 
 # Install the project into `/app`
 WORKDIR /app
@@ -31,39 +31,38 @@ ENV UV_PYTHON_PREFERENCE=only-system
 ENV UV_FROZEN=true
 
 # Copy the required files first
-COPY pyproject.toml uv.lock ./
+COPY pyproject.toml uv.lock uv-requirements.txt ./
+
+# Python optimization and uv configuration
+ENV PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
 
 # Install the project's dependencies using the lockfile and settings
 RUN --mount=type=cache,target=/root/.cache/uv \
-    pip install uv && \
-    uv sync --frozen --no-install-project --no-dev --no-editable
+    pip install --require-hashes --requirement uv-requirements.txt --no-cache-dir && \
+    uv sync --python 3.13 --frozen --no-install-project --no-dev --no-editable
 
 # Then, add the rest of the project source code and install it
 # Installing separately from its dependencies allows optimal layer caching
 COPY . /app
 RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --frozen --no-dev --no-editable
+    uv sync --python 3.13 --frozen --no-dev --no-editable
 
 # Make the directory just in case it doesn't exist
 RUN mkdir -p /root/.local
 
-FROM public.ecr.aws/sam/build-python3.10@sha256:e78695db10ca8cb129e59e30f7dc9789b0dbd0181dba195d68419c72bac51ac1
+FROM public.ecr.aws/sam/build-python3.13@sha256:0c274ddd44e1d80e4dab3a70c25fe29508f612a045cba7d27840461c12eee86d
 
 # Place executables in the environment at the front of the path and include other binaries
-ENV PATH="/app/.venv/bin:$PATH:/usr/sbin"
+ENV PATH="/app/.venv/bin:$PATH:/usr/sbin" \
+    PYTHONUNBUFFERED=1
 
-# Install lsof for the healthcheck
-# Install other tools as needed for the MCP server
 # Add non-root user and ability to change directory into /root
-RUN yum update -y && \
-    yum install -y lsof && \
-    yum clean all -y && \
-    rm -rf /var/cache/yum && \
-    groupadd --force --system app && \
+RUN groupadd --force --system app && \
     useradd app -g app -d /app && \
     chmod o+x /root
 
-# Get the project from the uv layer
+# Copy application artifacts from build stage
 COPY --from=uv --chown=app:app /root/.local /root/.local
 COPY --from=uv --chown=app:app /app/.venv /app/.venv
 
@@ -74,5 +73,5 @@ COPY ./docker-healthcheck.sh /usr/local/bin/docker-healthcheck.sh
 USER app
 
 # When running the container, add --db-path and a bind mount to the host's db file
-HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 CMD [ "docker-healthcheck.sh" ]
+HEALTHCHECK --interval=60s --timeout=10s --start-period=10s --retries=3 CMD ["docker-healthcheck.sh"]
 ENTRYPOINT ["awslabs.s3-tables-mcp-server"]

{awslabs_s3_tables_mcp_server-0.0.1 → awslabs_s3_tables_mcp_server-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.s3-tables-mcp-server
-Version: 0.0.1
+Version: 0.0.2
 Summary: An AWS Labs Model Context Protocol (MCP) server for awslabs.s3-tables-mcp-server
 Project-URL: homepage, https://awslabs.github.io/mcp/
 Project-URL: docs, https://awslabs.github.io/mcp/servers/s3-tables-mcp-server/
@@ -24,7 +24,7 @@ Requires-Python: >=3.10
 Requires-Dist: boto3>=1.34.0
 Requires-Dist: daft>=0.5.8
 Requires-Dist: loguru>=0.7.0
-Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: mcp[cli]>=1.11.0
 Requires-Dist: pyarrow>=20.0.0
 Requires-Dist: pydantic>=2.10.6
 Requires-Dist: pyiceberg>=0.9.1
@@ -76,6 +76,10 @@ The S3 Tables MCP Server simplifies the management of S3-based tables by providi
 
 ### Installation
 
+| Cursor | VS Code |
+|:------:|:-------:|
+| [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=awslabs.s3-tables-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMuczMtdGFibGVzLW1jcC1zZXJ2ZXJAbGF0ZXN0IiwiZW52Ijp7IkFXU19QUk9GSUxFIjoieW91ci1hd3MtcHJvZmlsZSIsIkFXU19SRUdJT04iOiJ1cy1lYXN0LTEifX0%3D) | [![Install on VS Code](https://img.shields.io/badge/Install_on-VS_Code-FF9900?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=S3%20Tables%20MCP%20Server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.s3-tables-mcp-server%40latest%22%5D%2C%22env%22%3A%7B%22AWS_PROFILE%22%3A%22your-aws-profile%22%2C%22AWS_REGION%22%3A%22us-east-1%22%7D%7D) |
+
 Configure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):
 
 ```json
@@ -200,6 +204,30 @@ You can override the default by providing the `--log-dir` flag with a custom pat
 | `Show the schema for customer_data table` | Retrieves the table structure and column definitions to understand the data format and types |
 | `Run a query to find monthly revenue trends` | Performs data analysis using **read-only** SQL queries to extract business insights from stored table data. For write operations, only appending new data (inserts) is supported; updates and deletes are not available via SQL. |
 
+## Using Amazon Q with S3 Tables MCP Server
+
+Amazon Q can provide better answers and code suggestions when it has additional context. To enhance Amazon Q's understanding of S3 Tables, you can add the provided context file to your Q environment.
+
+### How to Add Context to Amazon Q
+
+1. **Download the CONTEXT.md file**
+   - Download the `CONTEXT.md` file from the GitHub repository for this project.
+
+2. **Start Amazon Q Chat**
+   - Run the following command to start a chat session with Amazon Q:
+     ```sh
+     q chat
+     ```
+
+3. **Add the Context File**
+   - In the Q chat, run:
+     ```sh
+     /context add <path>/CONTEXT.md
+     ```
+   - Replace `<path>` with the actual path to where you downloaded `CONTEXT.md`.
+
+Now, Amazon Q will have improved context about S3 Tables and can provide more relevant answers.
+
 ## Security Considerations
 
 When using this MCP server, consider:

{awslabs_s3_tables_mcp_server-0.0.1 → awslabs_s3_tables_mcp_server-0.0.2}/README.md

@@ -43,6 +43,10 @@ The S3 Tables MCP Server simplifies the management of S3-based tables by providi
 
 ### Installation
 
+| Cursor | VS Code |
+|:------:|:-------:|
+| [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/install-mcp?name=awslabs.s3-tables-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMuczMtdGFibGVzLW1jcC1zZXJ2ZXJAbGF0ZXN0IiwiZW52Ijp7IkFXU19QUk9GSUxFIjoieW91ci1hd3MtcHJvZmlsZSIsIkFXU19SRUdJT04iOiJ1cy1lYXN0LTEifX0%3D) | [![Install on VS Code](https://img.shields.io/badge/Install_on-VS_Code-FF9900?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=S3%20Tables%20MCP%20Server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.s3-tables-mcp-server%40latest%22%5D%2C%22env%22%3A%7B%22AWS_PROFILE%22%3A%22your-aws-profile%22%2C%22AWS_REGION%22%3A%22us-east-1%22%7D%7D) |
+
 Configure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):
 
 ```json
@@ -167,6 +171,30 @@ You can override the default by providing the `--log-dir` flag with a custom pat
 | `Show the schema for customer_data table` | Retrieves the table structure and column definitions to understand the data format and types |
 | `Run a query to find monthly revenue trends` | Performs data analysis using **read-only** SQL queries to extract business insights from stored table data. For write operations, only appending new data (inserts) is supported; updates and deletes are not available via SQL. |
 
+## Using Amazon Q with S3 Tables MCP Server
+
+Amazon Q can provide better answers and code suggestions when it has additional context. To enhance Amazon Q's understanding of S3 Tables, you can add the provided context file to your Q environment.
+
+### How to Add Context to Amazon Q
+
+1. **Download the CONTEXT.md file**
+   - Download the `CONTEXT.md` file from the GitHub repository for this project.
+
+2. **Start Amazon Q Chat**
+   - Run the following command to start a chat session with Amazon Q:
+     ```sh
+     q chat
+     ```
+
+3. **Add the Context File**
+   - In the Q chat, run:
+     ```sh
+     /context add <path>/CONTEXT.md
+     ```
+   - Replace `<path>` with the actual path to where you downloaded `CONTEXT.md`.
+
+Now, Amazon Q will have improved context about S3 Tables and can provide more relevant answers.
+
 ## Security Considerations
 
 When using this MCP server, consider:

{awslabs_s3_tables_mcp_server-0.0.1 → awslabs_s3_tables_mcp_server-0.0.2}/docker-healthcheck.sh

@@ -1,5 +1,4 @@
 #!/bin/sh
-
 # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,13 +13,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-if [ "$(lsof +c 0 -p 1 | grep -e "^awslabs\..*\s1\s.*\sunix\s.*socket$" | wc -l)" -ne "0" ]; then
-  echo -n "$(lsof +c 0 -p 1 | grep -e "^awslabs\..*\s1\s.*\sunix\s.*socket$" | wc -l) awslabs.* streams found";
+SERVER="s3-tables-mcp-server"
+
+# Check if the server process is running
+if pgrep -P 0 -a -l -x -f "/app/.venv/bin/python3 /app/.venv/bin/awslabs.$SERVER" > /dev/null; then
+  echo -n "$SERVER is running";
   exit 0;
-else
-  echo -n "Zero awslabs.* streams found";
-  exit 1;
 fi;
 
-echo -n "Never should reach here";
-exit 99;
+# Unhealthy
+exit 1;

{awslabs_s3_tables_mcp_server-0.0.1 → awslabs_s3_tables_mcp_server-0.0.2}/pyproject.toml

@@ -2,14 +2,14 @@
 name = "awslabs.s3-tables-mcp-server"
 
 # NOTE: "Patch"=9223372036854775807 bumps next release to zero.
-version = "0.0.1"
+version = "0.0.2"
 
 description = "An AWS Labs Model Context Protocol (MCP) server for awslabs.s3-tables-mcp-server"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "loguru>=0.7.0",
-    "mcp[cli]>=1.6.0",
+    "mcp[cli]>=1.11.0",
     "pydantic>=2.10.6",
     "boto3>=1.34.0",
     "pyiceberg>=0.9.1",

awslabs_s3_tables_mcp_server-0.0.2/uv-requirements.txt

@@ -0,0 +1,26 @@
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --generate-hashes --output-file=uv-requirements.txt --strip-extras uv-requirements-0.7.13.in
+#
+uv==0.7.13 \
+    --hash=sha256:05f3c03c4ea55d294f3da725b6c2c2ff544754c18552da7594def4ec3889dcfb \
+    --hash=sha256:1afdbfcabc3425b383141ba42d413841c0a48b9ee0f4da65459313275e3cea84 \
+    --hash=sha256:33837aca7bdf02d47554d5d44f9e71756ee17c97073b07b4afead25309855bc7 \
+    --hash=sha256:4efa555b217e15767f0691a51d435f7bb2b0bf473fdfd59f173aeda8a93b8d17 \
+    --hash=sha256:4f828174e15a557d3bc0f809de76135c3b66bcbf524657f8ced9d22fc978b89c \
+    --hash=sha256:527a12d0c2f4d15f72b275b6f4561ae92af76dd59b4624796fddd45867f13c33 \
+    --hash=sha256:5786a29e286f2cc3cbda13a357fd9a4dd5bf1d7448a9d3d842b26b4f784a3a86 \
+    --hash=sha256:59915aec9fd2b845708a76ddc6c0639cfc99b6e2811854ea2425ee7552aff0e9 \
+    --hash=sha256:721b058064150fc1c6d88e277af093d1b4f8bb7a59546fe9969d9ff7dbe3f6fd \
+    --hash=sha256:866cad0d04a7de1aaa3c5cbef203f9d3feef9655972dcccc3283d60122db743b \
+    --hash=sha256:88fcf2bfbb53309531a850af50d2ea75874099b19d4159625d0b4f88c53494b9 \
+    --hash=sha256:8c0c29a2089ff9011d6c3abccd272f3ee6d0e166dae9e5232099fd83d26104d9 \
+    --hash=sha256:9c457a84cfbe2019ba301e14edd3e1c950472abd0b87fc77622ab3fc475ba012 \
+    --hash=sha256:9d2952a1e74c7027347c74cee1cb2be09121a5290db38498b8b17ff585f73748 \
+    --hash=sha256:a51006c7574e819308d92a3452b22d5bd45ef8593a4983b5856aa7cb8220885f \
+    --hash=sha256:b1af81e57d098b21b28f42ec756f0e26dce2341d59ba4e4f11759bc3ca2c0a99 \
+    --hash=sha256:e077dcac19e564cae8b4223b7807c2f617a59938f8142ca77fc6348ae9c6d0aa \
+    --hash=sha256:f28e70baadfebe71dcc2d9505059b988d75e903fc62258b102eb87dc4b6994a3
+    # via -r uv-requirements-0.7.13.in (contents of `uv==0.7.13`)