# stamenov/stackexchange_mcp_python_server architecture

> Architecture diagram of the GitHub repository stamenov/stackexchange_mcp_python_server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stamenov/stackexchange_mcp_python_server
- Repository: https://github.com/stamenov/stackexchange_mcp_python_server

## Overview

##### Project type and purpose
- This repository delivers two sibling “MCP servers” (Model Context Protocol servers) that expose a Stack Overflow search-and-answer service:
- A production-ready Python implementation (mcp-stackexchage-python)
- An experimental TypeScript version (mcp-stackexchage-ts)
- Both accept a natural-language query and return the best matching question(s) plus accepted or top-voted answers via a simple stdio transport or CLI.

##### File structure
- Top-level:
– README.md – global overview
– mcp-stackexchage-python/
– mcp-stackexchage-ts/
- Python folder:
– main.py – CLI entrypoint for one-off queries
– server.py – long-running MCP server process
– pyproject.toml + uv.lock – build and dependency declarations
– .python-version, .gitignore
- TypeScript folder:
– stackoverflow-mcp.ts – single-file MCP server + CLI
– package.json – dependencies (@modelcontextprotocol/sdk, tsx, zod)

##### README for additional insights
- The Python server implements a four-pass search strategy (A–D), cross-site fallback, intelligent re-ranking, tag/date filtering, and an optional API key
- The TypeScript variant offers a pared-down flow, Zod validation, and basic similar-question lookup
- Both expose the same MCP methods (so.search_and_answers, ping)

## Diagram (Mermaid)

```mermaid
flowchart TD
    MCPClient["MCP Client"]:::client

    subgraph "Python MCP Server"
        direction TB
        CLI["main.py"]:::python
        ServerProcess["server.py"]:::python
        subgraph "Search Strategy Engine"
            direction TB
            PassA["Pass A"]:::core
            PassB["Pass B"]:::core
            PassC["Pass C"]:::core
            PassD["Pass D"]:::core
            ReRank["Re-ranking & Filters"]:::core
        end
        ConfigPy["Config Loader"]:::config
        PyProject["pyproject.toml"]:::config
        UvLock["uv.lock"]:::config
        GitIgnore[".gitignore"]:::config
        PyVersion[".python-version"]:::config
        PyReadme["README.md"]:::config

        MCPClient --> CLI
        CLI --> ServerProcess
        CLI --> PassA
        ServerProcess --> PassA
        PassA --> PassB
        PassB --> PassC
        PassC --> PassD
        PassD --> ReRank
        ReRank --> ServerProcess
        ConfigPy -->|uses| ReRank
    end

    subgraph "TypeScript MCP Server"
        direction TB
        TSEntrypoint["stackoverflow-mcp.ts"]:::ts
        SDKLayer["@modelcontextprotocol/sdk"]:::ts
        Zod["Schema Validation (Zod)"]:::ts
        ConfigTS["Config Loader"]:::config
        TSPackage["package.json"]:::config

        MCPClient --> TSEntrypoint
        TSEntrypoint --> SDKLayer
        TSEntrypoint --> Zod
        TSEntrypoint --> ConfigTS
    end

    subgraph "External Systems"
        direction TB
        StackAPI["Stack Exchange API"]:::external
        APIKey["API Key Service"]:::external
    end

    ServerProcess -->|REST calls| StackAPI
    TSEntrypoint -->|REST calls| StackAPI
    ConfigPy -.->|reads env| APIKey
    ConfigTS -.->|reads env| APIKey
    StackAPI -->|responses| ReRank
    StackAPI -->|responses| TSEntrypoint

    click CLI "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-python/main.py"
    click ServerProcess "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-python/server.py"
    click ConfigPy "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-python/server.py"
    click PyProject "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-python/pyproject.toml"
    click UvLock "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-python/uv.lock"
    click GitIgnore "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-python/.gitignore"
    click PyVersion "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-python/.python-version"
    click PyReadme "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-python/README.md"
    click TSEntrypoint "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-ts/stackoverflow-mcp.ts"
    click TSPackage "https://github.com/stamenov/stackexchange_mcp_python_server/blob/main/mcp-stackexchage-ts/package.json"

    classDef client fill:#FFD966,stroke:#333,stroke-width:1px;
    classDef python fill:#F2F2F2,stroke:#367FA9,stroke-width:2px;
    classDef ts fill:#FFF2CC,stroke:#B45F06,stroke-width:2px;
    classDef core fill:#D5E8D4,stroke:#82B366,stroke-width:2px,stroke-dasharray: 5 5;
    classDef config fill:#E1D5E7,stroke:#9673A6,stroke-width:1px;
    classDef external fill:#F8CECC,stroke:#B85450,stroke-width:1px;
```
