winfunc/asterisk-mcp-server

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.