mdclient/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

mdclient is a Python library for interacting with Markdown note services (CodiMD, HedgeDoc, HackMD). The project is designed as a Python-first library with an optional CLI tool for quick operations.

Key Design Principle: Library-first architecture - all functionality is exposed through Python APIs (MDAuth, MDClient classes), with the CLI tool (mdclient_cli.py) being a thin wrapper that uses these APIs.

Architecture

Core Components

1. mdclient/ - Main Python package

   • MDAuth class (auth.py) - Handles authentication and session management
   • MDClient class (client.py) - All note operations (CRUD + export/search)
   • __init__.py - Package entry point, exports MDClient and MDAuth

2. mdclient_cli.py - Optional CLI tool

   • Standalone script that imports and uses the mdclient package
   • Supports .env file integration for credentials
   • Not installed as a package command (run directly with python3 mdclient_cli.py)

Session Management Pattern

The library uses a cookie-based session system:

• MDAuth.login() - Authenticates and saves cookies to a JSON file (key.conf by default)
• MDClient._load_cookie() - Automatically loads cookies for each request
• Cookies are stored in simple JSON format: {"connect.sid": "...", "_csrf": "..."}

Multi-Endpoint Strategy

Both authentication and note operations attempt multiple API endpoints to handle different server implementations:

• Login: /login, /auth/login, /api/login, /signin
• Note retrieval: /api/notes/{id}, /api/notes/{id}/content, /{id}/download, /{id}
• Note listing: /api/me/notes, /api/notes, /history, /me/notes

This pattern is essential for compatibility across different Markdown note service implementations.

Development Commands

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Code formatting (line length: 100)
black mdclient/

# Type checking
mypy mdclient/

# Install with .env support
pip install -e ".[env]"

Testing Authentication

When working on authentication-related features, test with:

# Test if current cookie is valid
python3 mdclient_cli.py test

# Login with credentials
python3 mdclient_cli.py login

# Or use Python directly
python3 -c "from mdclient import MDAuth; MDAuth().test_cookie()"

Language and Localization

Important: All user-facing text and documentation must use Traditional Chinese (Taiwan) with natural, direct expression. Avoid translationese and mainland Chinese terminology.

Common term mappings:

• 登录 → 登入
• 服务器 → 伺服器
• 地址 → 位址
• 保存 → 儲存
• 文件 → 檔案
• 导入 → 匯入
• 导出 → 匯出
• 创建 → 建立
• 获取 → 取得
• 用户 → 使用者
• 邮箱 → 信箱
• 请求 → 請求
• 响应 → 回應

Environment Variables

The library supports these environment variables (typically set in .env file):

• MDCLIENT_URL - Server URL
• MDCLIENT_EMAIL - Login email
• MDCLIENT_PASSWORD - Login password
• MDCLIENT_COOKIE_FILE - Cookie file path (default: key.conf)

Key API Patterns

When adding new note operations or endpoints:

1. Always try multiple endpoints - Different services use different API patterns
2. Handle both JSON and text responses - Some endpoints return HTML/Markdown directly
3. Return None on failure - Consistent error handling pattern
4. Print status messages - Users expect feedback during operations
5. Use Taiwan Traditional Chinese - For all user-facing messages

Common Patterns

Adding a New Note Operation

def new_operation(self, param: str) -> Optional[Dict]:
    """
    新操作的簡短描述

    Args:
        param: 參數說明

    Returns:
        操作結果，失敗時返回 None
    """
    print(f"正在執行操作: {param}")

    # 嘗試多個可能的端點
    endpoints = ['/api/endpoint1', '/api/endpoint2']

    for endpoint in endpoints:
        response = self._request('GET', endpoint)
        if response and response.status_code == 200:
            try:
                data = response.json()
                print("✓ 操作成功")
                return data
            except json.JSONDecodeError:
                # 處理非 JSON 回應
                pass

    print("✗ 操作失敗")
    return None

CLI Command Pattern

CLI commands in mdclient_cli.py should:

1. Load .env file automatically
2. Support both command-line args and environment variables
3. Use MDClient and MDAuth classes (no direct HTTP requests)
4. Provide clear success/failure messages

Package Structure

mdclient/
├── mdclient/           # Core library (Python package)
│   ├── __init__.py    # Exports MDClient, MDAuth
│   ├── auth.py        # Authentication logic
│   └── client.py      # Note operations API
├── mdclient_cli.py    # CLI tool (uses mdclient package)
├── pyproject.toml     # Package configuration
├── example.py         # Usage examples
└── .env.example       # Environment variable template

Important Notes

• The library uses requests for HTTP operations with timeout=10 on all requests
• Cookie files are stored as JSON in the current working directory
• The CLI tool is meant for quick operations, not programmatic use
• All methods print status messages to stdout for user feedback
• Error handling returns None rather than raising exceptions