postgres_ai 0.1.0__tar.gz

postgres_ai-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: postgres_ai
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: databases>=0.9.0
+Requires-Dist: fastapi>=0.131.0
+Requires-Dist: fastmcp>=3.0.2
+Requires-Dist: pandas>=3.0.1
+Requires-Dist: polars>=1.38.1
+Requires-Dist: typer>=0.24.1
+Requires-Dist: uvicorn>=0.41.0
+
+# pg_ai  <img src="https://upload.wikimedia.org/wikipedia/commons/a/ad/Logo_PostgreSQL.png" alt="PostgreSQL" width="100">
+[![GitHub license](https://img.shields.io/github/license/saiprasaad2002/pg_ai)](https://github.com/saiprasaad2002/pg_ai/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/saiprasaad2002/pg_ai)](https://github.com/saiprasaad2002/pg_ai/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/saiprasaad2002/pg_ai)](https://github.com/saiprasaad2002/pg_ai/issues)
+
+## Overview
+
+pg_ai is an open-source MCP (Model Context Protocol) server tailored for PostgreSQL databases. It bridges LLMs with your Postgres data by allowing users to define custom "skills" — encapsulated business logic in markdown files — that guide intelligent database interactions. By implementing the SKILL Graph technique, pg_ai enables dynamic, on-demand context expansion, preventing LLM overload while scaling complexity through interconnected skills.
+
+Inspired by Anthropic's Claude Skills and the SKILL Graph concept (as discussed in [this X thread](https://x.com/arscontexta/status/2023957499183829467?s=20)), pg_ai turns your database into a contextual powerhouse for AI agents.
+
+## Key Features
+
+- **Postgres Integration**: Asynchronous connections for efficient querying.
+- **Skill Management**: Load custom skills from markdown files (SKILL.md) in a progressive, token-efficient manner.
+- **Dynamic Context Growth**: Use SKILL Graph to link and load skills on-demand, building a network of reusable logic.
+- **MCP Compliance**: Exposes tools for LLMs to read business logic, load specific skills, and execute SQL queries.
+- **Logging and Configurability**: Environment-based setup with dedicated logging.
+
+## Architecture
+
+pg_ai is built on FastMCP (a FastAPI-based MCP implementation) and uses asyncpg for PostgreSQL interactions. The core components include:
+
+1. **Server Setup (app.py)**: Initializes the MCP server with a lifespan hook for database connection management.
+2. **PgMCP Class (src/mcp_server/server.py)**: Wraps FastMCP to configure the server with tools and lifespan.
+3. **Postgres Connector (src/connectors/pg_connector.py)**: Handles async connect/disconnect to Postgres using the `databases` library.
+4. **Environment Loader (src/loaders/env_loader.py)**: Loads settings from `.env` using Pydantic for validation.
+5. **Logger (src/logger/mcp_logger.py)**: Configures file-based logging for server events.
+6. **Tools (src/mcp_tools/tools.py)**: Defines MCP tools:
+   - `read_business_logic()`: Loads default business logic from `pg_skills/business-logic/SKILL.md`.
+   - `load_skill(skill_name)`: Dynamically loads a specific skill's instructions from `pg_skills/<skill_name>/SKILL.md`.
+   - `execute_query(sql_query)`: Executes SQL queries on the connected Postgres DB and returns results as a Polars DataFrame.
+
+The SKILL Graph is realized through interconnected skills: Each SKILL.md can reference other skills, allowing the LLM to traverse the graph by calling `load_skill` as needed. This grows context incrementally, aligning with MCP's goal of efficient external system integration.
+
+## Installation
+
+### Prerequisites
+- Python >= 3.12
+- PostgreSQL database
+- Git
+
+### Steps
+1. Clone the repository:
+   ```
+   git clone https://github.com/saiprasaad2002/pg_ai.git
+   cd pg_ai
+   ```
+2. Create virtual environment (preferably python 3.12):
+   ```
+   uv venv --python 3.12
+   ```
+   
+3. Install dependencies:
+   ```
+   uv sync
+   ```
+
+4. Copy and configure the environment file:
+   ```
+   cp .env.example .env
+   ```
+   Edit `.env` with your Postgres credentials and MCP server settings:
+   - `DB_USER`, `DB_PASS`, `DB_HOST`, `DB_PORT`, `DB_NAME`: Postgres connection details.
+   - `MCP_SERVER_HOST`, `MCP_SERVER_PORT`, `MCP_SERVER_TRANSPORT`: Server config (e.g., `STREAMABLE-HTTP` for production).
+
+5. Run the server:
+   ```
+   uv run app.py
+   ```
+
+The server will start, connect to your Postgres DB, and expose MCP endpoints.
+
+## Usage
+
+### Adding Skills
+Skills are stored in the `pg_skills/` directory. Each skill is a subfolder containing a `SKILL.md` file.
+
+- **Structure Example**:
+  ```
+  pg_skills/
+  ├── business-logic/
+  │   └── SKILL.md  # Default business logic (e.g., table schemas, query guidelines)
+  └── custom-skill/
+      └── SKILL.md  # Custom skill instructions (YAML frontmatter + Markdown body)
+  ```
+
+- **SKILL.md Format** (Inspired by Claude Skills):
+  - **YAML Frontmatter**: Minimal metadata (name, description) for progressive disclosure.
+  - **Body**: Detailed instructions, examples, or business logic for the LLM.
+  - Example:
+    ```
+    ---
+    name: inventory-check
+    description: Checks inventory levels in the products table. Use when querying stock.
+    ---
+
+    # Inventory Check Skill
+
+    To check inventory:
+    1. Query the `products` table: SELECT * FROM products WHERE id = {id};
+    2. Analyze stock levels.
+    ...
+    ```
+
+Skills can reference others (e.g., "Load the 'reporting' skill for summaries"), forming a graph for dynamic loading.
+
+### Interacting with the Server
+- Connect your LLM (e.g., Claude, ChatGPT) via an MCP client.
+- The LLM can call tools to load skills and execute queries, building context as needed.
+- Logs are saved in `mcp_logs/pg_ai_log.log`.
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feature/new-feature`.
+3. Commit changes: `git commit -m 'Add new feature'`.
+4. Push to the branch: `git push origin feature/new-feature`.
+5. Open a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## References
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro)
+- [Claude Skills Blog](https://www.anthropic.com/news/skills)
+- [SKILL Graph Discussion](https://x.com/arscontexta/status/2023957499183829467?s=20)
+
+For questions, open an issue or contact the maintainer.
+

postgres_ai-0.1.0/README.md

@@ -0,0 +1,132 @@
+# pg_ai  <img src="https://upload.wikimedia.org/wikipedia/commons/a/ad/Logo_PostgreSQL.png" alt="PostgreSQL" width="100">
+[![GitHub license](https://img.shields.io/github/license/saiprasaad2002/pg_ai)](https://github.com/saiprasaad2002/pg_ai/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/saiprasaad2002/pg_ai)](https://github.com/saiprasaad2002/pg_ai/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/saiprasaad2002/pg_ai)](https://github.com/saiprasaad2002/pg_ai/issues)
+
+## Overview
+
+pg_ai is an open-source MCP (Model Context Protocol) server tailored for PostgreSQL databases. It bridges LLMs with your Postgres data by allowing users to define custom "skills" — encapsulated business logic in markdown files — that guide intelligent database interactions. By implementing the SKILL Graph technique, pg_ai enables dynamic, on-demand context expansion, preventing LLM overload while scaling complexity through interconnected skills.
+
+Inspired by Anthropic's Claude Skills and the SKILL Graph concept (as discussed in [this X thread](https://x.com/arscontexta/status/2023957499183829467?s=20)), pg_ai turns your database into a contextual powerhouse for AI agents.
+
+## Key Features
+
+- **Postgres Integration**: Asynchronous connections for efficient querying.
+- **Skill Management**: Load custom skills from markdown files (SKILL.md) in a progressive, token-efficient manner.
+- **Dynamic Context Growth**: Use SKILL Graph to link and load skills on-demand, building a network of reusable logic.
+- **MCP Compliance**: Exposes tools for LLMs to read business logic, load specific skills, and execute SQL queries.
+- **Logging and Configurability**: Environment-based setup with dedicated logging.
+
+## Architecture
+
+pg_ai is built on FastMCP (a FastAPI-based MCP implementation) and uses asyncpg for PostgreSQL interactions. The core components include:
+
+1. **Server Setup (app.py)**: Initializes the MCP server with a lifespan hook for database connection management.
+2. **PgMCP Class (src/mcp_server/server.py)**: Wraps FastMCP to configure the server with tools and lifespan.
+3. **Postgres Connector (src/connectors/pg_connector.py)**: Handles async connect/disconnect to Postgres using the `databases` library.
+4. **Environment Loader (src/loaders/env_loader.py)**: Loads settings from `.env` using Pydantic for validation.
+5. **Logger (src/logger/mcp_logger.py)**: Configures file-based logging for server events.
+6. **Tools (src/mcp_tools/tools.py)**: Defines MCP tools:
+   - `read_business_logic()`: Loads default business logic from `pg_skills/business-logic/SKILL.md`.
+   - `load_skill(skill_name)`: Dynamically loads a specific skill's instructions from `pg_skills/<skill_name>/SKILL.md`.
+   - `execute_query(sql_query)`: Executes SQL queries on the connected Postgres DB and returns results as a Polars DataFrame.
+
+The SKILL Graph is realized through interconnected skills: Each SKILL.md can reference other skills, allowing the LLM to traverse the graph by calling `load_skill` as needed. This grows context incrementally, aligning with MCP's goal of efficient external system integration.
+
+## Installation
+
+### Prerequisites
+- Python >= 3.12
+- PostgreSQL database
+- Git
+
+### Steps
+1. Clone the repository:
+   ```
+   git clone https://github.com/saiprasaad2002/pg_ai.git
+   cd pg_ai
+   ```
+2. Create virtual environment (preferably python 3.12):
+   ```
+   uv venv --python 3.12
+   ```
+   
+3. Install dependencies:
+   ```
+   uv sync
+   ```
+
+4. Copy and configure the environment file:
+   ```
+   cp .env.example .env
+   ```
+   Edit `.env` with your Postgres credentials and MCP server settings:
+   - `DB_USER`, `DB_PASS`, `DB_HOST`, `DB_PORT`, `DB_NAME`: Postgres connection details.
+   - `MCP_SERVER_HOST`, `MCP_SERVER_PORT`, `MCP_SERVER_TRANSPORT`: Server config (e.g., `STREAMABLE-HTTP` for production).
+
+5. Run the server:
+   ```
+   uv run app.py
+   ```
+
+The server will start, connect to your Postgres DB, and expose MCP endpoints.
+
+## Usage
+
+### Adding Skills
+Skills are stored in the `pg_skills/` directory. Each skill is a subfolder containing a `SKILL.md` file.
+
+- **Structure Example**:
+  ```
+  pg_skills/
+  ├── business-logic/
+  │   └── SKILL.md  # Default business logic (e.g., table schemas, query guidelines)
+  └── custom-skill/
+      └── SKILL.md  # Custom skill instructions (YAML frontmatter + Markdown body)
+  ```
+
+- **SKILL.md Format** (Inspired by Claude Skills):
+  - **YAML Frontmatter**: Minimal metadata (name, description) for progressive disclosure.
+  - **Body**: Detailed instructions, examples, or business logic for the LLM.
+  - Example:
+    ```
+    ---
+    name: inventory-check
+    description: Checks inventory levels in the products table. Use when querying stock.
+    ---
+
+    # Inventory Check Skill
+
+    To check inventory:
+    1. Query the `products` table: SELECT * FROM products WHERE id = {id};
+    2. Analyze stock levels.
+    ...
+    ```
+
+Skills can reference others (e.g., "Load the 'reporting' skill for summaries"), forming a graph for dynamic loading.
+
+### Interacting with the Server
+- Connect your LLM (e.g., Claude, ChatGPT) via an MCP client.
+- The LLM can call tools to load skills and execute queries, building context as needed.
+- Logs are saved in `mcp_logs/pg_ai_log.log`.
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feature/new-feature`.
+3. Commit changes: `git commit -m 'Add new feature'`.
+4. Push to the branch: `git push origin feature/new-feature`.
+5. Open a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## References
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro)
+- [Claude Skills Blog](https://www.anthropic.com/news/skills)
+- [SKILL Graph Discussion](https://x.com/arscontexta/status/2023957499183829467?s=20)
+
+For questions, open an issue or contact the maintainer.
+

postgres_ai-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "postgres_ai"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "asyncpg>=0.31.0",
+    "databases>=0.9.0",
+    "fastapi>=0.131.0",
+    "fastmcp>=3.0.2",
+    "pandas>=3.0.1",
+    "polars>=1.38.1",
+    "typer>=0.24.1",
+    "uvicorn>=0.41.0",
+]
+[project.scripts]
+postgres_ai = "postgres_ai.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/postgres_ai"]

postgres_ai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

postgres_ai-0.1.0/src/postgres_ai/cli.py

@@ -0,0 +1,89 @@
+import asyncio
+import typer
+from typing import Optional
+from postgres_ai.loaders.env_loader import get_mcp_settings
+from postgres_ai.mcp_server.server import PgMCP
+from postgres_ai.connectors.pg_connector import PGConnector
+from postgres_ai.logger.mcp_logger import get_mcp_logger
+from fastmcp.server.lifespan import lifespan
+
+
+app = typer.Typer(
+    name="postgres_ai",
+    help="Postgres AI MCP Server — run AI tools directly on your database",
+    add_completion=True,
+    no_args_is_help=True,
+)
+
+@app.command()
+def main(
+    env_file: Optional[str] = typer.Option(".env", "--env-file", "-e", help="Path to .env file"),
+    host: str = typer.Option("0.0.0.0", "--host", help="MCP server host"),
+    port: int = typer.Option(8000, "--port", "-p", help="MCP server port"),
+    transport: str = typer.Option("streamable-http", "--transport"),
+    db_host: Optional[str] = typer.Option(None, "--db-host", envvar="DB_HOST"),
+    db_port: Optional[int] = typer.Option(None, "--db-port", envvar="DB_PORT"),
+    db_user: Optional[str] = typer.Option(None, "--db-user", envvar="DB_USER"),
+    db_name: Optional[str] = typer.Option(None, "--db-name", envvar="DB_NAME"),
+    prompt_password: bool = typer.Option(
+        False, "--prompt-password", help="Interactively ask for DB password (overrides .env)"
+    ),
+):
+    """Start the postgres_ai MCP Server"""
+    print("🚀 Welcome to postgres_ai MCP Server!")
+
+    try:
+        settings = get_mcp_settings(env_file)
+    except Exception as e:
+        typer.secho(f"❌ Config error: {e}", fg=typer.colors.RED)
+        typer.secho("Tip: Copy .env.example → .env and fill the values", fg=typer.colors.YELLOW)
+        raise typer.Exit(1)
+
+    # Apply CLI overrides
+    db_host = db_host or settings.db_host
+    db_port = db_port or settings.db_port
+    db_user = db_user or settings.db_user
+    db_name = db_name or settings.db_name
+
+    # Password handling
+    if prompt_password or not getattr(settings, "db_pass", None):
+        db_pass = typer.prompt("Database Password", hide_input=True, confirmation_prompt=True)
+    else:
+        db_pass = settings.db_pass
+
+    logger = get_mcp_logger()
+
+    conn = PGConnector(
+        db_user=db_user,
+        db_host=db_host,
+        db_port=db_port,
+        db_pass=db_pass,
+        db_name=db_name,
+    )
+
+    @lifespan
+    async def mcp_lifespan(server):
+        try:
+            database = await conn.connect()
+            logger.info(f"✅ Connected to Postgres @ {db_host}:{db_port}")
+            yield {"pg_connection": database, "logger": logger}
+        finally:
+            await conn.disconnect()
+            logger.info("Database connection closed")
+
+    server_config = PgMCP(
+        lifespan=mcp_lifespan,
+        server_name="postgres_ai",
+        instructions="MCP Server to handle Postgres database operations with AI tools",
+    )
+    mcp_server = server_config.get_mcp_server()
+
+    typer.secho(f"Connected with Database @ {db_host}:{db_port}", fg=typer.colors.GREEN)
+    typer.secho(f"MCP Server starting @ {host}:{port}", fg=typer.colors.GREEN)
+    asyncio.run(
+        mcp_server.run_async(transport=transport, host=host, port=port)
+    )
+
+
+if __name__ == "__main__":
+    app()

postgres_ai-0.1.0/src/postgres_ai/connectors/pg_connector.py

@@ -0,0 +1,23 @@
+# from sqlalchemy.ext.declarative import declarative_base
+from databases import Database
+
+class PGConnector:
+    def __init__(self, db_user: str, db_pass: str, db_host: str, db_port: int | str, db_name: str):
+        self.db_user = db_user
+        self.db_pass = db_pass
+        self.db_host = db_host
+        self.db_port = str(db_port)
+        self.db_name = db_name
+        self.DB_URL = f"postgresql+asyncpg://{self.db_user}:{self.db_pass}@{self.db_host}:{self.db_port}/{self.db_name}"
+    
+    async def connect(self):
+        try:
+            self.database = Database(self.DB_URL)
+            await self.database.connect()
+            return self.database
+        except Exception as e:
+            raise RuntimeError(f"Failed to connect to Postgres: {e}") from e
+    
+    async def disconnect(self):
+        if hasattr(self, "database") and self.database is not None:
+            await self.database.disconnect()

postgres_ai-0.1.0/src/postgres_ai/loaders/env_loader.py

@@ -0,0 +1,24 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from functools import lru_cache
+from typing import Optional
+
+class MCPSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False
+    )
+    db_host: str
+    db_port: int
+    db_user: str
+    db_pass: str
+    db_name: str
+    mcp_server_host: str
+    mcp_server_port: int
+    mcp_server_transport: str
+
+@lru_cache
+def get_mcp_settings(env_file: Optional[str] = None):
+    if env_file and env_file != ".env":
+        return MCPSettings(_env_file=env_file)
+    return MCPSettings()

postgres_ai-0.1.0/src/postgres_ai/logger/mcp_logger.py

@@ -0,0 +1,20 @@
+import logging
+from pathlib import Path
+from functools import lru_cache
+
+LOG_DIR = Path("mcp_logs")
+LOG_DIR.mkdir(parents=True, exist_ok=True)
+LOG_FILE = LOG_DIR / "pg_ai_log.log"
+
+logging.basicConfig(
+    filename=LOG_FILE, 
+    format="{asctime} - {name} - {levelname} - {message}",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    level=logging.INFO,
+    style="{"
+)
+
+@lru_cache
+def get_mcp_logger():
+    return logging.getLogger("mcp_logger")
+

postgres_ai-0.1.0/src/postgres_ai/mcp_server/server.py

@@ -0,0 +1,30 @@
+from fastmcp import FastMCP
+from postgres_ai.mcp_tools.tools import get_mcp_tools
+from fastmcp.server.lifespan import Lifespan
+
+class PgMCP:
+    def __init__(self,
+                 lifespan: Lifespan, 
+                 server_name: str | None = None, 
+                 instructions: str | None = None,
+                 version: str | None = None,
+                 website_url: str | None = None,
+                ):
+        self.lifespan = lifespan
+        self.server_name = server_name
+        self.instructions = instructions
+        self.version = version
+        self.website_url = website_url
+        tools = get_mcp_tools()
+        self.mcp_tools = tools.mcp_tools
+
+    def get_mcp_server(self):
+        mcp_server = FastMCP(
+            lifespan=self.lifespan,
+            name=self.server_name,
+            instructions=self.instructions,
+            version=self.version,
+            website_url=self.website_url,
+            tools=self.mcp_tools
+        )
+        return mcp_server

postgres_ai-0.1.0/src/postgres_ai/mcp_tools/tools.py

@@ -0,0 +1,44 @@
+from pathlib import Path
+from postgres_ai.types.pg_ai_types import Content, DatabaseResult, MCPTools
+from fastmcp import Context
+from sqlalchemy import text
+import polars as pl
+
+async def read_business_logic():
+    try:
+        with open(Path("pg_skills")/"business-logic"/"SKILL.md", encoding="utf-8") as bl:
+            content = bl.read()
+        return Content(content=content)
+    except Exception as e:
+        raise e
+
+async def load_skill(skill_name: str):
+    """
+    Load the respective skill to get the references for table schema, query instructions, etc.,
+    """
+    try:
+        with open(Path("pg_skills")/skill_name/"SKILL.md", encoding="utf-8") as skill:
+            content = skill.read()
+        return Content(content=content)
+    except Exception as e:
+        raise e
+    
+async def execute_query(sql_query: str, ctx: Context):
+    """
+    Tool to execute the prepared sql query in the Postgres database
+    """
+    database = ctx.lifespan_context.get("pg_connection")
+    try:
+        if database:
+            result = await database.fetch_all(text(sql_query))
+            dataframe = pl.DataFrame(result)
+            return DatabaseResult(sql_query=sql_query,sql_result=dataframe)
+        return Content(content="No database connection acquired")
+    except Exception as e:
+        raise e
+
+
+def get_mcp_tools():
+    return MCPTools(
+        mcp_tools=[read_business_logic, load_skill, execute_query]
+    )

postgres_ai-0.1.0/src/postgres_ai/types/pg_ai_types.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel, Field
+from typing import List, Callable, Any
+
+class Content(BaseModel):
+    content: str = Field(description="The returned skill file content")
+
+class MCPTools(BaseModel):
+    mcp_tools: List[Callable] = Field(description="List of MCP tools to be used to host the MCP server")
+
+class DatabaseResult(BaseModel):
+    sql_query: str = Field(description="The prepared sql query")
+    sql_result: Any = Field(description="The result of sql execution wrapped as DataFrame")
+

postgres_ai-0.1.0/src/postgres_ai.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: postgres_ai
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: databases>=0.9.0
+Requires-Dist: fastapi>=0.131.0
+Requires-Dist: fastmcp>=3.0.2
+Requires-Dist: pandas>=3.0.1
+Requires-Dist: polars>=1.38.1
+Requires-Dist: typer>=0.24.1
+Requires-Dist: uvicorn>=0.41.0
+
+# pg_ai  <img src="https://upload.wikimedia.org/wikipedia/commons/a/ad/Logo_PostgreSQL.png" alt="PostgreSQL" width="100">
+[![GitHub license](https://img.shields.io/github/license/saiprasaad2002/pg_ai)](https://github.com/saiprasaad2002/pg_ai/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/saiprasaad2002/pg_ai)](https://github.com/saiprasaad2002/pg_ai/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/saiprasaad2002/pg_ai)](https://github.com/saiprasaad2002/pg_ai/issues)
+
+## Overview
+
+pg_ai is an open-source MCP (Model Context Protocol) server tailored for PostgreSQL databases. It bridges LLMs with your Postgres data by allowing users to define custom "skills" — encapsulated business logic in markdown files — that guide intelligent database interactions. By implementing the SKILL Graph technique, pg_ai enables dynamic, on-demand context expansion, preventing LLM overload while scaling complexity through interconnected skills.
+
+Inspired by Anthropic's Claude Skills and the SKILL Graph concept (as discussed in [this X thread](https://x.com/arscontexta/status/2023957499183829467?s=20)), pg_ai turns your database into a contextual powerhouse for AI agents.
+
+## Key Features
+
+- **Postgres Integration**: Asynchronous connections for efficient querying.
+- **Skill Management**: Load custom skills from markdown files (SKILL.md) in a progressive, token-efficient manner.
+- **Dynamic Context Growth**: Use SKILL Graph to link and load skills on-demand, building a network of reusable logic.
+- **MCP Compliance**: Exposes tools for LLMs to read business logic, load specific skills, and execute SQL queries.
+- **Logging and Configurability**: Environment-based setup with dedicated logging.
+
+## Architecture
+
+pg_ai is built on FastMCP (a FastAPI-based MCP implementation) and uses asyncpg for PostgreSQL interactions. The core components include:
+
+1. **Server Setup (app.py)**: Initializes the MCP server with a lifespan hook for database connection management.
+2. **PgMCP Class (src/mcp_server/server.py)**: Wraps FastMCP to configure the server with tools and lifespan.
+3. **Postgres Connector (src/connectors/pg_connector.py)**: Handles async connect/disconnect to Postgres using the `databases` library.
+4. **Environment Loader (src/loaders/env_loader.py)**: Loads settings from `.env` using Pydantic for validation.
+5. **Logger (src/logger/mcp_logger.py)**: Configures file-based logging for server events.
+6. **Tools (src/mcp_tools/tools.py)**: Defines MCP tools:
+   - `read_business_logic()`: Loads default business logic from `pg_skills/business-logic/SKILL.md`.
+   - `load_skill(skill_name)`: Dynamically loads a specific skill's instructions from `pg_skills/<skill_name>/SKILL.md`.
+   - `execute_query(sql_query)`: Executes SQL queries on the connected Postgres DB and returns results as a Polars DataFrame.
+
+The SKILL Graph is realized through interconnected skills: Each SKILL.md can reference other skills, allowing the LLM to traverse the graph by calling `load_skill` as needed. This grows context incrementally, aligning with MCP's goal of efficient external system integration.
+
+## Installation
+
+### Prerequisites
+- Python >= 3.12
+- PostgreSQL database
+- Git
+
+### Steps
+1. Clone the repository:
+   ```
+   git clone https://github.com/saiprasaad2002/pg_ai.git
+   cd pg_ai
+   ```
+2. Create virtual environment (preferably python 3.12):
+   ```
+   uv venv --python 3.12
+   ```
+   
+3. Install dependencies:
+   ```
+   uv sync
+   ```
+
+4. Copy and configure the environment file:
+   ```
+   cp .env.example .env
+   ```
+   Edit `.env` with your Postgres credentials and MCP server settings:
+   - `DB_USER`, `DB_PASS`, `DB_HOST`, `DB_PORT`, `DB_NAME`: Postgres connection details.
+   - `MCP_SERVER_HOST`, `MCP_SERVER_PORT`, `MCP_SERVER_TRANSPORT`: Server config (e.g., `STREAMABLE-HTTP` for production).
+
+5. Run the server:
+   ```
+   uv run app.py
+   ```
+
+The server will start, connect to your Postgres DB, and expose MCP endpoints.
+
+## Usage
+
+### Adding Skills
+Skills are stored in the `pg_skills/` directory. Each skill is a subfolder containing a `SKILL.md` file.
+
+- **Structure Example**:
+  ```
+  pg_skills/
+  ├── business-logic/
+  │   └── SKILL.md  # Default business logic (e.g., table schemas, query guidelines)
+  └── custom-skill/
+      └── SKILL.md  # Custom skill instructions (YAML frontmatter + Markdown body)
+  ```
+
+- **SKILL.md Format** (Inspired by Claude Skills):
+  - **YAML Frontmatter**: Minimal metadata (name, description) for progressive disclosure.
+  - **Body**: Detailed instructions, examples, or business logic for the LLM.
+  - Example:
+    ```
+    ---
+    name: inventory-check
+    description: Checks inventory levels in the products table. Use when querying stock.
+    ---
+
+    # Inventory Check Skill
+
+    To check inventory:
+    1. Query the `products` table: SELECT * FROM products WHERE id = {id};
+    2. Analyze stock levels.
+    ...
+    ```
+
+Skills can reference others (e.g., "Load the 'reporting' skill for summaries"), forming a graph for dynamic loading.
+
+### Interacting with the Server
+- Connect your LLM (e.g., Claude, ChatGPT) via an MCP client.
+- The LLM can call tools to load skills and execute queries, building context as needed.
+- Logs are saved in `mcp_logs/pg_ai_log.log`.
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feature/new-feature`.
+3. Commit changes: `git commit -m 'Add new feature'`.
+4. Push to the branch: `git push origin feature/new-feature`.
+5. Open a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## References
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro)
+- [Claude Skills Blog](https://www.anthropic.com/news/skills)
+- [SKILL Graph Discussion](https://x.com/arscontexta/status/2023957499183829467?s=20)
+
+For questions, open an issue or contact the maintainer.
+

postgres_ai-0.1.0/src/postgres_ai.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/postgres_ai/__init__.py
+src/postgres_ai/cli.py
+src/postgres_ai.egg-info/PKG-INFO
+src/postgres_ai.egg-info/SOURCES.txt
+src/postgres_ai.egg-info/dependency_links.txt
+src/postgres_ai.egg-info/entry_points.txt
+src/postgres_ai.egg-info/requires.txt
+src/postgres_ai.egg-info/top_level.txt
+src/postgres_ai/connectors/pg_connector.py
+src/postgres_ai/loaders/env_loader.py
+src/postgres_ai/logger/mcp_logger.py
+src/postgres_ai/mcp_server/server.py
+src/postgres_ai/mcp_tools/tools.py
+src/postgres_ai/types/pg_ai_types.py

postgres_ai-0.1.0/src/postgres_ai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

postgres_ai-0.1.0/src/postgres_ai.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+postgres_ai = postgres_ai.cli:app

postgres_ai-0.1.0/src/postgres_ai.egg-info/requires.txt

@@ -0,0 +1,8 @@
+asyncpg>=0.31.0
+databases>=0.9.0
+fastapi>=0.131.0
+fastmcp>=3.0.2
+pandas>=3.0.1
+polars>=1.38.1
+typer>=0.24.1
+uvicorn>=0.41.0

postgres_ai-0.1.0/src/postgres_ai.egg-info/top_level.txt

@@ -0,0 +1 @@
+postgres_ai