Stateless Outlook MCP

🚀 无状态Outlook MCP——基于零状态图的AI代理集成层

下一代模型上下文协议（MCP）服务器，通过原子化、以用户为中心的工具和高级搜索功能，为人工智能代理提供强大且直观的Microsoft Outlook电子邮件数据访问能力。

  

______________________________________________________________________

🌟 为什么这个项目存在

该项目重新定义了Outlook与AI代理的集成方式，重点在于提高精确度、清晰度和可扩展性。

• 强大的搜索引擎基于Microsoft Search API构建，以提供准确、上下文感知的结果，便于大型语言模型轻松理解。
• 目标驱动型工具每种工具都是为单一、明确界定的任务而设计的，参数简洁明了，确保交互可预测且无错误。
• 已准备好支持多租户设计用于在网页环境中支持多个用户安全、并发地使用。

______________________________________________________________________

✨ 核心功能

1. 🔍（放大镜） 使用 Microsoft Graph 搜索 API 进行增强搜索

此项目采用Microsoft Graph Search API作为其核心搜索引擎——能够在Outlook消息中实现深度、准确且灵活的探索。

主要优势：

• 全文覆盖在所有电子邮件字段中进行搜索，支持高级运算符
• 专为探索而打造专为搜索场景设计，提供稳定一致的表现
• 针对大型语言模型（LLM）优化的语法AI代理能够轻松生成的自然且直观的查询结构
• 高质量成果基于相关性的排名确保用户获得最相关的匹配结果

# Traditional approach (limited, complex)
filter="from/emailAddress/address eq 'john@example.com' and subject eq 'report'"

# Our approach (powerful, intuitive) 
keywords=["meeting", "Q4"], from_email="john@example.com"

搜索API为电子邮件发现提供了稳定、强大的基础，极大地提高了准确性和用户体验。

2. 拼图块（或积木块） 以用户为中心的原子级工具设计

每个工具都是围绕真实用户的工作流程而精心设计的，而非围绕API端点。 功能被拆分为专注、单一职责的工具，这些工具保持参数简洁且直观。

设计理念：

• 一工具，一用途每种工具都针对特定的用户意图
• 简化参数仅显示必要选项
• 与人类对齐的命名参数遵循用户和AI代理自然表达任务的方式
• 降低复杂性显著降低大型语言模型（LLM）的认知负荷

示例：获取最近的电子邮件

工具包为每种场景提供了不同的工具，而不是一个过于通用的API：

• get_inbox_messages_by_count “获取我最近的电子邮件”
• get_inbox_messages_by_date_range “获取上周的电子邮件”
• search_mail_messages “查找关于项目X的电子邮件”

每个工具都是独立自给的，并针对其使用场景进行了优化——确保可靠性和可预测性。

3. 🌐（表示互联网或全球网络） 无状态多租户架构

从零开始构建，旨在 可扩展的网络应用程序 并且 多用户环境。

核心设计原则：

• 默认无状态每个请求都携带自己的access_token和refresh_token
• 客户端OAuth流程在客户端安全地处理身份验证和刷新
• 并发就绪多个用户可以同时进行交互而不会发生冲突
• 可扩展部署无状态架构支持跨环境的水平扩展

适合：

• 带有用户级认证的Web应用程序
• 集成了Outlook功能的SaaS平台
• 服务于多个账户的AI助手
• 无服务器或分布式工作负载

# Example: concurrent user access
await search_mail_messages(
    access_token="user_alice_access_token",
    refresh_token="user_alice_refresh_token", # Alice's mailbox
    keywords=["proposal"]
)

await search_mail_messages(
    access_token="user_bob_access_token",
    refresh_token="user_bob_refresh_token",   # Bob's mailbox
    keywords=["invoice"]
)

其结果是为Outlook集成应用程序提供了一个简洁、安全且可扩展的基础，既适用于人类驱动的用例，也适用于人工智能驱动的用例。

______________________________________________________________________

🚀 快速入门

先决条件

• Python 3.11+
• 紫外线 包管理器
• Microsoft Azure AD 应用程序 具有Mail.Read权限

安装

# Clone the repository
git clone https://github.com/yourusername/project-name.git
cd project-name

# Install dependencies
uv sync

# Optional: Configure environment variables
cp .env.example .env

运行服务器

# Start with stdio transport (default, for MCP clients)
uv run main.py

# Or use HTTP transport for web integrations
uv run main.py --transport streamable-http

______________________________________________________________________

🔧 可用工具

所有工具均需有效 access_token 并且 refresh_token 用于身份验证的参数。

电子邮件搜索与发现

search_mail_messages

使用自然语言查询并结合高级过滤功能搜索电子邮件。

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "eyJhbGciOiJI...",
  "keywords": ["quarterly", "report"],
  "keywords_operator": "AND",
  "from_email": "manager@company.com",
  "start_date": "2025-01-01",
  "max_results": 50
}

返回值： 带有智能分页功能的完整电子邮件对象

______________________________________________________________________

get_inbox_messages_by_count

获取收件箱中最新的N条消息——简单快捷。

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "eyJhbGciOiJI...",
  "count": 100
}

用例： “给我显示最近50封邮件”

______________________________________________________________________

get_inbox_messages_by_date_range

检索特定日期范围内的电子邮件。

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "eyJhbGciOiJI...",
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "top": 100
}

用例： “获取一月份的所有电子邮件”

______________________________________________________________________

电子邮件检索

get_mail_message

获取特定电子邮件的详细信息。

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "eyJhbGciOiJI...",
  "message_id": "AAMkAGI2T..."
}

______________________________________________________________________

batch_get_mail_messages

在单个请求中高效检索多封电子邮件（最多20封）。

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "eyJhbGciOiJI...",
  "message_ids": ["AAMkAGI2T...", "AAMkAGI2U...", "AAMkAGI2V..."]
}

演出 使用 Microsoft Graph 批处理 API 以实现最佳速度

______________________________________________________________________

文件夹管理

list_mail_folders

列出所有邮箱文件夹。

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "eyJhbGciOiJI...",
  "top": 50
}

______________________________________________________________________

list_mail_folder_messages

列出特定文件夹中的消息，并应用过滤条件。

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "eyJhbGciOiJI...",
  "folder_id": "inbox",
  "filter": "isRead eq false",
  "top": 50
}

______________________________________________________________________

🏗️ 建筑学

无状态请求流程

sequenceDiagram
    participant Client as Client
(Web App)
    participant MCP as MCP Server
(Stateless)
    participant Graph as Microsoft Graph
API
    
    Client->>MCP: Request with access_token & refresh_token
    MCP->>MCP: Create GraphClient instance
    MCP->>Graph: API Request with access_token
    
    alt Token Valid
        Graph-->>MCP: Response Data
        MCP-->>Client: Return Data
    else Token Expired (401)
        Graph-->>MCP: 401 Unauthorized
        alt OAuth Configured
            MCP->>Graph: Refresh Token Request
            Graph-->>MCP: New access_token
            MCP->>Graph: Retry API Request
            Graph-->>MCP: Response Data
            MCP-->>Client: Return Data
        else OAuth Not Configured
            MCP-->>Client: Authentication Error
        end
    end
    
    Note over Client,Graph: Every request contains user tokens
Server remains stateless

关键组件

• FastMCP 服务器工具注册和MCP协议处理
• 图形客户端微软Graph API的异步HTTP客户端
• 搜索API集成用于电子邮件发现的主要搜索引擎
• 批处理API助手高效多消息检索
• 原子工具以用户为中心，单一用途功能

______________________________________________________________________

📦 项目结构

project-name/
├── main.py                    # Server entry point
├── pyproject.toml             # Dependencies & configuration
├── .env.example               # Environment variables template
├── core/
│   ├── server.py             # FastMCP server instance
│   ├── graph_client.py       # Microsoft Graph API client
│   ├── config.py             # Pydantic settings
│   ├── logger.py             # Logging configuration
│   └── exceptions.py         # Custom exceptions
├── tools/
│   ├── outlook.py            # MCP tool definitions
│   └── helpers/
│       ├── search_api.py     # Search API integration
│       ├── batch_api.py      # Batch API utilities
│       ├── query_builders.py # Query construction
│       └── data_cleaners.py  # Response normalization
└── auth/
    └── decorator.py          # Authentication decorator

______________________________________________________________________

🧪 测试

使用MCP Inspector

npx @modelcontextprotocol/inspector uv run main.py

手动测试

# Start server in HTTP mode
uv run main.py --transport streamable-http

# Send test requests to http://127.0.0.1:8000

______________________________________________________________________

⚙️ 配置

环境变量

\* 注： Azure OAuth 参数（AZURE_TENANT_ID， AZURE_CLIENT_ID， AZURE_CLIENT_SECRET如果您的应用程序需要在服务器端自动刷新用户令牌，则需要这些参数。对于客户端处理令牌刷新的无状态架构，可以省略这些参数。

本地开发：

# Use defaults - no configuration needed
uv run main.py

使用 Azure OAuth 令牌刷新功能：

# Configure in .env file
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

Kubernetes 部署（或：Kubernetes 部署方式）

env:
  - name: OUTLOOK_MCP_SERVER_HOST
    value: "0.0.0.0"  # Accept external connections
  - name: OUTLOOK_MCP_SERVER_PORT
    value: "8080"
  # Optional: Add Azure OAuth configuration for token refresh
  - name: AZURE_TENANT_ID
    valueFrom:
      secretKeyRef:
        name: outlook-mcp-secrets
        key: tenant-id
  - name: AZURE_CLIENT_ID
    valueFrom:
      secretKeyRef:
        name: outlook-mcp-secrets
        key: client-id
  - name: AZURE_CLIENT_SECRET
    valueFrom:
      secretKeyRef:
        name: outlook-mcp-secrets
        key: client-secret

______________________________________________________________________

📄 许可证

这个项目遵循MIT许可证授权——详见 许可证 详情请查阅文件。

______________________________________________________________________

🙏 致谢

• 模型上下文协议 - 协议规范
• FastMCP - MCP服务器框架
• Microsoft Graph API - 电子邮件数据访问
• 开源社区

______________________________________________________________________

为AI代理社区倾心打造

⭐ 如果你觉得这个仓库有用，就给它点个星吧！ ⭐