yahoo-furigana-mcp 1.0.0

package/README.md

@@ -0,0 +1,152 @@
+# Yahoo! ふりがな API MCP サーバ
+
+Yahoo! JAPAN テキスト解析の[ふりがなAPI（V2）](https://developer.yahoo.co.jp/webapi/jlp/furigana/v2/furigana.html)を利用したMCPサーバです。
+
+日本語テキストにふりがな（ひらがな読み）やローマ字を付けることができます。
+
+## 必要な環境
+
+- Node.js 18以上
+- Yahoo! JAPAN デベロッパーネットワークの Client ID（アプリケーションID）
+  - [Yahoo! ID連携 v2 アプリケーションの登録](https://developer.yahoo.co.jp/yconnect/v2/registration.html)から取得できます
+
+## セットアップ
+
+### 1. 依存関係のインストール
+
+```bash
+npm install
+```
+
+### 2. ビルド
+
+```bash
+npm run build
+```
+
+## Claude Desktop での設定
+
+### 方法1: npx経由で実行（推奨）
+
+ローカルにリポジトリを配置せず、npm経由で実行する方法です。
+
+`claude_desktop_config.json` に以下を追加してください：
+
+```json
+{
+  "mcpServers": {
+    "yahoo-furigana": {
+      "command": "npx",
+      "args": ["-y", "yahoo-furigana-mcp"],
+      "env": {
+        "YAHOO_CLIENT_ID": "あなたのClient ID"
+      }
+    }
+  }
+}
+```
+
+### 方法2: ローカルから実行
+
+リポジトリをクローンして実行する方法です。
+
+`claude_desktop_config.json` に以下を追加してください：
+
+```json
+{
+  "mcpServers": {
+    "yahoo-furigana": {
+      "command": "node",
+      "args": ["/path/to/yahoo-furigana-mcp/dist/index.js"],
+      "env": {
+        "YAHOO_CLIENT_ID": "あなたのClient ID"
+      }
+    }
+  }
+}
+```
+
+`/path/to/yahoo-furigana-mcp` は実際のパスに置き換えてください。
+
+## 提供するツール
+
+### gen_furigana
+
+日本語テキストにふりがなを付けます。
+
+#### パラメータ
+
+| 名前 | 型 | 必須 | 説明 |
+|------|-----|------|------|
+| `text` | string | ○ | ふりがなを付けたい日本語テキスト |
+| `grade` | number | - | 学年指定（1-8）。指定した学年までに習う漢字にはふりがなを付けません |
+| `output_format` | string | - | 出力形式（デフォルト: `bracket`） |
+
+#### output_format の値
+
+| 値 | 説明 | 出力例 |
+|----|------|--------|
+| `bracket` | 括弧形式（デフォルト） | `漢字（かんじ）` |
+| `ruby` | HTMLルビ形式 | `<ruby>漢字<rt>かんじ</rt></ruby>` |
+| `roman` | ローマ字付き詳細形式 | `漢字: かんじ (kanji)` |
+
+#### grade の値
+
+| 値 | 対象 |
+|----|------|
+| 1 | 小学1年生までに習う漢字 |
+| 2 | 小学2年生までに習う漢字 |
+| 3 | 小学3年生までに習う漢字 |
+| 4 | 小学4年生までに習う漢字 |
+| 5 | 小学5年生までに習う漢字 |
+| 6 | 小学6年生までに習う漢字 |
+| 7 | 中学生までに習う漢字 |
+| 8 | それ以上 |
+
+#### 使用例
+
+**bracket形式（デフォルト）:**
+
+```
+入力: "漢字の読み方を教えてください"
+出力: "漢字（かんじ）の読（よ）み方（かた）を教（おし）えてください"
+```
+
+**ruby形式:**
+
+```
+入力: "漢字の読み方"
+出力: "<ruby>漢字<rt>かんじ</rt></ruby>の<ruby>読<rt>よ</rt></ruby>み<ruby>方<rt>かた</rt></ruby>"
+```
+
+## 特徴
+
+- **自動チャンク分割**: 4KBを超える長いテキストも自動的に分割して処理します。文の区切り（。！？など）で分割するため、自然な結果が得られます。
+
+## npm公開（開発者向け）
+
+このパッケージをnpmに公開する手順：
+
+```bash
+# ビルド
+npm run build
+
+# パッケージの内容を確認
+npm pack --dry-run
+
+# npmにログイン（初回のみ）
+npm login
+
+# 公開
+npm publish
+```
+
+公開後、ユーザーは `npx yahoo-furigana-mcp` でローカルにリポジトリを配置せずに利用できます。
+
+## 制限事項
+
+- Yahoo! JAPAN APIの利用規約に従ってください
+
+## ライセンス
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// Client ID from environment variable
+const CLIENT_ID = process.env.YAHOO_CLIENT_ID;
+if (!CLIENT_ID) {
+    console.error("Error: YAHOO_CLIENT_ID environment variable is required");
+    process.exit(1);
+}
+const API_ENDPOINT = "https://jlp.yahooapis.jp/FuriganaService/V2/furigana";
+// Maximum text size per request (in bytes) - leaving room for JSON overhead
+const MAX_CHUNK_SIZE = 3000;
+// Function to call Yahoo Furigana API
+async function getFurigana(text, grade) {
+    const requestBody = {
+        id: "1",
+        jsonrpc: "2.0",
+        method: "jlp.furiganaservice.furigana",
+        params: {
+            q: text,
+        },
+    };
+    if (grade !== undefined && grade >= 1 && grade <= 8) {
+        requestBody.params.grade = grade;
+    }
+    const response = await fetch(API_ENDPOINT, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "User-Agent": `Yahoo AppID: ${CLIENT_ID}`,
+        },
+        body: JSON.stringify(requestBody),
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP error: ${response.status} ${response.statusText}`);
+    }
+    return (await response.json());
+}
+// Split text into chunks at sentence boundaries
+function splitTextIntoChunks(text) {
+    const encoder = new TextEncoder();
+    const textBytes = encoder.encode(text);
+    // If text fits in one chunk, return as is
+    if (textBytes.length <= MAX_CHUNK_SIZE) {
+        return [text];
+    }
+    const chunks = [];
+    // Split by sentence-ending punctuation (Japanese and English)
+    const sentences = text.split(/(?<=[。．！？\n])/);
+    let currentChunk = "";
+    for (const sentence of sentences) {
+        const testChunk = currentChunk + sentence;
+        const testBytes = encoder.encode(testChunk);
+        if (testBytes.length > MAX_CHUNK_SIZE) {
+            if (currentChunk) {
+                chunks.push(currentChunk);
+                currentChunk = sentence;
+            }
+            else {
+                // Single sentence is too long, split by characters
+                let remaining = sentence;
+                while (remaining) {
+                    let end = remaining.length;
+                    while (encoder.encode(remaining.slice(0, end)).length > MAX_CHUNK_SIZE && end > 1) {
+                        end = Math.floor(end / 2);
+                    }
+                    // Try to find a better break point
+                    while (end < remaining.length && encoder.encode(remaining.slice(0, end + 1)).length <= MAX_CHUNK_SIZE) {
+                        end++;
+                    }
+                    chunks.push(remaining.slice(0, end));
+                    remaining = remaining.slice(end);
+                }
+            }
+        }
+        else {
+            currentChunk = testChunk;
+        }
+    }
+    if (currentChunk) {
+        chunks.push(currentChunk);
+    }
+    return chunks;
+}
+// Process text with chunking support
+async function processTextWithChunking(text, grade, format) {
+    const chunks = splitTextIntoChunks(text);
+    if (chunks.length === 1) {
+        // Single chunk, process normally
+        const response = await getFurigana(text, grade);
+        if (response.error) {
+            throw new Error(`APIエラー: ${response.error.message} (code: ${response.error.code})`);
+        }
+        if (!response.result) {
+            throw new Error("結果が取得できませんでした");
+        }
+        return formatResult(response.result, format);
+    }
+    // Multiple chunks, process each and combine
+    const results = [];
+    for (let i = 0; i < chunks.length; i++) {
+        const response = await getFurigana(chunks[i], grade);
+        if (response.error) {
+            throw new Error(`APIエラー (チャンク ${i + 1}/${chunks.length}): ${response.error.message}`);
+        }
+        if (!response.result) {
+            throw new Error(`結果が取得できませんでした (チャンク ${i + 1}/${chunks.length})`);
+        }
+        results.push(formatResult(response.result, format));
+    }
+    // For roman format, join with newlines; for others, join directly
+    return format === "roman" ? results.join("\n") : results.join("");
+}
+// Format with bracket notation: 漢字（かんじ）
+function formatBracket(result) {
+    const parts = [];
+    for (const word of result.word) {
+        if (word.furigana && word.surface !== word.furigana) {
+            parts.push(`${word.surface}（${word.furigana}）`);
+        }
+        else if (word.subword) {
+            const subParts = word.subword
+                .map((sw) => {
+                if (sw.furigana && sw.surface !== sw.furigana) {
+                    return `${sw.surface}（${sw.furigana}）`;
+                }
+                return sw.surface;
+            })
+                .join("");
+            parts.push(subParts);
+        }
+        else {
+            parts.push(word.surface);
+        }
+    }
+    return parts.join("");
+}
+// Format with HTML ruby tags: <ruby>漢字<rt>かんじ</rt></ruby>
+function formatRuby(result) {
+    const parts = [];
+    for (const word of result.word) {
+        if (word.furigana && word.surface !== word.furigana) {
+            parts.push(`<ruby>${word.surface}<rt>${word.furigana}</rt></ruby>`);
+        }
+        else if (word.subword) {
+            const subParts = word.subword
+                .map((sw) => {
+                if (sw.furigana && sw.surface !== sw.furigana) {
+                    return `<ruby>${sw.surface}<rt>${sw.furigana}</rt></ruby>`;
+                }
+                return sw.surface;
+            })
+                .join("");
+            parts.push(subParts);
+        }
+        else {
+            parts.push(word.surface);
+        }
+    }
+    return parts.join("");
+}
+// Format with roman characters
+function formatWithRoman(result) {
+    const lines = [];
+    for (const word of result.word) {
+        const surface = word.surface;
+        const furigana = word.furigana || "";
+        const roman = word.roman || "";
+        if (word.subword) {
+            const subDetails = word.subword
+                .map((sw) => `  - ${sw.surface}: ${sw.furigana || ""} (${sw.roman || ""})`)
+                .join("\n");
+            lines.push(`${surface}:\n${subDetails}`);
+        }
+        else if (furigana || roman) {
+            lines.push(`${surface}: ${furigana} (${roman})`);
+        }
+        else {
+            lines.push(`${surface}`);
+        }
+    }
+    return lines.join("\n");
+}
+// Create MCP server
+const server = new McpServer({
+    name: "yahoo-furigana",
+    version: "1.0.0",
+});
+// Format result based on output format
+function formatResult(result, format) {
+    switch (format) {
+        case "ruby":
+            return formatRuby(result);
+        case "roman":
+            return formatWithRoman(result);
+        case "bracket":
+        default:
+            return formatBracket(result);
+    }
+}
+// Register the furigana tool
+server.tool("gen_furigana", "日本語テキストにふりがな（ひらがな読み）を付けます。漢字かな混じりのテキストを入力すると、各単語の読み方を返します。", {
+    text: z.string().describe("ふりがなを付けたい日本語テキスト"),
+    grade: z
+        .number()
+        .min(1)
+        .max(8)
+        .optional()
+        .describe("学年指定（1-8）。指定した学年までに習う漢字にはふりがなを付けません。1=小1, 2=小2, ..., 6=小6, 7=中学, 8=それ以上"),
+    output_format: z
+        .enum(["bracket", "ruby", "roman"])
+        .optional()
+        .describe("出力形式。bracket=括弧形式「漢字（かんじ）」、ruby=HTMLルビ形式「<ruby>漢字<rt>かんじ</rt></ruby>」、roman=ローマ字付き詳細形式（デフォルト: bracket）"),
+}, async ({ text, grade, output_format }) => {
+    try {
+        const format = output_format || "bracket";
+        const formatted = await processTextWithChunking(text, grade, format);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatted,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `エラーが発生しました: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Yahoo Furigana MCP server started");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "yahoo-furigana-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Yahoo! JAPAN Furigana API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "yahoo-furigana-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "furigana",
+    "japanese",
+    "yahoo",
+    "api"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/analekt/yahoo-furigana-mcp.git"
+  },
+  "author": "",
+  "license": "MIT"
+}