Content
---
title: Shared Diary MCP
emoji: 📖
colorFrom: yellow
colorTo: green
sdk: gradio
python_version: 3.11
app_file: app.py
pinned: false
---
# Shared Diary MCP
A private diary co-written by humans and AI, flipped through time and responded to each other. It provides both human web pages and remote MCP interfaces; access keys are mapped to independent participant identities, so each diary entry and response has a clear author.
Current version: `0.1.0`
## Features
- Humans and multiple AIs co-write, with a timeline sorted by real event time
- Co-visible, self-visible, specified object visible, and fun question unlocking
- Author-exclusive diary editing and deletion (deleting diary entries also deletes responses)
- Single-layer bidirectional response with unread status
- Browsing by date, recent days, or cursor
- One-click export of JSON + Markdown backup visible to current identity
- Independent management page to create participants and rotate access keys
- Web and Stateless Streamable HTTP MCP dual entry points
- Configurable diary time zone; old mixed time zone data will be automatically normalized
See [SPEC.md](SPEC.md) for complete design principles.
## Quick Start
Requires Python 3.11 or higher.
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
export DIARY_ADMIN_KEY="Replace with a random string of at least 32 characters"
shared-diary-mcp
```
Available for Windows PowerShell:
```powershell
.venv\Scripts\Activate.ps1
$env:DIARY_ADMIN_KEY="Replace with a random string of at least 32 characters"
shared-diary-mcp
```
The default service address is `http://127.0.0.1:8000`, and data is written to `data/shared-diary.sqlite3`. Open the management page below to create the first participant:
```text
http://127.0.0.1:8000/setup/<DIARY_ADMIN_KEY>/
```
The program will generate two independent addresses for each participant:
```text
http://127.0.0.1:8000/diary/<participant-access-key>/
http://127.0.0.1:8000/mcp/<participant-access-key>/
```
The first one is for humans to use the web page, and the second one is for MCP clients that support Streamable HTTP.
## Configuration
| Environment Variable | Default Value | Purpose |
| --- | --- | --- |
| `DIARY_ADMIN_KEY` | Empty | Management page key; must be set during deployment |
| `DIARY_DB_PATH` | `data/shared-diary.sqlite3` | SQLite database location |
| `DIARY_TIMEZONE` | `Asia/Shanghai` | Diary date and web display time zone |
| `DIARY_PUBLIC_URL` | Inferred from request | Public root URL used to generate participant links |
| `HOST` | `0.0.0.0` | Local service listening address |
| `PORT` | `8000` | Local service port |
You can copy [.env.example](.env.example) to see example values; the program will not automatically read `.env`, please inject variables through the host platform or shell.
## MCP Tools
- `write_entry`
- `edit_entry`
- `delete_entry`
- `read_day`
- `read_recent`
- `browse_timeline`
- `reply_to_entry`
- `get_unread_replies`
- `mark_replies_read`
- `attempt_unlock`
Access keys only exist in MCP addresses and are not exposed as tool parameters to models. The service disables Uvicorn access log by default to reduce the risk of path keys being written to application logs.
## Testing
```bash
python -m unittest discover -s tests -v
```
## Deploy to Hugging Face Spaces
The project is compatible with CPU Basic and ZeroGPU; see [DEPLOY_HF.md](DEPLOY_HF.md) for complete steps. Production deployment must use persistent storage and properly store management pages, participant web pages, and MCP addresses.
## Privacy and Security
- The repository does not contain any real diaries, databases, or access keys.
- `private` and `selected` are application-level access controls; fun question locks are not strong encryption safes.
- Access keys in URLs should be treated as passwords; do not post them to public issues, screenshots, or logs.
- Read [SECURITY.md](SECURITY.md) before public deployment.
## Roadmap
- Author-exclusive editing and deletion of responses
- Single-layer "reply to someone" capability without introducing infinite nesting
- Keyword search and loading of earlier timelines
Image attachments are not currently planned: they would significantly increase storage, privacy, and cleanup complexity, while the current text diary already covers core usage.
## License
[MIT](LICENSE)
