Teams Communication Fabric via MCP

This repository details a pure Model Context Protocol (MCP) intermediary service designed to synchronize Microsoft Teams interactions with any MCP-compliant consuming entity (e.g., advanced autonomous agents, LLM orchestration layers, or a specialized terminal interface). All operational facets are channeled exclusively through MCP constructs (tools, resource bindings, and streamed events), ensuring zero reliance on conventional RESTful service exposure.

Core Capabilities

Native integration of Teams chat streams into the MCP ecosystem.
High-performance Information Retrieval (IR) backend leveraging a PostgreSQL instance.
Durable ledger of conversational artifacts stored within an embedded DuckDB instance.
Advanced querying combining lexical matching (BM25) with vector similarity, inspired by FlockMTL architectures.
Provision of a dedicated Command Line Interface (CLI) for credential management and direct interaction testing against the rich MCP client layer.
Event publication mechanism based on periodic state polling to notify subscribers of new transmissions.
Support for bidirectional, low-latency data flow, enabling live feedback loops for AI systems and interactive CLI use.
Operation is anchored to a service identity (single bot account).

Operational Blueprint

+-----------------------+      +-------------------------+      +-----------------------+
|   Agent/CLI MCP Client| <===>| Core MCP Broker (Python)| <===>| Microsoft Teams System |
| (Rich Terminal Proxy) |      | (FastMCP Implementation)|      | (Graph Services)      |
+-----------------------+      +-------------------------+      +-----------------------+
           |                            |                          
           |                            v                          
           |                    +-------------------+      +-------------------+
           |                    | Local Data Vault  |      | Search Engine (IR)| 
           |                    |     (DuckDB)      |      | (PostgreSQL/Vector)| 
           |                    +-------------------+      +-------------------+
                                                             |                   
                                                             v                   
                                                    +---------------------+ 
                                                    | Vector Store Index  | 
                                                    | (pgvector)          | 
                                                    +---------------------+

All data ingress/egress, query execution, and state manipulation occur strictly via MCP semantics.
Conversational history persistence is handled by the embedded DuckDB module.
The dedicated IR subsystem leverages PostgreSQL coupled with the pgvector extension for enhanced semantic search.
The IR subsystem communicates with the main MCP Broker via a proprietary HTTP interface.

Deployment Procedures

Prerequisites

Mandate Python version 3.9 or newer.
[pip] package manager availability.
Operational Docker and Docker Compose environments (recommended for orchestration).

Method A: Direct Local Setup

1. Source Code Acquisition

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

2. Dependency Resolution

pip install -r requirements.txt

3. Credential Initialization

Replicate the configuration template and populate required Azure identity parameters:

cp .env.template .env
# Edit .env file with requisite Azure AD and service parameters

Refer to the environment variable table below for configuration details.

Method B: Containerized Deployment (Preferred)

1. Obtain Repository

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

2. Configure Runtime Parameters

Populate the secrets file:

cp .env.template .env
# Securely edit .env contents

3. Orchestration Execution

docker-compose up -d

To monitor service health:

docker-compose logs -f teams_mcp  # View broker service output
docker-compose logs -f ir_server  # View search service output

Operational Settings (.env Map)

Parameter	Rationale / Function	Default / Example
AZURE_CLIENT_ID	Identifier for the registered Azure AD application	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
AZURE_CLIENT_SECRET	Secret credential for application authentication	`your-secret`
AZURE_TENANT_ID	Directory identifier for the Azure subscription	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
AZURE_APP_OBJECT_ID	Unique identifier for the registered application entity	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
DUCKDB_PATH	File system location for persistent message log storage	`db/teams_mcp.duckdb`
TOKEN_PATH	Path where authentication tokens are securely cached	`db/token_cache.json`
POLL_INTERVAL	Frequency (in seconds) for checking Teams for new items	`10`
DEMO_MODE	Flag to switch to simulated API interaction	`false`
OPENAI_API_KEY	Key for accessing embedding generation services	`sk-...`
POSTGRES_USER	Database credential for IR service access	`postgres`
POSTGRES_PASSWORD	Database password for IR service access	`postgres`
POSTGRES_DB	Target database name on the PostgreSQL instance	`mcp_ir`
IR_SERVER_HOST	Network address of the running Search Engine service	`ir_server`
IR_SERVER_PORT	Network port utilized by the Search Engine service	`8090`

Service Execution

Local Runtime (No Orchestration)

python mcp_server/server.py

Containerized Stack Startup

docker-compose up -d

Debug Logging

Access diagnostic output via:

docker-compose logs -f teams_mcp
docker-compose logs -f ir_server

Simulation Mode

Set DEMO_MODE=true in the environment file to bypass live Teams integration.

Agent Interface (CLI)

1. Authentication Workflow

python cli/login.py login    # Establish session
python cli/login.py status   # Display current session state
python cli/login.py logout   # Terminate session

2. Rich Agent Interaction (MCP StdIO Protocol)

Retrieve list of active conversations

python cli/mcp_client.py list_chats

Fetch message history for a specific thread

python cli/mcp_client.py get_messages <thread_identifier>

Transmit a new artifact to a thread

python cli/mcp_client.py send_message <thread_identifier> "Direct message content here!"

Initiate a novel one-to-one exchange

python cli/mcp_client.py create_chat <recipient_email_or_id>

Execute semantic or keyword content lookup

python cli/mcp_client.py search_messages "critical system report" --mode hybrid --top_k 5

python cli/mcp_client.py stream

Search Engine Subsystem (IR)

The IR component manages complex content indexing and retrieval using PostgreSQL/pgvector, exposing its functionality via a lightweight HTTP API consumed by the MCP broker.

Exposed HTTP Endpoints

1. System Status Probe

GET http://localhost:8090/

2. Tool Manifest Retrieval

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

3. Content Search Operation

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

Payload:

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

4. Data Ingestion for Indexing

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

Payload:

{
  "content": "The data payload to encode.",
  "source_type": "teams",
  "metadata": {
    "author": "Agent Name",
    "created": "2025-04-01T12:00:00Z"
  }
}

Detailed IR documentation is located at [ir/README.md].

Data Flow & Advanced Techniques

Inquiry Mode: Utilizes fusion of BM25 ranking and vector similarity, optionally incorporating LLM reranking for result refinement.
Event Flow: Real-time data reception is managed by subscribing to the messages/incoming MCP event channel.

Modification and Expansion

Introduce new MCP methods/actions within mcp_server/server.py.
Adjust Teams API interaction logic in teams/graph.py.
Refine vectorization and indexing strategies within the IR service.
Integrate new analytical processing or RAG components utilizing DuckDB/PostgreSQL outputs and LLM services.
The CLI client serves as the primary functional verification harness for all implemented MCP protocols.

Debugging Diagnostics

Auth Failure: Verify Azure AD credentials housed in .env.
Data Lag: Confirm polling service activity and bot membership in target Teams.
DB Corruption: Inspect file system permissions for the DuckDB storage path.
IR Unreachable: Check Docker Compose status and logs for the search container.
Testing Isolation: Activate DEMO_MODE=true to simulate interactions.

Referenced Specifications

[FlockMTL Paper]: Insights on deep integration of LLMs and RAG within database contexts (https://arxiv.org/html/2504.01157v1)
[MCP Specification]: Governing protocol documentation (https://modelcontextprotocol.io)
[Microsoft Graph]: Official API reference documentation (https://learn.microsoft.com/en-us/graph/overview)
[pgvector]: PostgreSQL extension for similarity search (https://github.com/pgvector/pgvector)

Comprehensive product specifications are detailed in [specs/app-spec.md].

BUSINESS MANAGEMENT SYSTEMS: These systems encompass the suite of computational tools, operational methodologies, and control mechanisms utilized by organizational entities to maintain agility against market fluctuations, secure competitive advantage, and enhance overall operational efficacy. These tools span functional domains such as strategic charting, workflow governance, historical record-keeping, personnel administration, and executive forecasting.

== Conceptual Framework == Management tooling can be categorized by operational focus: methods for data ingestion/verification, mechanisms for process refinement, platforms for data aggregation and insight generation. The current technology landscape demands a highly strategic selection process for these applications, often leading to superior outcomes when the tool is molded to the enterprise requirements, rather than forcing the enterprise to conform to inflexible software constraints. A major driver in this evolution is the continuous pressure to decrease expenditure while maximizing revenue, deeply understanding client needs, and delivering solutions precisely as specified.

== Benchmarked Adoption (2013 Survey Insights) == Data from a Bain & Company survey indicated the global adoption trends for core management disciplines, which include:

Strategic Planning
Client Relationship Management (CRM)
Organizational Feedback Mechanisms
Comparative Performance Analysis (Benchmarking)
Performance Measurement Frameworks (e.g., Balanced Scorecard)
Identification of Core Competencies
Operational Restructuring (Outsourcing)
Organizational Transition Programs
Logistics and Procurement Oversight (SCM)
Defining Corporate Vision and Mandate
Client Population Segmentation
Total Quality Initiatives (TQM)

mcp-teams-comm-fabric

Author

imoon

Quick Info

Actions

Tags