Sophotron

sopho- (σοφία, wisdom) + -tron (instrument) — a wisdom-instrument for philosophy research.

Sophotron is a tool for searching and retrieving philosophy papers, built for AI research assistants that need to ground themselves in the actual philosophical literature rather than the shallow, mis-classified philosophy slice of general academic databases. It is exposed today as an MCP server; a CLI and other frontends can sit on the same interface-agnostic core.

It combines four open sources, each doing what it does best:

Runs fully keyless. An optional Semantic Scholar API key raises rate limits; optional contact emails opt into the OpenAlex/Unpaywall "polite pool." No source requires registration.

Why four sources? Philosophy is under-served by general infrastructure: low open-access (~15%) and DOI-assignment (~60%) rates, canonical works predating DOIs, and systematic mis-classification (Rawls's A Theory of Justice tagged "Sociology" in Semantic Scholar; Heidegger's Being and Time with a null field). And as of 2026, the PhilPapers/PhilArchive web APIs sit behind Cloudflare bot-protection. OpenAlex + Unpaywall therefore supply the open-access PDFs an automated client can actually fetch, while a cached PhilArchive harvest adds philosophy-specific coverage.

Install

npm install
npm run build
npm run smoke   # optional: MCP stdio smoke test

Requires Node.js ≥ 22.

Related MCP server: academic-search-mcp

Configure

All configuration is optional — copy .env.example to .env and fill in what you want:

# Optional: raises Semantic Scholar rate limits (request at
# https://www.semanticscholar.org/product/api). Without it, S2 still works but
# rate-limits aggressively (HTTP 429) on its shared unauthenticated pool.
SEMANTIC_SCHOLAR_API_KEY=

# Optional: OpenAlex/Unpaywall "polite pool" contact (a courtesy id, not a key).
# OPENALEX_EMAIL=you@example.com
# UNPAYWALL_EMAIL=you@example.com

Advanced overrides (SOPHOTRON_OAI_ENDPOINT, SOPHOTRON_DATA_DIR, SOPHOTRON_LIBRARY_PATH) are documented in .env.example.

Use with an MCP client

Claude Code / any stdio MCP client (~/.claude/settings.json):

{
  "mcpServers": {
    "sophotron": {
      "command": "node",
      "args": ["/absolute/path/to/sophotron/dist/index.js"],
      "env": { "SEMANTIC_SCHOLAR_API_KEY": "optional" }
    }
  }
}

Claude Desktop / Cowork (MCPB bundle): a manifest.json is included. Pack it with the MCPB CLI and install the resulting .mcpb:

npx @anthropic-ai/mcpb pack

Tools

Taxonomy navigation (the discourse-cartographer layer)

The PhilPapers taxonomy is more than a list to browse: each category is treated as an inferred SPECTER2 region (a coordinate in embedding space, seeded from the category name), so you can navigate papers relative to a category. Pass a category_id (the id browse_taxonomy returns) to search_papers or get_related to rerank the results by proximity to that region, or call category_papers for influence-ranked papers near it.

This is a semantic lens over an inferred mapping, not a classification claim — results are tagged with relative proximity (nearer / farther / unplaceable), placement: "inferred", and an honest confidence tier (distinct for semantically-clear coarse categories, low for fine, catch-all, or thinly-seeded ones). Transient Semantic Scholar outages are reported as unavailable, never as a confident empty region.

PDF resolution (get_pdf)

Tries sources in order of reliability and stops at the first hit, reporting where the PDF came from and whether an automated client can fetch it:

1. Semantic Scholar openAccessPdf → agentFetchable: true

2. Unpaywall by DOI → agentFetchable: true

3. OpenAlex by DOI (or title search) → agentFetchable: true

4. PhilArchive best-effort URL → agentFetchable: false (philarchive.org is Cloudflare-walled to automated clients; open these in a browser)

// get_pdf { "paper_id": "10.1007/s11019-014-9560-2" }
{ "pdfUrl": "https://…/paper.pdf", "source": "unpaywall", "agentFetchable": true, "oaStatus": "green", … }

Cross-referencing (PhilArchive ↔ Semantic Scholar)

PhilArchive's OAI-PMH metadata omits DOIs, so papers are linked by fuzzy title + author matching (title 50% / author 35% / year 15%; accept > 0.85). Match results carry a confidence score so uncertain links can be reviewed.

Rate limits & access reality

Project structure

src/
├── index.ts                  # MCP server frontend (18 tools)
├── types.ts                  # shared types
├── adapters/                 # one module per external API; never throw to callers
│   ├── semantic-scholar.ts   # S2 Graph/Recommendations API (+ SPECTER2 embeddings)
│   ├── openalex.ts           # OpenAlex works + OA discovery
│   ├── unpaywall.ts          # DOI → OA PDF
│   ├── crossref-api.ts       # api.crossref.org DOI metadata fallback
│   ├── philarchive.ts        # PhilArchive/PhilPapers OAI-PMH + cache
│   └── taxonomy.ts           # PhilPapers category hierarchy (cached)
├── services/                 # cross-source logic
│   ├── crossref.ts           # S2 ↔ PhilArchive fuzzy cross-reference
│   ├── pdf-resolver.ts       # S2 → Unpaywall → OpenAlex → PhilArchive chain
│   ├── paper-download.ts     # download_paper / read_paper full-text store
│   ├── library.ts            # personal library (JSON-on-disk)
│   └── taxonomy-bridge.ts    # taxonomy→papers semantic bridge (inferred centroids)
└── utils/
    ├── fuzzy-match.ts         # title/author matching
    ├── vector.ts             # cosine / centroid / proximity ranking
    ├── rate-limit.ts         # serial rate limiter (S2 1 req/s)
    └── http.ts               # shared retry/backoff fetch

data/                         # philarchive-cache.json, crossref-cache.json, category-centroids.json (regenerable)
scripts/smoke-test.mjs        # MCP stdio smoke test (also runs in CI)

Develop

npm run build       # tsc (tsconfig.build.json — excludes tests/experiments)
npm run typecheck   # tsc --noEmit (full, incl. tests)
npm test            # vitest (set SKIP_INTEGRATION=true to skip live tests)
npm run smoke       # MCP stdio smoke test

Start with CONTRIBUTING.md; the operational guide (architecture, conventions, correctness contracts) is CLAUDE.md. Tests are the verification spine — every adapter has unit tests with mocked fetch, plus a network-gated integration suite.

License

MIT