mcp-server-cr-academic
v0.4.1
Published
MCP server to search Costa Rican academic repositories (OAI-PMH) and format citations
Maintainers
Readme
mcp-server-cr-academic
An MCP server that searches Costa Rican academic repositories (theses, articles, and reports harvested over OAI-PMH) and formats citations. It runs over stdio, so it works with opencode, Claude Desktop, Claude Code, Cursor, VS Code, and other MCP clients.
Tools
search_academic_publications
Searches harvested records. Every word in query must appear in the title, creators, abstract, or subjects. Matching ignores case and accents. Results are sorted newest first.
| Parameter | Type | Description |
| --- | --- | --- |
| query | string, required | Free-text search. |
| institutions | string[] | Repository codes, for example ["CONARE", "UCR"]. Defaults to all enabled repositories. |
| date_from | integer | Earliest publication year, inclusive. |
| date_to | integer | Latest publication year, inclusive. |
| max_results | integer, 1–20 | Defaults to 10. |
Matching uses the words that remain after dropping common Spanish and English stopwords, and document-type words such as "tesis" or "artículo". For example, "La tesis de Paola Aguero con el acta de los nublados" searches for paola, aguero, acta, and nublados. Every remaining word must match. The response includes terms, which lists the words used, and sources, which reports per repository whether the harvest was ok, truncated, not_configured, disabled (see Repositories), or failed with an error.
Each result carries has_pdf (true, false, or null when the repository could not be checked). Records the repository holds as metadata only also carry access: "metadata_only" and external_url, pointing at the institutional login where the full text lives. For CONARE, has_pdf: true can still be a link-only file; download_pdf reports that case.
format_citation
Formats a citation for a record returned by a previous search. The record is looked up by handle in the cached results, so run a search first.
| Parameter | Type | Description |
| --- | --- | --- |
| handle | string, required | For example 1234/5 or https://hdl.handle.net/1234/5. |
| style | APA7, BibTeX, or IEEE | Defaults to APA7. |
| institution | string | Repository code to search in. Defaults to all enabled repositories. |
download_pdf
Downloads the PDF of a record into a local folder and returns the saved path, size, and SHA-256 checksum. Use the handle from a search result.
| Parameter | Type | Description |
| --- | --- | --- |
| institution | string, required | Enabled repository code, for example "UCR". |
| handle | string, required | Handle such as 20.500.14951/3427, or its URL. |
| output_dir | string, optional | Subfolder of the download folder, for example "tesis/UCR". Must stay inside the download folder. Defaults to a subfolder named after the repository, for example cr-academic-downloads/UCR. |
Files are named after the record title, in lowercase and without accents, followed by the handle: analisis_de_contexto_del_planes_2026-2030_20.500.12337_11841.pdf. The title part is capped at 80 characters. If the record has no usable title, the name is {REPO}_{handle}.pdf. If a file with the same name already exists, the new copy gets a numbered suffix (_2, _3, ...) instead of overwriting it.
Only enabled repositories are supported (BCCR, CONARE, UCR, UNA, TEC; UNED is disabled, see Repositories). The tool reads the item through the repository's REST API, so it does not depend on search results and works for any handle the repository knows. It downloads only files the repository serves publicly, and it never bypasses logins.
Each download is capped at 100 MiB, checked for a %PDF- header, and written atomically, so a failed transfer leaves no partial file. Failures are returned as a tool error with a code:
| Code | Meaning |
| --- | --- |
| outside_download_dir | output_dir resolves outside the download folder, directly or through a link. Nothing is downloaded. |
| not_found | The repository has no item with this handle. |
| no_files | The record has no files attached. |
| no_pdf | The record has files, but none is a PDF. The message lists them. |
| link_only | The repository's PDF is a one-page link to the document (common for CONARE), and no open copy of the article could be found. Nothing is saved. The response includes external_url (the address the file points to, usually a DOI) and message lists what was tried. |
| stale_link | The repository's PDF links to a section of a web page that no longer exists there. Nothing is saved; external_url is the linked address. |
| web_article_only | The repository's PDF links to a web article that offers no document to download. Nothing is saved; external_url is the linked address. |
| blocked_by_captcha | The linked site answers automated requests with a bot-protection challenge, so the document could not be fetched. Nothing is saved; external_url is the linked address. |
| external_login_required | The repository holds only metadata for the record, and the full text lives behind an institutional login. external_url is the login address. |
When the repository only links to the article, download_pdf looks for an open copy in this order, and accepts the first one that is a real PDF of the same work:
- Another record with the same DOI in the harvested repositories (
via: "repository"). - The linked address, if it is itself a PDF (
via: "link"). - Open-access PDF locations for the DOI from OpenAlex (
via: "openalex"). - Documents the linked page itself points to, such as a journal's galley download (
via: "link"). - A Tableau dashboard render the linked page embeds (
via: "tableau"). - A figure from the linked web article, when the linked address is a plain web page (
via: "figure"). - As a last resort, when
CR_ACADEMIC_BROWSERis set and a browser package is installed, a headless rendering of the linked page (via: "link").
A copy counts as the same work when its text contains the DOI, or when most of the record's title words appear in its first two pages. Paywalled and login-protected files are never fetched around, and sites that refuse automated access (such as HTTP 403) are reported as failed attempts.
The result's via field says which route produced the file, and source_url gives where it came from. Open-access copies may be preprints or other versions of the work, not necessarily the published version.
| Code | Meaning |
| --- | --- |
| unsafe_url | A link points somewhere the server refuses to contact: a non-web address, a private or internal network address, or a redirect to one. Nothing is fetched. |
| restricted | The repository denied access, usually because the file requires login. |
| too_large | The file is larger than 100 MiB. |
| invalid_pdf | The file does not start with a PDF header. |
| not_configured | The repository is disabled or has no REST endpoint. The message gives the reason. |
Repositories
| Code | Institution | Status |
| --- | --- | --- |
| CONARE | Consejo Nacional de Rectores | Searchable |
| UCR | Universidad de Costa Rica (Repositorio SIBDI-UCR, including former Kérwá items) | Searchable |
| BCCR | Banco Central de Costa Rica (read through its REST API; its OAI-PMH endpoint returns HTTP 500) | Searchable |
| UNA | Universidad Nacional (Repositorio Académico Institucional, OAI-PMH) | Searchable, slow first harvest (about 5 minutes for about 14,000 records) |
| TEC | Instituto Tecnológico de Costa Rica (RepositorioTEC, OAI-PMH) | Searchable |
| UNED | Universidad Estatal a Distancia | Disabled (see below) |
UNED is disabled
The UNED repository (repositorio.uned.ac.cr) is switched off in this version. Its HTTPS service does not accept connections, so no records can be harvested and no files can be downloaded. Diagnosed on 2026-11-14: DNS resolves, port 443 times out from several networks, and port 80 answers only with HTTP 403.
While it is disabled:
- Searches leave UNED out of the default set. An explicit
institutions: ["UNED"]returns no records and reportssources.UNED.statusasdisabled: …. download_pdfwithinstitution: "UNED"fails with the codenot_configuredand does not contact the repository.
To re-enable it, check that https://repositorio.uned.ac.cr/server/api/discover/search/objects answers over HTTPS, then set verified: true and remove disabledReason for UNED in src/config.ts, and run npm test. Aggregators such as Kímuk or LA Referencia hold UNED metadata but not its files, so they are not a substitute for downloads.
Each search harvests every record a repository exposes, up to MAX_HARVEST_PAGES pages of 100 records. The default covers about 30,000 records per repository. Repositories that reach the limit are marked truncated in sources.
The server starts harvesting every repository as soon as it launches, so the first search usually finds the cache ready. Harvests run in parallel, and REST-based repositories fetch pages in batches. Repositories sometimes drop connections under load, so each request is retried up to five times with growing pauses. A cold harvest of UNA can still take several minutes, and a search that runs during it waits for the harvest to finish. Later searches use the cache until CACHE_TTL expires.
Configuration
Set these environment variables in your client's env or environment block. All are optional.
| Variable | Default | Description |
| --- | --- | --- |
| CACHE_TTL | 86400 | Seconds to keep harvested records in memory. |
| MAX_HARVEST_PAGES | 300 | Maximum OAI-PMH pages per repository per harvest (100 records per page). |
| CR_ACADEMIC_USER_AGENT | mcp-server-cr-academic/0.4.1 | User-Agent sent to repository servers. Set it to a contact address if you run this heavily. |
| CR_ACADEMIC_DOWNLOAD_DIR | ./cr-academic-downloads (the working directory where the server starts) | Root folder for download_pdf. Clients can choose only a subfolder with output_dir; paths that resolve outside this folder, including through links, are refused. |
Earlier versions saved downloads to ~/cr-academic-downloads. Files already there are not moved; set CR_ACADEMIC_DOWNLOAD_DIR to that path to keep using it.
| CR_ACADEMIC_BROWSER | unset | Optional headless browser for link-only records that sit behind a JavaScript challenge. Set to playwright or puppeteer to enable it; the package must be installed separately, so the default install stays dependency-free. Used only as a last resort. |
Harvested records are cached in memory until CACHE_TTL expires.
Client setup
Every snippet launches the package with npx -y, so nothing needs to be installed in advance. Requires Node.js 24 or newer.
opencode
Add to opencode.json in your project, or to ~/.config/opencode/opencode.json for all projects:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"cr-academic": {
"type": "local",
"command": ["npx", "-y", "mcp-server-cr-academic"],
"enabled": true,
"timeout": 180000
}
}
}The timeout is raised because the first search, which harvests every repository, can take over a minute. opencode's default is 30 seconds. A search that includes UNA during its first harvest can take about five minutes, so either raise the timeout further or wait for the background harvest to finish.
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"cr-academic": {
"command": "npx",
"args": ["-y", "mcp-server-cr-academic"]
}
}
}Claude Code
claude mcp add --transport stdio cr-academic -- npx -y mcp-server-cr-academicCursor
Add to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json for all projects:
{
"mcpServers": {
"cr-academic": {
"command": "npx",
"args": ["-y", "mcp-server-cr-academic"]
}
}
}VS Code
Add to .vscode/mcp.json in your workspace. VS Code uses servers as the top-level key, not mcpServers:
{
"servers": {
"cr-academic": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-server-cr-academic"]
}
}
}Development
npm install
npm run build # compile src/ to dist/
npm test # run the test suite
npm run test:coverage # run the suite with coverage thresholds
npm run lint # ESLint with security rules
npm run typecheck # TypeScript without emitting files
npm run bench # run performance benchmarks (offline, uses fixed fixtures)
npm run inspect # open MCP Inspector against dist/index.jsThe entry point is src/index.ts, which connects the stdio transport. Tool definitions live in src/server.ts. Logs go to stderr only, because stdout carries the protocol.
Security
The server reads text from third-party sites, so it treats every remote address as untrusted:
- Every outbound request is checked before it is sent: only
httpandhttps, no embedded credentials, and no hostname or redirect that resolves to a private, loopback, link-local or cloud-metadata address. Each redirect is checked again. - API and HTML responses are capped in size, and downloads are capped at 100 MiB.
- Text from repositories (titles, abstracts, creators, subjects) is cleaned and truncated before it reaches the client, and
download_pdfnever writes outsideCR_ACADEMIC_DOWNLOAD_DIR. - BibTeX output escapes LaTeX control characters.
- At most two downloads run at the same time.
Known residual risks: a DNS record can change between the check and the connection, and the optional headless browser (CR_ACADEMIC_BROWSER) checks only the page it opens, not the sub-resources it loads. Enable it only if you accept that. To report a vulnerability, see SECURITY.md.
Known limitations
- Harvested records are kept in memory. A restart clears the cache, so
format_citationneeds a search first. - Name formatting is simple. Creators with several given names or particles (for example "d.") may get awkward initials in citations.
- Only enabled repositories are searched by default.
- UNED is disabled because its repository does not answer over HTTPS. See UNED is disabled.
