# winfunc/asterisk-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/winfunc/asterisk-mcp-server
- Repository: https://github.com/winfunc/asterisk-mcp-server

## Overview

1. **Repository purpose**
   - This is a Python package that implements an **MCP server** for security analysis.
   - Its role is not to analyze code locally, but to **broker requests from AI clients/IDEs to the external Asterisk Vulnerability Scanner API**.

2. **Top-level architecture**
   - The system has three main boundaries:
     - **MCP client side**: IDEs and AI assistants (Claude, Cursor, Cline, Windsurf, etc.)
     - **MCP server**: this repository’s runtime
     - **Asterisk API**: external HTTP/HTTPS security analysis service
   - The server sits in the middle and translates MCP tool calls into API requests and returns findings back to the caller.

3. **Core runtime package**
   - The main Python package is `asterisk_mcp_server/`.
   - `server.py` is the central orchestration layer: it likely defines the MCP server, registers the available tools, and handles request/response conversion.
   - `__init__.py` marks the package boundary for import and distribution.

4. **Entry and startup path**
   - `cli.py` is the command-line entry point.
   - It is responsible for process startup, argument parsing, and selecting runtime options such as API URL, API key, transport type, server name, port, and logging settings.
   - From the README, this is what users invoke via `pipx run asterisk-mcp-server ...`.

5. **Transport boundary**
   - The server supports two MCP transports:
     - **stdio** for editor/agent integrations that launch the process directly
     - **SSE** for networked server mode
   - This is a key architectural boundary because it separates the MCP protocol layer from how the server is exposed to clients.

6. **External service dependency**
   - The only major external runtime dependency is the **Asterisk Vulnerability Scanner API**.
   - All meaningful security analysis appears to be delegated to that service over **HTTP/HTTPS**.
   - Authentication is API-key based, so the server also acts as a credentialed proxy/broker.

7. **Functional tool surface**
   - The MCP server exposes a small tool set:
     - `scan_snippet` for individual code samples
     - `scan_codebase` for multi-file or broader context analysis
     - `verify` for checking whether changes introduce vulnerabilities
     - `settings` for opening the configuration UI
   - These tools define the primary request types and are the main diagram nodes inside the MCP server boundary.

8. **Settings/UI subsystem**
   - `asterisk_mcp_server/ui/settings.py` is a separate UI-focused subsystem.
   - The README indicates a “beautiful settings UI,” and the presence of `dearpygui` suggests this is a local desktop configuration interface rather than a web UI.
   - This UI is for managing server configuration, not for performing scans itself.

9. **Configuration model**
   - Configuration can come from **CLI arguments** or the **settings UI**.
   - The important config domains are:
     - API connection settings: URL, key, timeout
     - MCP server settings: server name, transport, port
     - Logging settings: level and console output
   - There is no sign of a database or persistent service in the tree, so configuration is likely file- or argument-driven rather than stateful.

10. **Logging and operational concerns**
    - Logging is a first-class operational concern, with configurable verbosity and optional console suppression.
    - This matters architecturally because the server is intended to run as a long-lived tool process in IDE workflows, where diagnosability is important.

11. **Packaging and release**
    - `pyproject.toml` and `uv.lock` define the package build, dependencies, and reproducible environment.
    - `scripts/publish.py` indicates a release/publishing workflow for distributing the package.
    - This repo is therefore both a runtime server and a distributable CLI package.

12. **Data flow summary**
    - A client sends an MCP request to this server.
    - The server routes the request to the relevant tool handler.
    - The handler calls the Asterisk API with the supplied code/context and API key.
    - The API returns security findings.
    - The server formats and returns those results to the client.

13. **What is not present**
    - There is no evidence of:
      - a local analysis engine
      - a database
      - background job processing
      - a web frontend
      - message queues or other infrastructure
    - That makes the architecture relatively compact: **client protocol layer + API proxy layer + optional local settings UI**.

Main entry points: [`asterisk_mcp_server/server.py`](https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/server.py) (MCP server), [`asterisk_mcp_server/cli.py`](https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/cli.py) (CLI entry), [`asterisk_mcp_server/ui/settings.py`](https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/ui/settings.py) (Settings UI), [`scripts/publish.py`](https://github.com/winfunc/asterisk-mcp-server/blob/main/scripts/publish.py) (Publish script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["MCP clients"]
  node_clients(("MCP clients<br/>consumer"))
end

subgraph group_server["MCP server"]
  node_cli["CLI entry<br/>startup<br/>[cli.py]"]
  node_server_runtime["MCP server<br/>orchestrator<br/>[server.py]"]
  node_package_init["Package init<br/>package boundary<br/>[__init__.py]"]
  node_transport(("Transport"))
  node_config{{"Config"}}
  node_logging(("Logging<br/>ops"))
  node_tool_router["Tool router<br/>tool dispatch"]
  node_scan_snippet["Snippet scan<br/>mcp tool"]
  node_scan_codebase["Codebase scan<br/>mcp tool"]
  node_verify["Verify<br/>mcp tool"]
  node_settings_tool["Settings tool<br/>mcp tool"]
  node_settings_ui["Settings UI<br/>desktop ui<br/>[settings.py]"]
end

subgraph group_api["Asterisk API"]
  node_asterisk_api[("Asterisk API<br/>external api")]
end

subgraph group_release["Packaging"]
  node_publish["Publish script<br/>release<br/>[publish.py]"]
  node_build_meta["Build config<br/>packaging<br/>[pyproject.toml]"]
end

node_clients -->|"MCP requests"| node_server_runtime
node_cli -->|"starts"| node_server_runtime
node_cli -->|"reads"| node_config
node_config -->|"applies"| node_server_runtime
node_server_runtime -->|"exposes"| node_transport
node_server_runtime -->|"dispatches"| node_tool_router
node_tool_router -->|"routes"| node_scan_snippet
node_tool_router -->|"routes"| node_scan_codebase
node_tool_router -->|"routes"| node_verify
node_tool_router -->|"routes"| node_settings_tool
node_scan_snippet -->|"calls"| node_asterisk_api
node_scan_codebase -->|"calls"| node_asterisk_api
node_verify -->|"calls"| node_asterisk_api
node_settings_tool -->|"opens"| node_settings_ui
node_settings_ui -->|"edits"| node_config
node_server_runtime -->|"emits"| node_logging
node_publish -->|"uses"| node_build_meta

click node_cli "https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/cli.py"
click node_server_runtime "https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/server.py"
click node_package_init "https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/__init__.py"
click node_settings_ui "https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/ui/settings.py"
click node_publish "https://github.com/winfunc/asterisk-mcp-server/blob/main/scripts/publish.py"
click node_build_meta "https://github.com/winfunc/asterisk-mcp-server/blob/main/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_clients toneBlue
class node_cli,node_server_runtime,node_package_init,node_transport,node_config,node_logging,node_tool_router,node_scan_snippet,node_scan_codebase,node_verify,node_settings_tool,node_settings_ui toneAmber
class node_asterisk_api toneMint
class node_publish,node_build_meta toneRose
```

## Components

### MCP clients

IDEs and AI assistants that call the server over MCP

- **MCP clients**: consumer · IDE and assistant callers such as Claude, Cursor, Cline, and Windsurf

### MCP server

This repository's runtime and tool broker

- [CLI entry](https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/cli.py): startup · Process startup and runtime option parsing · `asterisk_mcp_server/cli.py`
- [MCP server](https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/server.py): orchestrator · Central MCP server runtime and request dispatcher · `asterisk_mcp_server/server.py`
- [Package init](https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/__init__.py): package boundary · Import and distribution boundary for the Python package · `asterisk_mcp_server/__init__.py`
- **Transport**: mcp transport · stdio and SSE exposure modes for MCP clients
- **Config**: runtime config · API URL, key, timeout, server name, transport, port, and logging options
- **Logging**: ops · Operational logging and console verbosity control
- **Tool router**: tool dispatch · Registers and routes MCP tool calls
- **Snippet scan**: mcp tool · Scan a code sample or fragment
- **Codebase scan**: mcp tool · Scan multi-file or broader project context
- **Verify**: mcp tool · Check whether changes introduce vulnerabilities
- **Settings tool**: mcp tool · Opens the local configuration UI
- [Settings UI](https://github.com/winfunc/asterisk-mcp-server/blob/main/asterisk_mcp_server/ui/settings.py): desktop ui · Local Dear PyGUI configuration interface · `asterisk_mcp_server/ui/settings.py`

### Asterisk API

External vulnerability scanning service

- **Asterisk API**: external api · External HTTP/HTTPS security analysis service

### Packaging

Build and publishing surface

- [Publish script](https://github.com/winfunc/asterisk-mcp-server/blob/main/scripts/publish.py): release · Package release and publishing workflow · `scripts/publish.py`
- [Build config](https://github.com/winfunc/asterisk-mcp-server/blob/main/pyproject.toml): packaging · Dependency and build definition for the distributable package · `pyproject.toml`

## Connections

- MCP clients → MCP server: MCP requests · Clients invoke the server over MCP
- CLI entry → MCP server: starts · CLI launches and configures the server process
- CLI entry → Config: reads · Startup options populate runtime configuration
- Config → MCP server: applies · Configuration drives server behavior
- MCP server → Transport: exposes · Server runs over stdio or SSE
- MCP server → Tool router: dispatches · Incoming requests are routed to tools
- Tool router → Snippet scan: routes · Snippet analysis tool
- Tool router → Codebase scan: routes · Codebase analysis tool
- Tool router → Verify: routes · Change verification tool
- Tool router → Settings tool: routes · Configuration UI launcher
- Snippet scan → Asterisk API: calls · Tool forwards analysis request to the external API
- Codebase scan → Asterisk API: calls · Tool forwards broader scan request to the external API
- Verify → Asterisk API: calls · Tool forwards verification request to the external API
- Settings tool → Settings UI: opens · The tool opens the local settings UI
- Settings UI → Config: edits · UI changes server and API configuration
- MCP server → Logging: emits · Server uses configurable logging for diagnostics
- Publish script → Build config: uses · Publishing relies on package metadata and dependencies