@mrfentmen/datamuse-mcp 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# Datamuse
+
+Use this MCP server to wordplay. Rhymes, related words, spell checks, and word suggestions for any phrase.
+
+## Quick start
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+The server uses stdio, so it can be connected to Claude Desktop, Cursor, VS Code, MCP Inspector, or another compatible MCP client.
+
+## Tools at a glance
+
+- `rhymes_with`: Find words that rhyme with a word.
+- `means_like`: Find words and phrases with a similar meaning, with definitions.
+- `related_to`: Find words commonly associated with a topic.
+- `spell_check`: Check a word
+- `word_suggestions`: Suggest words starting with a prefix.
+
+## Limits and privacy
+
+This project is intentionally narrow. It should be treated as a practical helper, not a complete certification or security audit. Check the implementation and the returned data before using it with sensitive material. No credentials are required unless the project explicitly says otherwise.
+
+## Try it
+
+After building, connect the server through your MCP client. The repository root also contains `smoke-test.mjs` for projects covered by the shared harness. A typical tool call starts with `rhymes_with`.

package/dist/api.d.ts

@@ -0,0 +1,16 @@
+export declare class DatamuseError extends Error {
+}
+export interface WordHit {
+    word: string;
+    score?: number;
+    numSyllables?: number;
+    defs?: string[];
+    tags?: string[];
+}
+export declare function rhymesWith(word: string, limit?: number): Promise<WordHit[]>;
+export declare function meansLike(word: string, limit?: number): Promise<WordHit[]>;
+export declare function relatedTo(word: string, limit?: number): Promise<WordHit[]>;
+export declare function spellCheck(word: string): Promise<WordHit[]>;
+export declare function suggest(prefix: string, limit?: number): Promise<WordHit[]>;
+export declare function formatHits(hits: WordHit[]): string;
+export declare function formatWithDefs(hits: WordHit[]): string;

package/dist/api.js

@@ -0,0 +1,48 @@
+/**
+ * Datamuse client. A word engine that knows how words sound and relate.
+ * Keyless, no signup. Great for rhymes, thesaurus lookups, and spelling.
+ */
+const BASE = "https://api.datamuse.com";
+export class DatamuseError extends Error {
+}
+async function words(params) {
+    const qs = new URLSearchParams(params).toString();
+    const res = await fetch(`${BASE}/words?${qs}`, { signal: AbortSignal.timeout(15000) });
+    if (!res.ok)
+        throw new DatamuseError(`Datamuse error ${res.status}`);
+    return (await res.json());
+}
+export function rhymesWith(word, limit = 10) {
+    return words({ rel_rhy: word, max: String(limit) });
+}
+export function meansLike(word, limit = 10) {
+    return words({ ml: word, max: String(limit) });
+}
+export function relatedTo(word, limit = 10) {
+    return words({ rel_trg: word, max: String(limit) });
+}
+export async function spellCheck(word) {
+    return words({ sp: word, max: "5" });
+}
+export async function suggest(prefix, limit = 10) {
+    const qs = new URLSearchParams({ s: prefix, max: String(limit) }).toString();
+    const res = await fetch(`${BASE}/sug?${qs}`, { signal: AbortSignal.timeout(15000) });
+    if (!res.ok)
+        throw new DatamuseError(`Datamuse error ${res.status}`);
+    return (await res.json());
+}
+export function formatHits(hits) {
+    return hits
+        .map((h, i) => `${i + 1}. ${h.word}${h.numSyllables != null ? ` (${h.numSyllables} syllables)` : ""}${h.score != null ? `, score ${h.score}` : ""}`)
+        .join("\n");
+}
+export function formatWithDefs(hits) {
+    return hits
+        .map((h, i) => {
+        const lines = [`${i + 1}. ${h.word}`];
+        for (const d of h.defs ?? [])
+            lines.push(`   ${d}`);
+        return lines.join("\n");
+    })
+        .join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,92 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { DatamuseError, formatHits, formatWithDefs, meansLike, relatedTo, rhymesWith, spellCheck, suggest, } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "datamuse-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("rhymes_with", {
+        title: "Rhymes with",
+        description: "Find words that rhyme with a word.",
+        inputSchema: z.object({ word: z.string().describe("The word to rhyme"), limit: z.number().int().min(1).max(50).default(10) }),
+        annotations: READ_ONLY,
+    }, async ({ word, limit }) => {
+        try {
+            const hits = await rhymesWith(word, limit);
+            return text(hits.length ? `Words that rhyme with "${word}":\n${formatHits(hits)}` : `No rhymes for "${word}".`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("means_like", {
+        title: "Means like",
+        description: "Find words and phrases with a similar meaning, with definitions.",
+        inputSchema: z.object({ word: z.string().describe("The meaning to match, e.g. 'retro gaming'"), limit: z.number().int().min(1).max(50).default(10) }),
+        annotations: READ_ONLY,
+    }, async ({ word, limit }) => {
+        try {
+            const hits = await meansLike(word, limit);
+            return text(hits.length ? `Words meaning like "${word}":\n${formatWithDefs(hits)}` : `Nothing meaning like "${word}".`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("related_to", {
+        title: "Related to",
+        description: "Find words commonly associated with a topic.",
+        inputSchema: z.object({ word: z.string().describe("The topic, e.g. 'cave'"), limit: z.number().int().min(1).max(50).default(10) }),
+        annotations: READ_ONLY,
+    }, async ({ word, limit }) => {
+        try {
+            const hits = await relatedTo(word, limit);
+            return text(hits.length ? `Words related to "${word}":\n${formatHits(hits)}` : `Nothing related to "${word}".`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("spell_check", {
+        title: "Spell check",
+        description: "Check a word's spelling and get corrections.",
+        inputSchema: z.object({ word: z.string().describe("The word to check") }),
+        annotations: READ_ONLY,
+    }, async ({ word }) => {
+        try {
+            const hits = await spellCheck(word);
+            const correct = hits.some((h) => h.word.toLowerCase() === word.toLowerCase());
+            const body = hits.length ? `Closest matches:\n${formatHits(hits)}` : "No close matches.";
+            return text(correct ? `"${word}" looks correctly spelled. ${body}` : `"${word}" may be misspelled. ${body}`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("word_suggestions", {
+        title: "Word suggestions",
+        description: "Suggest words starting with a prefix.",
+        inputSchema: z.object({ prefix: z.string().describe("Word start, e.g. 'comp'"), limit: z.number().int().min(1).max(50).default(10) }),
+        annotations: READ_ONLY,
+    }, async ({ prefix, limit }) => {
+        try {
+            const hits = await suggest(prefix, limit);
+            return text(hits.length ? `Words starting with "${prefix}":\n${formatHits(hits)}` : `Nothing starts with "${prefix}".`);
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof DatamuseError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mrfentmen/datamuse-mcp",
+  "version": "1.0.0",
+  "description": "Use this MCP server to wordplay. Rhymes, related words, spell checks, and word suggestions for any phrase",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/datamuse-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/datamuse-mcp.git"
+  },
+  "bin": {
+    "datamuse-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "rm -rf dist && tsc -p tsconfig.json && node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "datamuse",
+    "api"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}