intelligent-automation-orchestrator

Intelligent Automation Orchestrator (MCP Server)

This repository hosts a sophisticated, Python-driven Model Context Protocol (MCP) service layer, architected using FastAPI for asynchronous performance and Pydantic for strict data validation. Its primary function is to expose a standardized interface, adhering strictly to the MCP specification, that allows generative AI entities (LLMs) to invoke a diverse array of operational tools.

Key operational domains covered include deep integration with Microsoft 365 ecosystems, direct interaction with Azure infrastructure components, processing of various document formats (PDF, DOCX, images via OCR), and sophisticated data analytics capabilities. The system is built for extensibility and enterprise-grade monitoring.

Core Capabilities

• Protocol Adherence: Full compliance with the Model Context Protocol (MCP) specification for dependable machine-to-machine communication.
• Unified Tool Gateway: Provides a singular API point for AI systems to access specialized functions.
• Enterprise Toolset:
  • Microsoft Productivity Suite: Full command set for Outlook, SharePoint, Teams integration via Microsoft Graph.
  • Cloud Resource Management: Utilities for interacting with Azure subscriptions and resource groups.
  • Content Handling: Tools for systematic text extraction from complex file types and optical character recognition (OCR).
  • Orchestration Layer: Built-in mechanisms for chaining multiple tool executions into complex, coherent operational sequences.
• Observability: Implements structured, detailed logging mechanisms utilizing Rich console output and persistent JSON log files. Includes real-time performance metrics capture.
• Configuration Flexibility: Configuration is managed through a hierarchical system favoring config.json augmented by environment variables for secrets management.
• Developer Utilities: A built-in Command Line Interface (CLI) simplifies server deployment, configuration auditing, tool discovery, and unit testing of specific functionalities.
• Asynchronous Design: Leverages asyncio and FastAPI to ensure low-latency request handling under heavy load.
• LLM Interoperability: Designed to interface effectively with models such as Anthropic Claude for advanced reasoning tasks.

🚀 Deployment and Initialization

Prerequisites

• Python environment (version 3.9 or newer).
• Package management via Pip.
• Required cloud credentials (Azure/M365 access tokens/secrets).

Setup Procedure

1. Source Code Retrieval: bash git clone cd intelligent-automation-orchestrator

2. Environment Isolation: Establish a dedicated virtual environment (highly recommended). bash python -m venv .venv source .venv/bin/activate # Use appropriate activation script for your OS

3. Dependency Installation: Install the necessary Python libraries. bash pip install . # For development/testing environment setup: # pip install -r requirements-dev.txt

4. Credential Configuration:

   • Duplicate the template file config.json.example into config.json.
   • Populate config.json with infrastructural details (e.g., M365 tenant identifiers, Azure subscription IDs).
   • For sensitive material (API keys, client secrets), utilize the .env.example template to create a .env file in the root directory. Environment variables specified in .env supersede corresponding entries in config.json.

Operating the Service

The orchestration server can be initiated via several methods:

1. Direct Execution: bash python server.py --config config.json --port 8000

2. CLI Invocation: bash python -m src.cli server --port 8000

Upon successful launch, the service status endpoint is typically available at http://localhost:8000, and the critical MCP service manifest resides at http://localhost:8000/mcp.json.

⚙️ MCP Interaction Model

The server exposes its toolkit catalog via the standard MCP manifest endpoint. LLM clients invoke capabilities by sending POST requests to the designated tool route, structured as /tool/{tool_identifier}.

Invocation Example (Conceptual Tool Call: Scheduling Appointment):

{ "contextId": "session-xyz-789", "invocationId": "call-456", "toolName": "M365_Calendar_Create_Event", "arguments": { "subject": "Quarterly Review Prep", "start_time": "2025-07-01T14:00:00", "attendees": ["manager@corp.com", "analyst@corp.com"] } }

Result Payload Example (Conceptual Success):

{ "contextId": "session-xyz-789", "invocationId": "call-456", "toolName": "M365_Calendar_Create_Event", "isError": false, "content": [ { "type": "application/json", "content": { "status": "Created", "event_id": "evt_987654" } } ] }

🛠️ Toolkit Catalog Summary

The system aggregates numerous specialized execution units, discoverable via python -m src.cli list-tools.

• Productivity Suite Integration: Handles email dispatch (M365_Email_Send), calendar manipulation, and SharePoint file discovery.
• Cloud Administration: Tools like Azure_VM_List and resource group enumeration.
• Document Processing: Logic for rendering text content from binary inputs (Document_Extract_Text_PDF, Document_OCR_Image).
• Generative Capabilities: Direct access to external LLMs via the Claude_Generate_Text wrapper.
• Operational Flow Control: Units designed for sequencing and conditional execution of other tools.

⌨️ Command Line Utilities (src/cli.py)

The integrated CLI streamlines operational tasks:

• Server Control: python -m src.cli server [OPTIONS]
• Catalog Listing: python -m src.cli list-tools
• Tool Validation: python -m src.cli test-tool <TOOL_NAME> '{"param1": "value"}' - Allows pre-execution testing of a specific function with provided JSON arguments.
• Configuration Auditing: python -m src.cli validate-config and python -m src.cli show-config.

🧑‍💻 Extensibility and Development Guide

To introduce novel functionality:

1. Implementation: Develop the required asynchronous function within a dedicated module under src/tools/. Ensure proper Pydantic or type hinting for input schema definition.
2. Decoration: Apply the @tool(...) decorator to define the tool's MCP metadata (name, description, parameter schema). The system supports automated schema inference from type hints.
3. Registration: Ensure the new module is imported within src/tools/__init__.py so that the registration routine automatically adds the function to the central ToolRegistry instance upon server startup.

Standardized Error Management: Developers are encouraged to wrap tool logic with the @with_error_handling("Tool_Identifier") decorator to guarantee exceptions are translated into compliant MCP error payloads rather than raw HTTP errors.

📜 Licensing and Attribution

Distributed under the permissive MIT License (see LICENSE file). Gratitude is extended to the creators of FastAPI, Pydantic, Structlog, Rich, and the platform providers (Microsoft, Anthropic) whose technologies underpin this orchestration layer.

🔮 Roadmap

Future iterations plan to incorporate advanced features such as runtime tool registration, granular access control policies for tool invocation, and the development of a dedicated administrative dashboard for monitoring and debugging active workflows.