# 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:** 86 tools across 12 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
│   ├── collections.ts    # 14 tools
│   ├── users.ts          # 9 tools
│   ├── groups.ts         # 8 tools
│   ├── comments.ts       # 6 tools
│   ├── shares.ts         # 5 tools
│   ├── revisions.ts      # 3 tools
│   ├── events.ts         # 3 tools
│   ├── attachments.ts    # 5 tools
│   ├── file-operations.ts # 4 tools
│   ├── oauth.ts          # 8 tools
│   └── auth.ts           # 2 tools
└── utils/
    ├── logger.ts
    └── security.ts
```

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

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