MIST - Model Intelligence System for Tasks

MIST is a comprehensive MCP (Model Context Protocol) server that empowers AI assistants with real-world capabilities for note management, Gmail, Calendar, Tasks, and Git integration. It bridges the gap between AI assistants and external tools, enabling them to interact with your data and services through a standardized protocol.

Overview

MIST allows AI assistants to:

• Manage notes: Create, edit, search, and organize notes with persistent storage

• Interact with Gmail: Search emails, read messages, send emails, manage labels

• Manage calendar events: View, create, update, and delete Google Calendar events

• Organize tasks: Create task lists, add tasks, mark tasks as complete

• Work with Git repositories: Perform Git operations like status, diff, commit, branch management

By implementing the Model Context Protocol (MCP), MIST enables AI assistants to perform actions in external systems, access real-time information, and maintain context across interactions.

Key Features

Note Management

• Create and store notes with rich text formatting

• Search notes by content, tags, or metadata

• Generate summaries of notes or collections

• Organize notes by subject, date, or custom categories

• Store notes locally in your filesystem

Gmail Integration

• Search emails with advanced filtering options

• Read complete email content

• Compose and send emails

• Manage email labels and organization

• Mark messages as read/unread

• Batch operations for multiple messages

Calendar Integration

• List all available calendars

• Create and manage calendar events

• Update existing events

• Search events by keyword or date range

• View detailed event information

Tasks Integration

• List and manage task lists

• Create tasks with titles, notes, and due dates

• Mark tasks as complete

• Delete completed tasks

• Organize tasks into different lists

Git Integration

• Perform Git operations in local repositories

• View status, diffs, and commit history

• Commit changes and manage branches

• Create, checkout and merge branches

• Manage remote repositories

• Display commit details and changes

Future Roadmap

MIST is continuously evolving to offer more integrations and features. Here's what we're planning to add:

Document & File Management

• Google Drive Integration: Access and manage files, search documents, and analyze content

• Google Sheets Integration: Create, read, and update spreadsheets for data analysis

Search & Information Access

• Google Custom Search: Enable web search capabilities for research and information retrieval

• Knowledge Base: Build local repositories of information for offline access

Collaboration Tools

• Google Classroom: Access courses, assignments, and educational materials

• Google Chat: Interact with chat spaces and messages for team collaboration

Data & Location Services

• Google Forms: Create and manage forms for data collection

• Google Maps: Add location-based services including geocoding and directions

Platform Improvements

• Enhanced Caching: Improve performance for frequently accessed data

• Multi-User Support: Add user profiles and permission management

• Expanded AI Assistant Compatibility: Support more AI assistants and models

We welcome contributions in any of these areas! Check our Contributing Guidelines for more information on how to get involved.

System Architecture

MIST operates as an MCP server that connects AI assistants to various services. It handles authentication, data retrieval, and actions with the appropriate services, returning structured data back to the AI assistant.

Communication Flow

Installation

Prerequisites

• Python 3.13 or newer

• UV package manager (recommended) or pip

• Google account (for Gmail/Calendar/Tasks integration)

• Git (for Git integration features)

Setup

1. Clone this repository:

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

2. Install dependencies:

   With UV (recommended):

   uv install

   With pip:

   pip install -e .

3. Configure your environment:

   # 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

   Edit the .env file to set the correct paths for your environment.

Environment Configuration

The following environment variables can be set in your .env file:

Google API Configuration

Setting up Gmail, Calendar, and Tasks APIs

1. Create a Google Cloud Project

   • Navigate to the Google Cloud Console

   • Create a new project or select an existing one

   • Give it a descriptive name (e.g., "MIST Integration")

2. Enable Required APIs

   • Go to "APIs & Services" > "Library"

   • Search for and enable:

     • Gmail API

     • Calendar API

     • Tasks API

3. Configure OAuth Consent Screen

   • Go to "APIs & Services" > "OAuth consent screen"

   • Select "External" user type (or "Internal" for Google Workspace)

   • Fill in required information:

     • App name: "MIST Integration"

     • User support email: Your email address

     • Developer contact information: Your email address

   • Click "Save and Continue"

   • Add necessary scopes for each API

   • Add your Google account as a test user

4. Create OAuth Credentials

   • Go to "APIs & Services" > "Credentials"

   • Click "Create Credentials" > "OAuth client ID"

   • Select "Desktop application" as the application type

   • Enter a name (e.g., "MIST Desktop Client")

   • Download the JSON file and save it as credentials.json in your project directory

Usage

Running the MCP Server

Start the MCP server with:

For production use, you may want to use a process manager like systemd, supervisor, or pm2.

Connecting to AI Assistants

Claude Desktop

Add the following to your Claude Desktop settings:

Zed Editor

Add the following to your Zed editor settings:

First Run Authentication

When you first run the server, you'll need to authenticate with Google:

1. A browser window will open with Google's authentication page

2. Sign in with your Google account

3. Grant the requested permissions

4. The authorization code will be captured automatically

5. MIST will save the authentication token for future use

API Reference

Note Management API

Gmail API

Calendar API

Tasks API

Git API

Below is a selection of commonly used Git tools. For a complete list and detailed parameters, please refer to the API Reference.

Project Structure

Security Considerations

• API keys and tokens are stored in the .env file or environment variables

• OAuth tokens are securely managed by Google's authentication flow

• Your data remains on your own device or within your own accounts

• No data is sent to third-party services unless explicitly configured

Troubleshooting

Authentication Issues

• Credentials not working: Delete token.json and re-authenticate

• Permission errors: Check OAuth consent screen for proper scopes

• Token expired: MIST should refresh tokens automatically, but you may need to re-authenticate if refresh fails

Connection Problems

• AI assistant cannot connect: Verify paths in configuration are correct

• Server fails to start: Check Python version (3.13+ required)

• API errors: Verify API keys and credentials are correctly set up

Data Issues

• Notes not saving: Check MIST_NOTES_DIR path exists and is writable

Development

Linting and Formatting

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details on how to get started.

1. Fork the repository

2. Create a feature branch: git checkout -b feature/amazing-feature

3. Make your changes and commit them: git commit -m 'Add amazing feature'

4. Push to your branch: git push origin feature/amazing-feature

5. Open a pull request

License

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

Acknowledgments

• Model Context Protocol for the protocol specification

• Google APIs for Gmail, Calendar, and Tasks integration

Made with ❤️ by CLoaKY