# huangwh826/halo-mcp-server architecture

> Architecture diagram of the GitHub repository huangwh826/halo-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huangwh826/halo-mcp-server
- Repository: https://github.com/huangwh826/halo-mcp-server

## Overview

##### Project type and purpose
- This is a Python-based MCP (Model Context Protocol) server for AI assistants (e.g., Claude Desktop) to manage a Halo blog system via natural-language commands. It acts as a microservice or plugin that registers “Tools” (CRUD operations) and “Prompts” (content generation workflows) to the MCP client, translates incoming requests into HTTP calls to Halo’s REST API, and returns results.

##### File structure
- Top level:
- configuration & metadata files (.env.example, pyproject.toml, setup scripts, version management, publish scripts)
- assets, examples, halo_apis_docs, tests
- src/halo_mcp_server:
- __main__.py → entrypoint when invoked via `python -m halo_mcp_server`
- server.py → MCP server initialization, tool/prompt registration, request dispatch
- config.py → reads environment variables for HALO_BASE_URL, HALO_TOKEN, logging, timeouts, feature flags
- client/halo_client.py & base.py → adapter to call Halo HTTP APIs (GET/POST/PUT/DELETE), handles authentication, retries, JSON serialization
- models/common.py → domain data models mapping Halo API schemas
- tools/*.py → implementations of 30 MCP Tools (post_tools, category_tools, tag_tools, attachment_tools) that invoke HaloClient methods
- prompts/blog_prompts.py → definitions of 10 Prompt templates for AI-driven content workflows
- utils/logger.py → centralized logging configuration
- tests/ and examples/ folders support development, not part of runtime.

##### README for additional insights
- Describes core features (CRUD tools vs AI prompts), integration steps, environment configuration, and natural-language workflows.
- Mentions layering: Tools (explicit API operations) vs Prompts (implicit content generation).
- Highlights async architecture (asyncio-based HTTP calls) and use of mcp.types to define Tool/Prompt schemas.

##### Detail and clarity
- Every runtime component that processes or routes data
- Data flow paths and dependencies explicitly

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    AICli["AI Assistant Client"]:::external

    %% Entry Point
    CLI["CLI/Launcher\n(__main__.py)"]:::protocol
    click CLI "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/__main__.py"

    %% MCP Server Core
    subgraph "MCP Server Core" 
        direction TB
        Server["Server Core\n(server.py)"]:::protocol
        click Server "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/server.py"
        Exceptions["Exceptions Module"]:::config
        click Exceptions "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/exceptions.py"
        Version["Package Metadata\n& Versioning"]:::config
        click Version "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/_version.py"
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utils"
        direction TB
        Config["Configuration Module\n(config.py)"]:::config
        click Config "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/config.py"
        Logger["Logging & Utilities\n(logger.py)"]:::config
        click Logger "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/utils/logger.py"
    end

    %% Client Wrapper
    ClientWrapper["Entry-point Helper\n(client.py)"]:::protocol
    click ClientWrapper "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/client.py"

    %% Business Logic: Prompts & Tools
    subgraph "Business Logic" 
        direction TB
        Prompts["Prompt Registry\n(blog_prompts.py)"]:::business
        click Prompts "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/prompts/blog_prompts.py"
        subgraph "Tool Registry" 
            direction TB
            PostTools["Post Tools\n(post_tools.py)"]:::business
            click PostTools "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/tools/post_tools.py"
            CategoryTools["Category Tools\n(category_tools.py)"]:::business
            click CategoryTools "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/tools/category_tools.py"
            TagTools["Tag Tools\n(tag_tools.py)"]:::business
            click TagTools "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/tools/tag_tools.py"
            AttachmentTools["Attachment Tools\n(attachment_tools.py)"]:::business
            click AttachmentTools "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/tools/attachment_tools.py"
        end
    end

    %% Adapter Layer & Models
    subgraph "Adapter & Models"
        direction TB
        BaseAdapter["Base Adapter\n(base.py)"]:::adapter
        click BaseAdapter "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/client/base.py"
        HTTPClient["HaloClient Adapter\n(halo_client.py)"]:::adapter
        click HTTPClient "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/client/halo_client.py"
        Models["Domain Models\n(common.py)"]:::adapter
        click Models "https://github.com/huangwh826/halo-mcp-server/blob/main/src/halo_mcp_server/models/common.py"
    end

    %% External Service
    HaloAPI["Halo Blog System\n(External REST API)"]:::external

    %% Connections
    AICli -->|"invoke via stdin/stdout"| CLI
    CLI -->|"start server"| Server
    Server -->|"load config"| Config
    Server -->|"setup logging"| Logger
    Server -->|"register tools/prompts"| Prompts
    Server -->|"register tools/prompts"| PostTools
    Server -->|"register tools/prompts"| CategoryTools
    Server -->|"register tools/prompts"| TagTools
    Server -->|"register tools/prompts"| AttachmentTools
    Server -->|"setup helper"| ClientWrapper

    Server -->|"on request"| Prompts
    Prompts -->|"invoke workflow"| PostTools
    Prompts -->|"invoke workflow"| CategoryTools

    Server -->|"on request"| PostTools
    Server -->|"on request"| CategoryTools
    Server -->|"on request"| TagTools
    Server -->|"on request"| AttachmentTools

    PostTools -->|"calls"| BaseAdapter
    CategoryTools -->|"calls"| BaseAdapter
    TagTools -->|"calls"| BaseAdapter
    AttachmentTools -->|"calls"| BaseAdapter

    BaseAdapter -->|"implements HTTP"| HTTPClient
    HTTPClient -->|"GET/POST/PUT/DELETE"| HaloAPI
    HTTPClient -->|"maps JSON"| Models
    HaloAPI -->|"response"| HTTPClient
    HTTPClient -->|"return data"| PostTools
    HTTPClient -->|"return data"| CategoryTools
    HTTPClient -->|"return data"| TagTools
    HTTPClient -->|"return data"| AttachmentTools

    Server -->|"respond"| AICli

    %% Styles
    classDef external fill:#ececec,stroke:#999,stroke-width:1px
    classDef protocol fill:#cce5ff,stroke:#2a83ff,stroke-width:2px
    classDef business fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef adapter fill:#fff3cd,stroke:#ffcd39,stroke-width:2px
    classDef config fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
```
