scholar-feed-mcp: Instructions file for Claude Code

Scholar Feed MCP — Project Instructions

The official MCP server for Scholar Feed (600k+ CS/AI/ML papers). Published to npm as scholar-feed-mcp and hosted remotely at https://mcp.scholarfeed.org/mcp.

Deep dev/release detail lives in CONTRIBUTING.md and .local-docs/ — this file is the load-bearing guardrails. When they conflict, fix the drift.

This repo is PUBLIC. Internal specs, handoffs, runbooks, and launch/distribution material go in .local-docs/ (gitignored), never in a tracked path. Only user-facing docs — README.md, CONTRIBUTING.md — are published.

What this repo is (and isn't)

• A thin MCP client. It exposes tools (search, citations, lineage, library, watches, …) and forwards to the real backend, which is a SEPARATE repo (../scholar-feed, FastAPI on Heroku
  • Supabase). Client tools routinely ship ahead of the backend routes they call — a tool can exist here before its endpoint is live in prod.
• Do not put business logic, DB access, or scoring here. If a tool needs new data, the change is usually a backend serializer/route in ../scholar-feed, then a thin tool here.

Architecture — three transports, one tool set

Tools live in src/tools/ (one file per tool, registered in src/tools/index.ts). src/client.ts is the backend API wrapper (auth + error handling).

🔴 Hard rules

• Publishing is AUTOMATED — never run npm publish by hand. publish.yml publishes on a pushed v* tag via npm OIDC trusted-publishing (no token, with provenance). Release from main: npm version <patch|minor|major> then git push --follow-tags — the tag push IS the publish. (Assistant may prepare the bump+tag; the human pushes.) See CONTRIBUTING.md → Releasing.
• All logging to stderr (console.error). console.log() corrupts the JSON-RPC stdio transport and silently breaks the client.
• Keep the package self-contained: dependencies must stay {}. tsup bundles everything (deps → devDeps) so cold-start npx is ~1 pkg / 0 transitive installs. Adding a runtime dep re-introduces the cold-start timeout that shipped as a silent "failed to connect".
• The remote endpoint is src/worker.ts (Cloudflare), not the Express server. The historical trap here was Vercel zero-config auto-detecting the stdio bin and 500'ing the endpoint for two days, which vercel.json existed to prevent. Vercel is fully gone as of 2026-07-30: the account was cancelled, vercel.json is deleted, and the GitHub integration is uninstalled (it had been red-failing every PR with "deployment blocked"). If a Vercel check ever reappears on a PR, the app got reinstalled — uninstall it rather than re-adding config. src/server.ts / src/server-http.ts still back npm run dev:http for local HTTP testing — don't delete them, but don't expect them to serve prod. SF_MCP_ALLOWED_HOSTS is required for any non-loopback deploy: unset = loopback-only, which rejects every real request. Never set SF_API_KEY on the remote surface (cross-tenant leak — each request derives its own key from the Authorization header).