@minicod/mcp-server

MCP server for Minicod — query academic papers and journals from Semantic Scholar, OpenAlex, PubMed, and Minicod's curated journal database through any MCP-compatible client (Claude Desktop, Cursor, Cline, Continue, etc.).

🔑 An API key is required. Sign up and generate one at https://www.minicod.com/ → Dashboard → API Keys. The key has the form sk-... (same format as OpenAI keys) and is used both for the REST API and this MCP server. Every tool call hits the Minicod API and consumes from your account's quota.

Quick start

1. Get an API key at https://www.minicod.com/ (free signup; pay-per-call after the included quota).
2. Add the snippet for your client below.
3. Restart the client. You should see 12 minicod tools available to the model.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "minicod": {
      "command": "npx",
      "args": ["-y", "@minicod/mcp-server"],
      "env": {
        "MINICOD_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (or per-project .cursor/mcp.json):

{
  "mcpServers": {
    "minicod": {
      "command": "npx",
      "args": ["-y", "@minicod/mcp-server"],
      "env": { "MINICOD_API_KEY": "sk-your-key-here" }
    }
  }
}

Cline / Continue / other stdio clients

Same shape — point to npx -y @minicod/mcp-server and pass MINICOD_API_KEY as an environment variable.

Configuration

| Env var | Required | Default | Notes | |---|---|---|---| | MINICOD_API_KEY | yes | — | Your sk-... API key from https://www.minicod.com/ | | MINICOD_API_BASE_URL | no | https://minicod.com/v1 | Override for self-hosted or staging | | MINICOD_TIMEOUT_MS | no | 30000 | Per-request timeout |

If MINICOD_API_KEY is missing, the server exits immediately with an instructional error message — the MCP client will surface that error in its logs.

The 17 tools

Tools are intentionally source-explicit: every paper tool requires you to pick one of semantic, openalex, or pubmed. Results are not merged across sources, and every returned item carries a source field so you can always tell where data came from. If you want cross-source coverage, call the tool multiple times in parallel.

Papers (6)

| Tool | What it does | |---|---| | search_papers | Keyword search with structured filters (year range, date range, open access, min citations, venue, subjects, types, sort) | | get_paper | Fetch one paper by its native source ID | | get_paper_by_doi | Resolve a DOI to a paper | | get_paper_authors | List authors of a paper | | get_paper_citations | List papers that cite this one (optional year/date filter) | | get_paper_references | List the paper's bibliography (optional year/date filter) |

Source guide:

• semantic — Semantic Scholar. Best citation graph, broad coverage.
• openalex — OpenAlex. Richest metadata, full open-access coverage (~250M works).
• pubmed — PubMed/NCBI. Biomedical and life sciences only. Honors query, limit, offset, sort, year_from/year_to, date_from/date_to, venue; other filters are silently ignored.

Authors (2, OpenAlex)

| Tool | What it does | |---|---| | search_authors | Find authors by name; returns h-index, citations, ORCID, affiliations | | get_author_papers | Papers published by a specific author (optional year/date filter) |

Journals (9, Minicod proprietary database)

| Tool | What it does | |---|---| | search_journals | Keyword search with rich filters: impact factor range, SJR range, h-index range, JCR / Scimago / FQB (中科院分区) quartile, CCF rank, country, publisher, open access, predatory-journal warning, etc. | | get_journal | Fetch one journal by id, issn, or name | | list_journals | Paginated browse with sort + basic filters | | compare_journals | Side-by-side comparison of 2+ journals | | suggest_journals | Prefix autocomplete — slim suggestions for type-ahead UI | | journals_by_category | Paginated journals filtered by subject category (combine with list_categories) | | list_categories | Subject categories + journal counts, grouped by taxonomy source / level | | list_publishers | Publishers + journal counts (descending) | | list_countries | Country codes + journal counts (descending) |

The journal database aggregates 11 sources into a single record per journal: Crossref, OpenAlex, DOAJ, Wikidata, SCImago, JCR, FQB (中科院分区), CCF, GJQK (国际期刊预警), LetPub, SciRev.

Search best practices

The upstream APIs treat the query (or keyword) field as keyword AND-matching, not natural-language parsing. Cramming year / venue / author / quartile into the query string will return empty or wrong results. Always decompose the user's request into structured fields.

Papers — decomposition rules

| User says | Use this field, NOT query | |---|---| | "in 2023" / "from 2020 to 2023" | year_from, year_to | | Specific date range | date_from, date_to (YYYY-MM-DD) | | "in Nature" / "at NeurIPS" | venue | | "highly cited" / "≥1000 citations" | min_citations | | "open access only" | open_access: true | | Field of study ("medicine", "CS") | subjects: ["medicine"] | | Document type ("review", "article") | types: ["review"] | | An author's name | Call search_authors first → get_author_papers |

❌ query: "attention is all you need 2017 NeurIPS Vaswani highly cited" ✅ query: "attention mechanism transformer", year_from: 2017, year_to: 2017, venue: "NeurIPS", min_citations: 1000

Journals — decomposition rules

| User says | Use this field, NOT keyword | |---|---| | "Q1" / "Q2" journals | jcr_quartile, scimago_best_quartile, or fqb_quartile | | "CCF A" | ccf_rank: "A" | | "IF > 30" | min_impact_factor: 30 | | SJR / h-index thresholds | min_sjr / max_sjr / min_h_index / max_h_index | | ISSN known | issn | | Publisher / country | publisher, country | | "open access" | is_oa: "true" |

❌ keyword: "Nature Q1 IF>30 oncology UK" ✅ keyword: "oncology", jcr_quartile: "Q1", min_impact_factor: 30, country: "United Kingdom"

Billing

Every tool call hits the Minicod public API and consumes from your account's quota (daily / monthly limits per your plan, plus any purchased token packages). Manage keys, view usage, and top up at https://www.minicod.com/.

Docker

A Dockerfile is included so the server can ship as a self-contained image. The container runs the MCP server over stdio — there's no port to publish, so always run with -i.

Build

# from the project root, using the bundled docker-compose profile
docker-compose --profile mcp build mcp-server

# or directly with docker
cd mcp-server && docker build -t minicod-mcp:local .

Run

docker run -i --rm \
  -e MINICOD_API_KEY=sk-your-key \
  minicod-mcp:local

MCP client config using Docker (instead of npx)

{
  "mcpServers": {
    "minicod": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MINICOD_API_KEY",
        "minicod-mcp:local"
      ],
      "env": { "MINICOD_API_KEY": "sk-your-key" }
    }
  }
}

Pointing the container at a self-hosted backend

If you self-host Minicod via the project's docker-compose stack, the backend lives on the bridge network as backend:8080. To talk to it from a containerised MCP server:

# From host (use host.docker.internal to reach the host's published nginx port)
docker run -i --rm \
  -e MINICOD_API_KEY=sk-... \
  -e MINICOD_API_BASE_URL=http://host.docker.internal:4600/v1 \
  minicod-mcp:local

# From inside the same docker-compose network (uses the internal backend service DNS)
docker-compose --profile mcp run --rm mcp-server
# (the compose service sets MINICOD_API_BASE_URL=http://backend:8080/v1 by default)

Local development

git clone <this repo>
cd mcp-server
npm install
npm run build
MINICOD_API_KEY=sk-... node dist/index.js   # speaks MCP over stdio

Interactive testing with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

End-to-end tests

Two test harnesses live in test/:

| Script | What it covers | |---|---| | npm run test:e2e | Spawns the local dist/index.js, drives the full MCP handshake, calls every tool and validates response shape against a real backend. | | npm run test:e2e:docker | Same flow but spawns docker run -i --rm minicod-mcp:local, proving the published image speaks MCP and can reach the backend. |

Both expect a real sk-... key:

# Local (against a Minicod backend reachable on host)
MINICOD_API_KEY=sk-... \
MINICOD_API_BASE_URL=http://localhost:4600/v1 \
npm run test:e2e

# Docker (image must be built first)
MINICOD_API_KEY=sk-... npm run test:e2e:docker

Each tool call is classified PASS / UPSTREAM / FAIL. UPSTREAM means the backend correctly forwarded the call but the underlying data source (e.g. a third-party API) was unreachable — that is not a MCP-layer bug; only FAIL exits non-zero.

Releasing (maintainers)

Use the bundled release script — it does all preflight checks (registry, login, clean tree, name availability), builds, previews the tarball, then runs npm version + npm publish interactively (you input the 2FA OTP).

# First-time publish (uses current version in package.json, no bump)
npm run release:first

# Subsequent releases
npm run release patch    # 0.2.0 → 0.2.1  bug fix / doc tweak
npm run release minor    # 0.2.0 → 0.3.0  new tools / new params, backward-compatible
npm run release major    # 0.2.0 → 1.0.0  breaking change

# Specific version
npm run release 1.2.3

# Dry-run (does everything except publish + git push)
npm run release:dry

# Bypass clean working tree check (rarely needed)
npm run release patch -- --force

After a successful publish, push the bump commit + tag:

git push --follow-tags

The script automatically:

• switches your npm registry to the official one for publishing (and restores on exit if you were using a mirror like npmmirror.com)
• refuses if the target version already exists on npm
• refuses if the pack would include unexpected files (src/, test/, Dockerfile, etc.)
• creates a git commit + annotated tag vX.Y.Z (when in a git repo)

License

MIT