Content
# ascii-art-mcp
**ascii-art-mcp** is a **Model Context Protocol (MCP) server** built with **Node.js and TypeScript** that exposes tools for retrieving **ASCII and Unicode art** from a local database.
The server communicates using **stdio transport**, making it compatible with MCP clients such as:
- Claude Desktop
- Cursor
- LM Studio
- Open WebUI
- Other MCP-compatible environments
https://theduodecim.github.io/ascii-art-mcp/
---
# ▶ Run this MCP
Just drop this link into any MCP-compatible AI chat:
```
https://github.com/theduodecim/ascii-art-mcp/tree/main
```
> "Run this MCP"
The AI will clone the repo, build it, and run it automatically. No setup needed on your end.
---
# 📦 Installation
The package is available on npm:
https://www.npmjs.com/package/ascii-art-mcp
Install locally:
```bash
npm install ascii-art-mcp
```
Or run directly:
```bash
npx ascii-art-mcp
```
---
# 🌐 MCP Registry
This server is also published in the official **Model Context Protocol Registry**:
https://registry.modelcontextprotocol.io/?q=ascii-art
Server name:
```
io.github.theduodecim/ascii-art
```
This allows MCP-compatible tools to **discover and install it automatically**.
---
# ⚙️ Requirements
- Node.js **20+**
- npm
---
# 🚀 Running the server manually
Development mode:
```bash
npm run dev
```
Build + production run:
```bash
npm run build
npm start
```
The server uses **stdio transport** and loads its data from:
```
db.json
```
located in the repository root.
---
# 🧰 Available MCP Tools
## get_ascii_art
Finds an art entry by exact **nombre** or by an exact value in **aliases**.
### Input
| Field | Type | Required |
|------|------|------|
| query | string | yes |
### Output
Returns the entry's **art** field as plain text.
---
## search_ascii
Searches entries by **categoria**, **tags**, or both.
### Input
| Field | Type | Required |
|------|------|------|
| categoria | string | optional |
| tag | string | optional |
At least **one filter is required**.
### Output
Returns matching entries' **art fields combined as text output**.
---
## random_ascii
Returns a random entry from the database.
### Input
| Field | Type | Required |
|------|------|------|
| tipo | ascii \| unicode | required |
### Output
Returns the selected entry's **art field as plain text**.
---
## list_categories
Lists all unique categories present in the database.
### Input
None
### Output
Category names as **newline-separated text**.
---
# 🗂 Data Model
Entries in `db.json` follow the **AsciiArtEntry TypeScript interface**:
```
src/types/asciiArt.ts
```
Each entry contains metadata such as:
- name
- category
- tags
- aliases
- art content
---
# 🧪 Testing the MCP Server
A simple integration test was used to verify MCP communication using **JSON-RPC over stdio**.
Example test script (`test.mjs`):
```javascript
import { spawn } from "child_process";
const proc = spawn("node", ["dist/server.js"], {
stdio: ["pipe", "pipe", "pipe"]
});
proc.stderr.on("data", (d) => {
console.log("LOG:", d.toString());
});
proc.stdout.on("data", (d) => {
console.log("SERVER:", d.toString());
});
function send(msg) {
const json = JSON.stringify(msg);
const payload = `Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}\r\n`;
console.log("\nSENDING:\n", json, "\n");
proc.stdin.write(payload);
}
setTimeout(() => {
send({
jsonrpc: "2.0",
id: 1,
method: "initialize",
params: {
protocolVersion: "2024-11-05",
capabilities: {},
clientInfo: {
name: "tester",
version: "1.0"
}
}
});
}, 500);
setTimeout(() => {
send({
jsonrpc: "2.0",
method: "initialized",
params: {}
});
}, 1000);
setTimeout(() => {
send({
jsonrpc: "2.0",
id: 2,
method: "tools/list"
});
}, 1500);
setTimeout(() => {
proc.kill();
console.log("TEST FINISHED");
}, 4000);
```
---
# 🧠 Architecture
```
src/
server.ts
tools/
types/
dist/
db.json
```
- TypeScript MCP server
- JSON database (`db.json`)
- Zod validation for tool inputs
- stdio transport
---
# 🎯 Purpose
This project demonstrates how to build a simple **MCP tool server** that:
- runs locally
- requires **no API keys**
- exposes structured tools
- serves static data through MCP
---
# 📜 License
MIT
