Article Manager
A complete full-stack TypeScript monolithic article management system designed for AI agents to save and manage research content. This self-hosted single-user POC system handles hundreds of markdown articles with multiple interfaces: Web UI, REST API, and MCP server.
Features
š Markdown-based articles with frontmatter support
š Search functionality with partial title matching
šØ Dark/Light theme toggle
š± Mobile-first responsive design
š Bearer token authentication for all interfaces
š REST API for programmatic access
š¤ MCP server integration for AI agent access
š³ Docker support with multi-stage builds and non-root user
ā” Bun runtime for fast TypeScript execution
š Request logging for monitoring and debugging
Architecture
Monolithic Structure
Technology Stack
Runtime: Bun (fast TypeScript execution)
Backend: TypeScript, @modelcontextprotocol/sdk
Frontend: React, react-markdown
Storage: File-based markdown with frontmatter
Deployment: Docker with oven/bun base image
Quick Start
Prerequisites
Bun installed (v1.0+)
Docker and Docker Compose (for containerized deployment)
Development Setup
1. Clone and install dependencies
2. Configure environment
3. Run development servers
Terminal 1 (Backend):
Terminal 2 (Frontend):
4. Access the application
Web UI: http://localhost:5000
To test the MCP Server you can use the MCP inspector
Production Build
Docker Deployment
Using Docker Compose (Recommended)
1. Configure environment
2. Start the container
3. View logs
4. Stop the container
Using Docker directly
GitHub Container Registry
To push to GitHub Container Registry:
Environment Variables
Variable | Required | Default | Description |
| Yes | - | Authentication token for all interfaces |
| No |
| Directory where markdown articles are stored |
| No |
| Server port |
| No |
| Environment mode |
REST API Documentation
All API endpoints require Bearer token authentication via the Authorization
header:
Endpoints
Health Check
Returns server health status (no auth required).
Response:
List Articles
Returns all articles with metadata, sorted by creation date (newest first).
Response:
Search Articles
Search articles by title (partial match, case-insensitive).
Query Parameters:
q
- Search query string
Response:
Read Article
Read a single article by filename.
Response:
Error Response (404):
Create Article
Creates a new article. Filename is auto-generated from title (e.g., "My New Article" ā "my-new-article.md").
Response (201):
Error Response (400):
Update Article
Updates an existing article. Preserves original creation date.
Response:
Delete Article
Deletes an article.
Response:
Authentication Errors
All authenticated endpoints return 401 for invalid/missing tokens:
MCP Server Documentation
The MCP (Model Context Protocol) server provides AI agents with tools to manage articles.
Endpoint
Available Tools
listArticles
List all articles with metadata.
Input Schema:
Response:
searchArticles
Search articles by title.
Input Schema:
readArticle
Read a single article.
Input Schema:
createArticle
Create a new article.
Input Schema:
updateArticle
Update an existing article.
Input Schema:
deleteArticle
Delete an article.
Input Schema:
List Available Tools
Article Format
Articles are stored as markdown files with YAML frontmatter:
Filename Generation
User provides title when creating articles
Filename is auto-generated: "My Article Name" ā "my-article-name.md"
Title is extracted from first
#
heading in markdown for displayFilename may differ from displayed title
Frontmatter Fields
title
: Article title (string)created
: ISO 8601 timestamp (string)
If frontmatter is missing, the system falls back to file system timestamps.
Web UI Usage
Login
Navigate to http://localhost:5000
Enter your AUTH_TOKEN
Click "Login"
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
File Structure
Troubleshooting
Port already in use
Permission denied on data directory
Docker build fails
Frontend not loading
Limitations
Single user only (no multi-tenancy)
Optimized for hundreds of articles (not thousands)
Simple partial text search (no full-text indexing)
Manual article creation (paste markdown)
No image uploads or media management
No tags, categories, or advanced metadata
File-based storage only (no database)
Bearer token auth only (no OAuth, sessions)
Single Docker container (not microservices)
Security Considerations
Store AUTH_TOKEN securely (use environment variables)
Use HTTPS in production (reverse proxy recommended)
Regularly backup the data directory
Keep dependencies updated
Docker container runs as non-root user (UID 1001) for security
Request logging enabled for monitoring and audit trails
License
MIT License - feel free to use and modify as needed.
Contributing
This is a POC project. For production use, consider:
Adding database support for better scalability
Implementing full-text search (e.g., Elasticsearch)
Adding user management and roles
Implementing rate limiting
Adding comprehensive test coverage
Setting up CI/CD pipelines
Support
For issues and questions, please open an issue on the GitHub repository.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables AI agents to save, search, and manage markdown-based research articles through a complete CRUD interface. Supports creating, reading, updating, and deleting articles with frontmatter metadata in a self-hosted file-based system.