chronicle-mcp-server 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- chronicle_mcp_server-1.0.0/LICENSE +21 -0
- chronicle_mcp_server-1.0.0/PKG-INFO +208 -0
- chronicle_mcp_server-1.0.0/README.md +193 -0
- chronicle_mcp_server-1.0.0/chronicle_mcp_server.egg-info/PKG-INFO +208 -0
- chronicle_mcp_server-1.0.0/chronicle_mcp_server.egg-info/SOURCES.txt +9 -0
- chronicle_mcp_server-1.0.0/chronicle_mcp_server.egg-info/dependency_links.txt +1 -0
- chronicle_mcp_server-1.0.0/chronicle_mcp_server.egg-info/entry_points.txt +2 -0
- chronicle_mcp_server-1.0.0/chronicle_mcp_server.egg-info/requires.txt +1 -0
- chronicle_mcp_server-1.0.0/chronicle_mcp_server.egg-info/top_level.txt +1 -0
- chronicle_mcp_server-1.0.0/pyproject.toml +23 -0
- chronicle_mcp_server-1.0.0/setup.cfg +4 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Leviathan
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: chronicle-mcp-server
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Local MCP server to sync, clean, and index AI chat logs locally. Saves up to 40% context tokens.
|
|
5
|
+
Author: Leviathan
|
|
6
|
+
License: MIT
|
|
7
|
+
Classifier: Programming Language :: Python :: 3
|
|
8
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Requires-Dist: mcp>=1.0.0
|
|
14
|
+
Dynamic: license-file
|
|
15
|
+
|
|
16
|
+
# Chronicle (Universal Chat Connector)
|
|
17
|
+
|
|
18
|
+
<p align="center">
|
|
19
|
+
<img src="assets/logo.png" alt="Chronicle Logo" width="400"/>
|
|
20
|
+
</p>
|
|
21
|
+
|
|
22
|
+
Chronicle is a tool that links your AI assistants (like ChatGPT or Claude) to your local saved chats. It helps the AI find, search, compare, and copy your past conversations.
|
|
23
|
+
|
|
24
|
+
Chronicle is on the MCP Marketplace. You can install it with one click there to connect your AI directly.
|
|
25
|
+
|
|
26
|
+
### NOTE:
|
|
27
|
+
Please give this repository a star if you used it so I can claim the special offers that are given to open-source contributers.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## What Chronicle Does
|
|
32
|
+
|
|
33
|
+
- **Client Folders**: Keeps your saved chats organized in folders for different AIs like ChatGPT or Claude.
|
|
34
|
+
- **Special Search**: Helps the AI find past chats by searching for similar meanings and not just exact matching words. You can also search for files saved between certain dates or group files by topic.
|
|
35
|
+
- **Token Efficiency**: Hides large chunks of code or shortens very long messages when reading past chats. This helps save data limits and keeps the AI fast.
|
|
36
|
+
- **Smart Helpers**: Helps the AI find tasks, summarize conversations, and compare chats.
|
|
37
|
+
- **Auto Saving**: Saves your active chats automatically when they get long.
|
|
38
|
+
- **Clean Storage**: Finds and deletes duplicate files and shrinks old files to save disk space.
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## How to Install and Set Up
|
|
43
|
+
|
|
44
|
+
### Prerequisites
|
|
45
|
+
You need Python version 3.10 or higher on your computer.
|
|
46
|
+
|
|
47
|
+
### Step 1: Download the Files
|
|
48
|
+
Clone the folder from GitHub and go inside it:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
git clone https://github.com/Leviathan0x0/Chronicle-MCP.git
|
|
52
|
+
cd Chronicle-MCP
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Step 2: Set Up Python
|
|
56
|
+
Create a private Python setup folder and activate it:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
python3 -m venv venv
|
|
60
|
+
source venv/bin/activate
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Step 3: Install Required Packages
|
|
64
|
+
Install the helper software packages:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pip install -r requirements.txt
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## How to Import Your Past Saved Chats
|
|
73
|
+
|
|
74
|
+
You can save new chats automatically or load your old ones.
|
|
75
|
+
|
|
76
|
+
### 1. Auto Saving
|
|
77
|
+
When you chat with an AI that has Chronicle connected, the AI will automatically save your chat in the background to your computer.
|
|
78
|
+
|
|
79
|
+
### 2. Copying Your Old Chats
|
|
80
|
+
If you want to load chats from before you had Chronicle:
|
|
81
|
+
|
|
82
|
+
#### Step A: Download your data
|
|
83
|
+
Go to settings inside ChatGPT or Claude. Click the export data button. You will get a zip file. Unzip this file on your computer.
|
|
84
|
+
|
|
85
|
+
#### Step B: Split big files
|
|
86
|
+
If your downloaded data is one big file with all your chats inside (like ChatGPT's conversations.json file):
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
# Activate your python setup folder
|
|
90
|
+
source venv/bin/activate
|
|
91
|
+
|
|
92
|
+
# Run the separator tool to split the big file into separate files
|
|
93
|
+
python3 split_chats.py
|
|
94
|
+
|
|
95
|
+
# Or run it with a custom folder path where you want the chats to go
|
|
96
|
+
python3 split_chats.py /path/to/your/folder
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
#### Step C: Move the files
|
|
100
|
+
If you have separate files for each chat:
|
|
101
|
+
- Copy and paste those files directly into the chats folder on your computer (located at ~/.chronicle/chats/).
|
|
102
|
+
- Or use the import tools from the AI to import the files.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Supported File Styles
|
|
107
|
+
|
|
108
|
+
Chronicle reads and translates different chat styles automatically:
|
|
109
|
+
|
|
110
|
+
### ChatGPT Style
|
|
111
|
+
- **How it works**: ChatGPT saves chats in connected text maps. Chronicle flattens these maps, sorts them by time, and extracts the text.
|
|
112
|
+
|
|
113
|
+
### Claude Style
|
|
114
|
+
- **How it works**: Claude saves chats in list style under chat_messages. Chronicle reads these lists and maps the sender names to user and assistant.
|
|
115
|
+
|
|
116
|
+
### Generic Style (Cline, Continue, and others)
|
|
117
|
+
- **How it works**: Other tools save chats as simple lists. Chronicle reads these lists and matches common words for sender and message content.
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Tool List
|
|
122
|
+
|
|
123
|
+
Chronicle has 25 tools to help your AI manage chats:
|
|
124
|
+
|
|
125
|
+
### Core Tools
|
|
126
|
+
- `list_all_stored_chats`: List your saved files page by page.
|
|
127
|
+
- `search_chats_by_keywords`: Search chats using keywords.
|
|
128
|
+
- `read_chat_message_range`: Read a range of messages with options to show shortened code to save space.
|
|
129
|
+
- `save_current_conversation_state`: Save active chats.
|
|
130
|
+
|
|
131
|
+
### Edit Tools
|
|
132
|
+
- `delete_stored_chat`: Delete a saved chat file.
|
|
133
|
+
- `get_chat_metadata`: See file details like size and date.
|
|
134
|
+
- `merge_conversation_into_archive`: Add new messages to an old file.
|
|
135
|
+
- `export_chat_as_markdown`: Export a chat as a text document.
|
|
136
|
+
|
|
137
|
+
### Search Tools
|
|
138
|
+
- `search_chats_semantic`: Search files using similar meanings.
|
|
139
|
+
- `get_chat_summary`: Get a short summary of a chat.
|
|
140
|
+
- `find_related_chats`: Find chats that talk about similar things.
|
|
141
|
+
- `filter_chats_by_date_range`: Find chats saved between two dates.
|
|
142
|
+
|
|
143
|
+
### Sync Tools
|
|
144
|
+
- `register_session_for_auto_save`: Mark a chat to save later.
|
|
145
|
+
- `trigger_auto_save_on_session_end`: Save marked chats now.
|
|
146
|
+
- `watch_chats_folder`: Watch your folders for new or changed files.
|
|
147
|
+
- `import_chat_from_content`: Import a chat from text.
|
|
148
|
+
- `import_chat_from_local_path`: Import a chat from a local file.
|
|
149
|
+
- `sync_agent_transcripts`: Sync saved chats from tools like Cursor, Continue, or Cline.
|
|
150
|
+
- `sync_cursor_agent_transcripts`: Sync saved chats from Cursor (older version).
|
|
151
|
+
|
|
152
|
+
### Info Tools
|
|
153
|
+
- `extract_action_items`: Find tasks and to-do lists in your chats.
|
|
154
|
+
- `build_knowledge_index`: Group your files by topic.
|
|
155
|
+
- `compare_two_chats`: See what two chats have in common and what is unique.
|
|
156
|
+
- `generate_project_brief_from_chats`: Combine chats into a project summary document.
|
|
157
|
+
|
|
158
|
+
### System Tools
|
|
159
|
+
- `configure_connector_settings`: Change settings like file size limits.
|
|
160
|
+
- `compress_old_chat_archives`: Compress old files to save space.
|
|
161
|
+
- `deduplicate_stored_chats`: Find and delete duplicate files.
|
|
162
|
+
- `get_server_capabilities`: See the list of all tools.
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Connecting to Your AI
|
|
167
|
+
|
|
168
|
+
### Claude Code
|
|
169
|
+
|
|
170
|
+
If you downloaded the code manually, run this command in your terminal. Note: You must change `/absolute/path/to/` to the actual folder path where you saved the files on your computer.
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
claude mcp add-json chronicle '{"command": "python3", "args": ["/absolute/path/to/Chronicle-MCP/chat_server.py"]}'
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
If you installed the tool via the marketplace or npm, you do not need to use a folder path. Run this command instead:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
claude mcp add-json chronicle '{"command": "npx", "args": ["-y", "chronicle-mcp"]}'
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Cursor or VS Code
|
|
183
|
+
|
|
184
|
+
If you downloaded the code manually, go to Cursor settings, find the MCP section, and add a command tool:
|
|
185
|
+
- Name: Chronicle
|
|
186
|
+
- Command: `python3 /absolute/path/to/Chronicle-MCP/chat_server.py`
|
|
187
|
+
|
|
188
|
+
If you installed the tool via the marketplace or npm, add this command instead:
|
|
189
|
+
- Name: Chronicle
|
|
190
|
+
- Command: `npx -y chronicle-mcp`
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## Testing Your Setup
|
|
195
|
+
|
|
196
|
+
You can run the test tool to make sure everything works:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
python3 test_all_tools.py
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## License
|
|
205
|
+
|
|
206
|
+
This project uses the MIT License. See the LICENSE file for details.
|
|
207
|
+
|
|
208
|
+
<!-- mcp-name: io.github.Leviathan0x0/chronicle-mcp -->
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
# Chronicle (Universal Chat Connector)
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="assets/logo.png" alt="Chronicle Logo" width="400"/>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
Chronicle is a tool that links your AI assistants (like ChatGPT or Claude) to your local saved chats. It helps the AI find, search, compare, and copy your past conversations.
|
|
8
|
+
|
|
9
|
+
Chronicle is on the MCP Marketplace. You can install it with one click there to connect your AI directly.
|
|
10
|
+
|
|
11
|
+
### NOTE:
|
|
12
|
+
Please give this repository a star if you used it so I can claim the special offers that are given to open-source contributers.
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## What Chronicle Does
|
|
17
|
+
|
|
18
|
+
- **Client Folders**: Keeps your saved chats organized in folders for different AIs like ChatGPT or Claude.
|
|
19
|
+
- **Special Search**: Helps the AI find past chats by searching for similar meanings and not just exact matching words. You can also search for files saved between certain dates or group files by topic.
|
|
20
|
+
- **Token Efficiency**: Hides large chunks of code or shortens very long messages when reading past chats. This helps save data limits and keeps the AI fast.
|
|
21
|
+
- **Smart Helpers**: Helps the AI find tasks, summarize conversations, and compare chats.
|
|
22
|
+
- **Auto Saving**: Saves your active chats automatically when they get long.
|
|
23
|
+
- **Clean Storage**: Finds and deletes duplicate files and shrinks old files to save disk space.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## How to Install and Set Up
|
|
28
|
+
|
|
29
|
+
### Prerequisites
|
|
30
|
+
You need Python version 3.10 or higher on your computer.
|
|
31
|
+
|
|
32
|
+
### Step 1: Download the Files
|
|
33
|
+
Clone the folder from GitHub and go inside it:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
git clone https://github.com/Leviathan0x0/Chronicle-MCP.git
|
|
37
|
+
cd Chronicle-MCP
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### Step 2: Set Up Python
|
|
41
|
+
Create a private Python setup folder and activate it:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
python3 -m venv venv
|
|
45
|
+
source venv/bin/activate
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Step 3: Install Required Packages
|
|
49
|
+
Install the helper software packages:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
pip install -r requirements.txt
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## How to Import Your Past Saved Chats
|
|
58
|
+
|
|
59
|
+
You can save new chats automatically or load your old ones.
|
|
60
|
+
|
|
61
|
+
### 1. Auto Saving
|
|
62
|
+
When you chat with an AI that has Chronicle connected, the AI will automatically save your chat in the background to your computer.
|
|
63
|
+
|
|
64
|
+
### 2. Copying Your Old Chats
|
|
65
|
+
If you want to load chats from before you had Chronicle:
|
|
66
|
+
|
|
67
|
+
#### Step A: Download your data
|
|
68
|
+
Go to settings inside ChatGPT or Claude. Click the export data button. You will get a zip file. Unzip this file on your computer.
|
|
69
|
+
|
|
70
|
+
#### Step B: Split big files
|
|
71
|
+
If your downloaded data is one big file with all your chats inside (like ChatGPT's conversations.json file):
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
# Activate your python setup folder
|
|
75
|
+
source venv/bin/activate
|
|
76
|
+
|
|
77
|
+
# Run the separator tool to split the big file into separate files
|
|
78
|
+
python3 split_chats.py
|
|
79
|
+
|
|
80
|
+
# Or run it with a custom folder path where you want the chats to go
|
|
81
|
+
python3 split_chats.py /path/to/your/folder
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
#### Step C: Move the files
|
|
85
|
+
If you have separate files for each chat:
|
|
86
|
+
- Copy and paste those files directly into the chats folder on your computer (located at ~/.chronicle/chats/).
|
|
87
|
+
- Or use the import tools from the AI to import the files.
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Supported File Styles
|
|
92
|
+
|
|
93
|
+
Chronicle reads and translates different chat styles automatically:
|
|
94
|
+
|
|
95
|
+
### ChatGPT Style
|
|
96
|
+
- **How it works**: ChatGPT saves chats in connected text maps. Chronicle flattens these maps, sorts them by time, and extracts the text.
|
|
97
|
+
|
|
98
|
+
### Claude Style
|
|
99
|
+
- **How it works**: Claude saves chats in list style under chat_messages. Chronicle reads these lists and maps the sender names to user and assistant.
|
|
100
|
+
|
|
101
|
+
### Generic Style (Cline, Continue, and others)
|
|
102
|
+
- **How it works**: Other tools save chats as simple lists. Chronicle reads these lists and matches common words for sender and message content.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Tool List
|
|
107
|
+
|
|
108
|
+
Chronicle has 25 tools to help your AI manage chats:
|
|
109
|
+
|
|
110
|
+
### Core Tools
|
|
111
|
+
- `list_all_stored_chats`: List your saved files page by page.
|
|
112
|
+
- `search_chats_by_keywords`: Search chats using keywords.
|
|
113
|
+
- `read_chat_message_range`: Read a range of messages with options to show shortened code to save space.
|
|
114
|
+
- `save_current_conversation_state`: Save active chats.
|
|
115
|
+
|
|
116
|
+
### Edit Tools
|
|
117
|
+
- `delete_stored_chat`: Delete a saved chat file.
|
|
118
|
+
- `get_chat_metadata`: See file details like size and date.
|
|
119
|
+
- `merge_conversation_into_archive`: Add new messages to an old file.
|
|
120
|
+
- `export_chat_as_markdown`: Export a chat as a text document.
|
|
121
|
+
|
|
122
|
+
### Search Tools
|
|
123
|
+
- `search_chats_semantic`: Search files using similar meanings.
|
|
124
|
+
- `get_chat_summary`: Get a short summary of a chat.
|
|
125
|
+
- `find_related_chats`: Find chats that talk about similar things.
|
|
126
|
+
- `filter_chats_by_date_range`: Find chats saved between two dates.
|
|
127
|
+
|
|
128
|
+
### Sync Tools
|
|
129
|
+
- `register_session_for_auto_save`: Mark a chat to save later.
|
|
130
|
+
- `trigger_auto_save_on_session_end`: Save marked chats now.
|
|
131
|
+
- `watch_chats_folder`: Watch your folders for new or changed files.
|
|
132
|
+
- `import_chat_from_content`: Import a chat from text.
|
|
133
|
+
- `import_chat_from_local_path`: Import a chat from a local file.
|
|
134
|
+
- `sync_agent_transcripts`: Sync saved chats from tools like Cursor, Continue, or Cline.
|
|
135
|
+
- `sync_cursor_agent_transcripts`: Sync saved chats from Cursor (older version).
|
|
136
|
+
|
|
137
|
+
### Info Tools
|
|
138
|
+
- `extract_action_items`: Find tasks and to-do lists in your chats.
|
|
139
|
+
- `build_knowledge_index`: Group your files by topic.
|
|
140
|
+
- `compare_two_chats`: See what two chats have in common and what is unique.
|
|
141
|
+
- `generate_project_brief_from_chats`: Combine chats into a project summary document.
|
|
142
|
+
|
|
143
|
+
### System Tools
|
|
144
|
+
- `configure_connector_settings`: Change settings like file size limits.
|
|
145
|
+
- `compress_old_chat_archives`: Compress old files to save space.
|
|
146
|
+
- `deduplicate_stored_chats`: Find and delete duplicate files.
|
|
147
|
+
- `get_server_capabilities`: See the list of all tools.
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Connecting to Your AI
|
|
152
|
+
|
|
153
|
+
### Claude Code
|
|
154
|
+
|
|
155
|
+
If you downloaded the code manually, run this command in your terminal. Note: You must change `/absolute/path/to/` to the actual folder path where you saved the files on your computer.
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
claude mcp add-json chronicle '{"command": "python3", "args": ["/absolute/path/to/Chronicle-MCP/chat_server.py"]}'
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
If you installed the tool via the marketplace or npm, you do not need to use a folder path. Run this command instead:
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
claude mcp add-json chronicle '{"command": "npx", "args": ["-y", "chronicle-mcp"]}'
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Cursor or VS Code
|
|
168
|
+
|
|
169
|
+
If you downloaded the code manually, go to Cursor settings, find the MCP section, and add a command tool:
|
|
170
|
+
- Name: Chronicle
|
|
171
|
+
- Command: `python3 /absolute/path/to/Chronicle-MCP/chat_server.py`
|
|
172
|
+
|
|
173
|
+
If you installed the tool via the marketplace or npm, add this command instead:
|
|
174
|
+
- Name: Chronicle
|
|
175
|
+
- Command: `npx -y chronicle-mcp`
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Testing Your Setup
|
|
180
|
+
|
|
181
|
+
You can run the test tool to make sure everything works:
|
|
182
|
+
|
|
183
|
+
```bash
|
|
184
|
+
python3 test_all_tools.py
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## License
|
|
190
|
+
|
|
191
|
+
This project uses the MIT License. See the LICENSE file for details.
|
|
192
|
+
|
|
193
|
+
<!-- mcp-name: io.github.Leviathan0x0/chronicle-mcp -->
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: chronicle-mcp-server
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Local MCP server to sync, clean, and index AI chat logs locally. Saves up to 40% context tokens.
|
|
5
|
+
Author: Leviathan
|
|
6
|
+
License: MIT
|
|
7
|
+
Classifier: Programming Language :: Python :: 3
|
|
8
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Description-Content-Type: text/markdown
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Requires-Dist: mcp>=1.0.0
|
|
14
|
+
Dynamic: license-file
|
|
15
|
+
|
|
16
|
+
# Chronicle (Universal Chat Connector)
|
|
17
|
+
|
|
18
|
+
<p align="center">
|
|
19
|
+
<img src="assets/logo.png" alt="Chronicle Logo" width="400"/>
|
|
20
|
+
</p>
|
|
21
|
+
|
|
22
|
+
Chronicle is a tool that links your AI assistants (like ChatGPT or Claude) to your local saved chats. It helps the AI find, search, compare, and copy your past conversations.
|
|
23
|
+
|
|
24
|
+
Chronicle is on the MCP Marketplace. You can install it with one click there to connect your AI directly.
|
|
25
|
+
|
|
26
|
+
### NOTE:
|
|
27
|
+
Please give this repository a star if you used it so I can claim the special offers that are given to open-source contributers.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## What Chronicle Does
|
|
32
|
+
|
|
33
|
+
- **Client Folders**: Keeps your saved chats organized in folders for different AIs like ChatGPT or Claude.
|
|
34
|
+
- **Special Search**: Helps the AI find past chats by searching for similar meanings and not just exact matching words. You can also search for files saved between certain dates or group files by topic.
|
|
35
|
+
- **Token Efficiency**: Hides large chunks of code or shortens very long messages when reading past chats. This helps save data limits and keeps the AI fast.
|
|
36
|
+
- **Smart Helpers**: Helps the AI find tasks, summarize conversations, and compare chats.
|
|
37
|
+
- **Auto Saving**: Saves your active chats automatically when they get long.
|
|
38
|
+
- **Clean Storage**: Finds and deletes duplicate files and shrinks old files to save disk space.
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## How to Install and Set Up
|
|
43
|
+
|
|
44
|
+
### Prerequisites
|
|
45
|
+
You need Python version 3.10 or higher on your computer.
|
|
46
|
+
|
|
47
|
+
### Step 1: Download the Files
|
|
48
|
+
Clone the folder from GitHub and go inside it:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
git clone https://github.com/Leviathan0x0/Chronicle-MCP.git
|
|
52
|
+
cd Chronicle-MCP
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Step 2: Set Up Python
|
|
56
|
+
Create a private Python setup folder and activate it:
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
python3 -m venv venv
|
|
60
|
+
source venv/bin/activate
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Step 3: Install Required Packages
|
|
64
|
+
Install the helper software packages:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pip install -r requirements.txt
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## How to Import Your Past Saved Chats
|
|
73
|
+
|
|
74
|
+
You can save new chats automatically or load your old ones.
|
|
75
|
+
|
|
76
|
+
### 1. Auto Saving
|
|
77
|
+
When you chat with an AI that has Chronicle connected, the AI will automatically save your chat in the background to your computer.
|
|
78
|
+
|
|
79
|
+
### 2. Copying Your Old Chats
|
|
80
|
+
If you want to load chats from before you had Chronicle:
|
|
81
|
+
|
|
82
|
+
#### Step A: Download your data
|
|
83
|
+
Go to settings inside ChatGPT or Claude. Click the export data button. You will get a zip file. Unzip this file on your computer.
|
|
84
|
+
|
|
85
|
+
#### Step B: Split big files
|
|
86
|
+
If your downloaded data is one big file with all your chats inside (like ChatGPT's conversations.json file):
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
# Activate your python setup folder
|
|
90
|
+
source venv/bin/activate
|
|
91
|
+
|
|
92
|
+
# Run the separator tool to split the big file into separate files
|
|
93
|
+
python3 split_chats.py
|
|
94
|
+
|
|
95
|
+
# Or run it with a custom folder path where you want the chats to go
|
|
96
|
+
python3 split_chats.py /path/to/your/folder
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
#### Step C: Move the files
|
|
100
|
+
If you have separate files for each chat:
|
|
101
|
+
- Copy and paste those files directly into the chats folder on your computer (located at ~/.chronicle/chats/).
|
|
102
|
+
- Or use the import tools from the AI to import the files.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
106
|
+
## Supported File Styles
|
|
107
|
+
|
|
108
|
+
Chronicle reads and translates different chat styles automatically:
|
|
109
|
+
|
|
110
|
+
### ChatGPT Style
|
|
111
|
+
- **How it works**: ChatGPT saves chats in connected text maps. Chronicle flattens these maps, sorts them by time, and extracts the text.
|
|
112
|
+
|
|
113
|
+
### Claude Style
|
|
114
|
+
- **How it works**: Claude saves chats in list style under chat_messages. Chronicle reads these lists and maps the sender names to user and assistant.
|
|
115
|
+
|
|
116
|
+
### Generic Style (Cline, Continue, and others)
|
|
117
|
+
- **How it works**: Other tools save chats as simple lists. Chronicle reads these lists and matches common words for sender and message content.
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Tool List
|
|
122
|
+
|
|
123
|
+
Chronicle has 25 tools to help your AI manage chats:
|
|
124
|
+
|
|
125
|
+
### Core Tools
|
|
126
|
+
- `list_all_stored_chats`: List your saved files page by page.
|
|
127
|
+
- `search_chats_by_keywords`: Search chats using keywords.
|
|
128
|
+
- `read_chat_message_range`: Read a range of messages with options to show shortened code to save space.
|
|
129
|
+
- `save_current_conversation_state`: Save active chats.
|
|
130
|
+
|
|
131
|
+
### Edit Tools
|
|
132
|
+
- `delete_stored_chat`: Delete a saved chat file.
|
|
133
|
+
- `get_chat_metadata`: See file details like size and date.
|
|
134
|
+
- `merge_conversation_into_archive`: Add new messages to an old file.
|
|
135
|
+
- `export_chat_as_markdown`: Export a chat as a text document.
|
|
136
|
+
|
|
137
|
+
### Search Tools
|
|
138
|
+
- `search_chats_semantic`: Search files using similar meanings.
|
|
139
|
+
- `get_chat_summary`: Get a short summary of a chat.
|
|
140
|
+
- `find_related_chats`: Find chats that talk about similar things.
|
|
141
|
+
- `filter_chats_by_date_range`: Find chats saved between two dates.
|
|
142
|
+
|
|
143
|
+
### Sync Tools
|
|
144
|
+
- `register_session_for_auto_save`: Mark a chat to save later.
|
|
145
|
+
- `trigger_auto_save_on_session_end`: Save marked chats now.
|
|
146
|
+
- `watch_chats_folder`: Watch your folders for new or changed files.
|
|
147
|
+
- `import_chat_from_content`: Import a chat from text.
|
|
148
|
+
- `import_chat_from_local_path`: Import a chat from a local file.
|
|
149
|
+
- `sync_agent_transcripts`: Sync saved chats from tools like Cursor, Continue, or Cline.
|
|
150
|
+
- `sync_cursor_agent_transcripts`: Sync saved chats from Cursor (older version).
|
|
151
|
+
|
|
152
|
+
### Info Tools
|
|
153
|
+
- `extract_action_items`: Find tasks and to-do lists in your chats.
|
|
154
|
+
- `build_knowledge_index`: Group your files by topic.
|
|
155
|
+
- `compare_two_chats`: See what two chats have in common and what is unique.
|
|
156
|
+
- `generate_project_brief_from_chats`: Combine chats into a project summary document.
|
|
157
|
+
|
|
158
|
+
### System Tools
|
|
159
|
+
- `configure_connector_settings`: Change settings like file size limits.
|
|
160
|
+
- `compress_old_chat_archives`: Compress old files to save space.
|
|
161
|
+
- `deduplicate_stored_chats`: Find and delete duplicate files.
|
|
162
|
+
- `get_server_capabilities`: See the list of all tools.
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## Connecting to Your AI
|
|
167
|
+
|
|
168
|
+
### Claude Code
|
|
169
|
+
|
|
170
|
+
If you downloaded the code manually, run this command in your terminal. Note: You must change `/absolute/path/to/` to the actual folder path where you saved the files on your computer.
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
claude mcp add-json chronicle '{"command": "python3", "args": ["/absolute/path/to/Chronicle-MCP/chat_server.py"]}'
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
If you installed the tool via the marketplace or npm, you do not need to use a folder path. Run this command instead:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
claude mcp add-json chronicle '{"command": "npx", "args": ["-y", "chronicle-mcp"]}'
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Cursor or VS Code
|
|
183
|
+
|
|
184
|
+
If you downloaded the code manually, go to Cursor settings, find the MCP section, and add a command tool:
|
|
185
|
+
- Name: Chronicle
|
|
186
|
+
- Command: `python3 /absolute/path/to/Chronicle-MCP/chat_server.py`
|
|
187
|
+
|
|
188
|
+
If you installed the tool via the marketplace or npm, add this command instead:
|
|
189
|
+
- Name: Chronicle
|
|
190
|
+
- Command: `npx -y chronicle-mcp`
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## Testing Your Setup
|
|
195
|
+
|
|
196
|
+
You can run the test tool to make sure everything works:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
python3 test_all_tools.py
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## License
|
|
205
|
+
|
|
206
|
+
This project uses the MIT License. See the LICENSE file for details.
|
|
207
|
+
|
|
208
|
+
<!-- mcp-name: io.github.Leviathan0x0/chronicle-mcp -->
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
chronicle_mcp_server.egg-info/PKG-INFO
|
|
5
|
+
chronicle_mcp_server.egg-info/SOURCES.txt
|
|
6
|
+
chronicle_mcp_server.egg-info/dependency_links.txt
|
|
7
|
+
chronicle_mcp_server.egg-info/entry_points.txt
|
|
8
|
+
chronicle_mcp_server.egg-info/requires.txt
|
|
9
|
+
chronicle_mcp_server.egg-info/top_level.txt
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
mcp>=1.0.0
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
assets
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "chronicle-mcp-server"
|
|
7
|
+
version = "1.0.0"
|
|
8
|
+
description = "Local MCP server to sync, clean, and index AI chat logs locally. Saves up to 40% context tokens."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
authors = [{ name = "Leviathan" }]
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
classifiers = [
|
|
13
|
+
"Programming Language :: Python :: 3",
|
|
14
|
+
"License :: OSI Approved :: MIT License",
|
|
15
|
+
"Operating System :: OS Independent",
|
|
16
|
+
]
|
|
17
|
+
requires-python = ">=3.10"
|
|
18
|
+
dependencies = [
|
|
19
|
+
"mcp>=1.0.0",
|
|
20
|
+
]
|
|
21
|
+
|
|
22
|
+
[project.scripts]
|
|
23
|
+
chronicle-mcp-server = "chat_server:mcp.run"
|