Command Palette

Search for a command to run...

UnylyUnyly
Browse all

Japanophile

FreeNot checked

Japanophile workstation: kanji/JLPT learning tools plus Japanese culture knowledge box. First -phile repo.

GitHubEmbed

About

Japanophile workstation: kanji/JLPT learning tools plus Japanese culture knowledge box. First -phile repo.

README

Release Just Python FastMCP CI MIT

Your Japanophile workstation: kanji/JLPT learning tools, Japanese culture knowledge box, travel and diary on the roadmap. First -phile repo (fleet doc: mcp-central-docs/projects/japanophile-mcp/PHILE_PATTERN.md). Polite name on listings; working title was weeaboo, retired to joke status.

Ports: backend 11193, frontend 11194. Registered in mcp-central-docs/operations/WEBAPP_PORTS.md.

Quick start (Stage 2)

cd D:\Dev\repos\japanophile-mcp
uv sync --group dev
.\start.ps1

Opens http://127.0.0.1:11194 (HTTP API + MCP on 11193). MCP-only (stdio): uv run python -m japanophile_mcp.server.

Claude Desktop bundle: just mcpb-pack → dist/japanophile-mcp-v{version}.mcpb (see scripts/mcpb-pack.ps1, mcp-central-docs/standards/MCPB_PACKAGING_STANDARDS.md).

Stage 1: MCP tools

Eight portmanteau tools, dialogic returns, seeds in assets/seed/, learning corpora in data/ (committed). Deliberately thin on the MCP side by design — this repo is primarily a human webapp (quizzes, games, reading), MCP tools are the agent-facing afterthought, not the product. vocab, jp_utils, and remember were added 2026-09-14 to close the gap against narrower competing MCP servers (Jisho MCP, JLPT Study MCP, Japan Utils MCP, Ayaka, Potto Japan) — see reports/quality-japanophile-mcp-2026-09-14.md:

Tool Operations Data
kanji lookup, search, by_jlpt, by_grade, by_radical, random assets/seed/kanji_database.db (13,108 kanji)
jlpt next, answer, progress assets/seed/jlpt_questions.db (600 Q + options)
vocab search (400k vocab + jmdict), by_jlpt, examples (278k example sentences) data/kanji.db (~135MB, vendored)
knowledge list, get — collection=culture (29 pages) or collection=language (grammar/vocab/keigo/exams, 11 pages) assets/knowledge/japan/.html, assets/language/.html
jp_utils kana_convert (hiragana/katakana/romaji), era_to_year, year_to_era pure Python — Hepburn table + Meiji-Reiwa era table
remember streak, due (missed-question queue) data/progress.db answers table (same store jlpt/answer writes)
crossconnect speak, library_search, media_search proxies speech-mcp/calibre-mcp/plex-mcp REST APIs (2026-09-15, see Crossconnects below)
webapp_ops get_ui_map, tour_page, demo_webapp, diagnose_webapp steers this repo's own webapp from webapp/public/ui-map.json (14 routes, phase-1 static receipts, port of the learnbot-mcp pilot 2026-10-16)
japanophile_help tool + data status -

No structured grammar tool: the fleet has no vendored JLPT-graded grammar-point database (unlike Ayaka/Potto Japan), and Makino/Tsutsui's grammar dictionaries are copyrighted — fabricating one would violate the no-fake-data standard. knowledge(collection=language) exposes the real vendored grammar prose page instead.

{ "mcpServers": { "japanophile-mcp": {
  "command": "uv",
  "args": ["run", "--directory", "D:\\Dev\\repos\\japanophile-mcp",
           "python", "-m", "japanophile_mcp.server"] } } }

Stage 2: webapp

Dashboard, Learn (kanji / JLPT quiz / vocab), Know, Games (vendored drills), Chat (japanophile-expert + local LLM), Skills, Tools, Settings, Help, Logs. Playwright e2e + screenshot automation in webapp/e2e/.

Webapp (for demo-vid and docs)

Page Purpose
Dashboard Backend health, KPI cards for kanji seed, JLPT question bank, and knowledge page count; surfaces fetch hints when large DBs are missing
Learn Kanji lookup and search, JLPT quiz with scored sessions, vocabulary search when kanji.db is fetched
Know Browse and read vendored Japan culture articles (history, travel, food, manga, and related topics) as plain text
Games Embedded HTML/JS practice tools: flashcards, stroke order, JLPT tests, grammar and listening drills
Chat Local LLM tutoring with the japanophile-expert skill loaded; routes answers through repo tools and knowledge pages (text today; voice via speech-mcp when connected)
Skills View the japanophile-expert skill markdown used by Chat
Tools One-click MCP tool runner (sample kanji lookup) for debugging and demos
Settings Ollama-compatible LLM endpoint and model selection for Chat
Help Ports, tool list, and pointers to install docs
Logs Sorted, filterable-style diagnostic view of backend health, database paths, and load errors from API probes

Narrated tour script (two sentences per page, 3s pause between): docs/demo-vid/narration.yaml. demo-vid-mcp loads it automatically for demo_vid_generate(repo="japanophile-mcp").

Preview: draft PNGs + agent-made demo MP4 in docs/screenshots/README.md (better PNG contrast planned 2026-09-14).

Inheritance

Learn tools (~15 html/js games), 29 knowledge pages, kanji/JLPT seeds vendored from ai-games-collection (docs/INHERITANCE.md). Canonical home for Japanese learning; ai-games-collection keeps hanafuda/cho-han play with crosslinks.

Crossconnects

  • local-llm-mcp — Chat tutoring (wired).
  • speech-mcp — TTS via crossconnect(speak) and the Know page's Listen button; proxied through /api/crossconnect/speak.wav so the browser never talks to speech-mcp's port directly (wired 2026-09-15).
  • calibre-mcp — crossconnect(library_search), Sandra's Japanese-literature/textbook/manga shelf by query or tag (wired 2026-09-15; client-side query filter works around an upstream bug — calibre-mcp's own query param is currently a no-op, see reports/quality-japanophile-mcp-2026-09-14.md follow-ups).
  • plex-mcp — crossconnect(media_search), Sandra's JP movies/anime by query and media_type (wired 2026-09-15; client-side type filter works around plex-mcp's media_type param currently being a no-op).
  • ai-games-collection — canonical home for hanafuda/cho-han gameplay; this repo owns learning.
  • Voice Command Bus — registered as a receiver (japanophile entity, direct route to kanji/vocab/jlpt/knowledge/japanophile_help) in mcp-central-docs/config/voice_command_bus.yaml + fleet-agent-mcp's FLEET_SERVERS (2026-09-15). Not yet functional — this repo's own /mcp streamable-HTTP mount currently fails session init; fleet-agent can't reach it until that's fixed (see mcp-central-docs/standards/VOICE_COMMAND_BUS.md §4c). See mcp-central-docs/standards/VOICE_COMMAND_BUS.md for the full pattern.
  • Full crossconnect map: mcp-central-docs/projects/japanophile-mcp/PHILE_PATTERN.md. No webapp browser UI yet for library_search/media_search — MCP/HTTP only so far.

Roadmap

  • Tauri NSIS winapp (installer built at 0.3.0; next release when rebased on 0.3.1).
  • Plan + Remember: travel planner APIs, diary, full SRS scheduler (today's remember tool is a missed-question queue, not SM-2/FSRS).
  • austrophile-mcp as second -phile template.

Docs: TOOLS - CONFIGURATION - INSTALL - CONTRIBUTORS

from github.com/sandraschi/japanophile-mcp

Installing Japanophile

This server has no published package — it is built from source. Open the repository and follow its README.

▸ github.com/sandraschi/japanophile-mcp

FAQ

Is Japanophile MCP free?

Yes, Japanophile MCP is free — one-click install via Unyly at no cost.

Does Japanophile need an API key?

No, Japanophile runs without API keys or environment variables.

Is Japanophile hosted or self-hosted?

Self-hosted: the server runs locally on your machine via the install command above.

How do I install Japanophile in Claude Desktop, Claude Code or Cursor?

Open Japanophile on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.

Related MCPs

Compare Japanophile with

Not sure what to pick?

Find your stack in 60 seconds

Author?

Embed badge for your README

Browse similar

All ai MCPs