Teams Messenger MCP 应用

该项目实现了一个纯 Model Context Protocol (MCP) 服务器，用于桥接 Microsoft Teams 和兼容 MCP 的客户端（LLMs、代理框架和一个功能丰富的 CLI MCP 客户端）。所有功能都通过 MCP 工具、资源和事件暴露出来——没有 REST API 端点。

功能

• 通过 MCP 集成 Microsoft Teams 聊天/消息
• 基于 PostgreSQL 的信息检索 (IR) 服务器，提供高级搜索功能
• 使用 DuckDB 进行聊天/消息历史的持久化存储
• 混合语义和词法搜索（BM25 + 向量，FlockMTL风格）
• 用于登录/令牌管理和本地测试的功能丰富的 MCP 客户端 CLI
• 通过轮询方式发出新消息事件
• 实时事件流和针对 LLMs 和 CLI 的搜索
• 单一代理（机器人）账户，不支持多用户

架构

+-------------------+      +-------------------+      +-------------------+
|   CLI MCP Client  |<---->|    MCP Server     |<---->|  Microsoft Teams  |
| (rich terminal UI)|      | (Python, FastMCP) |      |  (Graph API)      |
+-------------------+      +-------------------+      +-------------------+
         |                        |                          
         |                        v                          
         |                +-------------------+      +-------------------+
         |                |     DuckDB DB     |      |    IR Server      |
         |                +-------------------+      | (PostgreSQL, API) |
                                                     +-------------------+
                                                              |
                                                              v
                                                     +-------------------+
                                                     |  PostgreSQL DB    |
                                                     |  (with pgvector)  |
                                                     +-------------------+

• 所有的聊天/消息/搜索逻辑都是通过 MCP 工具/资源/事件来实现的
• Teams MCP 服务器使用 DuckDB 来存储消息
• IR 服务器通过 PostgreSQL 和 pgvector 提供高级搜索功能
• IR 服务器为与 MCP 服务器通信提供 HTTP API

安装

要求

• Python 3.9+
• pip
• Docker 和 Docker Compose（用于容器化部署）

选项 1: 本地安装

1. 克隆仓库

git clone <your-repo-url>
cd mcp-teams

2. 安装依赖

pip install -r requirements.txt

3. 配置环境变量

复制模板并填写您的 Azure AD/Teams 凭证：

cp .env.template .env
# Edit .env and fill in your Azure AD and other settings

请参阅下表以了解变量描述。

选项 2: Docker 部署（推荐）

1. 克隆仓库

git clone <your-repo-url>
cd mcp-teams

2. 配置环境变量

复制模板并填写您的凭证：

cp .env.template .env
# Edit .env and fill in your settings

3. 构建并启动服务

docker-compose up -d

环境变量 (.env)

请注意，原文中的代码块 #0, #1, #2, #3, #4, #5, #6 保持不变。如果这些是具体的命令或配置，请替换它们为实际内容。

运行 MCP 服务器

本地模式（无 Docker）

python mcp_server/server.py

Docker 模式（所有服务）

docker-compose up -d

要查看日志：

docker-compose logs -f teams_mcp  # Teams MCP server logs
docker-compose logs -f ir_server  # IR server logs

演示模式（不进行实际 Teams API 调用）

在你的 .env 文件中设置 DEMO_MODE=true，然后按上述方式运行。

CLI 使用

1. 登录和令牌管理

python cli/login.py login
python cli/login.py status
python cli/login.py logout

2. 丰富的 CLI MCP 客户端

以下所有命令都使用 MCP stdio 协议与服务器通信。

列出聊天

python cli/mcp_client.py list_chats

从聊天中获取消息

python cli/mcp_client.py get_messages <chat_id>

发送消息

python cli/mcp_client.py send_message <chat_id> "Hello from CLI!"

创建新的 1:1 聊天

python cli/mcp_client.py create_chat <user_id_or_email>

搜索消息（混合、BM25 或向量）

python cli/mcp_client.py search_messages "project update" --mode hybrid --top_k 5

流式处理新收到的消息（实时事件订阅）

python cli/mcp_client.py stream

IR 服务器使用

IR 服务器通过 PostgreSQL 和 pgvector 提供高级搜索功能。它暴露了一个 HTTP API 用于与 MCP 服务器通信。

IR 服务器 API 端点

1. 健康检查

GET http://localhost:8090/

2. 列出可用工具

GET http://localhost:8090/api/tools

3. 搜索内容

POST http://localhost:8090/api/tools/search

请求体:

{
  "query": "your search query",
  "search_type": "hybrid",
  "limit": 10
}

4. 索引内容

POST http://localhost:8090/api/tools/index_content

Body:

{
  "content": "Text content to index",
  "source_type": "teams",
  "metadata": {
    "author": "User Name",
    "created": "2025-04-01T12:00:00Z"
  }
}

有关更详细的 IR 服务器文档，请参阅 ir/README.md。

搜索和事件流

• 混合搜索：结合 BM25 和向量搜索，并使用 LLM 重新排序
• 实时流：订阅 messages/incoming 以获取实时更新

开发与扩展

• 在 mcp_server/server.py 中添加新的 MCP 工具/资源
• 在 teams/graph.py 中扩展 Teams 集成
• 修改 IR 服务器中的 IR 功能
• 使用 DuckDB、PostgreSQL 和 LLM 添加分析、摘要或 RAG 功能
• 使用 CLI 作为所有 MCP 功能的测试框架

故障排除与常见问题

• 登录失败：检查您的 Azure AD 凭据和 .env 值
• 没有消息显示：确保轮询正在运行并且您的机器人帐户在 Teams 聊天中
• DuckDB 错误：检查 .env 中的文件权限和路径
• IR 服务器无响应：检查 Docker 日志并确保容器正在运行
• 演示模式：设置 DEMO_MODE=true 以便在没有真实 Teams 的情况下进行本地测试

参考资料

• 超越 Quacking：语言模型和 RAG 在 DuckDB 中的深度集成 (FlockMTL)
• Model Context Protocol 文档
• Microsoft Graph API 文档
• 带有 pgvector 扩展的 PostgreSQL

有关完整的产品详细信息，请参阅 specs/app-spec.md。