mcp-outline-postgresql/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

[1.3.9] - 2026-01-31

Fixed

• Document Visibility (Critical): create_document now creates initial revision
  • Was: Documents created via MCP didn't appear in Outline interface
  • Cause: Outline requires entry in revisions table to display documents
  • Now: Uses transaction to insert into both documents and revisions tables
  • Documents created via MCP now visible immediately in Outline

[1.3.8] - 2026-01-31

Fixed

• Collection Sort Field: create_collection now sets default sort value
  • Was: sort column left NULL, causing frontend error "Cannot read properties of null (reading 'field')"
  • Now: Sets {"field": "index", "direction": "asc"} as default
  • Outline frontend requires this field to render collections

[1.3.7] - 2026-01-31

Fixed

• Tool Name Length: Shortened outline_bulk_remove_users_from_collection to outline_bulk_remove_collection_users
  • MCP tool names with prefix mcp__outline-postgresql__ were exceeding 64 character limit
  • Claude API returns error 400 for tool names > 64 chars

[1.3.6] - 2026-01-31

Fixed

• Schema Compatibility: Fixed 3 additional bugs in write operations found during Round 3 testing
  • create_document - Added missing required columns: id, urlId, teamId, isWelcome, fullWidth, insightsEnabled
  • create_collection - Added missing required columns: id, maintainerApprovalRequired
  • shares_create - Added missing required columns: id, allowIndexing, showLastUpdated

Validated

• Production Testing (2026-01-31): Full CRUD cycle validated via MCP

  • list_collections - 2 collections listed ✅
  • create_document - Document created and published ✅
  • update_document - Text updated, version incremented ✅
  • delete_document - Permanently deleted ✅
  • SSH tunnel active on port 5433
  • 164 tools available and functional

• Code Review Session: All 6 bug fixes confirmed in source code

  • INSERT statements verified with correct columns
  • ID generation logic validated (gen_random_uuid, urlId generation)
  • Unit tests: 209/209 passing
  • HTTP server: 164 tools loading correctly

[1.3.5] - 2026-01-31

Fixed

• Schema Compatibility: Fixed 3 bugs found during comprehensive MCP tool testing (Round 1-2)
  • outline_auth_config - Removed non-existent ap.updatedAt column from authentication_providers query
  • outline_get_subscription_settings - Added LIMIT 25 to prevent returning all subscriptions (was causing 136KB+ responses)
  • list_collections - Removed documentStructure field from list query (use get_collection for full details)

Tested

• MCP Tools Coverage (Round 3 - Write Operations):

  • Documents: create_document, update_document, archive_document, restore_document, delete_document ✅
  • Collections: create_collection, delete_collection ✅
  • Groups: create_group, delete_group ✅
  • Comments: comments_create, comments_delete ✅
  • Shares: shares_create, shares_revoke ✅
  • Stars: stars_create, stars_delete ✅
  • Pins: pins_create, pins_delete ✅
  • API Keys: api_keys_create, api_keys_delete ✅
  • Webhooks: webhooks_create, webhooks_delete ✅

• MCP Tools Coverage (Round 1 & 2 - Read Operations):

  • Documents: list_documents, search_documents ✅
  • Collections: list_collections, get_collection ✅
  • Users: list_users, get_user ✅
  • Groups: list_groups, get_group ✅
  • Comments: comments_list ✅
  • Shares: shares_list ✅
  • Revisions: revisions_list ✅
  • Events: events_list, events_stats ✅
  • Attachments: attachments_list, attachments_stats ✅
  • File Operations: file_operations_list ✅
  • OAuth: oauth_clients_list, oauth_authentications_list ✅
  • Auth: auth_info ✅, auth_config ❌ (fixed)
  • Stars: stars_list ✅
  • Pins: pins_list ✅
  • Views: views_list ✅
  • Reactions: reactions_list ✅
  • API Keys: api_keys_list ✅
  • Webhooks: webhooks_list ✅
  • Backlinks: backlinks_list ✅
  • Search Queries: search_queries_list, search_queries_stats ✅
  • Teams: get_team, get_team_stats, list_team_domains ✅
  • Integrations: list_integrations ✅
  • Notifications: list_notifications, get_notification_settings ✅
  • Subscriptions: list_subscriptions, get_subscription_settings ✅ (fixed)
  • Templates: list_templates ✅
  • Imports: list_imports ✅
  • Emojis: list_emojis ✅
  • User Permissions: list_user_permissions ✅
  • Analytics: All 6 tools ✅
  • Advanced Search: All 6 tools ✅

[1.3.4] - 2026-01-31

Added

• Test Suite: Comprehensive Jest test infrastructure with 209 tests
  • jest.config.js: Jest configuration for TypeScript
  • src/utils/__tests__/security.test.ts: Security utilities tests (44 tests)
  • src/utils/__tests__/validation.test.ts: Zod validation tests (34 tests)
  • src/utils/__tests__/pagination.test.ts: Cursor pagination tests (25 tests)
  • src/utils/__tests__/query-builder.test.ts: Query builder tests (38 tests)
  • src/tools/__tests__/tools-structure.test.ts: Tools structure validation (68 tests)

Tested

• Utilities Coverage:

  • UUID, email, URL validation
  • Rate limiting behaviour
  • HTML escaping and sanitization
  • Pagination defaults and limits
  • Cursor encoding/decoding
  • SQL query building

• Tools Structure:

  • All 164 tools validated for correct structure
  • Input schemas have required properties defined
  • Unique tool names across all modules
  • Handlers are functions

Dependencies

• Added ts-jest for TypeScript test support

[1.3.3] - 2026-01-31

Fixed

• Schema Compatibility: Fixed 8 additional column/table mismatches found during comprehensive testing
  • outline_list_groups - Removed non-existent g.description column
  • outline_analytics_collection_stats - Changed collection_group_memberships to group_permissions
  • outline_list_notifications - Removed non-existent n.data column
  • outline_list_imports - Removed non-existent i.type, documentCount, fileCount columns
  • outline_list_emojis - Added graceful handling when emojis table doesn't exist
  • outline_get_team - Removed non-existent passkeysEnabled, description, preferences columns
  • list_collection_documents - Changed updatedById to lastModifiedById
  • outline_revisions_compare - Changed updatedById to lastModifiedById

Tested

• Comprehensive Testing: 45+ tools tested against production database
  • All read operations verified
  • Analytics, search, and advanced features confirmed working
  • Edge cases (orphaned docs, duplicates) handled correctly

Statistics

• Production: hub.descomplicar.pt (462 documents, 2 collections)
• Total Tools: 164 (33 modules)
• Bugs Fixed: 8

[1.3.2] - 2026-01-31

Fixed

• Schema Compatibility: Fixed column name mismatch with production Outline database
  • Changed emoji to icon in documents queries (8 files affected)
  • Changed emoji to icon in revisions queries
  • Updated export/import tools to use icon field
  • Updated templates tools to use icon field
  • reactions.emoji kept unchanged (correct schema)

Files Updated

• src/tools/documents.ts - SELECT queries
• src/tools/advanced-search.ts - Search queries
• src/tools/analytics.ts - Analytics queries + GROUP BY
• src/tools/export-import.ts - Export/import with metadata
• src/tools/templates.ts - Template queries + INSERT
• src/tools/collections.ts - Collection document listing
• src/tools/revisions.ts - Revision comparison

Verified

• Production connection: hub.descomplicar.pt (448 documents)
• All 164 tools build without errors

[1.3.1] - 2026-01-31

Added

• Production Deployment: Configured for hub.descomplicar.pt (EasyPanel)

  • SSH tunnel script start-tunnel.sh for secure PostgreSQL access
  • Tunnel connects via 172.18.0.46:5432 (Docker bridge network)
  • Local port 5433 for production, 5432 reserved for local dev

• Credentials Backup: CREDENTIALS-BACKUP.md with all connection details

  • Production credentials (EasyPanel PostgreSQL)
  • Local development credentials
  • Old API-based MCP configuration (for rollback if needed)

Changed

• Claude Code Configuration: Updated ~/.claude.json
  • Removed old outline MCP (API-based, 4 tools)
  • Updated outline-postgresql to use production database
  • Now connects to hub.descomplicar.pt with 164 tools

Deployment

Environment	Database	Port	Tunnel Required
Production	descomplicar	5433	Yes (SSH)
Development	outline	5432	No (local Docker)

Usage

# Start tunnel before Claude Code
./start-tunnel.sh start

# Check status
./start-tunnel.sh status

# Stop tunnel
./start-tunnel.sh stop

[1.3.0] - 2026-01-31

Added

• Multi-Transport Support: Added HTTP transport alongside existing stdio

  • src/index-http.ts: New entry point for HTTP/StreamableHTTP transport
  • src/server/: New module with shared server logic
    • create-server.ts: Factory function for MCP server instances
    • register-handlers.ts: Shared handler registration
  • Endpoints: /mcp (MCP protocol), /health (status), /stats (tool counts)
  • Supports both stateful (session-based) and stateless modes

• New npm Scripts:

  • start:http: Run HTTP server (node dist/index-http.js)
  • dev:http: Development mode for HTTP server

Changed

• Refactored src/index.ts: Now uses shared server module for cleaner code
• Server Version: Updated to 1.3.0 across all transports

Technical

• Uses StreamableHTTPServerTransport from MCP SDK (recommended over deprecated SSEServerTransport)
• HTTP server listens on 127.0.0.1:3200 by default (configurable via MCP_HTTP_PORT and MCP_HTTP_HOST)
• CORS enabled for local development
• Graceful shutdown on SIGINT/SIGTERM

[1.2.5] - 2026-01-31

Fixed

• Connection Leak (PgClient): Fixed connection leak in testConnection() method
  • pg-client.ts: Client is now always released using finally block
  • Previously, if SELECT 1 query failed after connection was acquired, the connection was never released
  • Prevents connection pool exhaustion during repeated connection test failures

[1.2.4] - 2026-01-31

Security

• SQL Injection Prevention (Pagination): Fixed critical SQL injection vulnerability in cursor pagination

  • pagination.ts: Added validateFieldName() function to sanitize field names
  • Field names (cursorField, secondaryField) are now validated against alphanumeric + underscore + dot pattern
  • Rejects dangerous SQL keywords (SELECT, INSERT, UPDATE, DELETE, DROP, UNION, etc.)
  • Prevents injection via cursor field names in ORDER BY clauses

• Cryptographic Random (Transaction Retry): Replaced Math.random() with crypto.randomBytes() for jitter calculation

  • transaction.ts: Retry jitter now uses cryptographically secure random generation
  • Maintains consistency with project security standards

Fixed

• Data Integrity (Comments): Fixed critical atomicity bug in comment deletion

  • comments.ts: DELETE operations now wrapped in transaction
  • Prevents orphaned replies if parent comment deletion fails
  • Uses withTransactionNoRetry() to ensure all-or-nothing deletion

• Error Handling (PgClient): Added try-catch to ROLLBACK operation

  • pg-client.ts: ROLLBACK failures now logged instead of crashing
  • Prevents unhandled errors during transaction rollback
  • Original error is still thrown after logging rollback failure

• Memory Leak (Pool Monitoring): Added .unref() to setInterval in PoolMonitor

  • monitoring.ts: Pool monitoring interval now allows process to exit gracefully
  • Prevents memory leak and hanging processes on shutdown

• Version Mismatch: Updated hardcoded server version to match package.json

  • index.ts: Server version now correctly reports '1.2.4'
  • Ensures consistency across all version references

[1.2.3] - 2026-01-31

Security

• Cryptographic Random Generation: Replaced Math.random() with crypto.randomBytes() for secure secret generation

  • oauth.ts: OAuth client secrets now use cryptographically secure random generation
  • api-keys.ts: API keys now use cryptographically secure random generation
  • API keys now store only the hash, not the plain text secret (prevents database breach exposure)

• URL Validation: Added isValidHttpUrl() to reject dangerous URL protocols

  • emojis.ts: Emoji URLs must be HTTP(S) - prevents javascript:, data:, file: protocols
  • webhooks.ts: Webhook URLs must be HTTP(S) - both create and update operations
  • users.ts: Avatar URLs must be HTTP(S) or null

• Integer Validation: Added validation for numeric IDs from external systems

  • desk-sync.ts: desk_project_id and desk_task_id validated as positive integers
  • Prevents injection via numeric parameters

• Memory Leak Fix: Fixed setInterval memory leak in rate limiting

  • Rate limit cleanup interval now properly managed with start/stop functions
  • Uses unref() to allow process to exit cleanly
  • Added graceful shutdown handler to clean up intervals

Fixed

• parseInt Radix: Added explicit radix (10) to all parseInt() calls across 5 files

  • collections.ts, groups.ts, revisions.ts, users.ts, security.ts

• Savepoint SQL Injection: Added sanitizeSavepointName() to prevent SQL injection in savepoints

  • Validates savepoint names against PostgreSQL identifier rules

• Share URL Generation: Replaced Math.random() with crypto.randomBytes() for share URL IDs

  • Also replaced deprecated .substr() with modern approach

[1.2.2] - 2026-01-31

Security

• SQL Injection Prevention: Fixed 21 SQL injection vulnerabilities across analytics, advanced-search, and search-queries modules

  • Replaced string interpolation with parameterized queries for all user inputs
  • Added validateDaysInterval() function for safe interval validation
  • Added isValidISODate() function for date format validation
  • Added validatePeriod() function for period parameter validation
  • All UUID validations now occur BEFORE string construction
  • Using make_interval(days => N) for safe interval expressions

• Transaction Support: Added atomic operations for bulk operations

  • bulk-operations.ts: All 6 bulk operations now use transactions
  • desk-sync.ts: Create project doc and link task use transactions
  • export-import.ts: Import markdown folder uses transactions

• Rate Limiting: Added automatic cleanup of expired entries (every 5 minutes)

Added

• Transaction Helper (src/utils/transaction.ts): Centralized transaction management with advanced features

  • withTransaction(): Execute operations with automatic retry for deadlocks (exponential backoff + jitter)
  • withTransactionNoRetry(): Execute without retry for operations with side effects
  • withReadOnlyTransaction(): Read-only transactions with SERIALIZABLE isolation
  • Savepoint class: Support for nested transaction-like behavior
  • Configurable retry (maxRetries, baseDelayMs, maxDelayMs, timeoutMs)
  • Automatic detection of retryable PostgreSQL errors (40001, 40P01, 55P03)

• SafeQueryBuilder (src/utils/query-builder.ts): Helper class for building parameterized queries

  • Automatic parameter index management
  • Built-in UUID validation (buildUUIDEquals, buildUUIDIn)
  • ILIKE helpers for case-insensitive search (buildILike, buildILikePrefix)
  • Comparison operators (buildEquals, buildBetween, buildGreaterThan, etc.)
  • Array operators (buildIn, buildNotIn)
  • NULL checks (buildIsNull, buildIsNotNull)
  • Condition builder with addCondition() and addConditionIf()

• Input Validation (src/utils/validation.ts): Zod-based validation system

  • Common schemas: uuid, email, pagination, isoDate, permission, userRole
  • withValidation() middleware for automatic tool input validation
  • Helper functions: validateUUIDs(), validateEnum(), validateStringLength(), validateNumberRange()
  • toolSchemas with pre-built schemas for common operations

• Audit Logging (src/utils/audit.ts): Automatic logging of write operations

  • logAudit(): Log single audit event to Outline's events table
  • logAuditBatch(): Batch logging for bulk operations
  • withAuditLog() middleware for automatic logging on tools
  • AuditEvents constants for all operation types
  • createTeamAuditLogger(): Team-scoped audit logger factory

• Database Indexes (migrations/001_indexes.sql): Performance optimization indexes

  • Full-text search GIN index for documents (10-100x faster searches)
  • Collection and membership lookup indexes (10x faster permission checks)
  • Event/audit log indexes (5-20x faster analytics)
  • User interaction indexes (stars, pins, views)
  • Composite indexes for common query patterns
  • See migrations/README.md for usage instructions

• Pool Monitoring (src/utils/monitoring.ts): Connection pool health monitoring

  • PoolMonitor class: Continuous monitoring with configurable alerts
  • monitorPool(): Quick setup function to start monitoring
  • checkPoolHealth(): One-time health check with issues list
  • logPoolStats(): Debug helper for current pool status
  • Configurable thresholds (warning at 80%, critical at 95%)
  • Automatic alerting for saturation and waiting connections
  • Statistics history with averages over time

• Cursor-Based Pagination (src/utils/pagination.ts): Efficient pagination for large datasets

  • paginateWithCursor(): High-level pagination helper
  • buildCursorQuery(): Build query parts for cursor pagination
  • processCursorResults(): Process results with cursor generation
  • encodeCursor() / decodeCursor(): Base64url cursor encoding
  • Compound cursors with secondary field for stable sorting
  • Bidirectional pagination (next/prev cursors)
  • Optional total count with extra query
  • Configurable limits (default 25, max 100)

Changed

• Refactored security utilities with new validation functions
• Improved error messages for invalid input parameters
• Consolidated transaction helpers from individual tool files to centralized module
• Updated utils/index.ts to export all new modules

[1.2.1] - 2026-01-31

Added

• Export/Import (2 tools): export_collection_to_markdown, import_markdown_folder - Advanced Markdown export/import with hierarchy
• Desk Sync (2 tools): create_desk_project_doc, link_desk_task - Desk CRM integration for project documentation

Changed

• Total tools increased from 160 to 164

[1.2.0] - 2026-01-31

Added

• Teams (5 tools): get, update, stats, domains, settings - Team/workspace management
• Integrations (6 tools): list, get, create, update, delete, sync - External integrations (Slack, embeds)
• Notifications (4 tools): list, mark read, mark all read, settings - User notification management
• Subscriptions (4 tools): list, subscribe, unsubscribe, settings - Document subscription management
• Templates (5 tools): list, get, create from, convert to/from - Document template management
• Imports (4 tools): list, status, create, cancel - Import job management
• Emojis (3 tools): list, create, delete - Custom emoji management
• User Permissions (3 tools): list, grant, revoke - Document/collection permission management
• Bulk Operations (6 tools): archive, delete, move, restore documents; add/remove users from collection
• Advanced Search (6 tools): advanced search, facets, recent, user activity, orphaned, duplicates
• Analytics (6 tools): overview, user activity, content insights, collection stats, growth metrics, search analytics

Changed

• Total tools increased from 108 to 160
• Updated module exports and index files
• Improved database schema compatibility

[1.1.0] - 2026-01-31

Added

• Stars (3 tools): list, create, delete - Bookmark documents/collections for quick access
• Pins (3 tools): list, create, delete - Pin important documents to collection tops
• Views (2 tools): list, create - Track document views and view counts
• Reactions (3 tools): list, create, delete - Emoji reactions on comments
• API Keys (4 tools): list, create, update, delete - Manage programmatic access
• Webhooks (4 tools): list, create, update, delete - Event notification subscriptions
• Backlinks (1 tool): list - View document link references (read-only view)
• Search Queries (2 tools): list, stats - Search analytics and popular queries

Changed

• Total tools increased from 86 to 108

[1.0.1] - 2026-01-31

Fixed

• Users: Adapted to Outline schema - use role enum instead of isAdmin/isViewer/isSuspended booleans
• Users: Removed non-existent username column
• Groups: Fixed group_users table queries - no deletedAt column, composite PK
• Groups: Fixed ambiguous column references in subqueries
• Attachments: Removed non-existent url and deletedAt columns
• Attachments: Changed delete to hard delete (no soft delete support)
• Auth: Use suspendedAt IS NOT NULL for suspended count, return role instead of isAdmin
• Comments: Use role='admin' for admin user queries
• Documents: Use suspendedAt IS NULL for active user checks
• Events: Return actorRole instead of actorIsAdmin
• Shares: Use role='admin' for admin user queries

Changed

• Users suspend/activate now use suspendedAt column instead of boolean
• Groups member count uses correct join without deletedAt filter
• All modules validated against Outline v0.78 PostgreSQL schema

[1.0.0] - 2026-01-31

Added

• Initial release of MCP Outline PostgreSQL
• 86 tools across 12 modules for direct PostgreSQL access to Outline Wiki
• Documents (19 tools): CRUD, search, archive, move, templates, memberships
• Collections (14 tools): CRUD, user/group memberships, export
• Users (9 tools): CRUD, suspend, activate, promote, demote
• Groups (8 tools): CRUD, memberships management
• Comments (6 tools): CRUD, resolve functionality
• Shares (5 tools): CRUD, revoke public links
• Revisions (3 tools): list, info, compare versions
• Events (3 tools): audit log, statistics
• Attachments (5 tools): CRUD, storage statistics
• File Operations (4 tools): import/export job management
• OAuth (8 tools): OAuth clients and authentications
• Auth (2 tools): authentication info and config
• PostgreSQL client with connection pooling
• Rate limiting and security utilities
• Full TypeScript implementation with type safety
• MCP SDK v1.0.0 compatibility

Technical

• Direct SQL access (not Outline API) for better performance
• Parameterized queries for SQL injection protection
• Soft delete support across all entities
• Full-text search using PostgreSQL tsvector
• Pagination and sorting on all list operations

---

Developed by Descomplicar® | descomplicar.pt