@iflow-mcp/ykhli-mcp-vestaboard 1.0.0

package/README.md

@@ -0,0 +1,232 @@
+# Vestaboard MCP Server
+
+![64C141F8-7167-4460-AB9F-FA4E4BBDCE19](https://github.com/user-attachments/assets/b33df4ee-2c1d-4682-9741-19f73265aaf1)
+
+Give Cursor agent the ability to display messages on your Vestaboard.
+
+More examples: 
+<img width="1301" height="733" alt="Screenshot 2025-09-12 at 8 22 42 AM" src="https://github.com/user-attachments/assets/993a6153-e100-483a-95a1-1244c04ec7f9" />
+
+
+
+## Features
+
+- **Text Mode**: Send simple text messages that are automatically formatted and centered by Vestaboard
+- **Board Mode**: Full control over the 6×22 character grid with precise positioning
+- **Color Support**: Use Vestaboard's built-in color codes (Red, Orange, Yellow, Green, Blue, Violet, White, Black)
+- **Symbol Support**: Display special characters, numbers, and punctuation
+- **MCP Integration**: Works seamlessly with AI assistants that support the Model Context Protocol
+
+## Installation
+
+1. Clone this repository:
+
+```bash
+git clone <repository-url>
+cd vestaboard-mcp
+```
+
+2. Install dependencies:
+
+```bash
+npm install
+```
+
+## Getting Your Vestaboard API Key
+
+1. Visit [Vestaboard Developer Portal](https://web.vestaboard.com/)
+2. Sign in with your Vestaboard account
+3. Go to "Read/Write API" section
+4. Generate a new API key for your board
+5. Copy the key to your `.env` file
+
+## Usage
+
+### Adding to Cursor as an MCP Server
+
+1. Open Cursor Settings (Cmd/Ctrl + ,)
+2. Go to "Features" → "Model Context Protocol"
+3. Add a new MCP server by copying and pasting this JSON configuration:
+
+```json
+{
+  "mcpServers": {
+    "vestaboard": {
+      "command": "npx",
+      "args": ["-y", "tsx", "path/to/vestaboard-mcp/index.ts"],
+      "env": {
+        "VESTABOARD_API_KEY": "YOUR_API_KEY"
+      }
+    }
+}
+```
+
+**Important**:
+
+- Replace `/absolute/path/to/vestaboard-mcp` with the actual absolute path to your cloned repository
+- Replace `your_vestaboard_api_key_here` with your actual Vestaboard API key
+
+4. Save the configuration and restart Cursor
+
+### Using with Cursor
+
+Once configured, you can ask Cursor to display messages on your Vestaboard using natural language. Cursor will automatically use the `display_message` tool to send messages to your Vestaboard.
+
+Examples:
+
+- "Display 'Good Morning!' on my Vestaboard"
+- "Show a colorful welcome message on the Vestaboard"
+- "Put 'Meeting in 5 mins' on my Vestaboard in red"
+- "Draw a minimal portrait of a Pikachu on my Vestaboard"
+
+#### Text Mode (Default)
+
+```json
+{
+  "message": "Hello World!",
+  "mode": "text"
+}
+```
+
+#### Board Mode (Advanced)
+
+```json
+{
+  "mode": "board",
+  "board": [
+    [0, 0, 8, 5, 12, 12, 15, 0, 23, 15, 18, 12, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+  ]
+}
+```
+
+## Character and Color Codes
+
+### Letters
+
+- A-Z: 1-26
+
+### Numbers
+
+- 0-9: 36, 27-35
+
+### Special Characters
+
+- Blank: 0
+- !: 37
+- @: 38
+- #: 39
+- $: 40
+- (: 41
+- ): 42
+- -: 44
+- +: 46
+- &: 47
+- =: 48
+- ;: 49
+- :: 50
+- ': 52
+- ": 53
+- %: 54
+- ,: 55
+- .: 56
+- /: 59
+- ?: 60
+- °: 62
+
+### Colors
+
+- Red: 63
+- Orange: 64
+- Yellow: 65
+- Green: 66
+- Blue: 67
+- Violet: 68
+- White: 69
+- Black: 70
+- Filled: 71
+
+## Project Structure
+
+```
+vestaboard-mcp/
+├── code.ts           # Vestaboard character and color code mappings
+├── index.ts          # Main MCP server implementation
+├── sendMessage.js    # Test utility for sending messages
+├── package.json      # Node.js dependencies
+└── README.md         # This file
+```
+
+## API Reference
+
+### Tool: `display_message`
+
+Displays a message on the Vestaboard using either text mode or board mode.
+
+#### Parameters
+
+- `message` (string, optional): The text message to display (required for text mode)
+- `mode` (enum, optional): Display mode - "text" or "board" (default: "text")
+- `board` (array, optional): 6×22 array of Vestaboard codes (required for board mode)
+
+#### Response
+
+Returns a success message indicating the content was displayed on the Vestaboard.
+
+## Examples
+
+### Simple Text Message
+
+```javascript
+// When you say: "Display 'Good Morning!' on my Vestaboard"
+// Cursor sends:
+{
+  "message": "Good Morning!",
+  "mode": "text"
+}
+```
+
+### Colorful Message with Board Mode
+
+```javascript
+// When you say: "Create a colorful hello world message on my Vestaboard"
+// Cursor sends:
+{
+  "mode": "board",
+  "board": [
+    [63, 63, 8, 5, 12, 12, 15, 63, 63, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [66, 66, 23, 15, 18, 12, 4, 66, 66, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+  ]
+}
+```
+
+## Requirements
+
+- Node.js 16 or higher
+- A Vestaboard device
+- Vestaboard API key
+- Cursor IDE with MCP support
+
+## License
+
+This project is open source and available under the MIT License.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues related to:
+
+- **Vestaboard API**: Check the [Vestaboard Developer Documentation](https://docs.vestaboard.com/)
+- **MCP Protocol**: See the [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- **This Project**: Open an issue in this repository

package/code.ts

@@ -0,0 +1,72 @@
+// Vestaboard character and color codes
+// Format: <Name>: <Code> // <Notes>
+export const VESTABOARD_CODES: Record<string, number> = {
+  Blank: 0, // Black on black Vestaboard / white on white Vestaboard
+  A: 1,
+  B: 2,
+  C: 3,
+  D: 4,
+  E: 5,
+  F: 6,
+  G: 7,
+  H: 8,
+  I: 9,
+  J: 10,
+  K: 11,
+  L: 12,
+  M: 13,
+  N: 14,
+  O: 15,
+  P: 16,
+  Q: 17,
+  R: 18,
+  S: 19,
+  T: 20,
+  U: 21,
+  V: 22,
+  W: 23,
+  X: 24,
+  Y: 25,
+  Z: 26,
+  1: 27,
+  2: 28,
+  3: 29,
+  4: 30,
+  5: 31,
+  6: 32,
+  7: 33,
+  8: 34,
+  9: 35,
+  0: 36,
+  "!": 37, // Exclamation Mark
+  "@": 38, // At
+  "#": 39, // Pound
+  $: 40, // Dollar
+  "(": 41, // Left Parenthesis
+  ")": 42, // Right Parenthesis
+  "-": 44, // Hyphen
+  "+": 46, // Plus
+  "&": 47, // Ampersand
+  "=": 48, // Equal
+  ";": 49, // Semicolon
+  ":": 50, // Colon
+  "'": 52, // Single Quote
+  '"': 53, // Double Quote
+  "%": 54, // Percent
+  ",": 55, // Comma
+  ".": 56, // Period
+  "/": 59, // Slash
+  "?": 60, // Question Mark
+  "°": 62, // Degree
+  Red: 63,
+  Orange: 64,
+  Yellow: 65,
+  Green: 66,
+  Blue: 67,
+  Violet: 68,
+  White: 69, // For the local API this is black on a white Vestaboard
+  Black: 70, // For the local API this is white on a white Vestaboard
+  Filled: 71, // White on black Vestaboard / black on white Vestaboard, not available for the local API
+};
+
+export default VESTABOARD_CODES;

package/index.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import fetch from "node-fetch";
+import dotenv from "dotenv";
+import { VESTABOARD_CODES } from "./code.js";
+dotenv.config();
+
+// Create an MCP server
+const server = new McpServer({
+  name: "vestaboard-server",
+  version: "1.0.0",
+});
+
+server.registerTool(
+  "display_message",
+  {
+    title: "Display Message on Vestaboard",
+    description: `Display a message on the Vestaboard using either text mode or board mode.\n\nModes:\n1. TEXT MODE (default): Uses Vestaboard's built-in text display - simply pass a string and Vestaboard handles formatting, centering, and wrapping automatically.\n2. BOARD MODE: Provide a full 6x22 array representation for complete control over each character position.\n\nVestaboard specifications:\n- 6 rows × 22 columns\n- In board mode, use numeric codes for each position\n\nVestaboard code mapping (from code.ts):\n${JSON.stringify(
+      VESTABOARD_CODES,
+      null,
+      2
+    )}\n\nExamples:\n- Text mode: { "message": "Hello World" }\n- Board mode: { "mode": "board", "board": [[0,0,8,5,12,12,15,...], [0,0,0,0,...], ...] }
+    
+    Make the message fun and colorful, liberally use colors and symbols!
+
+    DOUBLE CHECK EVERYTHING before you send a message, make sure the message is correct according to the code mapping above!`,
+    inputSchema: {
+      message: z
+        .string()
+        .optional()
+        .describe("The text message to display (for text mode)"),
+      mode: z
+        .enum(["text", "board"])
+        .optional()
+        .describe(
+          "Display mode: 'text' for simple text display, 'board' for full array control (default: 'text')"
+        ),
+      board: z
+        .array(z.array(z.number()))
+        .optional()
+        .describe("6x22 array of Vestaboard codes (for board mode)"),
+    },
+  },
+  async ({ message, mode = "text", board }) => {
+    const apiKey = process.env.VESTABOARD_API_KEY;
+    if (!apiKey)
+      throw new Error("VESTABOARD_API_KEY is not set in environment variables");
+
+    let requestBody;
+    let displayText;
+
+    if (mode === "text") {
+      if (!message) throw new Error("Message is required for text mode");
+      requestBody = { text: message };
+      displayText = `Text "${message}" displayed on Vestaboard using built-in text formatting`;
+    } else if (mode === "board") {
+      if (!board) throw new Error("Board array is required for board mode");
+      if (board.length !== 6) throw new Error("Board must have exactly 6 rows");
+      if (!board.every((row) => row.length === 22))
+        throw new Error("Each row must have exactly 22 columns");
+      requestBody = board;
+      displayText = "Custom board layout displayed on Vestaboard";
+    } else {
+      throw new Error("Invalid mode. Must be 'text' or 'board'");
+    }
+
+    // 在测试环境下，只模拟发送请求，不实际调用API
+    if (apiKey === "test_key_for_validation") {
+      // 测试模式：模拟成功响应
+      return {
+        content: [{ type: "text", text: `[TEST MODE] ${displayText}` }],
+      };
+    }
+
+    await fetch("https://rw.vestaboard.com/", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Vestaboard-Read-Write-Key": apiKey,
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    return {
+      content: [{ type: "text", text: displayText }],
+    };
+  }
+);
+
+const transport = new StdioServerTransport();
+server.connect(transport);

package/language.json

@@ -0,0 +1 @@
+nodejs

package/package.json

@@ -0,0 +1 @@
+{"name":"@iflow-mcp/ykhli-mcp-vestaboard","version":"1.0.0","description":"MCP server for Vestaboard display integration","type":"module","bin":{"iflow-mcp_ykhli-mcp-vestaboard":"./index.ts"},"dependencies":{"@modelcontextprotocol/sdk":"^1.15.1","dotenv":"^17.2.0","node-fetch":"^3.3.2"},"devDependencies":{"@types/node":"^24.3.1","@types/node-fetch":"^2.6.13","tsx":"^4.21.0","typescript":"^5.9.3"}}

package/package_name

@@ -0,0 +1 @@
+@iflow-mcp/ykhli-mcp-vestaboard

package/push_info.json

@@ -0,0 +1,5 @@
+{
+  "push_platform": "github",
+  "fork_url": "https://github.com/iflow-mcp/ykhli-mcp-vestaboard",
+  "fork_branch": "iflow"
+}

package/run.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+cd /app/auto-mcp-upload/data/13696
+VESTABOARD_API_KEY=test_key_for_validation npx tsx index.ts

package/run.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('./index.js');