MCP Worklog Server

A standalone Model Context Protocol (MCP) server for a local work journal (Worklog). Written in Python 3.12, designed to run in WSL (Ubuntu 24.04), and optimized for airgapped environments (no uv dependency, uses standard venv and pip).

Project Structure

mcp-worklog/
├── requirements.txt      # Dependencies (mcp SDK)
├── mcp_config.json       # MCP client configuration template
├── system_prompt.md      # Prompt for your AI assistant
├── src/
│   ├── __init__.py       # Package marker
│   ├── server.py         # MCP entrypoint and FastMCP tools definition
│   └── worklog.py        # Core logic (file reading, writing, searching)
├── logs/
│   └── index.json        # Auto-updated JSON index of dates and categories
└── tests/
    └── verify_worklog.py # Local verification script

Setup Instructions for WSL (Ubuntu)

Execute these commands in your WSL Ubuntu terminal to initialize the project:

1. Create the Project Directory

mkdir -p ~/mcp-worklog
cd ~/mcp-worklog

(If you are working out of a mounted Windows directory, change directory to it, e.g., cd /mnt/d/dev/mcp-worklog)

2. Set Up Virtual Environment & Dependencies

Initialize a standard Python 3.12 virtual environment and install the required MCP library:

# Update package list and ensure python3-venv is installed (if needed)
sudo apt update
sudo apt install -y python3.12-venv python3-pip

# Create virtual environment named .venv
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate

# Upgrade pip inside venv
pip install --upgrade pip

# Install dependencies (MCP SDK)
pip install mcp

3. Setup Project Files

Create the directory structure:

mkdir -p src logs tests

Place the files (src/worklog.py, src/server.py, requirements.txt, etc.) in their respective locations.

4. Verify Setup

Run the verification script to test the core logic:

python tests/verify_worklog.py

---

MCP Configuration (for Jan.ai, Claude Desktop, etc.)

To register this MCP server in Windows applications, use the following snippet in your client's configuration file (e.g., config.json or mcp_config.json). It uses wsl to directly execute Python inside the WSL environment.

{
  "mcpServers": {
    "worklog": {
      "command": "wsl",
      "args": [
        "/mnt/d/dev/mcp-worklog/.venv/bin/python3",
        "/mnt/d/dev/mcp-worklog/src/server.py"
      ],
      "env": {}
    }
  }
}

(Note: Replace /mnt/d/dev/mcp-worklog with the actual path to your project folder inside WSL).

---

System Prompt for Jan.ai / Opencode

To set up your AI assistant to act as a Worklog Assistant, paste the contents of system_prompt.md into the System Prompt text area of your AI client.

The prompt instructs the AI to:

1. Actively prompt you to log your tasks.
2. Read the existing logs first to prevent duplicate records.
3. Proofread drafts before writing.
4. Correctly categorize entries (e.g. Feature, Bugfix, Meeting, Refactoring, Documentation).