jisho-mcp 1.0.0

package/README.md

@@ -0,0 +1,47 @@
+# jisho mcp
+
+The [Jisho.org](https://jisho.org) Japanese English dictionary. Words,
+readings, senses, JLPT levels. No key.
+
+## Tools
+
+- `search_words`, Japanese text, romaji, or English keywords
+- `search_by_tag`, feature searches: `#common`, `jlpt-n1`…`jlpt-n5`,
+`wanikani10`, English meanings
+
+## Run
+
+```bash
+npm install && npm run build && node dist/index.js
+```
+
+## Example
+
+> "What does 大丈夫 mean?"
+> `search_words("daijoubu")` → 大丈夫 (だいじょうぶ), safe; sound; problem free [Na adj] ⭐common, JLPT N5
+
+> "Give me common JLPT N5 words"
+> `search_by_tag("jlpt-n5")`
+
+## 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
+
+- `search_words`: Search the Jisho Japanese-English dictionary. Accepts Japanese text,
+- `search_by_tag`: Search Jisho by feature or tag:
+
+## 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 `search_words`.

package/dist/api.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Jisho.org API v1 client — Japanese-English dictionary.
+ * Docs: https://jisho.org/forum/54fefc1f6e71740b1f000000 (unofficial)
+ * Endpoints: /api/v1/search/words?keyword=... and /api/v1/search/sentences?keyword=...
+ */
+export declare class JishoError extends Error {
+}
+export interface WordResult {
+    slug: string;
+    isCommon: boolean;
+    jlpt: string[];
+    tags: string[];
+    japanese: {
+        word?: string;
+        reading?: string;
+    }[];
+    senses: {
+        englishDefinitions: string[];
+        partsOfSpeech: string[];
+        tags: string[];
+        seeAlso: string[];
+    }[];
+}
+export declare function searchWords(keyword: string, limit?: number): Promise<WordResult[]>;
+/**
+ * Tag/feature searches the words endpoint supports: "#common", "jlpt-n5",
+ * "wanikani10", English meanings, etc.
+ */
+export declare function searchByTag(keyword: string, limit?: number): Promise<WordResult[]>;
+export declare function formatWord(w: WordResult, index?: number): string;

package/dist/api.js

@@ -0,0 +1,77 @@
+/**
+ * Jisho.org API v1 client — Japanese-English dictionary.
+ * Docs: https://jisho.org/forum/54fefc1f6e71740b1f000000 (unofficial)
+ * Endpoints: /api/v1/search/words?keyword=... and /api/v1/search/sentences?keyword=...
+ */
+const BASE = "https://jisho.org/api/v1/search";
+export class JishoError extends Error {
+}
+async function search(kind, keyword) {
+    const res = await fetch(`${BASE}/${kind}?keyword=${encodeURIComponent(keyword)}`, {
+        headers: { Accept: "application/json", "User-Agent": "jisho-mcp/1.0" },
+    });
+    if (!res.ok)
+        throw new JishoError(`Jisho API error ${res.status}: ${res.statusText}`);
+    const data = (await res.json());
+    return data.data ?? [];
+}
+export async function searchWords(keyword, limit = 10) {
+    const results = await search("words", keyword);
+    return results.slice(0, limit).map((r) => ({
+        slug: r.slug,
+        isCommon: r.is_common,
+        jlpt: r.jlpt ?? [],
+        tags: r.tags ?? [],
+        japanese: r.japanese ?? [],
+        senses: (r.senses ?? []).map((s) => ({
+            englishDefinitions: s.english_definitions ?? [],
+            partsOfSpeech: s.parts_of_speech ?? [],
+            tags: s.tags ?? [],
+            seeAlso: s.see_also ?? [],
+        })),
+    }));
+}
+/**
+ * Tag/feature searches the words endpoint supports: "#common", "jlpt-n5",
+ * "wanikani10", English meanings, etc.
+ */
+export async function searchByTag(keyword, limit = 10) {
+    const results = await search("words", keyword);
+    return results.slice(0, limit).map((r) => ({
+        slug: r.slug,
+        isCommon: r.is_common,
+        jlpt: r.jlpt ?? [],
+        tags: r.tags ?? [],
+        japanese: r.japanese ?? [],
+        senses: (r.senses ?? []).map((s) => ({
+            englishDefinitions: s.english_definitions ?? [],
+            partsOfSpeech: s.parts_of_speech ?? [],
+            tags: s.tags ?? [],
+            seeAlso: s.see_also ?? [],
+        })),
+    }));
+}
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+export function formatWord(w, index = 0) {
+    const head = w.japanese
+        .map((j) => `${j.word ?? ""}${j.reading ? ` (${j.reading})` : ""}`.trim())
+        .filter(Boolean)
+        .join(" / ");
+    const lines = [`${index > 0 ? `${index}. ` : ""}${head || w.slug}`];
+    const firstSense = w.senses[0];
+    if (firstSense) {
+        const pos = firstSense.partsOfSpeech.length ? ` [${firstSense.partsOfSpeech.join(", ")}]` : "";
+        const defs = firstSense.englishDefinitions.slice(0, 4).join("; ");
+        lines.push(`   ${defs}${pos}`);
+    }
+    if (w.isCommon)
+        lines[lines.length - 1] += " ⭐common";
+    if (w.jlpt.length)
+        lines.push(`   JLPT: ${w.jlpt.join(", ")}`);
+    if (w.senses.length > 1) {
+        lines.push(`   (+${w.senses.length - 1} more senses)`);
+    }
+    return lines.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("Jisho 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,63 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { JishoError, formatWord, searchByTag, searchWords, } 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: "jisho-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("search_words", {
+        title: "Search words",
+        description: "Search the Jisho Japanese-English dictionary. Accepts Japanese text, " +
+            "romaji, or English keywords.",
+        inputSchema: z.object({
+            keyword: z.string().describe("e.g. 'daijoubu', '大丈夫', or 'friendship'"),
+            limit: z.number().int().min(1).max(15).default(10).describe("Max results"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ keyword, limit }) => {
+        try {
+            const words = await searchWords(keyword, limit);
+            if (words.length === 0)
+                return text(`No results for "${keyword}".`);
+            return text(`Jisho results for "${keyword}":\n` +
+                words.map((w, i) => formatWord(w, i + 1)).join("\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("search_by_tag", {
+        title: "Search by tag",
+        description: "Search Jisho by feature or tag: '#common' for common words, " +
+            "'jlpt-n5' through 'jlpt-n1' for JLPT levels, 'wanikani5' etc., " +
+            "or any English meaning.",
+        inputSchema: z.object({
+            keyword: z.string().describe("e.g. '#common', 'jlpt-n4', 'wanikani10', or 'friendship'"),
+            limit: z.number().int().min(1).max(15).default(10).describe("Max results"),
+        }),
+        annotations: READ_ONLY,
+    }, async ({ keyword, limit }) => {
+        try {
+            const words = await searchByTag(keyword, limit);
+            if (words.length === 0)
+                return text(`No results for "${keyword}".`);
+            return text(`Jisho results for "${keyword}":\n` +
+                words.map((w, i) => formatWord(w, i + 1)).join("\n"));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}
+function errorMessage(e) {
+    if (e instanceof JishoError)
+        return `Error: ${e.message}`;
+    if (e instanceof Error)
+        return `Error: ${e.message}`;
+    return `Error: ${String(e)}`;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "jisho-mcp",
+  "version": "1.0.0",
+  "description": "Use this MCP server to Jisho, the Japanese English dictionary. Words, kanji, readings, and example sentences",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/jisho-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrfentmen/jisho-mcp.git"
+  },
+  "bin": {
+    "jisho-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",
+    "jisho",
+    "japanese",
+    "dictionary",
+    "kanji",
+    "language",
+    "weeb"
+  ],
+  "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"
+  }
+}