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 服务器提供 HTTP API 以与 MCP 服务器通信

安装

要求

• 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)

变量	描述	示例 / 默认值
AZURE_CLIENT_ID	Azure AD 应用程序（客户端）ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_CLIENT_SECRET	Azure AD 应用程序密钥	your-secret
AZURE_TENANT_ID	Azure AD 租户 ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_APP_OBJECT_ID	Azure AD 应用程序对象 ID	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DUCKDB_PATH	DuckDB 数据库文件路径	db/teams_mcp.duckdb
TOKEN_PATH	存储持久化 token 缓存的路径	db/token_cache.json
POLL_INTERVAL	轮询新消息的时间间隔（秒）	10
DEMO_MODE	设置为 true 以启用模拟/演示模式（不进行实际 Teams API 调用）	false
OPENAI_API_KEY	用于生成嵌入的 OpenAI API 密钥	sk-...
POSTGRES_USER	PostgreSQL 用户名	postgres
POSTGRES_PASSWORD	PostgreSQL 密码	postgres
POSTGRES_DB	PostgreSQL 数据库名称	mcp_ir
IR_SERVER_HOST	IR 服务器主机名	ir_server
IR_SERVER_PORT	IR 服务器端口	8090

运行 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. 登录和 Token 管理

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

2. 功能丰富的 CLI MCP 客户端

以下所有命令都使用 MCP 标准输入输出协议与服务器通信。

列出聊天

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

正文:

{
  "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 的情况下进行本地测试

参考资料

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

---

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