Skip to content

ROADMAP.md

Latest commit

 

History

History
208 lines (149 loc) · 7.79 KB

ROADMAP.md

File metadata and controls

208 lines (149 loc) · 7.79 KB
Raw

Roadmap — PostgreSQL MCP Server

Kế hoạch phát triển các tính năng tương lai, sắp xếp theo mức ưu tiên.

Trạng thái hiện tại: 45 tools, 5 resources, 5 prompts, 189 unit tests, stdio transport.

Phase 8: SSE / Streamable HTTP Transport

Ưu tiên: Cao · Cho phép triển khai remote, nhiều client kết nối cùng lúc.

  • Implement SSE transport trong index.ts (thay thế placeholder hiện tại)
  • Hỗ trợ Streamable HTTP transport (MCP spec mới)
  • Thêm middleware CORS cho remote access
  • Authentication cho remote transport (API key / Bearer token)
  • TLS termination hướng dẫn (reverse proxy / trực tiếp)
  • Health endpoint HTTP (GET /health) cho load balancer
  • Config: MCP_TRANSPORT=sse|streamable-http, MCP_PORT, MCP_AUTH_TOKEN

Phase 9: Docker & Deployment

Ưu tiên: Cao · Đóng gói sẵn sàng cho production.

  • Dockerfile (multi-stage build, distroless/alpine image)
  • docker-compose.yml (MCP server + PostgreSQL dev)
  • .dockerignore tối ưu image size
  • GitHub Actions CI/CD pipeline:
    • Lint + typecheck + test trên mỗi PR
    • Build & push Docker image khi merge vào main
    • Tự động publish npm khi tag release
  • npm prepublishOnly kiểm tra version bump
  • Hướng dẫn deploy lên fly.io / Railway / VPS

Phase 10: Integration Testing

Ưu tiên: Cao · Đảm bảo chất lượng end-to-end.

  • Setup PostgreSQL container cho CI (GitHub Actions service)
  • Integration tests với real database:
    • Tạo bảng → insert → query → update → delete → drop
    • Schema inspection accuracy
    • Permission enforcement end-to-end
    • Rate limiting behavior
    • Transaction rollback on failure
  • Test SSE transport end-to-end (client ↔ server ↔ DB)
  • Performance benchmarks (response time, throughput)
  • Load testing với nhiều concurrent requests

Phase 11: Audit Logging

Ưu tiên: Trung bình–Cao · Theo dõi mọi thao tác write/admin cho compliance.

  • Audit log cho mọi write operations (INSERT/UPDATE/DELETE)
  • Audit log cho DDL operations (CREATE/ALTER/DROP)
  • Audit log cho admin operations (terminate, cancel, vacuum)
  • Log format: timestamp, tool name, user context, SQL summary, affected rows
  • Output targets: stderr (default), file (rotated), PostgreSQL table (optional)
  • Config: AUDIT_LOG_ENABLED, AUDIT_LOG_TARGET, AUDIT_LOG_FILE
  • Không log sensitive data (password, connection string)

Phase 12: Schema Caching & Sampling

Ưu tiên: Trung bình · Giảm tải cho DB khi LLM liên tục inspect schema.

  • Cache schema introspection results (TTL-based, default 5 phút)
  • Auto-invalidate cache khi DDL tool được gọi (create_table, alter_table, ...)
  • Tool refresh_schema_cache: manual invalidate
  • Sampling: resource postgres://sample/{table} trả 5 dòng đầu tiên
  • Config: SCHEMA_CACHE_TTL_MS (0 = disabled)

Phase 13: Multi-Database Support

Ưu tiên: Trung bình · Cho phép LLM làm việc với nhiều database cùng lúc.

  • Config nhận nhiều connection strings qua POSTGRES_DATABASES (JSON array)
  • Mỗi tool call nhận optional database parameter
  • Connection pool per database (lazy init)
  • Resource postgres://databases: liệt kê tất cả databases đã configure
  • Tool switch_database: chuyển database mặc định
  • Tự động prefix database name trong output để tránh nhầm lẫn

Phase 14: Query History & Context

Ưu tiên: Trung bình · LLM có thể reference lại queries trước đó.

  • Lưu N queries gần nhất (in-memory ring buffer, default 50)
  • Resource postgres://history: danh sách queries đã chạy + kết quả tóm tắt
  • Tool get_query_history: lấy lịch sử theo filter
  • Tool rerun_query: chạy lại query từ lịch sử (by index)
  • Tự động attach execution time, row count vào mỗi entry
  • Config: QUERY_HISTORY_SIZE (0 = disabled)

Phase 15: Migration Management

Ưu tiên: Trung bình · Hỗ trợ LLM tạo và chạy migration files.

  • Tool generate_migration: tạo migration file (SQL up/down) từ schema diff
  • Tool list_migrations: liệt kê migrations đã chạy (đọc từ migration table)
  • Tool run_migration: chạy migration (yêu cầu admin permission)
  • Tool rollback_migration: rollback migration gần nhất
  • Tương thích format với các migration tools phổ biến (Knex, Prisma, Flyway)
  • Directory: migrations/ hoặc configurable path

Phase 16: PostgreSQL Extension Support

Ưu tiên: Thấp–Trung bình · Hỗ trợ các extension phổ biến.

  • PostGIS: tools cho spatial queries (ST_Distance, ST_Contains, ...)
  • pg_trgm: fuzzy search tool (similarity(), % operator)
  • hstore/jsonb: tools chuyên biệt cho JSON operations
  • pgvector: vector similarity search cho AI embeddings
  • Auto-detect extensions đã cài trong database
  • Resource postgres://extensions: liệt kê extensions + version

Phase 17: Streaming Results

Ưu tiên: Thấp–Trung bình · Xử lý large result sets qua MCP streaming.

  • Stream rows qua MCP progress notifications thay vì load toàn bộ vào memory
  • Tool query_stream: query trả kết quả theo batch (chunk_size configurable)
  • Hỗ trợ cursor-based pagination cho datasets lớn
  • Memory limit per query (default 50MB), abort nếu vượt
  • Config: STREAM_CHUNK_SIZE, MAX_RESULT_MEMORY_MB

Phase 18: Security Hardening

Ưu tiên: Thấp (nice-to-have) · Bảo mật nâng cao.

  • IP whitelist cho remote transport
  • Per-tool permission overrides (VD: cho phép query nhưng block execute)
  • Schema-level permission (chỉ cho phép truy cập schema public)
  • Table-level permission (whitelist/blacklist bảng cụ thể)
  • Query cost estimation — reject query nếu EXPLAIN cost quá cao
  • Secrets masking trong log output (connection strings, passwords)
  • Config: ALLOWED_SCHEMAS, ALLOWED_TABLES, MAX_QUERY_COST

Phase 19: Observability

Ưu tiên: Thấp · Monitoring cho production deployments.

  • Prometheus metrics endpoint (/metrics):
    • mcp_tool_calls_total (counter, label: tool_name, status)
    • mcp_tool_duration_seconds (histogram)
    • mcp_db_pool_connections (gauge: active, idle, waiting)
    • mcp_rate_limit_rejected_total (counter)
  • OpenTelemetry tracing (optional dependency)
  • Structured JSON logging (machine-parseable)
  • Config: METRICS_ENABLED, METRICS_PORT

Phase 20: Developer Experience

Ưu tiên: Thấp · Cải thiện trải nghiệm phát triển.

  • ESLint + Prettier config
  • Husky pre-commit hooks (lint + test)
  • CONTRIBUTING.md hướng dẫn contribute
  • CLI mode: npx postgres-mcp --interactive cho testing nhanh
  • MCP Inspector integration guide
  • Changelog tự động từ conventional commits

Tóm tắt ưu tiên

Ưu tiên Phase Chủ đề
🔴 Cao 8 SSE / Streamable HTTP Transport
🔴 Cao 9 Docker & CI/CD
🔴 Cao 10 Integration Testing
🟡 TB–Cao 11 Audit Logging
🟡 TB 12 Schema Caching & Sampling
🟡 TB 13 Multi-Database Support
🟡 TB 14 Query History & Context
🟡 TB 15 Migration Management
🟢 Thấp–TB 16 PostgreSQL Extension Support
🟢 Thấp–TB 17 Streaming Results
🟢 Thấp 18 Security Hardening
🟢 Thấp 19 Observability (Metrics/Tracing)
🟢 Thấp 20 Developer Experience

Cập nhật lần cuối: 2026-03-01