cite-nexus-mcp 0.2.0__tar.gz

cite_nexus_mcp-0.2.0/.env.example

@@ -0,0 +1,25 @@
+# No credentials are needed for the default Crossref, DataCite and Europe PMC search.
+# CITE_NEXUS_CONTACT_EMAIL=researcher@university.edu
+# CITE_NEXUS_DEFAULT_PROVIDERS=crossref,datacite,europe_pmc
+
+# Optional graph APIs. A configured key does not add a provider to default searches.
+# SEMANTIC_SCHOLAR_API_KEY=
+# OPENALEX_API_KEY=
+
+# Optional commercial/institutional search.
+# SERPAPI_API_KEY=
+# SCOPUS_API_KEY=
+# SCOPUS_INSTTOKEN=
+# WOS_API_KEY=
+# Legacy SERP_API_KEY and SERPAPI_KEY are also accepted.
+
+# Optional open-access enrichment; Unpaywall requires an actual contact email.
+# UNPAYWALL_EMAIL=researcher@university.edu
+
+# Operational limits.
+# CITE_NEXUS_TIMEOUT=12
+# CITE_NEXUS_OPERATION_TIMEOUT=40
+# CITE_NEXUS_RETRIES=1
+# CITE_NEXUS_CONCURRENCY=6
+# CITE_NEXUS_CACHE_TTL=300
+# CITE_NEXUS_CACHE_SIZE=256

cite_nexus_mcp-0.2.0/.gitignore

@@ -0,0 +1,59 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Environment
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Virtualenv
+.uv/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Project specific
+OPT_PLAN.md
+plan.md
+CLAUDE.md
+
+# Test, lint and local configuration artifacts
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env.*
+!.env.example

cite_nexus_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.2.0 — 2026-09-17
+
+CiteNexus becomes a provider-independent scholarly metadata service with public API defaults.
+
+- Migrate to MCP Python SDK 2.2 and protocol 2026-07-28, preserving the legacy protocol path.
+- Add typed tools, output schemas, read-only annotations, resources, prompts and progress.
+- Add local Streamable HTTP alongside stdio, plus configuration discovery and explicit `.env` loading.
+- Add Crossref, DataCite, Europe PMC, arXiv, Semantic Scholar, OpenAlex, Scopus and Web of Science
+  Starter alongside the revised SerpAPI integration; add optional Unpaywall enrichment.
+- Introduce namespaced identifiers, exact lookup checks, provenance, retained source disagreements,
+  version-aware deduplication, native Europe PMC cursor paging and bounded provider requests.
+- Add deterministic BibTeX/RIS/CSL-JSON export, citation verification, bounded batch export,
+  open-access discovery and citation/reference traversal.
+- Correct the citation-count bug: provider totals replace citation-page lengths.
+- Remove automatic AI formatting, inferred bibliographic facts and the paid-provider startup requirement.
+- Move standalone legacy AI helpers to an optional extra; retain old MCP tool names and SerpAPI aliases.
+- Add offline provider fixtures, protocol integration tests, a separate public-API smoke script,
+  Python version CI, build configuration and a non-root stdio container definition.
+- Rewrite product positioning, configuration, migration and source-access documentation.
+- Integrate WTF-P's citation-search workflow through a bounded companion using real MCP stdio;
+  preserve candidates and source records, select vendors explicitly, and test timeout cleanup.
+- Add `cite-nexus-wtfp --check` and `--no-env-file` for reproducible client-managed configuration.
+- Prepare versioned registry and portable/Codex/Claude plugin metadata, a 41-channel marketplace
+  inventory, launch copy, icon/social assets, troubleshooting and agent installation guidance.
+
+No release publication or registry registration is performed by this change.

cite_nexus_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Install development dependencies with `uv sync --locked`. Before submitting changes, run the lint,
+type, test and build commands in the README. Tests must not require network access or account keys.
+Use `scripts/smoke_public.py` separately for explicit public API checks.
+
+## Architecture
+
+- `config.py` reads explicit settings; only the CLI loads `.env`.
+- `http.py` owns request limits, retries, pacing, response-size bounds, caching and sanitized failures.
+- `providers/` contains source-specific endpoints and normalization.
+- `models.py` defines public records and structured tool outputs.
+- `identifiers.py` parses namespaced identifiers without fetching arbitrary URLs.
+- `service.py` coordinates search, identity checks, source merging and research workflows.
+- `citations.py` formats observed metadata without a language model.
+- `server.py` exposes typed MCP tools, resources and prompts and manages the service lifecycle.
+
+Keep source-specific API behavior in its adapter. Changes to the research service should remain
+independent of MCP client implementation or transport. Keep output schemas accurate and preserve
+error distinctions; clients depend on the difference between no result and an unavailable source.
+
+## Adding a source
+
+Document the API's access tier, terms, authentication, request limits and paging model first.
+Implement the `Provider` interface, use the shared HTTP layer, and add it to the registry. A provider
+must declare only the operations it implements. Commercial access must be explicitly selected or
+configured as a default; setting credentials alone must not introduce automatic charges.
+
+Normalize native IDs, preserve provider URLs and counts, and identify incomplete author lists.
+Never map a snippet to a full abstract or a partial graph page to a citation total. Do not fabricate
+metadata to fill a schema. Search results may be candidates; exact resolution must verify the
+requested identifier against the returned record.
+
+Add realistic, non-sensitive fixtures for search, lookup and any supported graph operations.
+Cover pagination, missing values, auth/rate-limit failures and malformed records. Add a live check
+only as an explicit opt-in script, and distinguish fixture coverage from live account validation
+in the documentation. Avoid storing licensed payloads without redistribution permission.
+
+## Releases
+
+Keep the version in `pyproject.toml` and `cite_nexus_mcp.__version__` aligned, refresh `uv.lock`, and
+build both artifacts with `uv build`. Verify that the wheel and source archive contain no `.env`,
+credentials, local assistant configuration or manual user experiments. Validate an installed wheel
+outside the repository before publishing. The local HTTP CLI is not a multi-user deployment layer.

cite_nexus_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 akougkas.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cite_nexus_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.5
+Name: cite-nexus-mcp
+Version: 0.2.0
+Summary: Evidence-backed scholarly discovery and citation tools for MCP, from open metadata to institutional databases.
+Project-URL: Homepage, https://github.com/akougkas/cite-nexus-mcp
+Project-URL: Issues, https://github.com/akougkas/cite-nexus-mcp/issues
+Author-email: "akougkas.io (Anthony K)" <a.kougkas@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: anyio<5,>=4.9
+Requires-Dist: bibtexparser<2,>=1.4.3
+Requires-Dist: defusedxml<1,>=0.7.1
+Requires-Dist: httpx2<3,>=2.5
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: python-dotenv<2,>=1.1
+Provides-Extra: legacy-ai
+Requires-Dist: litellm<2,>=1.82.1; extra == 'legacy-ai'
+Requires-Dist: requests<3,>=2.32; extra == 'legacy-ai'
+Description-Content-Type: text/markdown
+
+# CiteNexus MCP
+
+<img src="https://raw.githubusercontent.com/akougkas/cite-nexus-mcp/v0.2.0/assets/cite-nexus.svg" alt="CiteNexus" width="88" height="88" align="right">
+
+**Scholarly discovery and citations with evidence you can trace.**
+
+CiteNexus connects research assistants to open scholarly metadata, specialist academic indexes,
+and optional commercial databases through the Model Context Protocol. Search without an API key,
+resolve stable identifiers, check references against their sources, and export citations without
+asking a language model to invent the missing fields.
+
+This is a citation and metadata service for the assistant you already use. It works alongside
+reference managers such as Zotero and writing environments that support MCP.
+
+**CiteNexus 0.2.0** includes the MCP service and the `cite-nexus-wtfp` companion.
+The WTF-P integration targets its separate 0.7.0 release. Marketplace listings and native
+client plugin qualification are tracked independently.
+
+[Quick start](#quick-start) · [WTF-P integration](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/wtf-p.md) ·
+[Provider guide](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/providers.md) · [Troubleshooting](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/troubleshooting.md) ·
+[Release information](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/release/README.md)
+
+- **Useful without credentials:** Crossref, DataCite and Europe PMC are the default search sources.
+  arXiv and Semantic Scholar are also available without mandatory keys.
+- **Optional specialist and commercial access:** OpenAlex, Google Scholar through SerpAPI,
+  Scopus and Web of Science Starter have explicit configuration and provider selection.
+- **Source-backed records:** namespaced identifiers, retrieval timestamps, field attribution,
+  incomplete-author warnings and provider-specific citation counts.
+- **Deterministic export:** BibTeX, RIS and CSL-JSON from retrieved metadata. No model is required.
+- **Current MCP:** Python SDK 2.2, the **2026-07-28** specification, structured tool results,
+  resources, prompts, progress, stdio and Streamable HTTP. Earlier clients remain supported by
+  the SDK's legacy protocol path.
+
+## Quick start
+
+Python 3.11+ and [uv](https://docs.astral.sh/uv/) are required.
+
+```bash
+uvx --from cite-nexus-mcp==0.2.0 cite-nexus-mcp --version
+uvx --from cite-nexus-mcp==0.2.0 cite-nexus-mcp --no-env-file --list-providers
+```
+
+For an MCP client with a `mcpServers` configuration:
+
+```json
+{
+  "mcpServers": {
+    "cite-nexus": {
+      "command": "uvx",
+      "args": ["--from", "cite-nexus-mcp==0.2.0", "cite-nexus-mcp", "--no-env-file"]
+    }
+  }
+}
+```
+
+The client starts MCP over stdio. No API key or `.env` file is required. Running the server
+command directly waits for a client; it is not an interactive search shell. If your client
+cannot find `uvx`, use its absolute executable path. The first run downloads the package and
+its dependencies.
+
+For a persistent installation, including the WTF-P companion:
+
+```bash
+uv tool install cite-nexus-mcp==0.2.0
+cite-nexus-wtfp --check
+```
+
+The diagnostic starts the actual MCP service and lists providers without querying vendor APIs.
+See the [WTF-P setup](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/wtf-p.md) for the separate integration and executable-path setting.
+
+For local HTTP clients:
+
+```bash
+uvx --from cite-nexus-mcp==0.2.0 cite-nexus-mcp --no-env-file --transport streamable-http --port 8000
+```
+
+Connect to `http://127.0.0.1:8000/mcp`. The CLI binds only to loopback and serves a single trust
+boundary. A public, multi-user deployment needs authentication, credential isolation and its
+own deployment integration; the CLI does not supply those features.
+
+## Sources and access
+
+| Provider ID | Coverage | Access | Setup |
+|---|---|---|---|
+| `crossref` | Publisher-deposited DOI metadata and citation counts | Free; default | Optional `CITE_NEXUS_CONTACT_EMAIL` for the polite pool |
+| `datacite` | Datasets, software and other DOI-registered research outputs | Free; default | None |
+| `europe_pmc` | Biomedical literature, PubMed/PMC records, references and citations | Free; default | None |
+| `arxiv` | Preprints in physics, mathematics, computing and related fields | Free | Select explicitly; paced to one request per three seconds |
+| `semantic_scholar` | Academic Graph discovery and citation traversal | Free/shared anonymous limits; optional key | Optional `SEMANTIC_SCHOLAR_API_KEY` |
+| `openalex` | Multidisciplinary research graph | Free credits / metered account access | `OPENALEX_API_KEY` |
+| `serpapi` | Google Scholar through a vendor API | Commercial; account allowances vary | `SERPAPI_API_KEY` |
+| `scopus` | Elsevier's curated literature index | Institutional/commercial entitlement | `SCOPUS_API_KEY`; optional `SCOPUS_INSTTOKEN` |
+| `wos` | Clarivate Web of Science Starter | Institutional/commercial entitlement | `WOS_API_KEY` |
+
+`find-open-access` can additionally enrich DOI records with **Unpaywall** when
+`UNPAYWALL_EMAIL` is configured. It returns reported legal OA locations and licensing information;
+it does not download PDFs or bypass access restrictions.
+
+Free access is subject to provider rate limits and terms. Anonymous Semantic Scholar can be
+heavily throttled. OpenAlex access policies have changed over time; CiteNexus requires a key for
+that adapter even when an anonymous request happens to succeed. Institution keys do not by
+themselves guarantee subscription access or access outside an institution's network.
+
+Commercial and metered adapters are called only when selected explicitly, when resolving their
+own namespaced IDs, or when deliberately configured as search defaults. Setting a key alone does
+not add a vendor to default searches. `list-providers` reports configuration, capabilities and
+documentation links without testing access or revealing key values.
+
+## Research workflows
+
+Use CiteNexus to build a literature shortlist, repair an uncertain reference, check the source
+behind a citation count, or prepare a bibliography for your writing tool. For a full writing
+workflow, the [WTF-P companion](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/wtf-p.md) connects discovery to evidence tables, outlines
+and manuscript work while keeping candidate references visible for review.
+
+Ask your assistant to use the tools directly, or start with the `literature-review` and
+`bibliography-audit` MCP prompts. Example tool arguments:
+
+```json
+{"query": "reproducible machine learning benchmarks", "providers": ["crossref", "arxiv"], "limit": 5}
+```
+
+```json
+{"identifier": "10.1038/nature14539", "format": "bibtex"}
+```
+
+```json
+{"citation": "10.1038/nature14539", "expected_title": "Deep learning", "expected_year": 2015}
+```
+
+```json
+{"identifier": "PMID:26017442", "direction": "references", "provider": "europe_pmc", "limit": 10}
+```
+
+```json
+{"identifiers": ["10.1038/nature14539", "arxiv:1706.03762"], "format": "csl-json"}
+```
+
+| Tool | Purpose |
+|---|---|
+| `list-providers` | Inspect source capabilities, access tiers and credential configuration |
+| `search-papers` | Concurrent federated search, conservative deduplication and per-source pagination |
+| `resolve-paper` | Retrieve and validate a DOI or namespaced identifier; optionally merge selected sources |
+| `get-citation` | Export one resolved record as `bibtex`, `ris` or `csl-json` |
+| `verify-citation` | Check an identifier or single BibTeX entry, including supplied title and year |
+| `batch-citations` | Resolve and export 1–20 identifiers with ordered results, partial failures and progress |
+| `related-papers` | Page through a source's citations or references |
+| `paper-metrics` | Return observed citation counts, separated by provider and index |
+| `find-open-access` | Find source-reported OA locations, with optional Unpaywall enrichment |
+| `enhance-citation` | Normalize BibTeX formatting while preserving supplied bibliographic facts |
+| `find-scholar-id` | Legacy Scholar discovery through SerpAPI; returns candidates for review |
+
+`search-papers` defaults to 10 results **per provider**, not 10 overall. Results interleave each
+provider's ranking, then merge compatible records. `limit` is 1–50, or at most 20 when using
+SerpAPI. Use each provider's `next_offsets` with the **same limit**, selecting that provider for
+the next call. Europe PMC search uses `next_cursors` instead: pass its token as `cursor`,
+select only `europe_pmc`, keep the same query and limit, and leave `offset` at zero.
+Offsets must be multiples of the limit, up to 10,000. `year_from`, `year_to` and
+`open_access_only` filter the fetched page; unknown values are excluded. Abstracts are omitted
+from search results by default; set `include_abstract: true` or resolve a record to retrieve them.
+Provider search languages differ: explicit advanced queries use that provider's syntax.
+
+Supported identifiers include `10.1038/nature14539`, `arxiv:1706.03762`, `PMID:26017442`,
+`PMC12345`, `openalex:W2919115771`, `s2:<paperId>`, `s2:CorpusId:<number>`,
+`scholar:<numericClusterId>`, `scopus:<numericId>`, and `WOS:<recordId>`. DOI, arXiv and PubMed
+URLs are recognized. Arbitrary URLs are not fetched, and unprefixed numeric strings are not
+assumed to be PubMed or Scholar IDs.
+
+DOI resolution tries Crossref, DataCite and Europe PMC in order until a matching record is
+retrieved. An explicit `providers` list instead checks each compatible selected source and
+retains evidence and disagreements. Native identifiers route to their corresponding source.
+A title search always returns candidates; it never silently declares the first result a match.
+
+Read the MCP resources `cite-nexus://methodology`, `cite-nexus://providers` and
+`cite-nexus://workflows` for machine-accessible guidance.
+
+## What “verified” means
+
+Verification establishes that an identifier exists in retrieved metadata and checks any supplied
+title and year. It does **not** establish that a paper's findings are correct, that every author
+is present, that the paper supports a specific claim, or that no retraction exists. A provider
+outage produces `unavailable`, rather than a claim that the citation is fabricated.
+
+Exports omit unavailable metadata. Partial author lists generate warnings; BibTeX uses `others`
+where appropriate. Citation counts retain their source, index and observation timestamp and are
+never summed across databases. Counts from different providers are not directly interchangeable.
+Metadata can contain errors or conflicting publication years, and an absent retraction flag is
+not proof that a paper is unretracted.
+
+CSL-JSON is structured bibliographic data. Use a CSL processor or your reference manager to render
+APA, IEEE or a journal's house style. `enhance-citation` supports `default` and `compact` formatting;
+it does not infer keywords, awards, impact factors or missing authors.
+
+## Configuration
+
+Copy `.env.example` to `.env` only if you need optional settings. Existing process environment
+variables take precedence. The CLI loads `./.env`, or an explicit `--env-file`; it never searches
+parent directories. Importing the Python package does not read `.env` or call external services.
+Pass `--no-env-file` for clients that manage credentials themselves. The WTF-P companion and
+plugin manifests always use this mode.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `CITE_NEXUS_DEFAULT_PROVIDERS` | `crossref,datacite,europe_pmc` | Explicit search source IDs, comma separated |
+| `CITE_NEXUS_TIMEOUT` | `12` | Timeout in seconds for each HTTP request |
+| `CITE_NEXUS_OPERATION_TIMEOUT` | `40` | Time budget for a provider operation or identifier resolution |
+| `CITE_NEXUS_RETRIES` | `1` | Retries for transport failures, HTTP 429 and 5xx responses |
+| `CITE_NEXUS_CONCURRENCY` | `6` | Maximum simultaneous outbound requests |
+| `CITE_NEXUS_CACHE_TTL` | `300` | In-process response-cache lifetime in seconds; `0` disables it |
+| `CITE_NEXUS_CACHE_SIZE` | `256` | Maximum cached responses; `0` disables caching |
+
+Cached records retain their original retrieval and citation-observation timestamps. The cache is
+bounded and partitions responses by credentials. Responses larger than 8 MB are rejected. Long
+`Retry-After` cooldowns return a provider issue instead of holding the call open. Keys and upstream
+error bodies are excluded from tool errors. Local stderr logging keeps stdout clean for MCP.
+
+See [provider details](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/providers.md), [migration notes](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/migration.md), and
+[product direction](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/product-direction.md) for access nuances and boundaries.
+
+## Development and verification
+
+To work from source:
+
+```bash
+git clone https://github.com/akougkas/cite-nexus-mcp.git
+cd cite-nexus-mcp
+uv sync --locked
+uv run ruff check src tests scripts
+uv run ruff format --check src tests scripts
+uv run mypy src/cite_nexus_mcp
+uv run python scripts/prepare_release.py --check
+uv run python scripts/marketplaces.py --check
+uv run pytest -q
+uv build
+```
+
+The automated suite uses synthetic provider fixtures and mock HTTP, plus real local stdio and
+Streamable HTTP processes. It requires no vendor credentials and blocks external network access
+from the test process. Paid and institutional adapters have fixture-based contract coverage;
+live entitlement testing requires an account with access.
+
+An explicit public-API smoke test is available separately:
+
+```bash
+uv run python scripts/smoke_public.py
+```
+
+It ignores account credentials and only contacts Crossref, DataCite, Europe PMC, arXiv and
+anonymous Semantic Scholar. Rate limits and network failures are reported as outcomes.
+
+The official MCP Tasks extension is not advertised. SDK 2.2 does not implement it yet.
+`batch-citations` is a bounded synchronous workflow with progress and cancellation, not a durable
+job queue. [The roadmap](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/product-direction.md) describes the criteria for adding persistent
+tasks, local libraries and further licensed providers.
+
+The [launch kit](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/release/launch-kit.md) includes positioning, listing copy, a demo script,
+and promotional drafts. The [marketplace inventory](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/release/marketplaces.md) tracks 41
+channels and leads, including verified routes, duplicate channels and inactive or unresolved
+sites. Source metadata, portable plugin manifests and image assets are prepared for review.
+See [data handling](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/docs/data-handling.md) before configuring optional providers or hosting.
+
+## License
+
+[MIT](https://github.com/akougkas/cite-nexus-mcp/blob/v0.2.0/LICENSE). Provider content, API access and redistribution remain subject to each source's terms.
+
+<!-- mcp-name: io.github.akougkas/cite-nexus-mcp -->