Teams Messenger MCP Bridge Component

This system implements a dedicated Model Context Protocol (MCP) intermediary layer, linking Microsoft Teams environments with standard MCP consumers (e.g., agents, LLM systems, or specialized CLI clients). All operational facets—data access, messaging, and state management—are exclusively exposed through native MCP primitives (tools, resources, and events), entirely avoiding conventional RESTful API exposure.

Key Functionality

• Native integration of MS Teams chat capabilities via the MCP standard.
• Utilizes a PostgreSQL backend, augmented with pgvector, for sophisticated Information Retrieval (IR) indexing and advanced query execution.
• Durable storage for all archival communication records is managed by DuckDB.
• Implements a sophisticated hybrid search methodology (combining lexical techniques like BM25 with vector similarity, mirroring FlockMTL's RAG approach).
• Includes a local command-line utility for credential handling (token lifecycle) and acting as a full-featured MCP client for development testing.
• New message notifications are propagated using a controlled, polling-based event mechanism.
• Supports real-time event propagation and dynamic search interaction for connected AI agents and the CLI.
• Operates using a designated single bot identity.

System Topology

+-------------------+ +-----------------------+ +-------------------+
| CLI MCP Client |<---->| MCP Broker Server |<---->| MS Teams Platform | | (Rich Terminal UI)| | (Built with FastMCP) | | (Via MS Graph API) | +-------------------+ +-----------------------+ +-------------------+
| |
| v
| +-------------------+ +-----------------------+ | | DuckDB Storage | | Indexing/Search IR | | +-------------------+ | (PostgreSQL Backend) | +-----------------------+ |
v
+-----------------------+ | PostgreSQL DB | | (with pgvector Index) | +-----------------------+

• Data interactions, conversational actions, and search operations strictly adhere to the MCP specification.
• The core Teams MCP service persists message data utilizing DuckDB.
• The dedicated IR service manages high-performance querying via PostgreSQL and vector embeddings.
• The IR service communicates with the MCP Broker over a localized HTTP interface.

Deployment Procedures

Prerequisites

• Python interpreter version 3.9 or newer.
• Python's package installer (pip).
• Containerization tools: Docker and Docker Compose.

Method A: Direct Local Setup

1. Repository Acquisition

bash git clone cd mcp-teams

2. Dependency Installation

bash pip install -r requirements.txt

3. Configuration Initialization

Duplicate the template file and populate required authentication details for Azure AD/Teams: bash cp .env.template .env

Manually edit .env with your credentials

Refer to the environment variable table below for variable definitions.

Method B: Containerized Environment (Recommended)

1. Repository Acquisition

bash git clone cd mcp-teams

2. Credential File Preparation

Prepare the .env configuration file with necessary parameters: bash cp .env.template .env

Configure your settings in .env

3. Service Orchestration

bash docker-compose up -d

To monitor running components: bash docker-compose logs -f teams_mcp # View Broker service activity docker-compose logs -f ir_server # View Indexing/Search service activity

Simulated Operation (Demo Mode)

Set the DEMO_MODE environment variable to true in .env to bypass live Teams API interactions during testing, then execute services as detailed above.

Configuration Parameters (.env)

Parameter Name	Purpose	Typical Value / Default
AZURE_CLIENT_ID	Identifier for the registered Azure AD application	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_CLIENT_SECRET	Secret key associated with the Azure AD application	your-secret
AZURE_TENANT_ID	The directory identifier for your Azure subscription	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_APP_OBJECT_ID	The unique identifier for the application instance	xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DUCKDB_PATH	File system location for the persistent message ledger	db/teams_mcp.duckdb
TOKEN_PATH	Location for caching authenticated tokens	db/token_cache.json
POLL_INTERVAL	Frequency (in seconds) for checking Teams for new messages	10
DEMO_MODE	Flag to enable mock API calls instead of live integration	false
OPENAI_API_KEY	Key required for generating vector embeddings (if utilized)	sk-...
POSTGRES_USER	Database access username	postgres
POSTGRES_PASSWORD	Database access password	postgres
POSTGRES_DB	Target database name for the IR service	mcp_ir
IR_SERVER_HOST	Network address for locating the Indexing/Search service	ir_server
IR_SERVER_PORT	Network port for the Indexing/Search service communication	8090

Service Execution Methods

Local Execution (Non-Containerized)

bash python mcp_server/server.py

Containerized Deployment (Full Stack)

bash docker-compose up -d

Checking component output streams: bash docker-compose logs -f teams_mcp docker-compose logs -f ir_server

Utilizing Demo Mode

Activate by setting DEMO_MODE=true in .env and launching the environment as described above.

CLI Client Operations

1. Authentication Management

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

2. Rich MCP Interaction via Stdio

The client communicates with the broker service using the MCP standard over standard input/output.

Retrieve list of active conversations

bash python cli/mcp_client.py list_chats

Fetch historical messages for a specific channel/chat

bash python cli/mcp_client.py get_messages

Transmit a new message

bash python cli/mcp_client.py send_message "Message payload here!"

Initiate a new one-on-one dialogue

bash python cli/mcp_client.py create_chat

Execute content discovery (hybrid, lexical, or vector)

bash python cli/mcp_client.py search_messages "query terms" --mode hybrid --top_k 5

Subscribe to real-time message ingress (live feed)

bash python cli/mcp_client.py stream

IR Server Interface Details

The Indexing and Retrieval (IR) component provides advanced data querying capabilities backed by PostgreSQL. It exposes a dedicated HTTP interface consumed by the primary MCP broker.

IR Server HTTP Endpoints

1. System Operational Status Check

GET http://localhost:8090/

2. Query Available Tools List

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

3. Execute Content Search Operation

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

Payload Example:

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

4. Inject Content for Indexing

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

Payload Example:

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

Comprehensive IR service documentation is available at ir/README.md.

Data Flow and Event Handling

• Search Strategy: Employing a combined BM25 and vector approach, refined potentially by LLM reranking logic.
• Real-time Updates: Active subscriptions to the messages/incoming event channel provide immediate updates.

Customization and Expansion

• Define novel MCP operations within mcp_server/server.py.
• Modify Teams API interaction logic in teams/graph.py.
• Adapt or enhance IR server functionalities.
• Integrate further analytical or generative AI features leveraging DuckDB, PostgreSQL, and language models.
• Leverage the CLI as a primary tool for rapid functional validation.

Common Issues and Resolutions

• Authentication Failure: Verify all requisite credentials within the .env file against your Azure AD configuration.
• Message Ingress Stalled: Confirm the polling mechanism is active and the service account has membership in the target Teams channels.
• DuckDB Access Errors: Examine file path validity and required OS file system permissions.
• IR Server Unreachable: Review Docker Compose logs for the IR service startup sequence.
• Testing Safely: Use DEMO_MODE=true to isolate local development from live external services.

Referenced Specifications

• FlockMTL Paper: Deep Integration of Language Models and RAG into DuckDB
• Model Context Protocol Specification
• Microsoft Graph API Documentation
• PostgreSQL Vectorization Extension

---

Detailed application specifications are located in specs/app-spec.md.

WIKIPEDIA SNIPPET: XMLHttpRequest (XHR) denotes an Application Programming Interface accessible via JavaScript, enabling web applications to dispatch HTTP requests asynchronously to a backend server post-page load, subsequently receiving server responses. XHR is foundational to the Ajax programming paradigm. Prior to its widespread adoption, server communication relied primarily on traditional page reloads initiated by form submissions or hyperlink navigation.

== Lineage == The precursor to XMLHttpRequest originated in 2000, developed by the Microsoft Outlook team. This concept was first realized in the Internet Explorer 5 browser (1999), although it initially employed COM object identifiers like ActiveXObject("Msxml2.XMLHTTP"). By the release of Internet Explorer 7 (2006), the standardized XMLHttpRequest naming convention achieved universal browser acceptance. This identifier subsequently became the established convention across major rendering engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Evolution === The World Wide Web Consortium (W3C) issued the first formal specification draft for the XMLHttpRequest object in April 2006. A Level 2 draft followed in February 2008, introducing capabilities for monitoring request progress, enabling cross-origin data exchange, and handling raw byte streams. By late 2011, the Level 2 enhancements were integrated back into the primary specification. Development responsibility transitioned to the WHATWG consortium in late 2012, which maintains the living document using Web IDL notation.

== Standard Operation Sequence == Sending a request via XMLHttpRequest generally involves a sequence of programmatic steps:

1. Object Instantiation: Invoking the constructor to generate an XMLHttpRequest instance.
2. Request Configuration: Utilizing the open method to define the request method (GET/POST, etc.), specify the target Uniform Resource Identifier (URI), and declare operation mode (synchronous or asynchronous).
3. Asynchronous Callback Setup: For non-blocking operations, registering an event handler function to manage state transitions.
4. Transmission Initiation: Triggering the data dispatch using the send method.
5. Response Handling: Monitoring the object's state changes via the registered listener. Upon successful completion (state 4, or 'done'), response data is accessible, typically in the responseText property.

Beyond these fundamentals, XHR offers extensive control over request fidelity. Custom HTTP headers can be injected to guide server behavior. Data can be uploaded via parameters in the send call. Responses can be automatically parsed from JSON into native JavaScript objects, or processed incrementally as data arrives, avoiding blocking waits. Furthermore, requests can be terminated prematurely or subjected to time-out constraints.

== Cross-Origin Constraints == In the nascent stages of the World Wide Web, mechanisms were established to prevent security vulnerabilities arising from unrestricted communication between scripts originating from different domains, a constraint that XHR must navigate.