Add Outline AI workflow guide
Documents how AI agents can interact with Outline wiki: - MCP server setup and available tools - REST API fallback methods - Common workflows for saving/searching docs - API key management Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alejandro Gutiérrez
259
docs/outline-ai-workflow.md
Normal file
259
docs/outline-ai-workflow.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# Outline AI Workflow Guide
|
||||
|
||||
**Date:** 2026-02-01
|
||||
**Purpose:** Document how AI agents can interact with Outline wiki for knowledge management
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Outline is the NUC's wiki/documentation system. AI agents can interact with it via:
|
||||
1. **MCP Server** (preferred) - `mcp-outline` for full CRUD operations
|
||||
2. **REST API** - Direct API calls when MCP not available
|
||||
3. **Browser Automation** - Playwriter fallback for UI-only features
|
||||
|
||||
---
|
||||
|
||||
## MCP Server Setup
|
||||
|
||||
### Installation
|
||||
|
||||
Added to `~/.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"outline": {
|
||||
"command": "uvx",
|
||||
"args": ["mcp-outline"],
|
||||
"env": {
|
||||
"OUTLINE_API_KEY": "<api-key>",
|
||||
"OUTLINE_API_URL": "http://192.168.1.3:3080/api"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Available MCP Tools
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| **Search & Discovery** | |
|
||||
| `search_documents` | Search by keywords with pagination |
|
||||
| `list_collections` | List all collections |
|
||||
| `get_collection_structure` | Get document hierarchy |
|
||||
| `get_document_id_from_title` | Find doc ID by title |
|
||||
| **Document Operations** | |
|
||||
| `read_document` | Get document content |
|
||||
| `create_document` | Create new document |
|
||||
| `update_document` | Update document (append mode available) |
|
||||
| `move_document` | Move to different collection/parent |
|
||||
| `export_document` | Export as markdown |
|
||||
| **Lifecycle** | |
|
||||
| `archive_document` | Archive a document |
|
||||
| `delete_document` | Delete or move to trash |
|
||||
| `restore_document` | Restore from trash |
|
||||
| **Batch Operations** | |
|
||||
| `batch_create_documents` | Create multiple docs |
|
||||
| `batch_update_documents` | Update multiple docs |
|
||||
| `batch_move_documents` | Move multiple docs |
|
||||
| **AI Features** | |
|
||||
| `ask_ai_about_documents` | Natural language queries |
|
||||
|
||||
---
|
||||
|
||||
## Collections
|
||||
|
||||
| Collection | ID | Purpose |
|
||||
|------------|-----|---------|
|
||||
| **NUC Docs** | `2a42945b-1a4f-4c92-add5-dfa147ef3f56` | Server documentation |
|
||||
| **Welcome** | (default) | Getting started guides |
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### 1. Save Session Findings to Wiki
|
||||
|
||||
When Claude discovers important information during a session:
|
||||
|
||||
```python
|
||||
# Using MCP (preferred)
|
||||
mcp__outline__create_document(
|
||||
title="Session Finding: <topic>",
|
||||
text="<markdown content>",
|
||||
collectionId="2a42945b-1a4f-4c92-add5-dfa147ef3f56", # NUC Docs
|
||||
publish=True
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Search Existing Documentation
|
||||
|
||||
Before solving a problem, check if solution exists:
|
||||
|
||||
```python
|
||||
# Search for relevant docs
|
||||
mcp__outline__search_documents(query="tailscale funnel setup")
|
||||
|
||||
# Read specific document
|
||||
mcp__outline__read_document(id="<doc-id>")
|
||||
```
|
||||
|
||||
### 3. Update Existing Documentation
|
||||
|
||||
When information changes:
|
||||
|
||||
```python
|
||||
# Find document
|
||||
doc_id = mcp__outline__get_document_id_from_title(title="Architecture")
|
||||
|
||||
# Update with new content
|
||||
mcp__outline__update_document(
|
||||
id=doc_id,
|
||||
text="<new content>",
|
||||
append=False # Replace content; True to append
|
||||
)
|
||||
```
|
||||
|
||||
### 4. Export for Backup
|
||||
|
||||
```python
|
||||
# Export single document
|
||||
mcp__outline__export_document(id="<doc-id>")
|
||||
|
||||
# Export entire collection
|
||||
mcp__outline__export_collection(id="2a42945b-1a4f-4c92-add5-dfa147ef3f56")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## REST API Fallback
|
||||
|
||||
When MCP is not available, use direct API calls:
|
||||
|
||||
### Authentication
|
||||
|
||||
```bash
|
||||
API_KEY="ol_api_..."
|
||||
curl -X POST 'http://192.168.1.3:3080/api/<endpoint>' \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '<json payload>'
|
||||
```
|
||||
|
||||
### Create Document
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://192.168.1.3:3080/api/documents.create' \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"title": "Document Title",
|
||||
"text": "Markdown content...",
|
||||
"collectionId": "2a42945b-1a4f-4c92-add5-dfa147ef3f56",
|
||||
"publish": true
|
||||
}'
|
||||
```
|
||||
|
||||
### Search Documents
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://192.168.1.3:3080/api/documents.search' \
|
||||
-H "Authorization: Bearer $API_KEY" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"query": "search term"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Key Management
|
||||
|
||||
### Generate New API Key
|
||||
|
||||
1. Navigate to: http://192.168.1.3:3080/settings/api-and-apps
|
||||
2. Click "New API key..."
|
||||
3. Set name and scopes:
|
||||
- `documents.create` - Create documents
|
||||
- `documents.update` - Update documents
|
||||
- `documents.read` - Read documents
|
||||
- `collections.read` - List collections
|
||||
- `collections.create` - Create collections
|
||||
4. Copy key immediately (shown only once)
|
||||
|
||||
### Current API Key
|
||||
|
||||
- **Name:** Docs Import 2
|
||||
- **Scopes:** documents.create, documents.update, collections.create, collections.read
|
||||
- **Expires:** Mar 03, 2026
|
||||
|
||||
---
|
||||
|
||||
## When to Use Outline
|
||||
|
||||
**DO save to Outline:**
|
||||
- Infrastructure documentation
|
||||
- Configuration guides
|
||||
- Troubleshooting procedures
|
||||
- Architecture decisions
|
||||
- Setup instructions
|
||||
- Persistent reference material
|
||||
|
||||
**DON'T save to Outline:**
|
||||
- Temporary session notes (use `.artifacts/`)
|
||||
- Sensitive credentials (use Vaultwarden)
|
||||
- One-time command outputs
|
||||
- Transient debugging info
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Systems
|
||||
|
||||
### From Gitea
|
||||
|
||||
NUC docs are also in Gitea at `http://192.168.1.3:3030/alezmad/nuc-docs`
|
||||
- Git repo is source of truth for docs
|
||||
- Outline provides searchable wiki interface
|
||||
- Sync manually when significant changes occur
|
||||
|
||||
### From n8n
|
||||
|
||||
Can automate Outline updates:
|
||||
- Webhook triggers on events
|
||||
- Scheduled documentation reviews
|
||||
- Auto-archive stale documents
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### MCP Connection Issues
|
||||
|
||||
```bash
|
||||
# Test API connectivity
|
||||
curl -s http://192.168.1.3:3080/api/auth.info \
|
||||
-H "Authorization: Bearer $API_KEY" | jq .ok
|
||||
```
|
||||
|
||||
### File Upload Limits
|
||||
|
||||
Outline file size limits (configured in Coolify env vars):
|
||||
- `FILE_STORAGE_UPLOAD_MAX_SIZE`: 100MB
|
||||
- `FILE_STORAGE_IMPORT_MAX_SIZE`: 100MB
|
||||
- `FILE_STORAGE_WORKSPACE_IMPORT_MAX_SIZE`: 100MB
|
||||
|
||||
### API Key Scope Errors
|
||||
|
||||
If "API key does not have access":
|
||||
1. Check key scopes in Settings > API & Apps
|
||||
2. Generate new key with required scopes
|
||||
3. Update `~/.claude/settings.json` with new key
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Architecture](./architecture.md) - NUC infrastructure overview
|
||||
- [MCP Research Guide](./mcp-research-guide.md) - Finding new MCPs
|
||||
- Outline API Docs: https://www.getoutline.com/developers
|
||||
- MCP Server: https://github.com/Vortiago/mcp-outline
|
||||
Reference in New Issue
Block a user