MIST - Model Intelligence System for Tasks

MIST - タスク向けモデルインテリジェンスシステム

MIST は、メモ管理、Gmail、カレンダー、タスク、Git との連携により、AI アシスタントに実用的な機能を提供する包括的な MCP（Model Context Protocol）サーバーです。AI アシスタントと外部ツールの橋渡しをし、標準化されたプロトコルを通じて、データやサービスとやり取りできるようにします。

概要

MIST を使うと、AI アシスタントは次のことができます。

• メモを管理する：永続ストレージを使用して、メモの作成、編集、検索、整理を行います
• Gmail を操作する：メールの検索、メッセージの閲覧、メールの送信、ラベルの管理を行います
• カレンダーの予定を管理する：Google カレンダーの予定の表示、作成、更新、削除を行います
• タスクを整理する：タスクリストの作成、タスクの追加、タスクの完了処理を行います
• Git リポジトリを操作する：ステータス、差分、コミット、ブランチ管理などの Git 操作を行います

MIST は Model Context Protocol（MCP）を実装することで、AI アシスタントが外部システムで操作を実行し、リアルタイムの情報にアクセスし、やり取りをまたいでコンテキストを保持できるようにします。

主な機能

メモ管理

• リッチテキスト形式でメモを作成、保存します
• 内容、タグ、メタデータでメモを検索します
• メモやメモのコレクションの要約を生成します
• 件名、日付、カスタムカテゴリでメモを整理します
• ファイルシステム上にメモをローカル保存します

Gmail 連携

• 高度なフィルタリングオプションでメールを検索します
• メールの全文を読み込みます
• メールを作成して送信します
• メールのラベルと整理方法を管理します
• メッセージを既読または未読に設定します
• 複数のメッセージに対する一括操作を行います

カレンダー連携

• 利用可能なすべてのカレンダーを一覧表示します
• カレンダーの予定を作成、管理します
• 既存の予定を更新します
• キーワードや期間で予定を検索します
• 予定の詳細情報を表示します

タスク連携

• タスクリストを一覧表示、管理します
• タイトル、メモ、期限を指定してタスクを作成します
• タスクを完了に設定します
• 完了したタスクを削除します
• タスクを複数のリストに分類します

Git 連携

• ローカルリポジトリで Git 操作を実行します
• ステータス、差分、コミット履歴を表示します
• 変更をコミットし、ブランチを管理します
• ブランチを作成、チェックアウト、マージします
• リモートリポジトリを管理します
• コミットの詳細と変更内容を表示します

今後のロードマップ

MIST は、より多くの連携機能や機能を提供できるよう、継続的に進化しています。今後、次の機能を追加する予定です。

ドキュメントとファイルの管理

• Google Drive 連携：ファイルへのアクセスと管理、ドキュメントの検索、内容の分析を行います
• Google Sheets 連携：データ分析用のスプレッドシートを作成、読み込み、更新します

検索と情報へのアクセス

• Google Custom Search：調査や情報検索に使えるウェブ検索機能を提供します
• ナレッジベース：オフラインでアクセスできる情報のローカルリポジトリを構築します

コラボレーションツール

• Google Classroom：コース、課題、教材にアクセスします
• Google Chat：チームでのコラボレーションに向けて、チャットスペースやメッセージを操作します

データと位置情報サービス

• Google Forms：データ収集用のフォームを作成、管理します
• Google Maps：ジオコーディングやルート案内など、位置情報に基づくサービスを追加します

プラットフォームの改善

• キャッシュ機能の強化：頻繁にアクセスされるデータのパフォーマンスを向上させます
• マルチユーザー対応：ユーザープロファイルと権限管理を追加します
• AI アシスタントとの互換性拡大：より多くの AI アシスタントとモデルに対応します

これらの分野への貢献を歓迎します！参加方法の詳細は、貢献ガイドラインをご確認ください。

システムアーキテクチャ

MIST は、AI アシスタントをさまざまなサービスに接続する MCP サーバーとして動作します。適切なサービスで認証、データ取得、アクションを処理し、構造化データを AI アシスタントに返します。

flowchart TB
    User[User] -->|Requests action| AI[AI Assistant]
    AI -->|Sends MCP request| MIST[MIST Server]

    subgraph "MIST Server Components"
        Router[MCP Request Router]
        NoteMgr[Note Manager]
        GmailMgr[Gmail Manager]
        TasksMgr[Tasks Manager]
        CalendarMgr[Calendar Manager]
        GitMgr[Git Manager]
        Auth[Authentication]
    end

    MIST --> Router
    Router -->|Note requests| NoteMgr
    Router -->|Gmail requests| GmailMgr
    Router -->|Tasks requests| TasksMgr
    Router -->|Calendar requests| CalendarMgr
    Router -->|Git requests| GitMgr
    GmailMgr -->|Auth requests| Auth
    TasksMgr -->|Auth requests| Auth
    CalendarMgr -->|Auth requests| Auth

    NoteMgr -->|Store/Retrieve| NoteDB[(Note Storage)]
    GmailMgr -->|API Calls| Gmail[(Gmail API)]
    TasksMgr -->|API Calls| Tasks[(Tasks API)]
    CalendarMgr -->|API Calls| Calendar[(Calendar API)]
    GitMgr -->|Git Operations| GitRepos[(Git Repositories)]

    MIST -->|Returns response| AI
    AI -->|Presents result| User

通信フロー

sequenceDiagram
    participant User
    participant AI as AI Assistant
    participant MIST as MIST Server
    participant Services as External Services

    User->>AI: "Send an email to John"
    AI->>MIST: MCP Request (action: sendEmail)
    MIST->>Services: Authenticate & API Call
    Services->>MIST: Response
    MIST->>AI: Structured Response
    AI->>User: "Email sent to John"

    User->>AI: "Take notes about my project"
    AI->>MIST: MCP Request (action: createNote)
    MIST->>Services: Store Note
    Services->>MIST: Confirmation
    MIST->>AI: Success Response
    AI->>User: "Notes saved successfully"

インストール

前提条件

• Python 3.13 以降
• UV パッケージマネージャー（推奨）または pip
• Google アカウント（Gmail／Calendar／Tasks との連携用）
• Git（Git 連携機能用）

セットアップ

1. このリポジトリをクローンします。

   git clone https://github.com/cloaky233/mist.git
   cd mist
   

2. 依存関係をインストールします。

   UV を使用する場合（推奨）：

   uv install
   

   pip を使用する場合：

   pip install -e .
   

3. 環境を設定します。

   # Create a .env file with your configuration
   echo "MIST_NOTES_DIR=/path/to/your/notes/directory" > .env
   echo "MIST_GOOGLE_CREDENTIALS_PATH=./credentials.json" >> .env
   echo "MIST_GOOGLE_TOKEN_PATH=./token.json" >> .env
   

   .env ファイルを編集して、環境に適したパスを設定します。

環境設定

.env ファイルには、次の環境変数を設定できます。

# Notes storage configuration
MIST_NOTES_DIR=/path/to/notes/directory

# Google API configuration
MIST_GOOGLE_CREDENTIALS_PATH=./credentials.json
MIST_GOOGLE_TOKEN_PATH=./token.json

Google API の設定

Gmail、Calendar、Tasks API の設定

flowchart TD
    A[Start] --> B[Create Google Cloud Project]
    B --> C[Enable Required APIs]
    C --> D[Configure OAuth Consent Screen]
    D --> E[Create OAuth Credentials]
    E --> F[Download credentials.json]
    F --> G[Run MIST First Time]
    G --> H[Complete OAuth Flow]
    H --> I[OAuth Token Saved]
    I --> J[MIST Ready for Google Integration]

1. Google Cloud プロジェクトを作成する

   • Google Cloud Console に移動します
   • 新しいプロジェクトを作成するか、既存のプロジェクトを選択します
   • 内容がわかる名前を付けます（例：「MIST Integration」）

2. 必要な API を有効にする

   • 「APIs & Services」>「Library」に移動します
   • 次の API を検索して有効にします。
     • Gmail API
     • Calendar API
     • Tasks API

3. OAuth 同意画面を設定する

   • 「APIs & Services」>「OAuth consent screen」に移動します
   • ユーザータイプとして「External」を選択します（Google Workspace の場合は「Internal」）
   • 必要な情報を入力します。
     • アプリ名：「MIST Integration」
     • ユーザーサポートのメールアドレス：ご自身のメールアドレス
     • デベロッパーの連絡先情報：ご自身のメールアドレス
   • 「Save and Continue」をクリックします
   • 各 API に必要なスコープを追加します
   • テストユーザーとしてご自身の Google アカウントを追加します

4. OAuth 認証情報を作成する

   • 「APIs & Services」>「Credentials」に移動します
   • 「Create Credentials」>「OAuth client ID」をクリックします
   • アプリケーションの種類として「Desktop application」を選択します
   • 名前を入力します（例：「MIST Desktop Client」）
   • JSON ファイルをダウンロードし、プロジェクトディレクトリに credentials.json として保存します

使用方法

MCP サーバーの実行

次のコマンドで MCP サーバーを起動します。

uv run --with mcp[cli] --with-editable . mcp run mist/server.py

本番環境では、systemd、supervisor、pm2 などのプロセスマネージャーを使用するとよいでしょう。

AI アシスタントへの接続

Claude Desktop

Claude Desktop の設定に次の内容を追加します。

{
  "mcpServers": {
    "M.I.S.T.": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/mist",
        "mcp",
        "run",
        "/path/to/mist/server.py"
      ],
      "env": {
        "MIST_GOOGLE_CREDENTIALS_PATH": "/path/to/mist/credentials.json",
        "MIST_GOOGLE_TOKEN_PATH": "/path/to/mist/token.json",
        "MIST_NOTES_DIR": "/path/to/notes"
      }
    }
  }
}

Zed Editor

Zed Editor の設定に次の内容を追加します。

"context_servers": {
  "mist-server": {
    "command": {
      "path": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/mist",
        "mcp",
        "run",
        "/path/to/mist/server.py"
      ],
      "env": {
        "MIST_GOOGLE_CREDENTIALS_PATH": "/path/to/mist/credentials.json",
        "MIST_GOOGLE_TOKEN_PATH": "/path/to/mist/token.json",
        "MIST_NOTES_DIR": "/path/to/notes"
      }
    },
    "settings": {
      "enable_server": true
    }
  }
}

初回実行時の認証

サーバーを初めて実行するときは、Google で認証する必要があります。

1. Google の認証ページがブラウザーウィンドウで開きます
2. Google アカウントにサインインします
3. 要求された権限を許可します
4. 認証コードが自動的に取得されます
5. MIST は今後の利用に備えて認証トークンを保存します

API リファレンス

ノート管理 API

関数	説明	パラメーター
add_note	新しいノートを作成します	title、content、subject（任意）
read_note	ID またはタイトルでノートを読み込みます	note_id または title
list_notes	フィルターを指定してノートを一覧表示します	subject、tag、limit
search_notes	内容でノートを検索します	query
edit_note	既存のノートを更新します	note_id、new_content
delete_note	ノートを削除します	note_id

Gmail API

関数	説明	パラメーター
search_emails	条件を指定してメールを検索します	各種フィルター
get_emails	ID を指定してメールの内容を取得します	message_ids
send_email	新しいメールを送信します	to、subject、body など
list_available_labels	Gmail のラベルを取得します	なし

Calendar API

関数	説明	パラメーター
list_calendars_tool	すべてのカレンダーを一覧表示します	なし
create_event_tool	カレンダーの予定を作成します	calendar_id、title など
search_events_tool	カレンダーの予定を検索します	calendar_id、query など

Tasks API

関数	説明	パラメーター
list_task_lists_tool	すべてのタスクリストを一覧表示します	なし
create_task_tool	新しいタスクを作成します	task_list_id、title など
complete_task_tool	タスクを完了としてマークします	task_list_id、task_id

Git API

以下は、よく使用される Git ツールの一部です。すべてのツールと詳細なパラメーターについては、API リファレンスを参照してください。

関数	説明	主なパラメーター
status_tool	作業ツリーの状態を表示します	repo_path
diff_unstaged_tool	ステージングされていない変更を表示します	repo_path
diff_staged_tool	ステージング済みの変更を表示します	repo_path
add_tool	コミットするファイルをステージングします	repo_path、files
reset_tool	現在の HEAD をリセットするか、ファイルのステージングを解除します	repo_path、commit_ish（任意）、mode（任意）
commit_tool	ステージング済みの変更をコミットします	repo_path、message
log_tool	コミット履歴を表示します	repo_path、max_count（任意）
branch_list_tool	すべてのブランチを一覧表示します	repo_path
create_branch_tool	新しいブランチを作成します	repo_path、branch_name、base_branch（任意）
checkout_tool	ブランチを切り替えます	repo_path、branch_name
merge_tool	ブランチをマージするか、マージ状態を管理します	repo_path、branch（任意）、abort（任意）
rebase_tool	現在のブランチをリベースするか、リベース状態を管理します	repo_path、branch_or_commit（任意）、interactive（任意）、abort（任意）、continue_rebase（任意）
stash_save_tool	現在の変更をスタッシュします	repo_path、message（任意）
pull_tool	リモートから変更をプルします	repo_path、remote（任意）、branch（任意）
push_tool	リモートに変更をプッシュします	repo_path、remote（任意）、branch（任意）、force（任意）、tags（任意）

プロジェクト構成

mist/
├── __init__.py               # Package initialization with version info
├── server.py                 # Main MCP server entry point
├── tools/                    # Tool implementations
│   ├── note_tools/           # Note management
│   │   ├── __init__.py
│   │   └── tool.py           # Note tool implementations
│   ├── gmail_tools/          # Gmail integration
│   │   ├── __init__.py
│   │   ├── config.py         # Gmail-specific config
│   │   ├── gmail.py          # Gmail API utilities
│   │   └── tool.py           # Gmail tool implementations
│   ├── calendar_tools/       # Calendar integration
│   │   ├── __init__.py
│   │   ├── calendar.py       # Calendar API utilities
│   │   ├── config.py         # Calendar-specific config
│   │   └── tool.py           # Calendar tool implementations
│   ├── tasks_tools/          # Tasks integration
│   │   ├── __init__.py
│   │   ├── config.py         # Tasks-specific config
│   │   ├── tasks.py          # Tasks API utilities
│   │   └── tool.py           # Tasks tool implementations
│   ├── git_tools/            # Git operations
│   │   ├── __init__.py
│   │   ├── config.py         # Git-specific config (imports from google_api)
│   │   ├── gitapi.py         # Core Git command implementations
│   │   └── tool.py           # Git tool functions exposed to MCP
│   ├── google_api/           # Common Google API utilities
│   │   ├── __init__.py
│   │   ├── client.py         # Google API client
│   │   └── config.py         # Shared Google API config
│   └── __init__.py           # Tools package init
├── config_docs/              # Configuration documentation
│   ├── api_reference.md      # API reference documentation
│   ├── configs.md            # Example configuration templates
│   ├── configuration_guide.md# Detailed configuration guide
│   └── troubleshooting_guide.md # Troubleshooting guide
├── .github/                  # GitHub configuration
│   └── ISSUE_TEMPLATE/       # Issue templates for bug reports, etc.
├── LICENSE                   # MIT License
├── CONTRIBUTING.md           # Contributing guidelines
├── README.md                 # Project documentation
├── pyproject.toml            # Project metadata and dependencies
├── uv.lock                   # UV lock file for dependencies
├── credentials.json          # Google API credentials (should be user-provided)
└── .env                      # Environment configuration (user-created)

セキュリティに関する考慮事項

• API キーとトークンは、.env ファイルまたは環境変数に保存されます
• OAuth トークンは、Google の認証フローによって安全に管理されます
• データはお使いのデバイス上、またはご自身のアカウント内に保持されます
• 明示的に設定しない限り、データがサードパーティサービスに送信されることはありません

トラブルシューティング

認証の問題

• 認証情報が機能しない：token.json を削除して、再認証してください
• 権限エラー：OAuth 同意画面で適切なスコープが設定されていることを確認してください
• トークンの有効期限切れ：MIST はトークンを自動的に更新しますが、更新に失敗した場合は再認証が必要になることがあります

接続の問題

• AI アシスタントが接続できない：設定内のパスが正しいことを確認してください
• サーバーが起動しない：Python のバージョンを確認してください（3.13 以降が必要です）
• API エラー：API キーと認証情報が正しく設定されていることを確認してください

データの問題

• ノートが保存されない：MIST_NOTES_DIR のパスが存在し、書き込み可能であることを確認してください

開発

リントとフォーマット

ruff check .
ruff format .

貢献

貢献を歓迎します！始め方の詳細については、貢献ガイドラインをご覧ください。

1. リポジトリをフォークします
2. 機能ブランチを作成します：git checkout -b feature/amazing-feature
3. 変更を加えてコミットします：git commit -m 'Add amazing feature'
4. ブランチにプッシュします：git push origin feature/amazing-feature
5. プルリクエストを作成します

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については、LICENSE ファイルをご覧ください。

謝辞

• プロトコル仕様を提供する Model Context Protocol
• Gmail、Calendar、Tasks との連携を提供する Google APIs

---

CLoaKY が ❤️ を込めて作成しました