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:

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

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