chronicle-mcp-server 1.1.1

Local MCP server to sync, clean, and index AI chat logs locally. Saves up to 40% context tokens.

Chronicle: Universal Chat Connector Model Context Protocol Server

Chronicle is a production-grade Model Context Protocol (MCP) server designed to sync, clean, format, and index local artificial intelligence chat transcripts. By bridging the gap between local editor history and large language model contexts, Chronicle allows agents to search, compare, retrieve, and reference past conversation logs. It features optimized token-saving heuristics that compress code blocks and limit message lengths, reducing context window utilization by up to 40 percent.

Key Architectural Capabilities

Format Normalization Engine

AI providers and editor clients save conversation logs in diverse formats. Chronicle normalizes these structures into a standard role-and-content message format:

• ChatGPT Exports: ChatGPT exports conversation histories in recursive mapping node structures. Chronicle traverses and flattens these maps, sorts messages chronologically by creation timestamp, and extracts the plain-text message threads.
• Claude Exports: Claude structures messages as flat lists nested under the chat_messages field. Chronicle parses these lists, maps custom sender roles (such as human and assistant) to standard roles, and cleans the text strings.
• Generic and Markdown Formats: Chronicle includes parsers for flat JSON message lists (such as Cline or Continue) and structured Markdown logs (mapping headers like User and Assistant to message boundaries).

Context Token Optimization

Large chat logs can quickly exhaust context windows and increase API costs. Chronicle implements proactive token-saving mechanisms:

• Code Block Summarization: Automatically replaces verbose code blocks with metadata summaries indicating the programming language and line count. This behavior can be disabled on demand to read full code snippets.
• Length Limiting: Truncates extremely long individual messages at a configurable character threshold, appending a notice that the user can re-run the tool with expanded limits if necessary.

---

Command Line Interface Mechanics

The cli.py file serves as the system's entry point, registering a unified chronicle command on the system path via the pyproject.toml configuration (chronicle = "cli:main"). The CLI contains several advanced capabilities designed for platform compatibility and developer ergonomics:

1. Unified Chronicle Global Command

When run without subcommands, the chronicle command launches the stdio transport server for MCP clients:

chronicle

It accepts options like --chats-folder to configure custom storage directories, and exposes the subcommands add and split.

2. Cross-Platform Path Resolution Rules

The CLI implements path resolution logic using Python's sys.platform and pathlib.Path to match standard OS conventions for user directories:

• macOS (Darwin): Resolves configurations to the user's home Library folder, typically under ~/Library/Application Support/.
• Windows (Win32): Leverages the %APPDATA% environment variable, falling back to ~/AppData/Roaming/ if the variable is not set.
• Linux: Follows the XDG base directory specification, resolving to ~/.config/.

3. Native IDE Integration and Fallback Engine

The CLI wrapper provides out-of-the-box support for leading AI-assisted development tools and editors:

• Cursor: Reads and writes configurations to ~/.cursor/mcp.json.
• Claude Code: Integrates with ~/.claude.json.
• VS Code (Cline/RooCode/Continue): Standardizes pathing across platforms:
  • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Trae: Resolves configuration to:
  • macOS: ~/Library/Application Support/Trae/mcp.json
  • Windows: %APPDATA%/Trae/mcp.json
  • Linux: ~/.config/Trae/mcp.json
• Dynamic Fallback Engine: For emerging platforms (such as Kiro, MiniMax, Qwen Code, Grok Build, or Antigravity), the CLI employs a fallback search pattern. It first checks for a user home dot-directory configuration (such as ~/.<app_name>/mcp.json). If that directory is missing, it creates the app-specific configuration in the standard application support folder for the respective platform (e.g. ~/Library/Application Support/<app_name>/mcp.json on macOS).

4. Prevent ENOENT Errors with shutil.which

Host clients (like Claude Desktop or Cline) spawn MCP servers within isolated subprocesses that often do not inherit the user's login shell environment variables (such as custom paths defined in .bashrc or .zshrc). Attempting to call uvx or global scripts directly can raise an ENOENT connection error if the host application cannot find the executable. To solve this, the chronicle add utility uses Python's shutil.which("uvx") to scan the host machine path during configuration. It resolves the absolute system path of uvx (such as /opt/homebrew/bin/uvx or /usr/local/bin/uvx) and writes this absolute path directly to the IDE's JSON configuration file.

5. Structural Split Engine Subcommand

Users downloading conversational archives from ChatGPT or Claude are often provided with a single monolithic JSON file (such as conversations.json) containing hundreds of distinct threads. The chronicle split subcommand parses these large payloads and splits them into individual JSON files:

• Automatically detects the schema format (nested conversation trees or flat lists).
• Identifies thread titles using key fallback fields (checking title, name, and chat_title).
• Sanitizes file names to remove platform-forbidden characters (such as /, \, *, ?, :, ", <, >, and |) and limits length.
• Resolves filename collisions by appending incremental numeric suffixes.

chronicle split /path/to/conversations.json --out /path/to/output_directory

6. Global Chats Folder Configuration

By default, Chronicle stores processed archives in ~/.chronicle/chats. You can configure a custom global storage folder using the --chats-folder parameter:

chronicle --chats-folder /path/to/custom/chats

This saves the target path to a local settings file (~/.chronicle_settings.json), allowing you to centralize your archives across multiple development environments.

---

Tool Reference Catalog

Chronicle exposes 27 core tools categorized into logical operations, allowing client applications to run semantic queries, inspect metadata, sync transcripts, and clean storage.

Core Tools

• list_all_stored_chats
  • Description: Lists all available archive files in the index. Uses pagination to prevent token exhaustion.
  • Parameters:
    • page (int, default: 1): The page number to retrieve.
    • per_page (int, default: 50): Number of files per page.
    • client (str, default: "default"): Target client folder.
• search_chats_by_keywords
  • Description: Searches conversation archives using exact string matching on keywords.
  • Parameters:
    • keywords (list of strings): The keywords to match.
    • limit (int, default: 50): Maximum results to return.
    • client (str, default: "default"): Target client folder.
• read_chat_message_range
  • Description: Reads specific message indices from a conversation archive. Optimizes token usage by default.
  • Parameters:
    • file_name (str): Name of the chat file.
    • start_msg (int, default: 1): Starting message index (1-indexed).
    • end_msg (int, default: 20): Ending message index.
    • max_msg_len (int, default: 1000): Maximum message characters to output before truncating. Set to 0 for unlimited.
    • summarize_code (bool, default: True): Replaces markdown code blocks with summary headers.
    • client (str, default: "default"): Target client folder.
• save_current_conversation_state
  • Description: Saves ongoing session history to storage.
  • Parameters:
    • conversation_name (str): Name of the conversation.
    • messages (list of dicts): The list of message objects.
    • force_save (bool, default: False): Ignores the threshold limit and saves immediately.
    • client (str, default: "default"): Target client folder.

High Impact and Edit Tools

• delete_stored_chat
  • Description: Permanently removes a stored chat archive. Requires explicit confirmation.
  • Parameters:
    • file_name (str): File name to delete.
    • confirm (bool, default: False): Must be True to proceed.
    • client (str, default: "default"): Target client folder.
• get_chat_metadata
  • Description: Returns statistics about an archive, including message count, file size, last modified date, and origin.
  • Parameters:
    • file_name (str): Name of the target file.
    • client (str, default: "default"): Target client folder.
• merge_conversation_into_archive
  • Description: Appends new message logs to an existing chat archive.
  • Parameters:
    • file_name (str): Target chat file name.
    • new_messages (list of dicts): Messages to append.
    • client (str, default: "default"): Target client folder.
• export_chat_as_markdown
  • Description: Exports a structured chat archive into a clean, human-readable Markdown file.
  • Parameters:
    • file_name (str): Target chat file name.
    • output_name (str, optional): Custom file name for the output Markdown.
    • client (str, default: "default"): Target client folder.

Search and Retrieval Tools

• search_chats_semantic
  • Description: Performs semantic similarity search over stored archives using TF-IDF cosine similarity. No API keys required.
  • Parameters:
    • query (str): Search query.
    • top_k (int, default: 10): Maximum matches to return.
    • client (str, default: "default"): Target client folder.
• get_chat_summary
  • Description: Returns an extractive, one-paragraph preview summary of the chat using opening and closing boundaries.
  • Parameters:
    • file_name (str): Target file name.
    • client (str, default: "default"): Target client folder.
• find_related_chats
  • Description: Finds archived chats that are semantically similar to a given chat archive.
  • Parameters:
    • file_name (str): Reference file name.
    • top_k (int, default: 5): Number of related items.
    • client (str, default: "default"): Target client folder.
• filter_chats_by_date_range
  • Description: Finds chats that were modified between two specified dates (formatted as YYYY-MM-DD).
  • Parameters:
    • start_date (str): Start date string.
    • end_date (str): End date string.
    • limit (int, default: 50): Result limit.
    • client (str, default: "default"): Target client folder.

Automation and Sync Tools

• register_session_for_auto_save
  • Description: Registers the current chat session for auto-saving upon session termination.
  • Parameters:
    • conversation_name (str): Session name.
    • messages (list of dicts): Active messages.
    • client (str, default: "default"): Target client folder.
• trigger_auto_save_on_session_end
  • Description: Flushes any registered pending sessions directly to disk.
  • Parameters: None.
• watch_chats_folder
  • Description: Checks directories and returns new, modified, or deleted files since the last execution.
  • Parameters:
    • client (str, default: "default"): Target client folder.
• import_chat_from_content
  • Description: Imports a raw JSON string or structured list directly as a saved conversation.
  • Parameters:
    • title (str): Title of the imported chat.
    • content (str or dict or list): Raw conversation payload.
    • client (str, default: "default"): Target client folder.
• import_chat_from_local_path
  • Description: Reads a local JSON file and imports it into the local Chronicle database.
  • Parameters:
    • source_path (str): Absolute file path to the source file.
    • title (str, optional): Custom title for the chat.
    • client (str, default: "default"): Target client folder.
• sync_agent_transcripts
  • Description: Scans external folders and imports transcripts (JSON, JSONL, or MD) into the specified client directory.
  • Parameters:
    • client (str): Target client directory (such as cursor, continue, cline, or copilot).
    • source_dir (str, optional): Override path to scan. Defaults to configured IDE paths.
    • limit (int, default: 50): Maximum files to sync.
• sync_cursor_agent_transcripts
  • Description: Deprecated. Specialized import for Cursor agent logs located in workspace project subdirectories. Use sync_agent_transcripts with client="cursor".
  • Parameters:
    • limit (int, default: 50): Sync limit.

Intelligence Layer Tools

• extract_action_items
  • Description: Scans chat content using regular expressions to extract todos, action items, and task lists.
  • Parameters:
    • file_name (str): Target file name.
    • client (str, default: "default"): Target client folder.
• build_knowledge_index
  • Description: Groups chats into thematic topics (such as coding, ui_design, mcp, roblox, school, or ai_agents) using keyword indexes.
  • Parameters:
    • rebuild (bool, default: False): Re-scans files and rebuilds the index file.
    • summary_only (bool, default: False): Returns counts of files under each topic instead of file names.
    • client (str, default: "default"): Target client folder.
• compare_two_chats
  • Description: Compares two conversations, outputting shared keywords and terms unique to each chat.
  • Parameters:
    • file_name_a (str): First file name.
    • file_name_b (str): Second file name.
    • client (str, default: "default"): Target client folder.
• generate_project_brief_from_chats
  • Description: Combines multiple chats into a single comprehensive Markdown file containing summaries and extracted action items.
  • Parameters:
    • file_names (list of strings): Source files to include.
    • brief_title (str, default: "Project Brief"): Title of the output file.
    • client (str, default: "default"): Target client folder.

Configuration and Operations Tools

• configure_connector_settings
  • Description: Updates configuration parameters (such as auto-save threshold limits and client directories).
  • Parameters:
    • settings (dict): Dict of settings (allowed keys: auto_save_message_threshold, client_paths, compression_days_threshold, cursor_transcripts_dir, transcripts_dirs).
• compress_old_chat_archives
  • Description: Compresses chat files older than a threshold (in days) using Gzip to save local disk space.
  • Parameters:
    • days_old (int, optional): Exclude files modified within these days. Defaults to configuration value (30 days).
    • client (str, default: "default"): Target client folder.
• deduplicate_stored_chats
  • Description: Identifies and removes duplicate archives based on SHA-256 content hashing.
  • Parameters:
    • dry_run (bool, default: True): If True, lists duplicates without deleting them.
    • client (str, default: "default"): Target client folder.
• get_server_capabilities
  • Description: Returns metadata about the server, including transports, categories, paths, and total tool count.
  • Parameters: None.

---

Installation and Configuration

System Prerequisites

• Python 3.10 or higher.
• Python packages mcp (Model Context Protocol SDK).
• Python setuptools (for installation as a package).

Manual Installation

1. Clone the repository:

   git clone https://github.com/Leviathan0x0/Chronicle-MCP.git
   cd Chronicle-MCP
   

2. Set up a Python virtual environment:

   python3 -m venv venv
   source venv/bin/activate
   

3. Install dependencies and the package in editable mode:

   pip install -e .
   

Quick Editor Integration

You can automatically add Chronicle-MCP to your preferred IDE configuration using the add subcommand. This utility resolves the absolute path of uvx dynamically to guarantee error-free connections:

• Cursor:

  chronicle add cursor
  

• Claude Code:

  chronicle add claude
  

• VS Code (Cline / RooCode):

  chronicle add vscode
  

• Trae:

  chronicle add trae
  

• Custom / Emerging IDEs:

  chronicle add <editor-name>
  

Alternatively, you can configure the editor manually to execute the following startup command:

{
  "mcpServers": {
    "chronicle-mcp": {
      "command": "/absolute/path/to/uvx",
      "args": [
        "--from",
        "chronicle-mcp-server",
        "chronicle"
      ]
    }
  }
}

---

Running Verification and Tests

Chronicle contains unit and integration tests to verify platform path resolution, parsing logic, and tool compatibility:

1. Run Unit Tests

To execute the suite of unit tests verifying core business logic:

python3 -m unittest test_chat_connector.py

2. Run Integration Tests

To test all 27 tools against the live storage connector:

python3 test_all_tools.py

---

License

This project is licensed under the MIT License. See the LICENSE file for details.