# richard-gyiko/autogen-ext-mcp architecture

> Architecture diagram of the GitHub repository richard-gyiko/autogen-ext-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/richard-gyiko/autogen-ext-mcp
- Repository: https://github.com/richard-gyiko/autogen-ext-mcp

## Overview

##### Project type and purpose
- This is a Python library (“autogen-ext-mcp”) that integrates Microsoft AutoGen agents with external data sources/tools via the Model Context Protocol (MCP).
- It exposes a set of “tool factories” (e.g., StdioServerParams, mcp_server_tools) that spin up or connect to MCP-compliant servers and convert their schemas into AutoGen-compatible tool objects.

##### File structure
- Top‐level:
- `.github/workflows/`: CI for build & publish (GitHub Actions)
- `pyproject.toml`, `README.md`, `LICENSE`: packaging & project metadata
- `src/autogen_ext_mcp/`: core code, subdivided into `tools/` modules
- `samples/`: usage examples
- `tests/`: unit tests for adapters
- `tools/` submodules reveal the internal architecture:
- `_config.py`: parameter definitions (e.g., server params)
- `_factory.py`: creation of tool objects
- `_session.py`: session management with MCP server
- `_sse.py`: event streaming interface
- `_stdio.py`: stdio transport implementation
- `_base.py`: common abstractions for all tools

##### README for additional insights
- Purpose: wrap any MCP-compliant server into AutoGen tools
- Usage flow:
a. Instantiate `ServerParams` (e.g., StdioServerParams)
b. Call `await mcp_server_tools(server_params)`
c. Pass returned tool list into an AutoGen agent

##### Detail
- Submodule appears if it has a distinct responsibility—don’t lump `session` and `stdio` together if both are vital.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User-facing layer
    subgraph "User-Facing Layer"
        direction TB
        Agent["AutoGen Agent\n(samples/agent_chat.py)"]:::frontend
    end

    %% Core library internals
    subgraph "autogen-ext-mcp Library" 
        direction TB
        ToolsPkg["Tools Package Root"]:::internals
        click ToolsPkg "https://github.com/richard-gyiko/autogen-ext-mcp/tree/main/src/autogen_ext_mcp/tools/"

        subgraph "Config Layer"
            direction TB
            Config["_config.py\n(Config Module)"]:::internals
            click Config "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/src/autogen_ext_mcp/tools/_config.py"
        end

        subgraph "Factory Layer"
            direction TB
            Factory["_factory.py\n(Factory Module)"]:::internals
            click Factory "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/src/autogen_ext_mcp/tools/_factory.py"
        end

        subgraph "Session Layer"
            direction TB
            Session["_session.py\n(Session Module)"]:::internals
            click Session "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/src/autogen_ext_mcp/tools/_session.py"
        end

        subgraph "Transport Layer"
            direction TB
            SSE["_sse.py\n(SSE Transport)"]:::internals
            click SSE "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/src/autogen_ext_mcp/tools/_sse.py"
            STDIO["_stdio.py\n(stdio Transport)"]:::internals
            click STDIO "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/src/autogen_ext_mcp/tools/_stdio.py"
        end

        subgraph "Core Abstractions"
            direction TB
            Base["_base.py\n(Core Abstractions)"]:::internals
            click Base "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/src/autogen_ext_mcp/tools/_base.py"
        end
    end

    %% Protocol channel
    MCPChannel[("MCP Protocol Channel")]:::protocol

    %% External systems
    subgraph "External MCP Servers"
        direction TB
        ExternalServer["External MCP Server\n(e.g., filesystem, database)"]:::external
    end

    %% CI/CD and Metadata
    subgraph "Project Metadata & CI"
        direction TB
        PyProject["pyproject.toml\n(Packaging & Metadata)"]:::ci
        click PyProject "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/pyproject.toml"
        Readme["README.md\n(Project README)"]:::ci
        click Readme "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/README.md"
        BuildWorkflow["build.yaml\n(GitHub Actions CI)"]:::ci
        click BuildWorkflow "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/.github/workflows/build.yaml"
        PublishWorkflow["publish.yaml\n(GitHub Actions Publish)"]:::ci
        click PublishWorkflow "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/.github/workflows/publish.yaml"
        UnitTests["test_adapter.py\n(Unit Tests)"]:::ci
        click UnitTests "https://github.com/richard-gyiko/autogen-ext-mcp/blob/main/tests/test_adapter.py"
    end

    %% Connections
    Agent -->|"calls mcp_server_tools() "| Factory
    Factory -->|"uses parameters"| Config
    Factory -->|"creates session"| Session
    Session -->|"opens stream via"| SSE
    Session -->|"spawns process via"| STDIO
    Factory -->|"defines abstractions"| Base
    SSE -->|"communicates over"| MCPChannel
    STDIO -->|"communicates over"| MCPChannel
    MCPChannel -->|"MCP protocol"| ExternalServer

    %% Styles
    classDef frontend fill:#FFA500,stroke:#333,stroke-width:1px
    classDef internals fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px
    classDef protocol fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef ci fill:#FFE4B5,stroke:#333,stroke-width:1px
```
