# ASCII Banner MCP Server
A classical [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that generates ASCII art banners from any string using [pyfiglet](https://github.com/pwaller/pyfiglet).
<a href="https://glama.ai/mcp/servers/@guilyx/ascii-banner-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@guilyx/ascii-banner-mcp/badge" />
</a>
## Features
- **`get_fonts`** — List all available pyfiglet font names (via `FigletFont.getFonts()`).
- **`generate_banner`** — Render a string as ASCII art with a chosen font (via `figlet_format(text, font=...)`).
## Requirements
- Python ≥ 3.10
- `mcp`, `pyfiglet`
## Installation
From the project root:
```bash
pip install -e .
```
For development (tests):
```bash
pip install -e ".[dev]"
```
## Usage
### Run the server (stdio)
MCP clients typically run the server as a subprocess and talk over stdio:
```bash
python -m ascii_banner_mcp.server
```
Or after install:
```bash
ascii-banner-mcp
```
### Config example
Copy and adjust one of the examples in [`config/`](config/):
- **stdio (local):** [`config/mcp-config.example.json`](config/mcp-config.example.json) — `command` + `args` for Cursor, Claude Desktop, etc.
- **streamable-http (e.g. Docker):** [`config/mcp-config-streamable-http.example.json`](config/mcp-config-streamable-http.example.json) — `url: "http://localhost:8000/mcp"` when the server runs over HTTP.
### Configure your MCP client
Add the server to your MCP client config (e.g. Cursor, Claude Desktop). Example (stdio):
```json
{
"mcpServers": {
"ascii-banner": {
"command": "python",
"args": ["-m", "ascii_banner_mcp.server"]
}
}
}
```
If you use a virtualenv, use the full path to that Python:
```json
{
"mcpServers": {
"ascii-banner": {
"command": "/path/to/venv/bin/python",
"args": ["-m", "ascii_banner_mcp.server"]
}
}
}
```
### Tools
| Tool | Description |
|------------------|-------------|
| `get_fonts` | Returns a list of available font names. Use this to discover fonts for `generate_banner`. |
| `generate_banner`| Renders `text` as ASCII art. Parameters: `text` (required), `font` (optional, default `"standard"`). Use fonts from `get_fonts()` (e.g. `"slant"`, `"block"`, `"big"`). |
Example (equivalent to your snippet):
```python
from pyfiglet import figlet_format
print(figlet_format("Hello", font="slant"))
```
Via this MCP server: call `generate_banner` with `text="Hello"` and `font="slant"`.
### MCP Inspector
Use [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) to test and debug the server.
**Option 1 — stdio (local process)**
1. Run the Inspector: `npx @modelcontextprotocol/inspector`
2. In the UI, add a server with **Stdio** transport.
3. Set **Command** to `python` (or full path to your Python/venv).
4. Set **Args** to `-m`, `ascii_banner_mcp.server`.
5. Ensure the project is installed (`pip install -e .`) or set **cwd** to the project root and use `python -m ascii_banner_mcp.server`.
**Option 2 — streamable-http (Docker or local)**
1. Start the server over HTTP:
- **Docker:** `docker compose -f .docker/docker-compose.yml up --build` (see [Docker](#docker) below).
- **Local:** `MCP_TRANSPORT=streamable-http python -m ascii_banner_mcp.server` (serves at `http://127.0.0.1:8000/mcp`).
2. Run the Inspector: `npx @modelcontextprotocol/inspector`
3. Add a server with **Streamable HTTP** (or URL) and set the URL to `http://localhost:8000/mcp`.
**Custom ports (Inspector):**
`CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector`
### Docker
Run the MCP server in a container. Use the [`.docker/`](.docker/) setup:
**stdio (default)** — client runs the container and talks via stdin/stdout:
```bash
docker build -f .docker/Dockerfile -t ascii-banner-mcp .
docker run -i --rm ascii-banner-mcp
```
**streamable-http (for Inspector or URL-based clients):**
```bash
docker compose -f .docker/docker-compose.yml up --build
```
Server is at `http://localhost:8000/mcp`. Use [`config/mcp-config-streamable-http.example.json`](config/mcp-config-streamable-http.example.json) or point MCP Inspector at that URL.
## Development
- **Tests:** `pytest`
- **Lint:** `ruff check src tests`
- **Format:** `black src tests`
- **Pre-commit:** Black, Ruff, and conventional-commit message checks (e.g. `feat:`, `fix:`). Install: `pip install -e ".[dev]"` then `pre-commit install` and `pre-commit install --hook-type commit-msg`. Run manually: `pre-commit run --all-files`.
## License
MIT
