Paper Scoring MCP

MCP v2 transport adapter for paper-scoring-core. It accepts normalized paper content, invokes an explicitly configured assessment connector, and returns the versioned core ScoreResult schema.

Install

Choose the provider extra needed at runtime:

python -m pip install "paper-scoring-mcp[openai]==0.1.0"

On Windows, the equivalent command is:

py -m pip install "paper-scoring-mcp[openai]==0.1.0"

The ollama, openalex, and all extras are also available. Dependencies between Paper Scoring repositories are normal PyPI requirements; no Git or filesystem dependency is embedded in the distribution.

Runtime configuration

Configuration is read only when the executable starts. Importing the package does not read .env or process environment values. Pass a UTF-8 file explicitly when dotenv injection is wanted:

paper-scoring-mcp --env-file .env --transport stdio

Existing process values take precedence over values in the file. The --env-file loader accepts only the keys shown in .env.example, which prevents an accidental dotenv file from changing unrelated process behavior. Never commit a populated .env file.

Transports

STDIO is suitable for local agent clients and keeps diagnostic logging on stderr so stdout remains an MCP protocol channel:

paper-scoring-mcp --env-file .env --transport stdio

Streamable HTTP exposes the MCP endpoint at /mcp:

paper-scoring-mcp --env-file .env --transport streamable-http \
  --host 127.0.0.1 --port 8000

PowerShell uses the same executable without shell-specific syntax:

paper-scoring-mcp --env-file .env --transport streamable-http --host 127.0.0.1 --port 8000

DNS-rebinding protection is always enabled. A wildcard bind accepts only loopback Host values by default. For a deliberate reverse-proxy deployment, repeat --allowed-host and --allowed-origin with the exact public values. The server does not provide authentication, so keep it on loopback or place it behind an authenticated reverse proxy.

The server exposes health, get_scoring_contract, and score_paper. source_url is treated as paper metadata; the MCP adapter never fetches a URL or accepts a local filesystem path.

Docker Compose

Docker Compose injects the selected environment file at container start. The published port is loopback-only, the root filesystem is read-only, Linux capabilities are dropped, and the image runs as an unprivileged user. Runtime Python dependencies are exported from uv.lock, hash-verified, and installed from public PyPI during the image build.

cp .env.example .env
docker compose up --build

To select a different runtime file without copying it into the image:

PAPER_SCORING_ENV_FILE=/absolute/path/runtime.env docker compose up --build

In PowerShell:

$env:PAPER_SCORING_ENV_FILE = "C:\\secure\\paper-scoring.env"
docker compose up --build