Internal Architecture

1. Browser → nginx (port 8081)
2. nginx → MCP Server (port 8080) for /mcp/v1 and /api/* requests
3. MCP Server validates session token
4. MCP Server routes request:
   - /mcp/v1 → JSON-RPC handler
   - /api/llm/* → LLM proxy handler
   - /api/user/info → User info handler
5. Response → nginx → Browser

// internal/database/connection.go

// ConnectionManager manages per-session database connections
type ConnectionManager struct {
    configs map[string]*Config  // sessionToken -> db config
    pools   map[string]*sql.DB  // sessionToken -> connection pool
    mu      sync.RWMutex
}

func (m *ConnectionManager) GetConnection(sessionToken string) (*sql.DB, error) {
    m.mu.RLock()
    defer m.mu.RUnlock()

    pool, exists := m.pools[sessionToken]
    if !exists {
        return nil, fmt.Errorf("no connection for session")
    }

    return pool, nil
}

// internal/chat/llm.go

type LLMClient interface {
    Chat(ctx context.Context, messages []Message, tools interface{}) (LLMResponse, error)
    ListModels(ctx context.Context) ([]string, error)
}

type anthropicClient struct { /* ... */ }
type openaiClient struct { /* ... */ }
type ollamaClient struct { /* ... */ }

┌──────────────────┐
│  web-client:8081 │
│  (nginx + React) │
└────────┬─────────┘
         │ Docker network: pgedge-network
         │ Internal hostname: mcp-server
         ▼
┌──────────────────┐     ┌──────────────┐
│  mcp-server:8080 │────▶│  PostgreSQL  │
│  (Go binary)     │     │  (external)  │
└──────────────────┘     └──────────────┘

# Proxy JSON-RPC requests to MCP server
location /mcp/v1 {
    proxy_pass http://mcp-server:8080/mcp/v1;
    proxy_http_version 1.1;
    proxy_set_header Authorization $http_authorization;
    # ... other headers
}

# Proxy API requests to MCP server
location /api/ {
    proxy_pass http://mcp-server:8080/api/;
    proxy_http_version 1.1;
    proxy_set_header Authorization $http_authorization;
    # ... other headers
}

# SPA routing - serve index.html for all other routes
location / {
    try_files $uri $uri/ /index.html;
}

# Stage 1: Build React app
FROM nodejs:20 AS builder
WORKDIR /workspace
COPY web/package*.json ./
RUN npm ci
COPY web/ ./
RUN npm run build

# Stage 2: Serve with nginx
FROM nginx:latest
COPY --from=builder /workspace/dist /opt/app-root/src
COPY docker/nginx.conf /etc/nginx/nginx.conf

# Stage 1: Build Go binary
FROM golang:1.23-alpine AS builder
WORKDIR /workspace
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o pgedge-postgres-mcp ./cmd/pgedge-pg-mcp-svr

# Stage 2: Minimal runtime
FROM ubi9/ubi-minimal:latest
COPY --from=builder /workspace/pgedge-postgres-mcp /app/
COPY docker/init-server.sh /app/
CMD ["/app/init-server.sh"]

# Terminal 1: Start MCP server
cd bin
./pgedge-postgres-mcp -http -addr :8080 -config pgedge-pg-mcp-web.yaml

# Terminal 2: Start Vite dev server
cd web
npm run dev

# Build and start all containers
docker-compose up -d

# View logs
docker-compose logs -f

# Access web client
open http://localhost:8081

func SetupHandlers(mux *http.ServeMux, llmProxyConfig *llmproxy.Config) {
    // Existing handlers...

    // Add new handler
    mux.HandleFunc("/api/llm/my-endpoint", func(w http.ResponseWriter, r *http.Request) {
        llmproxy.HandleMyEndpoint(w, r, llmProxyConfig)
    })
}

func RegisterTools(registry *Registry, db *database.Client, llm *llm.Client) {
    // Existing tools...

    // Add new tool
    registry.Register(Tool{
        Name:        "my_tool",
        Description: "Description of my tool",
        InputSchema: schema,
        Handler:     myToolHandler,
    })
}

Client → POST /api/chat/compact → Compactor
                                      ↓
                        ┌─────────────┴──────────────┐
                        │                            │
                   Classifier                  TokenEstimator
                        │                            │
                        ↓                            ↓
                  5-tier classes            Provider-specific
                  (Anchor→Transient)        token counting

// internal/compactor/compactor.go

func (c *Compactor) Compact(messages []Message) CompactResponse {
    // 1. Check cache for previous result
    if cached := c.cache.Get(messages, maxTokens, recentWindow); cached {
        return cached
    }

    // 2. Estimate token usage with provider-specific counter
    originalTokens := c.estimateTokens(messages)

    // 3. Always keep: first message + recent window
    anchors := []Message{messages[0]}
    recent := messages[len(messages)-recentWindow:]

    // 4. Classify and keep important middle messages
    middle := messages[1 : len(messages)-recentWindow]
    important := c.classifyAndKeepImportant(middle)

    // 5. Build compacted list
    compacted := append(anchors, important...)
    compacted = append(compacted, recent...)

    // 6. If still over budget, create summary
    if tokenEstimate > maxTokens || enableSummarization {
        summary := c.createSummary(middle, important)
        // Insert summary message after first anchor
        compacted = insertSummary(compacted, summary)
    }

    // 7. Cache result and record analytics
    c.cache.Set(messages, result)
    c.analytics.RecordCompaction(result)

    return result
}

// internal/compactor/token_counter.go

type TokenCounterType string

const (
    TokenCounterGeneric   = "generic"   // 4.0 chars/token
    TokenCounterOpenAI    = "openai"    // 4.0 chars/token, GPT-4 optimized
    TokenCounterAnthropic = "anthropic" // 3.8 chars/token, Claude optimized
    TokenCounterOllama    = "ollama"    // 4.5 chars/token, conservative
)

// SHA256-based cache key from messages + config
// TTL-based expiration with background cleanup
cache.Set(messages, maxTokens, recentWindow, result)

// Extract actions, entities, queries, errors
summary := llmSummarizer.GenerateSummary(ctx, messages, basicSummary)
// Returns: "[Enhanced context: Actions: show, create, Entities: users,
//           products, 2 SQL operations, Tables: users, Tools: query_database,
//           5 messages compressed]"

// Track compression metrics
metrics := analytics.GetMetrics()
// Returns: total compactions, messages in/out, tokens saved,
//          average compression ratio, average duration

// internal/chat/client.go

func (c *Client) compactMessages(messages []Message) []Message {
    // Try server compaction
    if result, ok := c.tryServerCompaction(messages, maxTokens, recentWindow); ok {
        return result
    }
    // Fallback to local (keep first + last 10)
    return c.localCompactMessages(messages, recentWindow)
}

// web/src/components/ChatInterface.jsx

const compactMessages = async (messages, sessionToken, maxTokens, recentWindow) => {
    try {
        const response = await fetch('/api/chat/compact', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${sessionToken}`
            },
            body: JSON.stringify({ messages, max_tokens: maxTokens, recent_window: recentWindow })
        });
        if (response.ok) {
            const data = await response.json();
            return data.messages;
        }
    } catch (error) {
        console.warn('Server compaction failed, using local:', error);
    }
    return localCompactMessages(messages, recentWindow);
};

# Run compactor tests
go test ./internal/compactor/...

# Test categories:
# - Message classification (12 tests)
# - Token estimation (14 tests)
# - Compaction algorithm (10 tests)
# - Provider token counting (8 tests)
# - Caching (7 tests)
# - Analytics (7 tests)
# - LLM summarization (8 tests)

pool.SetMaxOpenConns(10)
pool.SetMaxIdleConns(5)
pool.SetConnMaxLifetime(time.Hour)

type CachedResponse struct {
    key       string
    response  LLMResponse
    timestamp time.Time
}

const toolResults = await Promise.all(
    toolUses.map(toolUse => mcpClient.callTool(toolUse.name, toolUse.input))
);

# Server-side
export PGEDGE_MCP_LOG_LEVEL=debug
export PGEDGE_DB_LOG_LEVEL=debug
export PGEDGE_LLM_LOG_LEVEL=debug

# Docker
docker-compose logs -f mcp-server | grep -i error