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:** 160 tools across 31 modules

## Commands

```bash
# 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
└── utils/
    ├── logger.ts
    └── security.ts
```

## Tools Summary (160 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 |

## Configuration

Add to `~/.claude.json` under `mcpServers`:

```json
{
  "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

```typescript
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.