OneNote-MCP-For-GeminiSpark

Microsoft OneNote와 Gemini Spark 통합을 위한 강력한 Model Context Protocol(MCP) 서버입니다. 이 저장소에는 OneNote 콘텐츠를 GeminiSpark 워크플로와 동기화하고, OneNote 노트를 GeminiSpark 호환 형식으로 내보내고, 일반적인 자동화 시나리오를 보여주는 코드, 구성 및 예제가 포함되어 있습니다.

🎯 이 도구가 하는 일

OneNote 전자 필기장을 AI가 액세스할 수 있는 지식 기반으로 변환합니다:

• 모든 전자 필기장, 섹션 및 페이지 나열

• 분석 및 검색을 위한 페이지 콘텐츠 읽기

• 자연어 쿼리 예: "DevOps 노트 보여줘" 또는 "프로젝트 계획에 대한 페이지 찾기"

• Microsoft Graph API를 사용한 안전한 OAuth 인증

• 상세 디버깅을 포함한 완벽한 오류 처리

✨ 이 구현이 특별한 이유

다른 OneNote MCP 서버와 달리 이 서버는:

• ✅ 실제로 작동 - 실제 OneNote 데이터로 광범위하게 테스트됨

• ✅ 완전한 기능 - 모든 핵심 OneNote 작업 구현

• ✅ 강력한 인증 - 엣지 케이스를 처리하는 2단계 디바이스 플로우

• ✅ 프로덕션 준비 - 적절한 오류 처리 및 로깅

• ✅ 간편한 설정 - 비기술 사용자를 위한 상세 지침

🚀 빠른 시작

사전 요구 사항

• 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 앱 등록

OneNote에 액세스하려면 Azure 앱을 만들어야 합니다. 걱정 마세요. 무료이며 5분밖에 걸리지 않습니다:

1. Azure Portal로 이동합니다(Microsoft 계정으로 로그인).

2. Azure Active Directory → 앱 등록 → 새 등록으로 이동합니다.

3. 양식을 작성합니다:

   • 이름: "OneNote MCP Server"(또는 원하는 이름)

   • 지원되는 계정 유형: "모든 조직 디렉터리의 계정 및 개인 Microsoft 계정"

4. 등록을 클릭합니다.

5. 애플리케이션(클라이언트) ID를 복사합니다. 이 ID가 필요합니다!

4. 권한 추가

Azure 앱에서 계속:

1. API 권한 → 권한 추가로 이동합니다.

2. Microsoft Graph → 위임된 권한을 선택합니다.

3. 다음 권한을 추가합니다:

   • Notes.Read - OneNote 전자 필기장 읽기

   • Notes.ReadWrite - OneNote 콘텐츠 만들기/수정(선택 사항이지만 권장)

   • User.Read - 사용자 프로필 읽기

   • Offline.access - 새로 고침 토큰 액세스 허용

4. 관리자 동의 허용(상단의 버튼)을 클릭합니다.

5. 매니페스트로 이동하여 signInAudience를 AzureADandPersonalMicrosoftAccount로, requestedAccessTokenVersion을 2로 업데이트하고 저장합니다.

5. Azure 새로 고침 토큰 생성(1회 활동)

• refresh_token.py 파일에서 Azure 클라이언트 ID를 업데이트하고 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
  

• 배포 후 MCP 서버 URL이 생성됩니다.

7. Gemini Spark에서 사용자 지정 연결 앱 설정

• 연결 앱을 클릭합니다.

• MCP 서버 URL/sse를 입력합니다(URL 끝에 /sse를 추가하는 것을 잊지 마세요).

• 고급 설정 -> Azure 클라이언트 ID를 입력합니다.

• 리디렉션 URI 복사를 클릭하고 Azure Portal --> Azure 클라이언트 앱 --> 인증 --> 리디렉션 URI --> URI 추가 --> 웹 --> 복사한 링크 붙여넣기 --> 다른 리디렉션 URI를 제거합니다.

• 연결 앱 대화 상자에서 다음을 클릭하고 화면의 지시를 따릅니다.

• 연결 앱 화면에 OneNote MCP 서버가 생성됩니다.

사용법

연결 앱이 설정되면 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

🛠 문제 해결

Gemini Spark 연결 앱 화면에서 "사용 가능한 도구 없음"

• 화면에서 리디렉션 URI를 복사하여 Microsoft Azure 앱에 올바르게 업데이트했는지 확인합니다.

• MCP 서버의 클라우드 배포에서 인증되지 않은 액세스가 활성화되어 있는지 확인합니다.

• uv가 설치되어 있는지 확인합니다: uv --version

인증 문제

• Safari OAuth 문제: Safari는 Microsoft의 OAuth 리디렉션을 제대로 처리하지 못할 수 있습니다. Firefox 또는 Chrome을 대신 사용하세요.

• "nativeclient" 프롬프트: 정상적인 Microsoft OAuth 동작이지만, 인증을 차단하면 다른 브라우저를 시도해 보세요.

• 권장 브라우저: 최상의 호환성을 위해 Firefox(작동 확인됨), Chrome 또는 Edge를 사용하세요.

"명령을 찾을 수 없음" 오류

• 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. 풀 리퀘스트를 제출합니다.

📄 라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

🙏 감사의 말

• FastMCP 프레임워크로 구축됨

• OneNote 액세스에 Microsoft Graph API 사용

• purpleslurple의 놀라운 작업에서 영감을 받음

⚠️ 중요 참고 사항

• 이 서버는 이미 액세스 권한이 있는 데이터만 읽고 씁니다.

• Azure 앱 자격 증명은 사용자 머신에 유지됩니다.

• 모든 인증은 사용자와 Microsoft 간에 직접 이루어집니다.

• 제3자에게 데이터가 전송되지 않습니다.

Gemini Spark + OneNote 커뮤니티를 위해 ❤️로 제작됨

OneNote를 AI가 액세스할 수 있는 지식 기반으로 바꿔 보세요!