Ascii Art

ascii-art-mcp

[Ascii Art MCP server]

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:

npm install ascii-art-mcp

Or run directly:

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:

npm run dev

Build + production run:

npm run buildnpm 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

Output

Returns the entry's art field as plain text.

search_ascii

Searches entries by categoria, tags, or both.

Input

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

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):

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