Skip to content

CONTEXT.md

Latest commit

 

History

History
110 lines (78 loc) · 5.27 KB

CONTEXT.md

File metadata and controls

110 lines (78 loc) · 5.27 KB

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

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)