mcp-outline-postgresql/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server for direct PostgreSQL access to Outline Wiki database. Follows patterns established by mcp-desk-crm-sql-v3.

Architecture: Claude Code -> MCP Outline (stdio) -> PostgreSQL (Outline DB)

Total Tools: 164 tools across 33 modules

Commands

# Build TypeScript to dist/
npm run build

# Run production server
npm start

# Development with ts-node
npm run dev

# Run tests
npm test

Project Structure

src/
├── index.ts              # MCP entry point
├── pg-client.ts          # PostgreSQL client wrapper
├── config/
│   └── database.ts       # DB configuration
├── types/
│   ├── index.ts
│   ├── tools.ts          # Base tool types
│   └── db.ts             # Database table types
├── tools/
│   ├── index.ts          # Export all tools
│   ├── documents.ts      # 19 tools - Core document management
│   ├── collections.ts    # 14 tools - Collection management
│   ├── users.ts          # 9 tools - User management
│   ├── groups.ts         # 8 tools - Group management
│   ├── comments.ts       # 6 tools - Comment system
│   ├── shares.ts         # 5 tools - Document sharing
│   ├── revisions.ts      # 3 tools - Version history
│   ├── events.ts         # 3 tools - Audit log
│   ├── attachments.ts    # 5 tools - File attachments
│   ├── file-operations.ts # 4 tools - Import/export jobs
│   ├── oauth.ts          # 8 tools - OAuth management
│   ├── auth.ts           # 2 tools - Authentication
│   ├── stars.ts          # 3 tools - Bookmarks
│   ├── pins.ts           # 3 tools - Pinned documents
│   ├── views.ts          # 2 tools - View tracking
│   ├── reactions.ts      # 3 tools - Emoji reactions
│   ├── api-keys.ts       # 4 tools - API keys
│   ├── webhooks.ts       # 4 tools - Webhooks
│   ├── backlinks.ts      # 1 tool - Link references
│   ├── search-queries.ts # 2 tools - Search analytics
│   ├── teams.ts          # 5 tools - Team/workspace
│   ├── integrations.ts   # 6 tools - External integrations
│   ├── notifications.ts  # 4 tools - Notifications
│   ├── subscriptions.ts  # 4 tools - Subscriptions
│   ├── templates.ts      # 5 tools - Templates
│   ├── imports-tools.ts  # 4 tools - Import jobs
│   ├── emojis.ts         # 3 tools - Custom emojis
│   ├── user-permissions.ts # 3 tools - Permissions
│   ├── bulk-operations.ts # 6 tools - Batch operations
│   ├── advanced-search.ts # 6 tools - Advanced search
│   ├── analytics.ts      # 6 tools - Analytics
│   ├── export-import.ts  # 2 tools - Markdown export/import
│   └── desk-sync.ts      # 2 tools - Desk CRM integration
└── utils/
    ├── logger.ts
    └── security.ts

Tools Summary (164 total)

Module	Tools	Description
documents	19	CRUD, search, archive, move, templates, memberships
collections	14	CRUD, memberships, groups, export
users	9	CRUD, suspend, activate, promote, demote
groups	8	CRUD, memberships
comments	6	CRUD, resolve
shares	5	CRUD, revoke
revisions	3	list, info, compare
events	3	list, info, stats
attachments	5	CRUD, stats
file-operations	4	import/export jobs
oauth	8	OAuth clients, authentications
auth	2	auth info, config
stars	3	list, create, delete (bookmarks)
pins	3	list, create, delete (highlighted docs)
views	2	list, create (view tracking)
reactions	3	list, create, delete (emoji on comments)
api-keys	4	CRUD (programmatic access)
webhooks	4	CRUD (event subscriptions)
backlinks	1	list (document links - read-only view)
search-queries	2	list, stats (search analytics)
teams	5	get, update, stats, domains, settings
integrations	6	list, get, create, update, delete, sync
notifications	4	list, mark read, mark all read, settings
subscriptions	4	list, subscribe, unsubscribe, settings
templates	5	list, get, create from, convert to/from
imports	4	list, status, create, cancel
emojis	3	list, create, delete
user-permissions	3	list, grant, revoke
bulk-operations	6	archive, delete, move, restore, add/remove users
advanced-search	6	advanced search, facets, recent, user activity, orphaned, duplicates
analytics	6	overview, user activity, content insights, collection stats, growth, search
export-import	2	export collection to markdown, import markdown folder
desk-sync	2	create desk project doc, link desk task

Configuration

Add to ~/.claude.json under mcpServers:

{
  "outline": {
    "command": "node",
    "args": ["/home/ealmeida/mcp-servers/mcp-outline-postgresql/dist/index.js"],
    "env": {
      "DATABASE_URL": "postgres://outline:password@localhost:5432/outline"
    }
  }
}

Environment

Required in .env:

DATABASE_URL=postgres://user:password@host:port/outline

Key Patterns

Tool Response Format

return {
  content: [{
    type: 'text',
    text: JSON.stringify(data, null, 2)
  }]
};

Naming Conventions

Type	Convention	Example
Tool name	snake_case with prefix	outline_list_documents
Function	camelCase	listDocuments
Type	PascalCase	DocumentRow
File	kebab-case	documents.ts

Database

PostgreSQL 15 - Direct SQL access (not Outline API)

Key tables: documents, collections, users, groups, comments, revisions, shares, attachments, events, stars, pins, views, file_operations, oauth_clients

Soft deletes: Most entities use deletedAt column, not hard deletes.

See SPEC-MCP-OUTLINE.md for complete database schema.