Claude Integration with MCP for Microsoft Graph API

Claude 与 Microsoft Graph API 的 MCP 集成

本仓库提供了一套完整的解决方案，可将 Claude 与 Model Context Protocol（MCP）服务集成，以访问 Microsoft Graph API。

分步实施指南

阶段 1：设置 MCP 服务

1. 克隆此仓库

   git clone https://github.com/JBAgent/Test1.git
   cd Test1
   

2. 安装 MCP 服务的依赖项

   cd mcp-server
   npm install
   

3. 配置环境变量

   cp .env.example .env
   # Edit .env with your Azure AD credentials
   

4. 启动 MCP 服务

   npm start
   

5. 测试 MCP 服务

   # Using the provided test client
   node test-client.js
   
   # Or using curl
   curl -X POST http://localhost:3000/api/graph \
     -H "Content-Type: application/json" \
     -H "X-User-ID: default-user" \
     -d '{"endpoint": "/users", "method": "GET", "queryParams": {"$top": 5}, "allData": false}'
   

阶段 2：设置 Claude 集成

1. 安装 Claude 应用的依赖项

   cd ../claude-app
   npm install
   

2. 配置环境变量

   cp .env.example .env
   # Edit .env with your Anthropic API key and MCP server URL
   

3. 启动 Claude 应用

   npm start
   

4. 测试 Claude 集成

   curl -X POST http://localhost:4000/api/chat \
     -H "Content-Type: application/json" \
     -d '{"messages": [{"role": "user", "content": "How many users are in our organization?"}]}'
   

阶段 3：自定义集成

1. 添加更多 Graph API 函数

   • 编辑 claude-mcp-integration.js，添加专用函数
   • 更新 claude-app.js 中的函数定义

2. 自定义系统提示词

   • 编辑 claude-app.js 中的系统提示词，以调整 Claude 的行为
   • 添加特定领域的上下文，以获得更好的回复

3. 实现缓存（可选）

   • 添加 Redis，以缓存常用的 Graph API 响应
   • 更新 MCP 服务，使其在发起 API 调用前检查缓存

4. 添加监控和日志记录

   • 为所有 Graph API 请求实现日志记录
   • 设置 MCP 服务和 Claude 应用的监控

项目结构

Test1/
├── mcp-server/               # MCP Server for Microsoft Graph API
│   ├── server.js             # Main server implementation
│   ├── test-client.js        # Test client for verification
│   ├── package.json          # Dependencies
│   ├── Dockerfile            # Container configuration
│   └── .env.example          # Example environment variables
│
├── claude-app/               # Claude Application
│   ├── claude-app.js         # Main application server
│   ├── claude-mcp-integration.js  # Integration module
│   ├── package.json          # Dependencies
│   └── .env.example          # Example environment variables
│
└── docs/                     # Documentation
    └── integration-guide.md  # Detailed integration guide

环境变量

MCP 服务（.env）

AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
PORT=3000
NODE_ENV=development         # Set to 'production' in production

Claude 应用（.env）

ANTHROPIC_API_KEY=your-anthropic-api-key
MCP_SERVER_URL=http://localhost:3000
MCP_USER_ID=default-user
PORT=4000

API 端点

MCP 服务

• POST /api/graph
  • 向 Microsoft Graph API 发起请求
  • 需要通过 X-User-ID 标头进行身份验证
  • 请求正文包含 Graph API 请求选项

Claude 应用

• POST /api/chat

  • 向 Claude 发送消息，并提供 Graph API 功能
  • 请求正文包含消息数组和可选的系统提示词

• POST /api/analyze-organization

  • 用于组织分析的专用端点
  • 简化有关组织的问题提问

Graph API 请求选项

向 MCP 服务发起请求时，可以包含以下选项：

{
  "endpoint": "/users",          // Required: Graph API endpoint
  "method": "GET",               // Optional: HTTP method (default: GET)
  "version": "beta",             // Optional: API version (default: beta)
  "queryParams": {},             // Optional: Query parameters
  "body": {},                    // Optional: Request body for POST/PUT/PATCH
  "allData": false               // Optional: Auto-pagination (default: false)
}

关于 consistencyLevel 的重要说明

经过测试，我们发现许多 Graph API 配置通常不支持 consistencyLevel 参数。为确保最大兼容性，我们已将其从所有默认请求中移除。

如果你需要在特定环境中使用此参数（例如，某些高级目录查询场景），可以手动将其添加到 queryParams 中：

{
  "endpoint": "/users",
  "method": "GET",
  "queryParams": {
    "$top": 5,
    "consistencyLevel": "eventual"
  }
}

不过，我们建议在使用此参数前仔细测试，因为它可能会在许多环境中导致错误。

JSON 格式要求

向 MCP 服务发起请求时，请确保 JSON 格式正确：

1. 键和值均使用双引号：

   {"endpoint": "/users", "method": "GET"}
   

2. 不要错误地嵌套 JSON 字符串：

   {"queryParams": {"$filter": "displayName eq 'John'"}}
   

3. 使用正确的 JSON 类型：

   {"allData": true, "count": 10}
   

获取 Microsoft Azure 凭据

若要获取 AZURE_CLIENT_ID 和 AZURE_CLIENT_SECRET：

1. 登录 Azure Portal
2. 前往 Azure Active Directory > App registrations
3. 创建新的注册，或使用现有注册
4. 复制 Application (client) ID，即 AZURE_CLIENT_ID
5. 前往 Certificates & secrets > New client secret
6. 创建新的密钥并复制其值，即 AZURE_CLIENT_SECRET
7. 在 API permissions 下，添加 Microsoft Graph 权限

安全注意事项

1. 身份验证

   • MCP 服务使用 Azure AD 对 Graph API 进行身份验证
   • Claude 应用应实现适当的身份验证

2. 授权

   • MCP 服务根据用户上下文强制执行权限
   • 为敏感操作实现基于角色的访问控制

3. 数据保护

   • 注意与 Claude 共享的数据
   • 实施数据保留策略

4. 审计日志

   • 记录所有 Graph API 请求以满足合规要求
   • 监控异常访问模式

故障排除

1. MCP 服务连接问题

   • 验证 Azure AD 凭据
   • 检查网络连接
   • 使用提供的 test-client.js 验证连接

2. JSON 解析错误

   • 确保请求使用有效的 JSON，并使用双引号
   • 不要发送单引号字符串或转义不正确的字符
   • 查看 test-client.js 中的请求格式示例

3. Graph API 错误

   • “Unrecognized query argument: consistencyLevel”——此错误表示你的 Graph API 配置不支持此参数。我们已将其从所有示例和默认行为中移除。
   • 检查 Azure AD 中的权限，确保已为应用授予正确的范围
   • 验证请求格式和参数
   • 检查是否存在速率限制问题

4. Claude API 错误

   • 验证 Anthropic API 密钥
   • 确保请求格式正确

贡献

欢迎贡献！请随时提交 Pull Request。