# M5 Petit Notes

## [English Page](./README_en.md)

M5 Petit(や、その他のClaudeベースのエージェント)のためのメモ帳MCPサーバーです。

記憶は「思い出す」もの。メモ帳は「見返す」もの。検索して呼び出す長期記憶とは違い、開けばすぐ見える場所にmarkdownファイルとして残る、永続的なノートを提供します。参照表・リスト・調べもののまとめなど、記憶を検索し直さずにいつでも見返したいものに向いています。

## 機能

- **ノート一覧** — 保存されているノートの名前とサイズを一覧表示
- **ノート読み取り** — 名前を指定してノートの全文を取得
- **ノート作成・上書き** — markdown形式でノートを新規作成、または既存ノートを丸ごと更新
- **追記** — 既存ノートの末尾にテキストを追加(なければ新規作成)
- **ノート削除** — 名前を指定してノートを削除
- **ファイル単位の永続化** — 1ノート=1つの`.md`ファイル。バックアップも人間による直接編集も簡単

## 必要環境

- Python 3.10+
- [uv](https://docs.astral.sh/uv/)

## セットアップ

uvが未インストールの場合は先にインストールします。

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```bash
git clone https://github.com/PetitOnes/m5-petit-notes.git
cd m5-petit-notes
uv sync
uv run notes-mcp
```

## 環境変数

| 変数名 | デフォルト | 説明 |
|----------|---------|-------------|
| `PETIT_DATA_DIR` | `~/petit_data` | データディレクトリのルート([m5-petit-app](https://github.com/PetitOnes/m5-petit-app)と共有) |
| `CHARACTER_ID` | `default` | キャラクターID。ノート保存先のパス決定に使う |
| `NOTES_DIR` | `$PETIT_DATA_DIR/characters/<character_id>/notes` | ノートファイル(`.md`)を保存するディレクトリ |

## Claude Code連携

`.mcp.json`(または`~/.claude/settings.json`)に追加します。

```json
{
  "mcpServers": {
    "notes": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/m5-petit-notes", "notes-mcp"],
      "env": {
        "CHARACTER_ID": "petit"
      }
    }
  }
}
```

## ツール一覧

### list_notes

保存されているノートを一覧表示します(名前とサイズ)。

### read_note

ノートを名前で読み取ります。

```json
{ "name": "light_values" }
```

### write_note

ノートを新規作成、または上書きします。markdown形式を想定しています。

```json
{
  "name": "favorite_sounds",
  "content": "# 好きな音\n\n- 雨の音\n- 風鈴"
}
```

### append_note

既存ノートの末尾にテキストを追記します。ノートが存在しなければ新規作成します。

```json
{
  "name": "log",
  "content": "今日見つけたこと: ..."
}
```

### delete_note

ノートを名前で削除します。

```json
{ "name": "old_draft" }
```

## 開発

```bash
# 開発依存をインストール
uv sync --all-extras

# テスト実行
uv run pytest

# lint
uv run ruff check .
```

## アーキテクチャ

```
m5-petit-notes/
├── src/notes_mcp/
│   ├── server.py       # MCPサーバー(list/read/write/append/delete)
│   └── __init__.py
└── tests/
```

## License

Apache License 2.0