jp-lit-mcp

List `jp-lit-m is an MCP server-searching Japanese databases from AI It supports various as the National Diet NDL Digital CiNii Research / Books / Dissertations, J-STAGE, IRDB, JDCat, nihuBridge, National Diet and records. The main assumed to be humanities and want to on which databases and how to It is not only for programming are two main- `M A connection port for searching and retrieving various from AI applications. - `Skills`: A that instructs AI on how to investigate, to search, expand search terms, and how to read normal use, no need to clone this repository. Register `npx -y jp` as an and install Skills following the instructions on the individual application pages. ## Who is it for? This tool is suitable for tasks such as: - Searching for books, papers, journal articles, research projects conference records related to a research theme. - Confirming bibliographic information, holdings, availability using NDL / CiN, etc. for phrases in text of Collection using OCR. - Searching for specialized databases, including classical literature, Japanese language research, and. - a research approach using the Reference Cooperative DatabaseDL Research- Verifying the existence of literature lists other services`jp-lit-mcp` assists in finding and organizing literature candidates, but evaluation and conclusion of research are done by humans. ## Key Terms For first-time users, understanding the following two terms is sufficient: - `MCP`: A adding external AI applications. Here, AI with a tool to search NDL and CiNii. - `Skills`: A procedure manual that instructs how to conduct investigations. While search with MCP alone provide stability which database to how to terms, and how to explain candidate strengths and## Roles of Skill and MCP M tool for searching and retrieving. It queries bibliographic information, holdings, OCR,, and research data. Skills guide the actual investigation, determining which source to use, how to terms, how to evaluate candidates, and how confirmation of the main text. - `jpearch`: A Skill for advancing Japanese literature research. It handles theme investigation, bibliographic materials, and main text/image search. --verification`: A Skill for extracting literature candidatesed text or other service responses and verifying their existence## Pre-InstallationThe following are required: - `Node.js 22` or higher ` - AI applications compatible with MCP You if Node.js and npm are available using the terminalbash node -v npm -v ``` v22` or higher Node.js is displayed, you to go. If not, install Node.js first CiNii Research API specification requires `appid`. Although respond without setting it, for formal use, setINII_RE_ID`. If not set continue to search CiNii-related sources ( dissertations, books) and attach a `II_APP_ID_REQUIRED` warning. ## Quick Installation most common issue during installation is the difference in MCP/S for each application does not list all registration commands. Follow the instructions on the individual application pages for, Skills installation, setting reflection, and common [Cursor Installation Procedure](docs/install/cursor.md) - [Claude Code Installation Procedure](docs/install/claude-code.md) - [Codex CLI Installation Procedure](docs/install/codex-cli.md) - [Codex App Installation Procedure](docs/install/codex-app.md) - [GitHub Installation](docs/install/github-skills.md) ## Additional Convenience ### Ci Research appid The `appid` obtained from CiNii Research API registration as an environment variable passed to the `jp-lit-m MCP server. The variable name is `CINSEARCH_APP_ID`. ### OpenAlex / Crossref Matching Settings `jp_lit_enrich_record` is an auxiliary matches found single literature candidates with DOI, title, and publication year using Crossref / OpenAlex. - `EX_API_KEY`: Used for OpenAlex matching., OpenAlex will be `skipped` will be used. - `CROSSREF_MAIL Polite pool contact information for Crossref. Although optional, is recommended for continuous use. Pass these as `env the MCP server settings for `jp-lit-mcp`, similar to `CINSEARCH_APP_ID`. il Library MCP [Calil Library MCP](httpsil.jp/ai/) is an MCP-compatible library catalog provided by Calil. If you want to search, local figures, local newspapers, local magazines, public holdings, adding Calil Library MCP is convenientil is not a `jp-lit-m but is added to the AI application side as a server. ## Post-Installation Confirmation Run the lightweight diagnostic```bash npx -y jp-lit ``` `: - `22` or higher - npm package availability MCP entry point visibility - Shipped Skills visibility - Cache/exports directory writability - `CINSEARCH_APP_ID` setting Live API access to is not performed. ## Example Requests Try the: ```text Search literature databases for studies on labor culture in modern Japan, papers and books. ``` Start literature. Suggest initial materials databases for studying Meiji-period haiku magazines. ``` Verify the existence of literature in this text using. ``` ## What Do ### Search for Literature Search for books, papers, journal articles, research data, research projects, conference records, etc., selecting sources according to the purpose. ### Confirm Bibliographic Information and Holdings Use NDL Search, NDL Catalog, CiNii Books, etc., to confirm bibliographic information, holdings year, volume/issue numbers, and online### Search for Papers, and Institutional Repositories for papers, bulletins, doctoral dissertations data, and links-text PDFs from Ci, CiNii Dissertations, J IRDB, JDCat, etc. for NDL Digital Full Text Use the digital library API for OCR full text-page search, character coordinates, and image/graphic search. ### Search for, Japanese Literature, Research Use databases the National Book Database, Japanese Literature Database, and Japanese language research/education databases for classical texts, manuscripts, printed books, Japanese, and Japanese language research materials. ### Search for National Diet and Imperial Diet Records for post-war National and pre-war Imperial Diet records by speech unit and. ### Search for Research Approaches and Reference Examples Cooperative Database, NDL Research Navigator, K, etc., to search for research theme entries, related reference materials, search term candidates, and links to research project/achievement report PDFs. ### Verify Candidates against External Bibliographic DB Candidates with known DOI, title, author, or year can be verified against Crossref/OpenAlex using `jp_lit_enrich_record`. This is not a search source but a tool to check if already found candidates match by DOI or bibliographic elements. Example: ```text jp_lit_enrich_record(title="Genji Monogatari Research", authors=["Taro Yamada"], issued_year="2020") ``` The `match_confidence` of the verification result does not confirm the content or importance. In Japanese humanities, there are important literature not listed in Crossref/OpenAlex. When confirming duplicate clusters of saved search results, use `jp_lit_refine_results(include_duplicate_clusters=true, include_enrichment=true)` or `jp_lit_export_view(..., duplicate_notes=true)` to overlay the `jp_lit_enrich_record` cache remaining in the same session on the cluster. This also does not query Crossref/OpenAlex newly but only arranges the existing verification metadata. ### Check Authorities, Aliases, and Subjects Use Web NDL Authorities to expand search terms from person names, organization names, subjects, NDC, etc. Example: ```text In the literature DB, confirm the name relationship between Shirokawa Takeo and Asada Tetsuya, and organize which name to search for. ``` For persons or subjects with many aliases, old characters, pen names, transliterations, or notation variations, checking authorities first can reduce search omissions. ### Verify the Existence of Literature The `jp-lit-verification` Skill extracts literature candidates from pasted text or answers from other services and confirms their existence, partial matches, suspected non-existence, or suspected confusion. Example: ```text Verify the existence of literature in the following reference list to check for non-existent or confused literature. ``` It distinguishes not only fictional literature but also cases where "the title is similar but the author or journal name is different" or "the author exists but only the paper title is mixed". ### Reorganize Search Results Search results are saved in the local cache and can be refined, integrated, difference-confirmed, and re-exported later. Examples of what can be done: - Narrow down to candidates with online publication - Integrate search results from multiple searches and organize duplicate candidates - View differences between previous and current searches - Add labels such as `confirmed` / `strong_candidate` / `weak_candidate` to adopted candidates - Export in Markdown / JSON / CSL JSON Adopted candidates exported in CSL JSON can be passed to literature management and citation processing tools such as Zotero, Pandoc, and citeproc. ### Leave Investigation Products and Progress In long investigations, not only search results but also investigation purposes, reasons for selecting sources, search trials, adoption/retention/exclusion reasons, text confirmation ranges, unconfirmed matters, and next actions can be left as a session trace. The roles of things left after investigation are different. Cache / session trace / handoff report are similar but have different roles. | Type | Role | | --- | --- | | `cache` | Storage of search results and acquisition payload | | `session trace` | Restoration of investigation process, judgments, unconfirmed matters, and next actions | | `handoff report` | Organized report for main agents or humans to read | | Final answer | Short report returned to the user on the spot | In long investigations using sub-agents, using a handoff report makes it easier to track the progress later. See [Usage Guide](docs/usage-guide.md#things-left-after-investigation) for details. ### Expand to Regional Materials, Local Persons, and Public Library Research For regional materials, local persons, local newspapers, and local magazines, NDL / CiNii / Japan Search may not be enough. In such cases, a search route combining prefectural libraries, city or ward central libraries, local history rooms, specialized material institutions, and Calil Library MCP can be considered. To use Calil Library MCP for actual search, setting and initial OAuth authorization on the AI client side are necessary. See [Regional Public Library and Local Materials Research Memo](docs/regional-public-library-research.md) for details. ## Why Use Skills MCP alone can search, but in that case, users or agents need to decide source names, search terms, confirmation order, and result handling very specifically. Using `jp-lit-research` Skill allows planning an investigation before searching and constructing sources and search terms while referring to Referece Cooperative Database or NDL Research Navigator as needed. When returning results, not only bibliographic information but also confirmed evidence, text confirmation presence, online entrance, and materials to see next are shown separately. `jp-lit-verification` Skill specializes in confirming the existence of literature. As a separate mode from literature exploration, it extracts candidates from pasted text, primarily using NDL Search as the first gate, and supplements confirmation with individual sources as needed. ## Using MCP Alone Even without Skills, MCP server can be registered and used for search. However, source selection, search term expansion, candidate evaluation, text confirmation labels, and investigation logs are left to the user or agent. If reproducibility and handover of investigation are important, using Skills is recommended. When not using Skills, avoid Skill activation words like "In literature DB" / "In literature verification" and directly specify source names or tool names as needed. ## Reading Notes `online=true`, links to PDF / HTML / digiコレ, and official viewer URLs indicate that there is an entrance online. It does not mean that the agent has read the text. Even for literature that has not been read, titles, abstracts, tables of contents, book reviews, publisher introductions, and fragments on the web can be temporarily organized. In such cases, it is clarified that it is not a text interpretation and what it is based on. The priority of candidates is the confirmation priority in the investigation. Publisher, publication journal, author attributes, citation/book review status, and text confirmation status are used as clues, but the value of literature is not determined solely by the publisher or media. The `cache.hit=true` of search and acquisition tools indicates that the saved cache was reused. In this case, it does not search the upstream API again, so if necessary, re-acquire with `force_refresh=true`. Old caches can be deleted after confirming candidates with `jp_lit_prune_cache`. ## Main Correspondence Frequently used sources are as follows: - `ndl_catalog`: Entrance to examine NDL's bibliographic and holding information - `ndl_digital`: NDL Digital Collection - `cinii_articles` / `cinii_dissertations` / `cinii_books`: Papers, doctoral dissertations/degree theses, university library books and journals - `jstage_articles`: Academic journals and research papers - `irdb`: University institutional repositories - `nihu_bridge`: Cross-search of humanities-specific DBs - `nijl_articles`: Japanese literature and Japanese literature research paper catalog - `kokusho`: Bibliography, authorship, and location confirmation of Japanese books/classics/manuscripts/printed books - `ninjal_bibliography`: Japanese research/Japanese education literature/national language education literature - `national_archives`: Government documents and specific historical archives of the National Archives of Japan - `jacar`: Diplomatic/military/old overseas/near-modern Asian historical materials of JACAR - `kokkai_minutes` / `teikoku_minutes`: Diet/Imperial Diet proceedings - `jdcat`: Research data in humanities and social sciences - `japan_search`: Cultural properties/museums/regional materials In the initial stage of investigation, the following auxiliary tools/web leads are often used, not as sources: - `jp_lit_search_guides_manuals` / `jp_lit_search_guides_cases`: Look up manuals and reference cases from the Reference Cooperative Database to find theme entrances, reference materials, and search term candidates - NDL Research Navigator: Not connected to API/MCP source. Used as a web guide to confirm and decide which DBs, indexes, reference bibliographies, and search term candidates to see Crossref/OpenAlex are not sources but used as auxiliary providers to verify existing candidates with `jp_lit_enrich_record`. For the Japanese Book Database, in addition to `jp_lit_search(source=kokusho, ...)`, there are `jp_lit_search_kokusho_fulltext` for full-text search and `jp_lit_search_kokusho_image_tags` for image tag search. Neither acquires the entire text, image body, or manifest body but returns URLs and metadata for confirmation on the official screen. See [Technical Reference](docs/reference.md) for details on supported sources and MCP tools. ## Documents - [Usage Guide](docs/usage-guide.md): Actual request examples, investigation flow, and output reading - [Introduction Procedure for Cursor](docs/install/cursor.md): Using MCP and Skills with Cursor - [Introduction Procedure for Claude Code](docs/install/claude-code.md): Using MCP and Skills with Claude Code - [Introduction Procedure for Codex CLI](docs/install/codex-cli.md): Using MCP and Skills with Codex CLI - [Introduction Procedure for Codex App](docs/install/codex-app.md): Using MCP and Skills with Codex App - [Regional Public Library and Local Materials Research Memo](docs/regional-public-library-research.md): Using Calil Library MCP for regional materials/local public library route - [Installing Skills with GitHub CLI](docs/install/github-skills.md): Another route using `gh skill install` - [Technical Reference](docs/reference.md): Sources, MCP tools, environment variables, constraints, development and verification commands - [Data Usage Conditions Memo](docs/source-usage-conditions.md): Display requirements and usage conditions of external DBs/APIs - [Implementation Status](docs/project-status.md): Current status, recent updates, and post-publication notes ## Development Usually, no cloning is needed for normal use. Clone this repository only when adding sources or making repairs. ```bash git clone https://github.com/itarunnn/jp-lit-mcp.git cd jp-lit-mcp npm install npm run build npm run smoke:mcp ``` Connection confirmation of Calil Library MCP can also be done in the development checkout. ```bash npm run smoke:calil-mcp ``` This is a separate Node smoke script from Codex's MCP settings. Initial browser OAuth authorization is required. ## License The code in this repository is under the `MIT License`. See [LICENSE](LICENSE) for details. However, the data usage conditions of external DBs/APIs accessed by MCP are different. Attention points differ between personal terminal investigation usage and public service/shared server operation that accumulates search results and provides them to multiple users. Conditions for redistribution, display, commercial use, and mirror-like saving are confirmed in [Data Usage Conditions Memo](docs/source-usage-conditions.md) and each provider's terms.