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