awslabs.postgres-mcp-server 1.0.3__tar.gz → 1.0.4__tar.gz

{awslabs_postgres_mcp_server-1.0.3 → awslabs_postgres_mcp_server-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: awslabs.postgres-mcp-server
-Version: 1.0.3
+Version: 1.0.4
 Summary: An AWS Labs Model Context Protocol (MCP) server for postgres
 Project-URL: homepage, https://awslabs.github.io/mcp/
 Project-URL: docs, https://awslabs.github.io/mcp/servers/postgres-mcp-server/
@@ -25,6 +25,7 @@ Requires-Dist: boto3>=1.38.5
 Requires-Dist: botocore>=1.38.5
 Requires-Dist: loguru>=0.7.0
 Requires-Dist: mcp[cli]>=1.11.0
+Requires-Dist: psycopg[pool]>=3.1.12
 Requires-Dist: pydantic>=2.10.6
 Description-Content-Type: text/markdown
 
@@ -58,6 +59,8 @@ An AWS Labs Model Context Protocol (MCP) server for Aurora Postgres
 
 Configure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):
 
+### Option 1: Using RDS Data API Connection (for Aurora Postgres)
+
 ```json
 {
   "mcpServers": {
@@ -83,6 +86,35 @@ Configure the MCP server in your MCP client configuration (e.g., for Amazon Q De
 }
 ```
 
+### Option 2: Using Direct PostgreSQL(psycopg) Connection (for Aurora Postgres and RDS Postgres)
+
+```json
+{
+  "mcpServers": {
+    "awslabs.postgres-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "awslabs.postgres-mcp-server@latest",
+        "--hostname", "[your data]",
+        "--secret_arn", "[your data]",
+        "--database", "[your data]",
+        "--region", "[your data]",
+        "--readonly", "True"
+      ],
+      "env": {
+        "AWS_PROFILE": "your-aws-profile",
+        "AWS_REGION": "us-east-1",
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+Note: The `--port` parameter is optional and defaults to 5432 (the standard PostgreSQL port). You only need to specify it if your PostgreSQL instance uses a non-standard port.
+
 ### Build and install docker image locally on the same host of your LLM client
 
 1. 'git clone https://github.com/awslabs/mcp.git'
@@ -91,6 +123,8 @@ Configure the MCP server in your MCP client configuration (e.g., for Amazon Q De
 
 ### Add or update your LLM client's config with following:
 
+#### Option 1: Using RDS Data API Connection (for Aurora Postgres)
+
 ```json
 {
   "mcpServers": {
@@ -115,8 +149,46 @@ Configure the MCP server in your MCP client configuration (e.g., for Amazon Q De
 }
 ```
 
+#### Option 2: Using Direct PostgreSQL (psycopg) Connection (for Aurora Postgres and RDS Postgres)
+
+```
+{
+  "mcpServers": {
+    "awslabs.postgres-mcp-server": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e", "AWS_ACCESS_KEY_ID=[your data]",
+        "-e", "AWS_SECRET_ACCESS_KEY=[your data]",
+        "-e", "AWS_REGION=[your data]",
+        "awslabs/postgres-mcp-server:latest",
+        "--hostname", "[your data]",
+        "--secret_arn", "[your data]",
+        "--database", "[your data]",
+        "--region", "[your data]",
+        "--readonly", "True"
+      ]
+    }
+  }
+}
+```
+
+Note: The `--port` parameter is optional and defaults to 5432 (the standard PostgreSQL port). You only need to specify it if your PostgreSQL instance uses a non-standard port.
+
 NOTE: By default, only read-only queries are allowed and it is controlled by --readonly parameter above. Set it to False if you also want to allow writable DML or DDL.
 
+## Connection Methods
+
+This MCP server supports two connection methods:
+
+1. **RDS Data API Connection** (using `--resource_arn`): Uses the AWS RDS Data API to connect to Aurora PostgreSQL. This method requires that your Aurora cluster has the Data API enabled.
+
+2. **Direct PostgreSQL Connection** (using `--hostname`): Uses psycopg to connect directly to any PostgreSQL database, including Aurora PostgreSQL, RDS PostgreSQL, or self-hosted PostgreSQL instances. This method provides better performance for frequent queries but requires direct network access to the database.
+
+Choose the connection method that best fits your environment and requirements.
+
 ### AWS Authentication
 
 The MCP server uses the AWS profile specified in the `AWS_PROFILE` environment variable. If not provided, it defaults to the "default" profile in your AWS configuration file.

{awslabs_postgres_mcp_server-1.0.3 → awslabs_postgres_mcp_server-1.0.4}/README.md

@@ -28,6 +28,8 @@ An AWS Labs Model Context Protocol (MCP) server for Aurora Postgres
 
 Configure the MCP server in your MCP client configuration (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):
 
+### Option 1: Using RDS Data API Connection (for Aurora Postgres)
+
 ```json
 {
   "mcpServers": {
@@ -53,6 +55,35 @@ Configure the MCP server in your MCP client configuration (e.g., for Amazon Q De
 }
 ```
 
+### Option 2: Using Direct PostgreSQL(psycopg) Connection (for Aurora Postgres and RDS Postgres)
+
+```json
+{
+  "mcpServers": {
+    "awslabs.postgres-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "awslabs.postgres-mcp-server@latest",
+        "--hostname", "[your data]",
+        "--secret_arn", "[your data]",
+        "--database", "[your data]",
+        "--region", "[your data]",
+        "--readonly", "True"
+      ],
+      "env": {
+        "AWS_PROFILE": "your-aws-profile",
+        "AWS_REGION": "us-east-1",
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+Note: The `--port` parameter is optional and defaults to 5432 (the standard PostgreSQL port). You only need to specify it if your PostgreSQL instance uses a non-standard port.
+
 ### Build and install docker image locally on the same host of your LLM client
 
 1. 'git clone https://github.com/awslabs/mcp.git'
@@ -61,6 +92,8 @@ Configure the MCP server in your MCP client configuration (e.g., for Amazon Q De
 
 ### Add or update your LLM client's config with following:
 
+#### Option 1: Using RDS Data API Connection (for Aurora Postgres)
+
 ```json
 {
   "mcpServers": {
@@ -85,8 +118,46 @@ Configure the MCP server in your MCP client configuration (e.g., for Amazon Q De
 }
 ```
 
+#### Option 2: Using Direct PostgreSQL (psycopg) Connection (for Aurora Postgres and RDS Postgres)
+
+```
+{
+  "mcpServers": {
+    "awslabs.postgres-mcp-server": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e", "AWS_ACCESS_KEY_ID=[your data]",
+        "-e", "AWS_SECRET_ACCESS_KEY=[your data]",
+        "-e", "AWS_REGION=[your data]",
+        "awslabs/postgres-mcp-server:latest",
+        "--hostname", "[your data]",
+        "--secret_arn", "[your data]",
+        "--database", "[your data]",
+        "--region", "[your data]",
+        "--readonly", "True"
+      ]
+    }
+  }
+}
+```
+
+Note: The `--port` parameter is optional and defaults to 5432 (the standard PostgreSQL port). You only need to specify it if your PostgreSQL instance uses a non-standard port.
+
 NOTE: By default, only read-only queries are allowed and it is controlled by --readonly parameter above. Set it to False if you also want to allow writable DML or DDL.
 
+## Connection Methods
+
+This MCP server supports two connection methods:
+
+1. **RDS Data API Connection** (using `--resource_arn`): Uses the AWS RDS Data API to connect to Aurora PostgreSQL. This method requires that your Aurora cluster has the Data API enabled.
+
+2. **Direct PostgreSQL Connection** (using `--hostname`): Uses psycopg to connect directly to any PostgreSQL database, including Aurora PostgreSQL, RDS PostgreSQL, or self-hosted PostgreSQL instances. This method provides better performance for frequent queries but requires direct network access to the database.
+
+Choose the connection method that best fits your environment and requirements.
+
 ### AWS Authentication
 
 The MCP server uses the AWS profile specified in the `AWS_PROFILE` environment variable. If not provided, it defaults to the "default" profile in your AWS configuration file.

{awslabs_postgres_mcp_server-1.0.3 → awslabs_postgres_mcp_server-1.0.4}/awslabs/postgres_mcp_server/__init__.py

@@ -14,4 +14,4 @@
 
 """awslabs.postgres-mcp-server"""
 
-__version__ = '0.0.4'
+__version__ = '1.0.4'

awslabs_postgres_mcp_server-1.0.4/awslabs/postgres_mcp_server/connection/__init__.py

@@ -0,0 +1,18 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""aws.postgres-mcp-server.connection"""
+
+from awslabs.postgres_mcp_server.connection.db_connection_singleton import DBConnectionSingleton
+from awslabs.postgres_mcp_server.connection.abstract_db_connection import AbstractDBConnection

awslabs_postgres_mcp_server-1.0.4/awslabs/postgres_mcp_server/connection/abstract_db_connection.py

@@ -0,0 +1,68 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Abstract database connection interface for postgres MCP Server."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional
+
+
+class AbstractDBConnection(ABC):
+    """Abstract base class for database connections."""
+
+    def __init__(self, readonly: bool):
+        """Initialize the database connection.
+
+        Args:
+            readonly: Whether the connection should be read-only
+        """
+        self._readonly = readonly
+
+    @property
+    def readonly_query(self) -> bool:
+        """Get whether this connection is read-only.
+
+        Returns:
+            bool: True if the connection is read-only, False otherwise
+        """
+        return self._readonly
+
+    @abstractmethod
+    async def execute_query(
+        self, sql: str, parameters: Optional[List[Dict[str, Any]]] = None
+    ) -> Dict[str, Any]:
+        """Execute a SQL query.
+
+        Args:
+            sql: The SQL query to execute
+            parameters: Optional parameters for the query
+
+        Returns:
+            Dict containing query results with column metadata and records
+        """
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Close the database connection."""
+        pass
+
+    @abstractmethod
+    async def check_connection_health(self) -> bool:
+        """Check if the database connection is healthy.
+
+        Returns:
+            bool: True if the connection is healthy, False otherwise
+        """
+        pass

awslabs_postgres_mcp_server-1.0.4/awslabs/postgres_mcp_server/connection/db_connection_singleton.py

@@ -0,0 +1,117 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Database connection singleton for postgres MCP Server."""
+
+import asyncio
+from awslabs.postgres_mcp_server.connection.rds_api_connection import RDSDataAPIConnection
+from loguru import logger
+
+
+class DBConnectionSingleton:
+    """Manages a single RDS Data API connection instance across the application."""
+
+    _instance = None
+
+    def __init__(
+        self,
+        resource_arn: str,
+        secret_arn: str,
+        database: str,
+        region: str,
+        readonly: bool = True,
+        is_test: bool = False,
+    ):
+        """Initialize a new DB connection singleton for RDS Data API.
+
+        Args:
+            resource_arn: The ARN of the RDS cluster
+            secret_arn: The ARN of the secret containing credentials
+            database: The name of the database to connect to
+            region: The AWS region where the RDS instance is located
+            readonly: Whether the connection should be read-only (default: True)
+            is_test: Whether this is a test connection (default: False)
+        """
+        if not all([resource_arn, secret_arn, database, region]):
+            raise ValueError(
+                'Missing required connection parameters for RDS Data API. '
+                'Please provide resource_arn, secret_arn, database, and region.'
+            )
+
+        self._db_connection = RDSDataAPIConnection(
+            cluster_arn=resource_arn,
+            secret_arn=secret_arn,
+            database=database,
+            region=region,
+            readonly=readonly,
+            is_test=is_test,
+        )
+
+    @classmethod
+    def initialize(
+        cls,
+        resource_arn: str,
+        secret_arn: str,
+        database: str,
+        region: str,
+        readonly: bool = True,
+        is_test: bool = False,
+    ):
+        """Initialize the singleton instance if it doesn't exist.
+
+        Args:
+            resource_arn: The ARN of the RDS cluster
+            secret_arn: The ARN of the secret containing credentials
+            database: The name of the database to connect to
+            region: The AWS region where the RDS instance is located
+            readonly: Whether the connection should be read-only (default: True)
+            is_test: Whether this is a test connection (default: False)
+        """
+        if cls._instance is None:
+            cls._instance = cls(
+                resource_arn=resource_arn,
+                secret_arn=secret_arn,
+                database=database,
+                region=region,
+                readonly=readonly,
+                is_test=is_test,
+            )
+
+    @classmethod
+    def get(cls):
+        """Get the singleton instance."""
+        if cls._instance is None:
+            raise RuntimeError('DBConnectionSingleton is not initialized.')
+        return cls._instance
+
+    @property
+    def db_connection(self):
+        """Get the database connection."""
+        return self._db_connection
+
+    @classmethod
+    def cleanup(cls):
+        """Clean up resources when shutting down."""
+        if cls._instance and cls._instance._db_connection:
+            # Handle calling async close method from sync context
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    # If we're in an async context, create a task
+                    asyncio.create_task(cls._instance._db_connection.close())
+                else:
+                    # If we're in a sync context, run the coroutine to completion
+                    loop.run_until_complete(cls._instance._db_connection.close())
+            except Exception as e:
+                logger.error(f'Error during connection cleanup: {str(e)}')