mcp-outline-postgresql/CHANGELOG.md

# Changelog

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

## [1.3.13] - 2026-01-31

### Fixed

- **Document Listing (Final Fix):** Documents now appear in collection sidebar
  - Added `revisionCount = 1` (was 0, Outline filters these out)
  - Added `content` field with minimal ProseMirror JSON structure
  - Both fields required for documents to appear in listing

## [1.3.12] - 2026-01-31

### Fixed

- **Document Listing:** Documents now appear in collection sidebar
  - `collaboratorIds` must contain the creator's userId, not empty array
  - Documents with empty `collaboratorIds` don't appear in listing
  - Now uses `ARRAY[$userId]::uuid[]` to include creator

## [1.3.11] - 2026-01-31

### Fixed

- **Document collaboratorIds:** Added missing `collaboratorIds` field (empty array)
  - Error: `TypeError: b.collaboratorIds is not iterable`
  - Outline expects this field to be an array, not NULL

## [1.3.10] - 2026-01-31

### Fixed

- **Document urlId Format:** Fixed urlId generation to match Outline format
  - Was: 21-char hex string (e.g., `86734d15885647618cb16`)
  - Now: 10-char alphanumeric (e.g., `b0a14475ff`)
  - Documents with wrong urlId format returned 404 "Not found"

## [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

```bash
# 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*