OneNote-MCP-For-GeminiSpark

Надёжный сервер Model Context Protocol (MCP) для интеграции Microsoft OneNote с Gemini Spark. Этот репозиторий содержит код, конфигурацию и примеры для синхронизации содержимого OneNote с рабочими процессами GeminiSpark, экспорта заметок OneNote в форматы, готовые для GeminiSpark, и демонстрации распространённых сценариев автоматизации.

🎯 Что это делает

Превратите свои записные книжки OneNote в базу знаний, доступную для ИИ:

• Перечислить все записные книжки, разделы и страницы

• Читать содержимое страниц для анализа и поиска

• Запросы на естественном языке, например «Покажи мои заметки по DevOps» или «Найди страницы о планировании проектов»

• Безопасная аутентификация OAuth через Microsoft Graph API

• Надёжная обработка ошибок с подробной отладкой

✨ Почему такая реализация

В отличие от других OneNote MCP-серверов, этот:

• ✅ Действительно работает — протестирован на реальных данных OneNote

• ✅ Полная функциональность — реализованы все основные операции OneNote

• ✅ Надёжная аутентификация — двухэтапный device flow, обрабатывающий пограничные случаи

• ✅ Готов к продакшену — правильная обработка ошибок и логирование

• ✅ Простая настройка — подробные инструкции для нетехнических пользователей

🚀 Быстрый старт

Предварительные требования

• Python 3.10+

• менеджер пакетов uv (рекомендуется) или pip

• Аккаунт Google Gemini

• Учётная запись Microsoft Azure (бесплатно)

1. Установите uv (если у вас его нет)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# or with Homebrew
brew install uv

2. Клонирование и настройка

git clone https://github.com/yourusername/onenote-mcp-server.git
cd onenote-mcp-server

# Create virtual environment and install dependencies
uv sync

3. Регистрация приложения Azure

Вам нужно создать приложение Azure для доступа к OneNote. Не волнуйтесь, это бесплатно и займёт 5 минут:

1. Перейдите на портал Azure (войдите с помощью своей учётной записи Microsoft)

2. Перейдите в Azure Active Directory → Регистрация приложений → Новая регистрация

3. Заполните форму:

   • Имя: "OneNote MCP Server" (или как вам нравится)

   • Поддерживаемые типы учётных записей: «Учётные записи в любом каталоге организации и личные учётные записи Microsoft»

4. Нажмите Зарегистрировать

5. Скопируйте Идентификатор приложения (клиента) — он вам понадобится!

4. Добавление разрешений

Всё ещё в вашем приложении Azure:

1. Перейдите в Разрешения API → Добавить разрешение

2. Выберите Microsoft Graph → Делегированные разрешения

3. Добавьте эти разрешения:

   • Notes.Read — чтение записных книжек OneNote

   • Notes.ReadWrite — создание/изменение содержимого OneNote (необязательно, но рекомендуется)

   • User.Read — чтение профиля пользователя

   • Offline.access — разрешить доступ к токену обновления

4. Нажмите «Предоставить согласие администратора» (кнопка вверху)

5. Перейдите в Manifest -> обновите signInAudience на AzureADandPersonalMicrosoftAccount и requestedAccessTokenVersion на 2, затем сохраните.

5. Создание токена обновления Azure (разовое действие)

• Обновите Azure Client ID в файле refresh_token.py и запустите его в cmd.

• Откроется окно браузера. Войдите с помощью своего Microsoft ID.

• После успешного входа в cmd будет сгенерирован токен.

6. Развёртывание MCP-сервера в облаке/локально

• Например, для развёртывания в Google Cloud выполните следующую команду.

  gcloud run deploy onenote-mcp-server --source . --region us-central1
  --set-env-vars="AZURE_REFRESH_TOKEN=YOUR_AZURE_REFRESH_TOKEN,AZURE_CLIENT_ID=YOUR_ACTUAL_CLIENT_ID"
  --allow-unauthenticated
  

• После развёртывания будет сгенерирован URL MCP-сервера.

7. Настройка пользовательского Connected App в Gemini Spark

• Нажмите на Connected Apps

• Заполните URL MCP-сервера/sse (не забудьте добавить /sse в конце URL)

• В дополнительных настройках -> укажите Azure Client ID

• Нажмите «Копировать Redirect URI» и перейдите на портал Azure --> Azure Client App --> Authentication --> Redirect URIs --> Добавить URI --> Web --> вставьте скопированную ссылку --> удалите все остальные Redirect URIs

• В диалоговом окне Connected App нажмите «Далее» и следуйте инструкциям на экране.

• Сервер OneNote MCP будет создан на экране Connected App.

Использование

После настройки Connected App попробуйте выполнить эти задачи в Gemini Spark:

List my OneNote notebooks
Show me sections in my Work notebook  
What pages are in my Ideas section?
Read the content of my "Project Plan" page

🛠 Устранение неполадок

«Нет доступных инструментов» на экране Connected Apps в Gemini Spark

• Убедитесь, что вы скопировали redirect URI с экрана и правильно обновили его в приложении Microsoft Azure.

• Проверьте, включён ли для вашего облачного развёртывания MCP-сервера неаутентифицированный доступ.

• Убедитесь, что uv установлен: uv --version

Проблемы с аутентификацией

• Проблемы OAuth в Safari: Safari может некорректно обрабатывать перенаправление OAuth от Microsoft — используйте Firefox или Chrome

• Запросы "nativeclient": нормальное поведение Microsoft OAuth, но если это блокирует аутентификацию, попробуйте другой браузер

• Рекомендуемые браузеры: Firefox (подтверждено), Chrome или Edge для наилучшей совместимости

Ошибки «Command not found»

• Убедитесь, что uv находится в вашем PATH

• Альтернатива: замените "uv" на "python" в конфигурации и используйте полный путь к вашему интерпретатору Python

Ошибки отказа в доступе

• Проверьте права доступа к файлам в вашем каталоге проекта

🏗 Разработка

Структура проекта

onenote-mcp-server/
├── onenote_mcp_server.py      # Main server implementation
├── pyproject.toml             # Dependencies and metadata
├── refresh_token.py           # Generate Refresh Token
├── README.md                  # This file
├── LICENSE                    # MIT License
└── .gitignore                 # Git ignore rules

Ключевые возможности

• Полная интеграция с Graph API: поддерживаются все операции OneNote

• Надёжная обработка ошибок: подробное логирование и корректные отказы

• Фреймворк FastMCP: чистая и поддерживаемая структура кода

• Конфигурация через переменные окружения: безопасная работа с учётными данными

Добавление новых функций

Сервер создан на FastMCP, что упрощает добавление новых инструментов:

if method == "tools/list":
                    await custom_send({"type": "http.response.start", "status": 200, "headers": [(b"content-type", b"application/json")]})
                    tools = [
  
    # Your implementation here
    return 

🤝 Вклад в проект

Вклад приветствуется! Пожалуйста:

1. Сделайте форк репозитория

2. Создайте ветку функции

3. Добавьте тесты для новой функциональности

4. Отправьте pull request

📄 Лицензия

Лицензия MIT — подробнее см. в файле LICENSE.

🙏 Благодарности

• Создано с помощью фреймворка FastMCP

• Использует Microsoft Graph API для доступа к OneNote

• Вдохновлено замечательной работой purpleslurple

⚠️ Важные примечания

• Этот сервер читает/записывает только те данные, к которым у вас уже есть доступ

• Учётные данные вашего приложения Azure остаются на вашем компьютере

• Вся аутентификация происходит напрямую между вами и Microsoft

• Никакие данные не передаются третьим лицам

Создано с ❤️ для сообщества Gemini Spark + OneNote

Превратите свой OneNote в базу знаний, доступную для ИИ!