Teams Integration Core (MCP)

This repository establishes a native Model Context Protocol (MCP) bridge interfacing with Microsoft Teams infrastructure. All operational endpoints—including data ingestion, state synchronization, and control mechanisms—are exposed exclusively through MCP resources, tools, and event subscriptions, completely eschewing traditional HTTP REST interfaces for client interaction.

Key Functionalities

• Seamless message relay between Teams environments and MCP endpoints (e.g., LLM pipelines, agent frameworks).
• Robust, persistent storage for all interactions, utilizing DuckDB for transaction logging.
• Sophisticated Information Retrieval (IR) backend built on PostgreSQL augmented with pgvector for complex, hybrid similarity searches (incorporating lexical ranking and vector embeddings, inspired by FlockMTL techniques).
• A dedicated Command Line Interface (CLI) for authentication workflows and direct MCP interaction testing.
• Mechanism for emitting new message events via controlled polling.
• Support for instantaneous event subscription (live streaming) for dynamic applications.
• Operationally confined to a singular, dedicated service account (bot).

System Topology

+-----------------------+      +-----------------------+      +-----------------------+
| CLI/Agentic Framework |<---->|     MCP Gateway       |<---->| Microsoft Teams Service |
| (MCP Consumer)        |      | (Python Core, FastMCP)|      | (Leveraging Graph API)  |
+-----------------------+      +-----------------------+      +-----------------------+
            |                           |                             
            |                           v                             
            |                   +-------------------+      +-----------------------+
            |                   | Message Archive DB  |      |   Retrieval Engine    |
            |                   | (DuckDB Instance)   |      | (PostgreSQL/pgvector) |
            |                   +-------------------+      +-----------------------+
                                                                    |
                                                                    v
                                                            +-----------------------+
                                                            | Vector Index Storage  |
                                                            +-----------------------+

• All communication and functionality translation occurs strictly via MCP paradigms.
• Temporal message logs reside within the local DuckDB store.
• The Retrieval Engine handles all complex semantic and keyword lookups.
• The MCP Gateway communicates with the Retrieval Engine via an internal protocol (HTTP API).

Deployment Pathways

Prerequisites

• Execution environment requires Python version 3.9 or later.
• Essential dependency management via pip.
• Container orchestration tools: Docker and Docker Compose.

Path A: On-Premise Setup

1. Repository Acquisition

git clone <repository-url>
cd mcp-teams-integration-suite

2. Dependency Resolution

pip install -r requirements.txt

3. Configuration Initialization

Duplicate the template configuration file and populate required authentication parameters for Azure Active Directory access:

cp .env.template .env
# Populate sensitive credentials within the newly created .env file

Refer to the configuration matrix below for variable definitions.

Path B: Containerized Operation (Recommended)

1. Repository Acquisition

git clone <repository-url>
cd mcp-teams-integration-suite

2. Configuration Initialization

Populate necessary credentials within .env:

cp .env.template .env
# Adjust environmental settings as needed

3. Service Orchestration

Initiate all dependent services:

docker-compose up -d

To observe operational status:

docker-compose logs -f teams_mcp  # Monitor the primary gateway process
docker-compose logs -f ir_server  # Monitor the search backend

Configuration Parameters (.env)

Variable Name	Purpose	Typical Value/Default
AZURE_CLIENT_ID	Identifier for the registered Azure AD Application (Client ID)	GUID format
AZURE_CLIENT_SECRET	Secret credential associated with the Azure AD Application	Secret string
AZURE_TENANT_ID	Directory identifier for the Azure AD tenant	GUID format
AZURE_APP_OBJECT_ID	Unique identifier for the application instance within AAD	GUID format
DUCKDB_PATH	File system location where chat persistence data is stored	db/session_log.duckdb
TOKEN_PATH	Location for caching authentication tokens securely	db/auth_cache.json
POLL_INTERVAL	Frequency (in seconds) for checking the Teams API for updates	10
DEMO_MODE	Flag to activate simulation mode (disables external API interaction)	false
OPENAI_API_KEY	Credential for embedding model services (if applicable)	sk-...
POSTGRES_USER	Database login credential for the IR component	postgres
POSTGRES_PASSWORD	Database access password	postgres
POSTGRES_DB	Name of the PostgreSQL database instance	mcp_retrieval
IR_SERVER_HOST	Network address for the Retrieval Engine service	ir_service
IR_SERVER_PORT	Network port for the Retrieval Engine's listening interface	8090

Executing the Gateway Service

Local Non-Containerized Execution

python mcp_server/main_entrypoint.py

Containerized Execution (Full Stack)

docker-compose up -d

Simulation Mode

Set DEMO_MODE to true in .env before launching services locally or via Compose.

Interacting via the Command Line Utility

Authentication Management

python cli/auth_handler.py authenticate
python cli/auth_handler.py check_status
python cli/auth_handler.py revoke_session

Rich MCP Client Operations

All subsequent CLI invocations communicate with the backend via the standard MCP input/output streams.

Retrieve Conversation Indices

python cli/mcp_client.py fetch_conversations

Fetch Transcript for a Specific Thread

python cli/mcp_client.py retrieve_transcript <thread_identifier>

Inject Message Payload

python cli/mcp_client.py transmit_message <thread_identifier> "Message content to dispatch"

Initiate New Direct Exchange

python cli/mcp_client.py establish_direct_link <recipient_identifier>

Execute Content Query (Hybrid, Lexical, or Vector)

python cli/mcp_client.py query_content "data extraction requirement" --method unified --k_results 5

Subscribe to Real-Time Event Stream

python cli/mcp_client.py listen_events

Retrieval Engine Interface Details

The Retrieval Engine exposes an HTTP interface to support the MCP Gateway's need for complex content querying, persisting index data in PostgreSQL/pgvector.

Endpoint Schemas

1. Operational Status Ping

GET http://localhost:8090/

2. Tool Discovery

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

3. Content Search Execution

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

Request Body:

{
  "query": "search term of interest",
  "search_type": "unified",
  "limit": 10
}

4. Data Indexing Operation

POST http://localhost:8090/api/discovery/index

Request Body:

{
  "payload": "Raw textual data payload",
  "context": "teams_channel",
  "context_meta": {
    "sender": "User Identity",
    "timestamp": "YYYY-MM-DDTHH:MM:SSZ"
  }
}

Comprehensive documentation for the Retrieval Engine is located at ir/API_SPEC.md.

Interaction Modalities

• Unified Retrieval: Search results are synthesized from BM25 scores and vector distances, potentially enhanced by downstream LLM evaluation.
• Event Propagation: Subscribing to the messages/incoming resource provides instantaneous event notification.

System Extensibility

• Introduce novel capabilities by defining new MCP tools/resources within mcp_server/main_entrypoint.py.
• Enhance Teams connectivity features within teams_adapter/connector.py.
• Modify the indexing and retrieval logic within the Retrieval Engine.
• Integrate analytical processes (e.g., summarization, RAG loops) utilizing DuckDB and PostgreSQL data sources.
• Utilize the CLI environment for systematic validation of all implemented MCP features.

Operational Debugging Guide

• Authentication Failure: Validate Azure credential accuracy and .env mapping.
• Data Ingestion Stalled: Confirm polling mechanism is active and the service account has requisite chat membership.
• DuckDB Integrity Issues: Verify filesystem write permissions for the configured path.
• Retrieval Service Unreachable: Examine Docker Compose service status and engine container logs.
• Testing Offline: Activate DEMO_MODE=true to simulate Teams interactions.

Related Resources

• Advanced Contextual Retrieval: Integrating LLMs with Persistent Data Stores (FlockMTL Pre-print)
• MCP Core Specification
• Microsoft Graph API Reference
• PostgreSQL Vector Indexing Extension

---

Refer to specs/system_contract.md for the full functional specification.