polish-academic-mcp: Instructions file for Codex

AGENTS.md — AI Coding Agent Reference

This file is written for AI coding agents (GitHub Copilot, Claude, Cursor, etc.). It describes the codebase architecture, conventions, and step-by-step instructions for extending the server so that agents can work autonomously without guessing.

Project overview

polish-academic-mcp is a local MCP server (Model Context Protocol) that exposes 125 tools letting any MCP-compatible LLM (Claude, GPT-4, etc.) search Polish academic, public, and cultural databases. It runs as a local Node.js process communicating via stdio, distributed exclusively through npm as the polish-academic-mcp package. All databases offer unauthenticated read access except for the three PBN tools (require PBN_APP_ID + PBN_APP_TOKEN).

This file describes the v1.1.0 architecture (npm-only, local stdio). Historical sections that reference Cloudflare Workers, MCPB bundles, or research evaluation apparatus are obsolete and have been removed; if you see references to those in the wild, treat them as out of date.

For the complete tool catalogue (125 entries with Polish descriptions) see README.md. For per-client configuration snippets see docs/CLIENTS.md. For AI agents that need to configure the server themselves see docs/AGENT-GUIDE.md.

File map

package.json           npm-only distribution; entry "bin": { "polish-academic-mcp": "dist/index.js" }
                       engines: "node": ">=18"; no MCPB; no eval; no telemetry deps

src/
├── index.ts           Stdio entry: --help, --version, --list-sources, setup/uninstall/doctor
│                      dispatch, --sources / POLISH_ACADEMIC_SOURCES, then the MCP transport
├── server.ts          createServer(env, { sources }) — registers the selected sources (default:
│                      all 125 tools), MCP instructions, readOnlyHint/openWorldHint on every tool
├── sources.ts         catalogue of 33 sources in 5 groups (nauka, dane, prawo, normy, kultura)
│                      + parseSourceSelection()
├── clients.ts         MCP client catalogue for setup: config paths per OS, entry formats,
│                      JSON/TOML config edits (pure functions over a HostContext)
├── cli.ts             setup / uninstall wizard, doctor, --list-sources, --help text
├── cache.ts           in-process TTL cache + 30s timeout + single retry on transient errors;
│                      POLISH_ACADEMIC_DEBUG=1 logs every request to stderr
├── tool-error-handling.ts   structured error classification without OTel
├── types.ts           Env interface (BDL_CLIENT_ID, PBN_APP_ID, PBN_APP_TOKEN optional)
└── tools/             33 files, one per database / source
    ├── biblioteka-nauki.ts  → bn_search_publications, bn_search_articles, bn_get_article
    ├── ruj.ts               → ruj_search, ruj_get_item
    ├── agh.ts               → agh_search, agh_get_item
    ├── amu.ts               → amu_search, amu_get_item
    ├── uafm.ts              → uafm_search, uafm_get_item   (currently: HTTP 404 from eRIKA)
    ├── icm.ts               → icm_search, icm_get_item
    ├── rodbuk.ts            → rodbuk_search
    ├── repod.ts             → repod_search, repod_get_dataset
    ├── dane.ts              → dane_search, dane_get_dataset
    ├── polon.ts             → polon_search
    ├── pbn.ts               → pbn_search_publications, pbn_search_persons, pbn_get_publication
    ├── bdl.ts               → bdl_search_subjects, bdl_search_variables, bdl_search_units,
    │                          bdl_get_variable, bdl_get_data_by_variable, bdl_get_data_by_unit
    ├── imgw.ts              → imgw_synop, imgw_hydro, imgw_meteo, imgw_warnings
    ├── pkn.ts               → pkn_search
    ├── wiedza.ts            → wiedza_search_norms, wiedza_get_standard
    ├── blz.ts               → blz_search, blz_get_listing, blz_listing_categories
    ├── baztol.ts            → baztol_search, baztol_browse_domain, baztol_get_resource
    ├── nac.ts               → nac_news_rss, nac_site_search, nac_get_post, nac_get_page
    ├── sum.ts               → sum_aleph_find, sum_aleph_present
    ├── ludzie-nauki.ts      → ludzie_search, ludzie_semantic_search, ludzie_get_scientist
    ├── pauart.ts            → pauart_search, pauart_get_artwork
    ├── isap.ts              → isap_search_acts, isap_get_act
    ├── sejm-bs.ts           → bs_sejm_search, bs_sejm_get_item
    ├── saos.ts              → saos_search_judgments, saos_get_judgment, saos_dump_services,
    │                          saos_dump_common_courts, saos_dump_sc_chambers,
    │                          saos_dump_judgments, saos_dump_enrichments
    ├── wolne-lektury.ts     → wolnelektury_list_taxonomy, wolnelektury_filter_books,
    │                          wolnelektury_get_book, wolnelektury_get_collection
    ├── ninateka.ts          → ninateka_search, ninateka_get_vod
    ├── gapla.ts             → gapla_search, gapla_get_poster
    ├── fototeka.ts          → fototeka_search, fototeka_get_photo
    ├── filmpolski.ts        → filmpolski_search, filmpolski_get_item
    ├── fototekaslaska.ts    → fototekaslaska_search, fototekaslaska_get_photo
    ├── filmoteka-repo.ts    → fn_repo_search, fn_repo_get_node, fn_repo_film_index, fn_repo_browse_kind
    ├── rcin.ts              → rcin_search, rcin_get_record
    └── dokumenty-slaska.ts  → dokumenty_slaska_get_page, dokumenty_slaska_medieval_catalog

tests/
├── package-contract.test.ts   version, --help, --version, npm-only, no MCPB / eval / telemetry
├── mcp-contract.test.ts       125 tool IDs stable, all tool + parameter descriptions in Polish
├── fetch-policy.test.ts       30s timeout, single retry on transient, no retry on 4xx
├── sources.test.ts            source selection, catalogue ↔ tool prefixes, filtered server
└── setup.test.ts              client config paths per OS, JSON/TOML edits, setup CLI end-to-end

scripts/
└── smoke-tools.ts             live smoke (82 tools + 5 dynamic search→get pairs)

tsconfig.json          TypeScript config (strict, module: ES2022, target: ES2022)
docs/
├── CLIENTS.md         per-client MCP configuration (what `setup` writes + manual steps)
├── AGENT-GUIDE.md     prompt for AI agents configuring the server (uses `setup --yes`)
├── CLOUDFLARE.md      remote Workers+Pages (OAuth 2.1, AI Search, connectors)
└── plans/             implementation plans

cloud/                optional Cloudflare Workers + Static Assets (separate package.json).
                       Shares src/tools/* via tool-bridge; not part of the npm CLI package.
                       OAuth 2.1 (/mcp), ORCID/email/passkey, D1 quotas, AI Gateway Haiku.
                       See docs/CLOUDFLARE.md.