MCP Markdown Manager

A complete full-stack TypeScript monolithic markdown article management system designed for AI agents to save and manage research content. This self-hosted single-user system handles hundreds of markdown articles with PostgreSQL database backend and multiple interfaces: Web UI, REST API, and MCP server.

🔒 Security

This project implements comprehensive security measures. See our detailed security documentation:

• Security Guide - Security best practices, configuration, and hardening

Key security features:

• Scoped access token system with read-only and write permissions
• Separate admin authentication (AUTH_TOKEN) and API/MCP access tokens
• Cryptographically secure token generation with sk-md- prefix
• Bearer token authentication for all interfaces
• Input validation and sanitization
• Rate limiting and DoS protection
• Parameterized database queries (SQL injection prevention)
• Path traversal prevention
• Session management with configurable limits and timeouts
• Security event logging
• Non-root container execution
• Request size limits

Features

• 📝 Database-backed articles with structured metadata storage
• 📁 Folder organization for hierarchical article structure
• 🔍 Search functionality with title and content search
• 🧠 Semantic search with RAG-style vector embeddings (optional)
• 📚 Version history with comprehensive change tracking
• 🎨 Dark/Light theme toggle
• 📱 Mobile-first responsive design
• 📲 Progressive Web App (PWA) support for offline access
• 🔐 Scoped access token system with read-only and write permissions
• 🌐 REST API for programmatic access
• 🤖 MCP server integration for AI agent access
• 🐳 Docker support with PostgreSQL integration
• ⚡ Bun runtime for fast TypeScript execution
• 📊 Request logging for monitoring and debugging
• 📦 Import utility for migrating existing markdown files

Architecture

Monolithic Structure

/src
  /backend
    /routes      - REST API endpoints
    /mcp         - MCP server tools
    /services    - Shared business logic (articles CRUD)
    /middleware  - Auth, error handling
    server.ts    - Main server (API + MCP + static serving)
  /frontend
    /components  - React components
    /pages       - Page components
    /styles      - CSS files
    App.tsx

Technology Stack

• Runtime: Bun (fast TypeScript execution)
• Backend: TypeScript, @modelcontextprotocol/sdk
• Frontend: React, react-markdown
• Database: PostgreSQL with pgvector extension
• Storage: Database-backed with structured metadata
• Deployment: Docker with PostgreSQL integration

Quick Start

Prerequisites

• Bun installed (v1.0+)
• Docker and Docker Compose (for containerized deployment)
• PostgreSQL 12+ with pgvector extension (for local development)

Development Setup

1. Clone and install dependencies

cd article_manager
bun install

2. Configure environment

cp .env.example .env
# Edit .env and set your AUTH_TOKEN (used for web UI admin login only)

3. Start database

# Start PostgreSQL with Docker
bun run dc:db

Note: The application automatically initializes the database schema on startup.

4. Run development servers

Using docker is easiest

bun run dc:ui

If you want to run locally without docker

# Start backend server
bun run dev:backend
# In another terminal, start frontend dev server
bun run dev:frontend

5. Access the application and generate API keys

• Web UI: http://localhost:5000
• Log in with your AUTH_TOKEN
• Navigate to Settings (⚙️) to generate access tokens for API/MCP access
• Use generated tokens for API: http://localhost:5000/api/*
• Use generated tokens for MCP: http://localhost:5000/mcp

6. Import existing articles (optional)

If you have existing markdown files to import:

# Validate import first
bun run import validate ./path/to/markdown/files

# Import with interactive conflict resolution
bun run import import ./path/to/markdown/files --conflict interactive

To test the MCP Server you can use the MCP inspector

npx @modelcontextprotocol/inspector

MCP Testing

You can test the MCP server using the MCP Inspector tool:

bun run dc:db
bun run dc:ui
bun run mcp:inspect

# when you are done Ctrl+C to stop the inspector then
docker compose down

This will open the MCP Inspector connected to your running MCP Markdown Manager instance. To connect you will need the AUTH_TOKEN and PORT you set in your .env file.

Production Build

# Build frontend
bun run build

# Start production server
bun run start

Progressive Web App (PWA)

The MCP Markdown Manager includes full PWA support, allowing you to:

• Install the app on your device (mobile or desktop)
• Work offline with cached articles and assets
• Access the app from your home screen like a native app

Installation

When you visit the web app in a supported browser, you'll see an install prompt. Click "Install" to add it to your home screen or desktop.

Alternatively, you can manually install:

• Chrome/Edge: Click the install icon in the address bar
• Safari (iOS): Tap the Share button → "Add to Home Screen"
• Firefox: Look for the install banner at the bottom of the page

PWA Features

• Offline Mode: Service worker caches static assets and API responses
• App-like Experience: Runs in standalone mode without browser UI
• Custom Icons: Optimized icons for different screen sizes (192x192, 512x512)
• Theme Integration: Matches your selected dark/light theme preference

Technical Details

The PWA implementation includes:

• manifest.json - Web app manifest with metadata and icons
• sw.js - Service worker for offline caching and asset management
• PWA meta tags in HTML for proper installation behavior
• Automatic service worker registration on app load

Docker Deployment

Using Docker Compose (Recommended)

1. Configure environment

cp .env.example .env
# Edit .env and set AUTH_TOKEN

2. Start the container

docker-compose up -d

3. View logs

docker-compose logs -f

4. Stop the container

docker-compose down

Using Docker directly

# Build image
docker build -t article-manager .

# Run container
docker run -d \
  -p 5000:5000 \
  -e AUTH_TOKEN=your-secret-token \
  -v $(pwd)/data:/data \
  --name article-manager \
  article-manager

Nginx Subpath Deployment

For deployment behind nginx on a subpath (e.g., /md, /articles):

Quick Start with Subpath

# 1. Configure environment for subpath
cp .env.example .env
echo "BASE_URL=http://localhost/md" >> .env

# 2. Deploy with nginx proxy
docker-compose -f docker-compose.subpath.yml up -d

# 3. Access application
# http://localhost/md

Production Deployment with SSL

# 1. Configure production environment
cp .env.example .env.production
# Edit .env.production with production values
echo "BASE_URL=https://yourdomain.com/articles" >> .env.production

# 2. Place SSL certificates in ./ssl/ directory
mkdir ssl
# Copy cert.pem and key.pem to ssl/

# 3. Deploy production stack
docker-compose -f docker-compose.production.yml --env-file .env.production up -d

# 4. Access application
# https://yourdomain.com/articles

Available Deployment Configurations

• docker-compose.yml - Standard deployment (root path)
• docker-compose.subpath.yml - Nginx subpath deployment with HTTP
• docker-compose.production.yml - Production deployment with SSL and security features

See the Deployment Examples guide for more deployment scenarios and the Nginx Subpath Deployment Guide for detailed configuration instructions.

GitHub Container Registry

To push to GitHub Container Registry:

# Build and tag
docker build -t ghcr.io/YOUR_USERNAME/article-manager:latest .

# Login to GHCR
echo $GITHUB_TOKEN | docker login ghcr.io -u YOUR_USERNAME --password-stdin

# Push
docker push ghcr.io/YOUR_USERNAME/article-manager:latest

Environment Variables

Required Variables

Authentication System

The application uses a two-tier authentication system:

1. Admin Authentication (AUTH_TOKEN):

   • Used exclusively for web UI admin login
   • Set via environment variable
   • Grants access to Settings page for token management

2. Access Tokens (Generated via Settings):

   • Used for API and MCP server access
   • Generated through the Settings page in web UI
   • Scoped permissions:
     • read-only: Can list, read, and search articles
     • write: Full access (read + create/update/delete)
   • Prefixed with sk-md- for identification
   • Can be named, viewed (masked), and revoked
   • Track last usage timestamp

Migration Note: After upgrading, API and MCP endpoints use scoped access tokens by default. For backward compatibility, existing MCP/API integrations using AUTH_TOKEN may continue to work via a temporary fallback, but this behavior is deprecated and will be removed in a future release. Log into the web UI and generate new access tokens in the Settings page, then update your integrations to use those tokens.

Base Path Configuration (Nginx Subpath Deployment)

The application supports runtime base path configuration for deployment behind nginx on subpaths (e.g., /md, /articles). This allows the same built frontend assets to work with different deployment paths without rebuilding.

Configuration Priority: BASE_URL takes precedence if both are set. The path portion is extracted from BASE_URL.

Path Normalization: The system automatically normalizes paths:

• md → /md
• /md/ → /md
• app/docs → /app/docs

Default Behavior: If neither variable is set, the application runs at root path (/).

Runtime Configuration: The base path is injected into the frontend at request time, enabling deployment flexibility without rebuilding assets.

Documentation:

• Nginx Subpath Deployment Guide - Comprehensive nginx configuration and deployment instructions
• Deployment Examples - Quick deployment examples for different scenarios

Database Configuration

Application Configuration

Semantic Search (Optional)

Semantic Search (RAG)

The system supports optional semantic search using vector embeddings for more intelligent content discovery. When enabled, articles are automatically chunked and embedded, allowing similarity-based search across content.

Setup

1. Enable semantic search in your .env:

   SEMANTIC_SEARCH_ENABLED=true
   

2. Choose an embedding provider:

   Option A: Ollama (Local, Recommended)

   EMBEDDING_PROVIDER=ollama
   EMBEDDING_MODEL=nomic-embed-text
   OLLAMA_BASE_URL=http://localhost:11434
   

   First, install and start Ollama:

   # Install Ollama (see https://ollama.ai)
   curl -fsSL https://ollama.ai/install.sh | sh
   
   # Pull the embedding model
   ollama pull nomic-embed-text
   

   Option B: OpenAI

   EMBEDDING_PROVIDER=openai
   EMBEDDING_MODEL=text-embedding-3-small
   OPENAI_API_KEY=your-api-key-here
   

3. Build the initial index:

   bun run reindex
   

   This will process all existing articles and create the vector index at DATA_DIR/index.vectors.jsonl.

How It Works

• Automatic indexing: New articles are automatically chunked and embedded on creation/update
• Chunk-based: Articles are split by headings and then into smaller chunks with overlap
• Vector storage: Embeddings stored in JSONL format (index.vectors.jsonl) in data directory
• Cosine similarity: Search uses cosine similarity to find relevant chunks
• Heading context: Results include the heading path for better context

Using Semantic Search

Web UI: Toggle between "Title Search" and "Semantic Search" in the search form

REST API:

GET /api/search?query=your+search&k=5
Authorization: Bearer YOUR_TOKEN

MCP Tool:

{
  "method": "tools/call",
  "params": {
    "name": "semanticSearch",
    "arguments": {
      "query": "your search query",
      "k": 5
    }
  }
}

Reindexing

If you change embedding models or need to rebuild the index:

bun run reindex

Database Management

The system uses PostgreSQL with pgvector extension for structured storage and semantic search capabilities.

Database Commands

Note: The application automatically initializes the schema on startup. These commands are for manual management.

# Manually initialize/update database schema
bun run db:init

# Check database health and connectivity
bun run db:health

# Get database information and statistics
bun run db:info

# Verify database schema and constraints
bun run db:verify

# Create database backup
bun run db:backup

# Restore from backup
bun run db:restore ./backups/backup-file.sql

# Reset database (WARNING: destroys all data)
bun run db:reset --confirm

Database Schema

The system uses three main tables:

• articles: Core article data with metadata fields
• article_history: Version history for all article changes
• embeddings: Vector embeddings for semantic search

Import Utility

The import utility allows migration from file-based markdown systems or bulk import of existing content.

Import Commands

# Validate import without making changes
bun run import validate ./markdown-directory

# Preview what would be imported
bun run import preview ./markdown-directory --preserve-folders

# Import with interactive conflict resolution
bun run import import ./markdown-directory --conflict interactive

# Import with automatic conflict handling
bun run import import ./markdown-directory --conflict skip --preserve-folders

# Get import statistics
bun run import stats ./markdown-directory

Import Options

• --preserve-folders: Maintain directory structure as article folders
• --conflict <action>: Handle conflicts (skip, rename, overwrite, interactive)
• --batch-size <n>: Process files in batches (default: 50)
• --dry-run: Show what would be imported without making changes
• --use-title-slug: Generate slugs from titles instead of filenames

Import Process

1. Validation: Scans directory for .md files and validates format
2. Conflict Detection: Identifies duplicate titles or slugs
3. Frontmatter Processing: Extracts YAML frontmatter into database fields
4. Content Cleaning: Stores pure markdown without frontmatter
5. Batch Import: Processes files in configurable batches
6. Progress Reporting: Shows real-time import progress

Migration from File-Based System

If migrating from the previous file-based version:

1. Backup existing data:

   cp -r ./data ./data-backup-$(date +%Y%m%d)
   

2. Validate migration:

   bun run import validate ./data
   

3. Import with conflict resolution:

   bun run import import ./data --conflict interactive --preserve-folders
   

4. Verify import:

   bun run db:health
   bun run db:info
   

REST API Documentation

All API endpoints require Bearer token authentication via the Authorization header using an access token generated from the Settings page:

Authorization: Bearer sk-md-your-access-token-here

Scope Requirements:

• Read operations (GET): Require read-only or write scope
• Write operations (POST/PUT/DELETE): Require write scope
• Token management: Requires web UI admin login (AUTH_TOKEN)

Access Token Management

List Access Tokens

GET /api/access-tokens
Authorization: Bearer YOUR_AUTH_TOKEN

List all access tokens with masked values. Requires web UI admin authentication.

Response:

[
  {
    "id": 1,
    "name": "Claude Desktop",
    "scope": "write",
    "created_at": "2025-01-15T10:30:00Z",
    "last_used_at": "2025-01-15T12:00:00Z",
    "masked_token": "sk-md-****...a1b2"
  }
]

Create Access Token

POST /api/access-tokens
Authorization: Bearer YOUR_AUTH_TOKEN
Content-Type: application/json

{
  "name": "Production API",
  "scope": "read-only"
}

Generate a new access token. Requires web UI admin authentication. The full token is returned only once.

Response (201):

{
  "id": 2,
  "token": "sk-md-1234567890abcdef...",
  "name": "Production API",
  "scope": "read-only",
  "created_at": "2025-01-15T10:30:00Z"
}

Delete Access Token

DELETE /api/access-tokens/:id
Authorization: Bearer YOUR_AUTH_TOKEN

Revoke an access token by ID. Requires web UI admin authentication.

Endpoints

Health Check

GET /health

Returns server health status (no auth required).

Response:

{
  "status": "ok"
}

List Articles

GET /api/articles

Returns all articles with metadata, sorted by creation date (newest first).

Response:

[
  {
    "filename": "my-article.md",
    "title": "My Article",
    "created": "2025-01-15T10:30:00Z"
  }
]

Search Articles

GET /api/articles?q=search+term

Search articles by title (partial match, case-insensitive).

Query Parameters:

• q - Search query string

Response:

[
  {
    "filename": "matching-article.md",
    "title": "Matching Article",
    "created": "2025-01-15T10:30:00Z"
  }
]

Semantic Search

GET /api/search?query=search+query&k=5

Perform semantic search across article content using vector embeddings. Returns chunks of content ranked by similarity.

Query Parameters:

• query - Search query string (required)
• k - Number of results to return (default: 5)

Response:

[
  {
    "chunk": {
      "filename": "article.md",
      "title": "Article Title",
      "headingPath": ["# Main Heading", "## Subheading"],
      "text": "Full chunk text..."
    },
    "score": 0.85,
    "snippet": "Truncated preview of the chunk..."
  }
]

Note: Requires SEMANTIC_SEARCH_ENABLED=true in environment.

Read Article

GET /api/articles/:filename

Read a single article by filename.

Response:

{
  "filename": "my-article.md",
  "title": "My Article",
  "content": "Article content in markdown...",
  "created": "2025-01-15T10:30:00Z"
}

Error Response (404):

{
  "error": "Article not found"
}

Create Article

POST /api/articles
Authorization: Bearer sk-md-your-write-token
Content-Type: application/json

{
  "title": "My New Article",
  "content": "Article content in markdown..."
}

Creates a new article. Filename is auto-generated from title (e.g., "My New Article" → "my-new-article.md"). Requires write scope.

Response (201):

{
  "filename": "my-new-article.md",
  "title": "My New Article",
  "content": "Article content in markdown...",
  "created": "2025-01-15T10:30:00Z"
}

Error Response (400):

{
  "error": "Title and content are required"
}

Update Article

PUT /api/articles/:filename
Authorization: Bearer sk-md-your-write-token
Content-Type: application/json

{
  "title": "Updated Title",
  "content": "Updated content..."
}

Updates an existing article. Preserves original creation date. Requires write scope.

Response:

{
  "filename": "my-article.md",
  "title": "Updated Title",
  "content": "Updated content...",
  "created": "2025-01-15T10:30:00Z"
}

Delete Article

DELETE /api/articles/:filename
Authorization: Bearer sk-md-your-write-token

Deletes an article. Requires write scope.

Response:

{
  "success": true
}

Authentication Errors

All authenticated endpoints return 401 for invalid/missing tokens:

{
  "error": "Unauthorized"
}

MCP Server Documentation

The MCP (Model Context Protocol) server provides AI agents with tools to manage articles. Tools are filtered based on the access token's scope.

Endpoint

POST /mcp
Authorization: Bearer sk-md-your-access-token
Content-Type: application/json

Token Scopes

MCP tools are filtered based on access token scope:

Read-Only Scope - Available tools:

• listArticles - List all articles
• listFolders - List folder structure
• searchArticles - Search by title
• multiSearchArticles - Batch search
• readArticle - Read article content
• semanticSearch - Vector similarity search (if enabled)
• multiSemanticSearch - Batch semantic search (if enabled)

Write Scope - All read-only tools PLUS:

• createArticle - Create new articles
• updateArticle - Update existing articles
• deleteArticle - Delete articles

Available Tools

listArticles

List all articles with metadata.

Input Schema:

{
  "method": "tools/call",
  "params": {
    "name": "listArticles",
    "arguments": {}
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"filename\":\"article.md\",\"title\":\"Article\",\"created\":\"2025-01-15T10:30:00Z\"}]"
    }
  ]
}

searchArticles

Search articles by title.

Input Schema:

{
  "method": "tools/call",
  "params": {
    "name": "searchArticles",
    "arguments": {
      "query": "search term"
    }
  }
}

semanticSearch

Perform semantic search across article content using vector embeddings. Available when SEMANTIC_SEARCH_ENABLED=true.

Input Schema:

{
  "method": "tools/call",
  "params": {
    "name": "semanticSearch",
    "arguments": {
      "query": "search query",
      "k": 5
    }
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"chunk\":{\"filename\":\"article.md\",\"title\":\"Article\",\"headingPath\":[\"# Heading\"],\"text\":\"...\"},\"score\":0.85,\"snippet\":\"...\"}]"
    }
  ]
}

readArticle

Read a single article.

Input Schema:

{
  "method": "tools/call",
  "params": {
    "name": "readArticle",
    "arguments": {
      "filename": "my-article.md"
    }
  }
}

createArticle

Create a new article. Requires write scope.

Input Schema:

{
  "method": "tools/call",
  "params": {
    "name": "createArticle",
    "arguments": {
      "title": "New Article",
      "content": "Article content..."
    }
  }
}

updateArticle

Update an existing article. Requires write scope.

Input Schema:

{
  "method": "tools/call",
  "params": {
    "name": "updateArticle",
    "arguments": {
      "filename": "my-article.md",
      "title": "Updated Title",
      "content": "Updated content..."
    }
  }
}

deleteArticle

Delete an article. Requires write scope.

Input Schema:

{
  "method": "tools/call",
  "params": {
    "name": "deleteArticle",
    "arguments": {
      "filename": "my-article.md"
    }
  }
}

List Available Tools

{
  "method": "tools/list"
}

Using with Agent Zero

Agent Zero is an AI agent framework that supports MCP servers via the Streamable HTTP transport. To connect this MCP server to Agent Zero:

1. Start the MCP Markdown Manager with a configured AUTH_TOKEN:

   docker run -d -p 8097:5000 \
     -e AUTH_TOKEN="your-secret-token-here" \
     -e MCP_SERVER_ENABLED="true" \
     -v $(pwd)/data:/data \
     ghcr.io/joelmnz/mcp-markdown-manager:latest
   

2. Generate an access token:

   • Log into the web UI at http://localhost:8097 with your AUTH_TOKEN
   • Navigate to Settings (⚙️ icon)
   • Create a new access token:
     • Name: "Agent Zero"
     • Scope: "write" (for full access) or "read-only" (for search/read only)
   • Copy the generated token (it will only be shown once)

3. Configure Agent Zero by adding the following to your tmp/settings.json under the mcp_servers key:

   {
     "name": "mcp-markdown-manager",
     "description": "Markdown article manager for research and notes",
     "type": "streaming-http",
     "url": "http://localhost:8097/mcp",
     "headers": {
       "Authorization": "Bearer sk-md-your-generated-token-here"
     },
     "disabled": false
   }
   

   Important Notes:

   • Replace sk-md-your-generated-token-here with your actual access token from Settings
   • If running both Agent Zero and MCP server in Docker, use the appropriate network hostname instead of localhost
   • The type: "streaming-http" is required for proper MCP protocol support
   • The server uses the MCP Streamable HTTP transport specification with session management

4. Verify the connection by checking Agent Zero logs for successful tool discovery. Available tools depend on token scope:

   With write scope (7+ tools):

   • mcp_markdown_manager.listArticles
   • mcp_markdown_manager.searchArticles
   • mcp_markdown_manager.readArticle
   • mcp_markdown_manager.createArticle
   • mcp_markdown_manager.updateArticle
   • mcp_markdown_manager.deleteArticle
   • Plus semantic search tools if enabled

   With read-only scope (4+ tools):

   • mcp_markdown_manager.listArticles
   • mcp_markdown_manager.searchArticles
   • mcp_markdown_manager.readArticle
   • Plus semantic search tools if enabled

5. Use the tools by instructing Agent Zero, for example:

   • "Create a new article about Python decorators"
   • "List all my articles"
   • "Search for articles about machine learning"

Transport Details:

• The server implements the MCP Streamable HTTP transport protocol
• Session management is handled automatically with mcp-session-id headers
• POST requests are used for initialization and method calls
• GET requests establish Server-Sent Event (SSE) streams for real-time updates
• DELETE requests terminate sessions

Article Format

Articles are stored in PostgreSQL database with structured metadata fields and clean markdown content.

Database Storage

Articles are stored with the following structure:

• Metadata Fields: title, slug, folder, creation/modification dates, public status
• Content: Pure markdown without YAML frontmatter
• Version History: Complete change history with timestamps and messages
• Embeddings: Vector embeddings for semantic search (optional)

Article Creation

When creating articles:

• Title: User-provided or extracted from first # heading
• Slug: Auto-generated from title for URL compatibility
• Folder: Optional hierarchical organization (e.g., "projects/web-dev")
• Content: Clean markdown without frontmatter

Import Format

When importing existing markdown files, the system processes:

---
title: Article Title
created: 2025-01-15T10:30:00Z
folder: projects/web-dev
---

# Article Title

Article content goes here...

## Section

More content...

The frontmatter is extracted into database fields, and only the clean markdown content is stored.

Folder Organization

• Root Level: Articles without folder (folder = "")
• Nested Folders: Hierarchical structure (e.g., "projects/web-dev/react")
• Folder Filtering: Search and list articles by folder
• Folder Migration: Move articles between folders while preserving content

Web UI Usage

Login

1. Navigate to http://localhost:5000
2. Enter your AUTH_TOKEN (admin authentication)
3. Click "Login"

Settings (Access Token Management)

After logging in with AUTH_TOKEN:

1. Click the Settings icon (⚙️) in the header
2. Generate new access tokens:
   • Enter a descriptive name (e.g., "Claude Desktop", "Production API")
   • Choose scope: write (full access) or read-only (search/read only)
   • Click "Generate Access Token"
3. Important: Copy the token immediately - it will only be shown once
4. Use the generated token for API and MCP access
5. View existing tokens (masked for security)
6. Delete tokens to revoke access

Home Page

• View last 10 articles (newest first)
• Search articles by title
• Click "New Article" to create
• Click any article to view

Article View

• Read rendered markdown
• See creation date
• Click "Edit" to modify
• Click "Delete" to remove

Article Edit

• Edit title and content
• Live preview pane (desktop)
• Save or cancel changes

Theme Toggle

• Click sun/moon icon in header
• Switches between dark and light themes
• Preference saved in browser

Development

Project Scripts

# Install dependencies
bun install

# Development (backend)
bun run dev:backend

# Development (frontend)
bun run dev:frontend

# Build frontend
bun run build

# Production server
bun run start

# Type checking
bun run typecheck

File Structure

article_manager/
├── src/
│   ├── backend/
│   │   ├── middleware/
│   │   │   └── auth.ts          # Authentication middleware
│   │   ├── mcp/
│   │   │   └── server.ts        # MCP server implementation
│   │   ├── routes/
│   │   │   └── api.ts           # REST API routes
│   │   ├── services/
│   │   │   └── articles.ts      # Article CRUD logic
│   │   └── server.ts            # Main server
│   └── frontend/
│       ├── components/
│       │   ├── ArticleList.tsx  # Article list component
│       │   ├── Header.tsx       # Header with theme toggle
│       │   └── Login.tsx        # Login page
│       ├── pages/
│       │   ├── ArticleEdit.tsx  # Edit/create page
│       │   ├── ArticleView.tsx  # Article view page
│       │   └── Home.tsx         # Home page
│       ├── styles/
│       │   └── main.css         # All styles
│       └── App.tsx              # Main app component
├── public/                      # Built frontend (generated)
│   ├── manifest.json            # PWA manifest
│   ├── sw.js                    # Service worker
│   ├── icon-192.png             # PWA icon (192x192)
│   ├── icon-512.png             # PWA icon (512x512)
│   ├── index.html               # Main HTML (generated)
│   ├── App.[hash].js            # Bundled JS (generated)
│   └── App.[hash].css           # Bundled CSS (generated)
├── scripts/
│   ├── build-html.cjs           # Generate index.html
│   ├── generate-icons.cjs       # Generate PWA icons
│   └── watch-frontend.ts        # Frontend dev watcher
├── data/                        # Article storage (gitignored)
├── Dockerfile                   # Multi-stage Docker build
├── docker-compose.yml           # Docker Compose config
├── package.json                 # Dependencies and scripts
├── tsconfig.json                # TypeScript config
├── .env.example                 # Environment template
├── .gitignore                   # Git ignore rules
└── README.md                    # This file

Troubleshooting

Port already in use

# Find process using port 5000
lsof -i :5000

# Kill the process
kill -9 <PID>

Permission denied on data directory

# Fix permissions
chmod -R 755 ./data

Docker build fails

# Clean build cache
docker builder prune -a

# Rebuild without cache
docker-compose build --no-cache

Frontend not loading

# Rebuild frontend
bun run build

# Check if public/index.html exists
ls -la public/

Limitations

• Single user only (no multi-tenancy)
• Optimized for hundreds to thousands of articles
• Manual article creation (paste markdown or import)
• No image uploads or media management
• No tags or categories (use folders for organization)
• Bearer token auth only (no OAuth, sessions)
• Single Docker container deployment (not microservices)
• PostgreSQL dependency for all operations

Security Considerations

• Store AUTH_TOKEN securely (use environment variables, never commit to git)
• Generate unique access tokens for each integration/client
• Use read-only scope when possible to limit permissions
• Revoke unused tokens immediately in Settings page
• Copy access tokens immediately - they're only shown once at creation
• Use HTTPS in production (reverse proxy recommended)
• Monitor token usage via last_used_at timestamps in Settings
• Regularly backup the database (includes token data)
• Keep dependencies updated
• Docker container runs as non-root user (UID 99, GID 100 - UNRAID compatible) for security
• Request logging enabled for monitoring and audit trails

Token Security Best Practices

1. Never share AUTH_TOKEN - it grants admin access to token management
2. Use descriptive token names - helps identify which integration uses which token
3. Rotate tokens periodically - delete old tokens and generate new ones
4. Use read-only tokens for monitoring/search-only integrations
5. Audit token usage - check last_used_at to identify inactive tokens

License

MIT License - feel free to use and modify as needed.

Contributing

This project now includes database backend support. For enhanced production use, consider:

• Adding user management and multi-tenancy
• Implementing advanced full-text search features
• Adding role-based access control
• Implementing rate limiting and API quotas
• Adding comprehensive test coverage
• Setting up CI/CD pipelines
• Adding real-time collaboration features

Support

For issues and questions, please open an issue on the GitHub repository.