CRM连接器

后台CRM MCP连接器（v1）

此存储库包含企业级入门工具包和解决方案设计，用于 后台CRM模型上下文协议（MCP）连接器.

该项目的主要目标是建立一个安全、可扩展和可生产的MCP服务器，作为组织的ChatGPT Enterprise工作区和Backstop CRM API之间的桥梁。此v1连接器将提供对关键CRM数据的只读访问，使用户能够使用自然语言查询帐户、联系人和活动。

项目概述

状态： 里程碑1-进行中
时间线： 6周（第1周正在进行中）
范围： 通过MCP工具对7个核心CRM实体进行只读访问

核心架构和技术栈

该解决方案被设计为一个安全、无状态和可扩展的微服务，部署在Azure应用平台[1]上，遵循企业最佳实践。

初始项目结构

该存储库的结构支持使用FastAPI最佳实践的可扩展分层架构。这种关注点的分离简化了开发、测试和长期维护。

/backstop_mcp_server
├──.github/workflows/
│   └── deploy.yml           # GitHub Actions CI/CD pipeline [5, 6]
├──.dockerignore
├──.gitignore
├── Dockerfile                 # Multi-stage build for a minimal, secure production image [9]
├── README.md                  # Project documentation (this file)
├── requirements.txt           # Python dependencies
└── app/
    ├── __init__.py
    ├── main.py                # FastAPI app factory, startup/shutdown events, middleware
    ├── core/
    │   ├── __init__.py
    │   └── config.py          # Settings management (reads from env vars & Key Vault)
    ├── api/
    │   ├── __init__.py
    │   └── tools.py           # FastAPI routers defining the 7 MCP tool endpoints [1]
    ├── services/
    │   ├── __init__.py
    │   └── backstop_client.py # All logic for Backstop API calls, caching, & rate limiting
    ├── middleware/
    │   ├── __init__.py
    │   └── logging.py         # Audit logging middleware [10, 11, 12]
    └── models/
        ├── __init__.py
        └── schemas.py         # Pydantic models for tool I/O and data transformation [13, 14]

项目里程碑和路线图

该项目遵循6周的开发时间表，有四个不同的里程碑：

里程碑1：可行性和规划（第1周）-- 进行中

建立基础架构和完善的技术计划，以指导未来五周的开发。

关键交付成果：

• 查看Backstop API文档
• 确认身份验证方法（OAuth 2.1+令牌）
• 最终确定工具清单和技术架构
• 计划和项目设置（Azure和Git）
• 为v1定义七（7）个核心只读工具

里程碑2：原型构建（第2-3周）

使用模拟数据构建功能原型，以便进行早期测试和验证。

关键交付成果：

• 实现核心FastAPI服务器和MCP工具定义(/api/tools.py)
• 为所有7个工具开发模拟数据响应，以实现并行UI测试
• 为“身份桥”逻辑实现核心身份验证存根
• 定义UI对齐的数据模式
• 对原型进行内部审查和测试

里程碑3：集成和测试（第4-5周）

连接到实时Backstop API并实现生产级功能。

关键交付成果：

• 将服务连接到实时Backstop API(/services/backstop_client.py)
• 使用Redis实现和测试分布式速率限制和缓存逻辑
• 使用托管身份与Azure密钥库集成
• 使用实时数据进行内部用户测试
• 收集用户反馈并进行必要的调整

里程碑4：部署和文件编制（第6周）

部署到生产环境并完成所有文档。

关键交付成果：

• 部署到Azure应用服务并完成 deploy.yml CI/CD管道
• 在ChatGPT Enterprise工作区注册生产MCP服务器[15]
• 准备最终文件
• 进行演示和最终端到端测试

关键集成和服务设计（v1）

本节详细介绍v1实现的技术规范。

1.v1只读工具

服务器将公开项目范围[1]中定义的以下七（7）个只读工具：

• search_accounts
• get_account_details
• list_contacts
• list_activities
• list_opportunities
• list_relationships
• list_products_vehicles

2.身份验证（双域）

安全性通过双域“身份桥”进行管理，以强制执行每个用户的权限：

• 域1（用户$\rightarrow$服务器）： ChatGPT使用我们的MCP服务器对用户进行身份验证 OAuth 2.1 流动。[16,17]我们的服务器收到一个验证用户身份的JWT。
• 域2（服务器$\rightarrow$CRM）： 我们的服务器使用经过验证的用户身份来检索他们的特定信息 24小时Backstop API代币 从Redis会话存储中。[1] 所有对Backstop API的后续调用都是使用此per-user令牌进行的，该令牌自然会强制该用户的特定CRM权限。[18]

3.利率限制

遵守 100个请求/分钟 limit[1]，我们将使用Azure Cache for Redis实现一个全局分布式速率限制器。这确保了即使应用程序服务扩展到多个实例，也不会违反出站请求限制。[19, 20]

4.安全与日志记录

• 资格证书： 所有机密（Backstop API密钥、Redis密码）将存储在 Azure密钥库 并在运行时由应用服务访问 管理身份.[3]这种“无密码”的方法意味着代码或环境变量中永远不会存储任何秘密。
• 运输： 所有流量都将使用HTTPS进行安全保护，由Azure应用程序服务和API管理进行管理。[21, 22, 1]
• 审计： 定制的FastAPI中间件将记录每个API调用，捕获 user_id, timestamp, endpoint_called，以及 status_code 转到Azure Monitor进行合规性和调试。[10, 11, 1, 12]

企业级部署建议

根据最初的项目文档，我们建议进行两项关键改进，以确保解决方案在生产环境中具有可扩展性、安全性和弹性。

1.优化：使用Redis进行会话和缓存存储

• 初步计划： “基本内存缓存”和“每个用户会话存储”。1.
• 挑战： 内存方法在现代云环境中不起作用。Azure应用服务运行无状态容器；如果应用程序扩展到多个实例，实例A上的内存令牌将不可用于实例B。此外，每次容器重新启动时，所有内存状态都会丢失。
• 推荐解决方案： 我们将利用 Redis的Azure缓存 管理所有应用程序状态。这至关重要，原因有三：
  1. 分布式会话状态： 它为每个用户24小时的Backstop令牌提供了一个中央持久存储，可以从任何容器实例访问。[23, 24, 25]
  2. 集中式速率限制： 它提供了在所有缩放实例中强制执行全局100请求/分钟限制所需的共享计数器。[26, 19]
  3. 性能缓存： 它为读取的、非易失性的CRM数据提供了分布式缓存，减少了冗余的API调用并保护了速率限制。[4, 27]

2.细化：实现“无密码”安全

• 初步计划： “机密必须安全存储（例如Azure）”。1.
• 推荐解决方案： 我们将超越仅仅 存储 秘密和实施a “无密码” 建筑。
• 实施： Azure应用服务本身将被分配一个 管理身份 通过Azure Active Directory。然后我们将批准 身份 （非个人或服务负责人）“读取”Azure密钥库中的机密。FastAPI应用程序将使用 azure-identity 库使用其自己的托管身份对密钥库进行身份验证，不需要硬编码的秘密。[3] 这是云安全的黄金标准。