Emanuel Almeida
fa0e052620
New modules (22 tools): - 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): list, create, update, delete - Webhooks (4): list, create, update, delete - Backlinks (1): list - read-only view - Search Queries (2): list, stats - analytics Total tools: 86 -> 108 (+22) All 22 new tools validated against Outline v0.78 schema. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
139 lines
3.7 KiB
Markdown
139 lines
3.7 KiB
Markdown
# 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:** 108 tools across 20 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 (108 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) |
|
|
|
|
## 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.
|