Metadata-Version: 2.4
Name: scholarly-gateway-mcp
Version: 0.2.2
Summary: A deterministic, reusable MCP substrate for scholarly publication retrieval.
Author-email: "Curtis D. Williams" <curtis.williams@asu.edu>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp
Requires-Dist: httpx
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# scholarly-gateway-mcp

[![CI](https://github.com/curtis-d-williams/scholarly-gateway-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/curtis-d-williams/scholarly-gateway-mcp/actions/workflows/ci.yml)

A reusable MCP (Model Context Protocol) server that provides a deterministic, provenance-aware gateway to scholarly publication sources. The V1 contract is frozen; behavior and tool schemas are stable and will not change without an explicit contract revision.

## Start here

- [Integration Guide](docs/INTEGRATION_GUIDE.md) — what this server is, quickstart, canonical tool call patterns, provider_status interpretation, and a reproducibility checklist
- [Examples](docs/EXAMPLES.md) — three canonical workflows: single-provider lookup, multi-provider query with not_supported handling, and re-run determinism verification
- [Troubleshooting](docs/TROUBLESHOOTING.md) — top failure modes with contract-aligned resolution steps

## V1 Contract
Authoritative spec: [docs/V1_CONTRACT.md](docs/V1_CONTRACT.md)

## Governance
- [CONTRIBUTING.md](CONTRIBUTING.md) — PR types, determinism rules, contract rule, and how to propose new features
- [docs/GOVERNANCE.md](docs/GOVERNANCE.md) — authority model, change control, versioning doctrine, and release checklist

## Setup (dev)

    python3 -m venv .venv
    source .venv/bin/activate
    pip install -U pip
    pip install -e ".[dev]"
    pytest -q

## Install

For local development (editable install):

    pip install -e ".[dev]"

For a regular install:

    pip install .

## Run

    scholarly-gateway

## Configuration

Environment variables:

- SCHOLARLY_GATEWAY_DB_PATH (optional): path to SQLite DB file used for cross-session lookup persistence.
  - Default: ./.data/scholarly_gateway.db
