feat: Initial release MCP Outline PostgreSQL v1.0.0

86 tools across 12 modules for direct PostgreSQL access to Outline Wiki: - Documents (19), Collections (14), Users (9), Groups (8) - Comments (6), Shares (5), Revisions (3), Events (3) - Attachments (5), File Operations (4), OAuth (8), Auth (2) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-31 13:25:09 +00:00
commit b05b54033f
30 changed files with 14439 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,130 @@
+# 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.