MIST - Model Intelligence System for Tasks

MIST - 任务模型智能系统

MIST 是一款全面的 MCP（模型上下文协议）服务，可为 AI 助手提供笔记管理、Gmail、日历、任务和 Git 集成等真实世界能力。它弥合了 AI 助手与外部工具之间的差距，让它们能够通过标准化协议与您的数据和服务交互。

概述

MIST 让 AI 助手能够：

• 管理笔记：创建、编辑、搜索和整理笔记，并进行持久化存储
• 与 Gmail 交互：搜索邮件、阅读邮件、发送邮件和管理标签
• 管理日历活动：查看、创建、更新和删除 Google 日历活动
• 整理任务：创建任务列表、添加任务并将任务标记为已完成
• 使用 Git 仓库：执行状态查看、差异比较、提交和分支管理等 Git 操作

通过实现模型上下文协议（MCP），MIST 让 AI 助手能够在外部系统中执行操作、访问实时信息，并在多次交互中保留上下文。

主要功能

笔记管理

• 创建和存储支持富文本格式的笔记
• 按内容、标签或元数据搜索笔记
• 生成笔记或笔记集合的摘要
• 按主题、日期或自定义类别整理笔记
• 在本地文件系统中存储笔记

Gmail 集成

• 使用高级筛选选项搜索邮件
• 阅读完整邮件内容
• 撰写并发送邮件
• 管理邮件标签和整理邮件
• 将邮件标记为已读或未读
• 对多封邮件执行批量操作

日历集成

• 列出所有可用日历
• 创建和管理日历活动
• 更新现有活动
• 按关键词或日期范围搜索活动
• 查看活动详细信息

任务集成

• 列出和管理任务列表
• 创建包含标题、备注和截止日期的任务
• 将任务标记为已完成
• 删除已完成的任务
• 将任务整理到不同列表中

Git 集成

• 在本地仓库中执行 Git 操作
• 查看状态、差异和提交历史
• 提交更改并管理分支
• 创建、检出和合并分支
• 管理远程仓库
• 显示提交详情和更改内容

未来规划

MIST 持续发展，不断提供更多集成和功能。以下是我们的计划：

文档和文件管理

• Google Drive 集成：访问和管理文件、搜索文档并分析内容
• Google Sheets 集成：创建、读取和更新电子表格，用于数据分析

搜索和信息访问

• Google Custom Search：提供网页搜索功能，用于研究和信息检索
• 知识库：构建本地信息库，以便离线访问

协作工具

• Google Classroom：访问课程、作业和教育材料
• Google Chat：与聊天空间和消息交互，支持团队协作

数据和位置服务

• Google Forms：创建和管理表单以收集数据
• Google Maps：添加地理编码和路线规划等基于位置的服务

平台改进

• 增强缓存：提升频繁访问数据的性能
• 多用户支持：添加用户配置文件和权限管理
• 扩展 AI 助手兼容性：支持更多 AI 助手和模型

欢迎在以上任何领域贡献力量！请查看我们的贡献指南，了解如何参与。

系统架构

MIST 作为 MCP 服务运行，将 AI 助手连接到各种服务。它负责身份验证、从相应服务检索数据并执行操作，然后将结构化数据返回给 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”
   • 搜索并启用：
     • 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 编辑器设置中：

"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. Fork 此仓库
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 提供协议规范
• 感谢 Google APIs 提供 Gmail、Calendar 和 Tasks 集成

---

由 CLoaKY 倾心打造 ❤️