crossref-local 0.4.0__tar.gz → 0.5.0__tar.gz

crossref_local-0.5.0/.env.example

@@ -0,0 +1,57 @@
+# CrossRef Local Configuration
+# Copy this file to .env and customize as needed
+
+# =============================================================================
+# LOCAL MODE - Direct database access
+# =============================================================================
+
+# Path to CrossRef SQLite database (optional - auto-detected if not set)
+# CROSSREF_LOCAL_DB=/path/to/crossref.db
+
+# =============================================================================
+# DEVELOPMENT / DEBUGGING
+# =============================================================================
+
+# Enable debug mode for verbose logging
+# CROSSREF_LOCAL_DEBUG_MODE=1
+
+# Cache directory (default: ~/.cache/crossref-local)
+# CROSSREF_LOCAL_CACHE_DIR=/path/to/cache
+
+# =============================================================================
+# REMOTE MODE - HTTP API access (via SSH tunnel or direct connection)
+# =============================================================================
+
+# Force remote mode (set to "remote" or "local")
+# CROSSREF_LOCAL_MODE=remote
+
+# API URL for remote mode (default: http://localhost:31291)
+# CROSSREF_LOCAL_API_URL=http://localhost:31291
+
+# Server host/port (for run-server-http)
+# CROSSREF_LOCAL_HOST=0.0.0.0
+# CROSSREF_LOCAL_PORT=31291
+
+# =============================================================================
+# SCITEX INTEGRATION (takes priority over CROSSREF_LOCAL_* variables)
+# =============================================================================
+# Port scheme: 3129X (31290: scitex-cloud, 31291: crossref, 31292: openalex)
+#
+# SCITEX_SCHOLAR_CROSSREF_DB=/path/to/crossref.db
+# SCITEX_SCHOLAR_CROSSREF_MODE=remote
+# SCITEX_SCHOLAR_CROSSREF_HOST=0.0.0.0
+# SCITEX_SCHOLAR_CROSSREF_PORT=31291
+
+# =============================================================================
+# TYPICAL SSH TUNNEL SETUP
+# =============================================================================
+# 1. Create SSH tunnel to your database server:
+#    ssh -L 31291:127.0.0.1:31291 your-nas-server
+#
+# 2. Set environment variables:
+#    export CROSSREF_LOCAL_MODE=remote
+#    export CROSSREF_LOCAL_API_URL=http://localhost:31291
+#
+# 3. Or use CLI flags:
+#    crossref-local --http search "machine learning"
+#    crossref-local --api-url http://localhost:31291 search "query"

{crossref_local-0.4.0 → crossref_local-0.5.0}/.github/workflows/test.yml

@@ -35,10 +35,10 @@ jobs:
           pytest tests/ -v --tb=short --cov=crossref_local --cov-report=term-missing --cov-report=xml
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v4
         if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v4
         with:
-          file: ./coverage.xml
+          files: ./coverage.xml
           fail_ci_if_error: false
 
       - name: Test CLI

{crossref_local-0.4.0 → crossref_local-0.5.0}/.gitignore

@@ -132,6 +132,7 @@ data/*
 **/*.ppt
 **/*.pptx
 **/*.txt
+!docs/sphinx/requirements.txt
 **/*.log
 **/*.db
 **/*.sqlite

crossref_local-0.5.0/.readthedocs.yaml

@@ -0,0 +1,31 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/sphinx" directory with Sphinx
+sphinx:
+  configuration: docs/sphinx/conf.py
+  fail_on_warning: false
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+  - epub
+
+# Python configuration
+python:
+  install:
+    # Install package with all optional dependencies
+    - method: pip
+      path: .
+      extra_requirements:
+        - all
+    # Install sphinx documentation requirements
+    - requirements: docs/sphinx/requirements.txt

{crossref_local-0.4.0 → crossref_local-0.5.0}/CHANGELOG.md

@@ -5,25 +5,44 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.4.0] - 2026-01-22
+## [0.4.0] - 2026-01-24
 
 ### Added
+- **Collections API** - HTTP endpoints for paper collections (`/collections/*`)
+  - CRUD operations: list, create, query, delete
+  - Download as JSON, CSV, BibTeX, or DOIs
+  - Statistics endpoint for collection analytics
+- **Citation HTTP endpoints** - RESTful citation access
+  - `GET /citations/{doi}/citing` - Papers citing this DOI
+  - `GET /citations/{doi}/cited` - Papers cited by this DOI
+  - `GET /citations/{doi}/count` - Citation count
+  - `GET /citations/{doi}/network` - Citation network graph
+- **Multi-tenant support** - X-User-ID header for collection scoping
+- **Security hardening**
+  - Path traversal protection via name sanitization
+  - Input validation with field whitelist (14 allowed fields)
+  - Size limits: MAX_LIMIT=10000, MAX_DOIS=1000
 - Shell completion command (`crossref-local completion bash/zsh/fish/install/status`)
-- Paper cache module for efficient collection management (`crossref-local cache`)
+- Paper cache module for efficient collection management
 - MCP subcommand group (`crossref-local mcp {start,doctor,installation,list-tools}`)
 - `--help-recursive` option for complete CLI help
 - Remote deployment docs with systemd and Docker examples
 - Automated MCP server installation via Makefile
+- RemoteClient collection methods mixin
 
 ### Changed
+- Default port changed from 8333 to 31291 (SCITEX convention)
+- Server refactored into modular package (`server/`)
 - Reorganized CLI commands for better clarity
 - Improved MCP tools alignment with CLI commands
+- SCITEX environment variables supported with fallback chain
 - Examples renamed to follow numbered convention (04_mcp_demo)
 - Updated .env.example with all environment variables
 
 ### Fixed
 - Remote client `get_many` batch response includes citation_count
 - CI workflow now includes pytest-cov for coverage reporting
+- Circular import between cache.py and cache_export.py
 
 ## [0.3.1] - 2026-01-14
 

{crossref_local-0.4.0 → crossref_local-0.5.0}/Makefile

@@ -137,39 +137,7 @@ help: ## Show this help
 ##@ Status & Information
 
 status: ## Show overall system status (run this first!)
-	@echo "╔════════════════════════════════════════════════════════════╗"
-	@echo "║           CROSSREF LOCAL - STATUS                         ║"
-	@echo "╚════════════════════════════════════════════════════════════╝"
-	@echo ""
-	@echo "=== Database ==="
-	@if [ -f "$(DB_PATH)" ]; then \
-		echo "  ✓ Database exists: $(DB_PATH)"; \
-		echo "  Size: $$(du -h "$(DB_PATH)" | cut -f1)"; \
-	else \
-		echo "  ✗ Database NOT FOUND: $(DB_PATH)"; \
-		echo "    Hint: Check data symlink or run 'make download'"; \
-	fi
-	@echo ""
-	@echo "=== MCP Server ==="
-	@$(SCRIPTS)/mcp/status.sh
-	@echo "=== NFS Server ==="
-	@$(SCRIPTS)/nfs/check.sh
-	@echo ""
-	@echo "=== Running Processes ==="
-	@ps aux | grep -E "(rebuild_citations|build_fts|sqlite3)" | grep -v grep | head -5 || echo "  No database processes running"
-	@echo ""
-	@echo "=== Screen Sessions ==="
-	@screen -ls 2>/dev/null | grep -E "(citations|fts|rebuild)" || echo "  No relevant screen sessions"
-	@echo ""
-	@echo "=== Quick Stats ==="
-	@if [ -f "$(DB_PATH)" ]; then \
-		echo "  Works:     $$(sqlite3 "$(DB_PATH)" "SELECT stat FROM sqlite_stat1 WHERE tbl='works' LIMIT 1;" 2>/dev/null | cut -d' ' -f1 || echo '?')"; \
-		echo "  Citations: $$(sqlite3 "$(DB_PATH)" "SELECT MAX(rowid) FROM citations;" 2>/dev/null || echo '?')"; \
-	fi
-	@echo ""
-	@echo "For detailed database info: make db-info"
-	@echo "For MCP server: make mcp-status"
-	@echo "For NFS details: make nfs-status"
+	@$(SCRIPTS)/status.sh
 
 db-info: ## Show database tables, indices, and row counts
 	@$(SCRIPTS)/database/99_db_info.sh
@@ -264,13 +232,13 @@ maintain-indices: ## Analyze and optimize indices
 ##@ MCP Server (Remote Access)
 
 mcp-install: ## Install MCP server as systemd service
-	@$(SCRIPTS)/mcp/install.sh $(if $(DB),--db $(DB),) $(if $(PORT),--port $(PORT),)
+	@$(SCRIPTS)/deployment/mcp/install.sh $(if $(DB),--db $(DB),) $(if $(PORT),--port $(PORT),)
 
 mcp-uninstall: ## Remove MCP systemd service
-	@$(SCRIPTS)/mcp/install.sh --uninstall
+	@$(SCRIPTS)/deployment/mcp/install.sh --uninstall
 
 mcp-status: ## Show MCP server status
-	@$(SCRIPTS)/mcp/status.sh
+	@$(SCRIPTS)/deployment/mcp/status.sh
 
 mcp-start: ## Start MCP server
 	@sudo systemctl start crossref-mcp

{crossref_local-0.4.0 → crossref_local-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crossref-local
-Version: 0.4.0
+Version: 0.5.0
 Summary: Local CrossRef database with 167M+ works and full-text search
 Project-URL: Homepage, https://github.com/ywatanabe1989/crossref_local
 Project-URL: Repository, https://github.com/ywatanabe1989/crossref_local
@@ -18,6 +18,7 @@ Classifier: Topic :: Database
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
 Provides-Extra: all
 Requires-Dist: fastapi>=0.100; extra == 'all'
 Requires-Dist: fastmcp>=0.4; extra == 'all'
@@ -53,7 +54,10 @@ Description-Content-Type: text/markdown
 
 Local CrossRef database with 167M+ scholarly works, full-text search, and impact factor calculation.
 
+[![PyPI version](https://badge.fury.io/py/crossref-local.svg)](https://badge.fury.io/py/crossref-local)
+[![Documentation](https://readthedocs.org/projects/crossref-local/badge/?version=latest)](https://crossref-local.readthedocs.io/en/latest/)
 [![Tests](https://github.com/ywatanabe1989/crossref-local/actions/workflows/test.yml/badge.svg)](https://github.com/ywatanabe1989/crossref-local/actions/workflows/test.yml)
+[![Coverage](https://codecov.io/gh/ywatanabe1989/crossref-local/branch/main/graph/badge.svg)](https://codecov.io/gh/ywatanabe1989/crossref-local)
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
@@ -181,34 +185,46 @@ Found 4 matches in 128.4ms
 
 Start the FastAPI server:
 ```bash
-crossref-local run-server-http --host 0.0.0.0 --port 8333
+crossref-local relay --host 0.0.0.0 --port 31291
 ```
 
 Endpoints:
 ```bash
 # Search works (FTS5)
-curl "http://localhost:8333/works?q=CRISPR&limit=10"
+curl "http://localhost:31291/works?q=CRISPR&limit=10"
 
 # Get by DOI
-curl "http://localhost:8333/works/10.1038/nature12373"
+curl "http://localhost:31291/works/10.1038/nature12373"
 
 # Batch DOI lookup
-curl -X POST "http://localhost:8333/works/batch" \
+curl -X POST "http://localhost:31291/works/batch" \
   -H "Content-Type: application/json" \
   -d '{"dois": ["10.1038/nature12373", "10.1126/science.aax0758"]}'
 
+# Citation endpoints
+curl "http://localhost:31291/citations/10.1038/nature12373/citing"
+curl "http://localhost:31291/citations/10.1038/nature12373/cited"
+curl "http://localhost:31291/citations/10.1038/nature12373/count"
+
+# Collection endpoints
+curl "http://localhost:31291/collections"
+curl -X POST "http://localhost:31291/collections" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my_papers", "query": "CRISPR", "limit": 100}'
+curl "http://localhost:31291/collections/my_papers/download?format=bibtex"
+
 # Database info
-curl "http://localhost:8333/info"
+curl "http://localhost:31291/info"
 ```
 
 HTTP mode (connect to running server):
 ```bash
 # On local machine (if server is remote)
-ssh -L 8333:127.0.0.1:8333 your-server
+ssh -L 31291:127.0.0.1:31291 your-server
 
 # Python client
 from crossref_local import configure_http
-configure_http("http://localhost:8333")
+configure_http("http://localhost:31291")
 
 # Or via CLI
 crossref-local --http search "CRISPR"
@@ -221,7 +237,7 @@ crossref-local --http search "CRISPR"
 
 Run as MCP (Model Context Protocol) server:
 ```bash
-crossref-local run-server-mcp
+crossref-local mcp start
 ```
 
 Local MCP client configuration:
@@ -230,7 +246,7 @@ Local MCP client configuration:
   "mcpServers": {
     "crossref-local": {
       "command": "crossref-local",
-      "args": ["run-server-mcp"],
+      "args": ["mcp", "start"],
       "env": {
         "CROSSREF_LOCAL_DB": "/path/to/crossref.db"
       }
@@ -242,7 +258,7 @@ Local MCP client configuration:
 Remote MCP via HTTP (recommended):
 ```bash
 # On server: start persistent MCP server
-crossref-local run-server-mcp -t http --host 0.0.0.0 --port 8082
+crossref-local mcp start -t http --host 0.0.0.0 --port 8082
 ```
 ```json
 {
@@ -254,12 +270,21 @@ crossref-local run-server-mcp -t http --host 0.0.0.0 --port 8082
 }
 ```
 
+Diagnose setup:
+```bash
+crossref-local mcp doctor        # Check dependencies and database
+crossref-local mcp list-tools    # Show available MCP tools
+crossref-local mcp installation  # Show client config examples
+```
+
 See [docs/remote-deployment.md](docs/remote-deployment.md) for systemd and Docker setup.
 
 Available tools:
 - `search` - Full-text search across 167M+ papers
 - `search_by_doi` - Get paper by DOI
+- `enrich_dois` - Add citation counts and references to DOIs
 - `status` - Database statistics
+- `cache_*` - Paper collection management
 
 </details>
 

{crossref_local-0.4.0 → crossref_local-0.5.0}/README.md

@@ -8,7 +8,10 @@
 
 Local CrossRef database with 167M+ scholarly works, full-text search, and impact factor calculation.
 
+[![PyPI version](https://badge.fury.io/py/crossref-local.svg)](https://badge.fury.io/py/crossref-local)
+[![Documentation](https://readthedocs.org/projects/crossref-local/badge/?version=latest)](https://crossref-local.readthedocs.io/en/latest/)
 [![Tests](https://github.com/ywatanabe1989/crossref-local/actions/workflows/test.yml/badge.svg)](https://github.com/ywatanabe1989/crossref-local/actions/workflows/test.yml)
+[![Coverage](https://codecov.io/gh/ywatanabe1989/crossref-local/branch/main/graph/badge.svg)](https://codecov.io/gh/ywatanabe1989/crossref-local)
 [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
 
@@ -136,34 +139,46 @@ Found 4 matches in 128.4ms
 
 Start the FastAPI server:
 ```bash
-crossref-local run-server-http --host 0.0.0.0 --port 8333
+crossref-local relay --host 0.0.0.0 --port 31291
 ```
 
 Endpoints:
 ```bash
 # Search works (FTS5)
-curl "http://localhost:8333/works?q=CRISPR&limit=10"
+curl "http://localhost:31291/works?q=CRISPR&limit=10"
 
 # Get by DOI
-curl "http://localhost:8333/works/10.1038/nature12373"
+curl "http://localhost:31291/works/10.1038/nature12373"
 
 # Batch DOI lookup
-curl -X POST "http://localhost:8333/works/batch" \
+curl -X POST "http://localhost:31291/works/batch" \
   -H "Content-Type: application/json" \
   -d '{"dois": ["10.1038/nature12373", "10.1126/science.aax0758"]}'
 
+# Citation endpoints
+curl "http://localhost:31291/citations/10.1038/nature12373/citing"
+curl "http://localhost:31291/citations/10.1038/nature12373/cited"
+curl "http://localhost:31291/citations/10.1038/nature12373/count"
+
+# Collection endpoints
+curl "http://localhost:31291/collections"
+curl -X POST "http://localhost:31291/collections" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my_papers", "query": "CRISPR", "limit": 100}'
+curl "http://localhost:31291/collections/my_papers/download?format=bibtex"
+
 # Database info
-curl "http://localhost:8333/info"
+curl "http://localhost:31291/info"
 ```
 
 HTTP mode (connect to running server):
 ```bash
 # On local machine (if server is remote)
-ssh -L 8333:127.0.0.1:8333 your-server
+ssh -L 31291:127.0.0.1:31291 your-server
 
 # Python client
 from crossref_local import configure_http
-configure_http("http://localhost:8333")
+configure_http("http://localhost:31291")
 
 # Or via CLI
 crossref-local --http search "CRISPR"
@@ -176,7 +191,7 @@ crossref-local --http search "CRISPR"
 
 Run as MCP (Model Context Protocol) server:
 ```bash
-crossref-local run-server-mcp
+crossref-local mcp start
 ```
 
 Local MCP client configuration:
@@ -185,7 +200,7 @@ Local MCP client configuration:
   "mcpServers": {
     "crossref-local": {
       "command": "crossref-local",
-      "args": ["run-server-mcp"],
+      "args": ["mcp", "start"],
       "env": {
         "CROSSREF_LOCAL_DB": "/path/to/crossref.db"
       }
@@ -197,7 +212,7 @@ Local MCP client configuration:
 Remote MCP via HTTP (recommended):
 ```bash
 # On server: start persistent MCP server
-crossref-local run-server-mcp -t http --host 0.0.0.0 --port 8082
+crossref-local mcp start -t http --host 0.0.0.0 --port 8082
 ```
 ```json
 {
@@ -209,12 +224,21 @@ crossref-local run-server-mcp -t http --host 0.0.0.0 --port 8082
 }
 ```
 
+Diagnose setup:
+```bash
+crossref-local mcp doctor        # Check dependencies and database
+crossref-local mcp list-tools    # Show available MCP tools
+crossref-local mcp installation  # Show client config examples
+```
+
 See [docs/remote-deployment.md](docs/remote-deployment.md) for systemd and Docker setup.
 
 Available tools:
 - `search` - Full-text search across 167M+ papers
 - `search_by_doi` - Get paper by DOI
+- `enrich_dois` - Add citation counts and references to DOIs
 - `status` - Database statistics
+- `cache_*` - Paper collection management
 
 </details>
 

{crossref_local-0.4.0 → crossref_local-0.5.0}/docs/remote-deployment.md

@@ -40,7 +40,7 @@ For production deployment, use systemd to manage the service.
 
 ```bash
 # Copy and customize the service file
-sudo cp examples/crossref-mcp.service /etc/systemd/system/
+sudo cp scripts/deployment/mcp/crossref-mcp.service /etc/systemd/system/
 
 # Edit to match your setup
 sudo nano /etc/systemd/system/crossref-mcp.service

crossref_local-0.5.0/docs/sphinx/api/crossref_local.rst

@@ -0,0 +1,34 @@
+crossref_local API
+==================
+
+Main Functions
+--------------
+
+.. autofunction:: crossref_local.search
+.. autofunction:: crossref_local.get
+.. autofunction:: crossref_local.get_many
+.. autofunction:: crossref_local.count
+.. autofunction:: crossref_local.exists
+.. autofunction:: crossref_local.configure
+.. autofunction:: crossref_local.configure_http
+.. autofunction:: crossref_local.enrich
+.. autofunction:: crossref_local.enrich_dois
+.. autofunction:: crossref_local.get_mode
+.. autofunction:: crossref_local.info
+
+Data Classes
+------------
+
+Work
+~~~~
+
+.. autoclass:: crossref_local.Work
+   :members:
+   :undoc-members:
+
+SearchResult
+~~~~~~~~~~~~
+
+.. autoclass:: crossref_local.SearchResult
+   :members:
+   :undoc-members:

crossref_local-0.5.0/docs/sphinx/cli_reference.rst

@@ -0,0 +1,142 @@
+CLI Reference
+=============
+
+CrossRef Local provides a comprehensive command-line interface.
+
+Global Options
+--------------
+
+.. code-block:: bash
+
+    crossref-local [OPTIONS] COMMAND [ARGS]...
+
+Options:
+
+- ``--http``: Use HTTP API instead of direct database
+- ``--api-url URL``: API URL for http mode (default: auto-detect)
+- ``--version``: Show version
+- ``-h, --help``: Show help
+- ``--help-recursive``: Show help for all commands
+
+Commands
+--------
+
+search
+~~~~~~
+
+Search for works by title, abstract, or authors.
+
+.. code-block:: bash
+
+    crossref-local search [OPTIONS] QUERY
+
+Options:
+
+- ``-n, --number INTEGER``: Number of results (default: 10)
+- ``-o, --offset INTEGER``: Skip first N results
+- ``-a, --abstracts``: Show abstracts
+- ``-A, --authors``: Show authors
+- ``-if, --impact-factor``: Show journal impact factor
+- ``--json``: Output as JSON
+
+Examples:
+
+.. code-block:: bash
+
+    crossref-local search "machine learning"
+    crossref-local search "CRISPR" -n 20 -a
+    crossref-local search "neural networks" --impact-factor
+    crossref-local search "deep learning" --json
+
+search-by-doi
+~~~~~~~~~~~~~
+
+Search for a work by DOI.
+
+.. code-block:: bash
+
+    crossref-local search-by-doi DOI [OPTIONS]
+
+Options:
+
+- ``--json``: Output as JSON
+- ``--citation``: Output as citation
+
+Examples:
+
+.. code-block:: bash
+
+    crossref-local search-by-doi 10.1038/nature12373
+    crossref-local search-by-doi 10.1038/nature12373 --citation
+
+status
+~~~~~~
+
+Show status and configuration.
+
+.. code-block:: bash
+
+    crossref-local status
+
+relay
+~~~~~
+
+Run HTTP relay server for remote database access.
+
+.. code-block:: bash
+
+    crossref-local relay [OPTIONS]
+
+Options:
+
+- ``--host TEXT``: Host to bind (default: 0.0.0.0)
+- ``--port INTEGER``: Port to listen on (default: 31291)
+
+Examples:
+
+.. code-block:: bash
+
+    crossref-local relay
+    crossref-local relay --port 8080
+
+MCP Commands
+------------
+
+mcp start
+~~~~~~~~~
+
+Start the MCP server.
+
+.. code-block:: bash
+
+    crossref-local mcp start [OPTIONS]
+
+Options:
+
+- ``-t, --transport [stdio|sse|http]``: Transport type (default: stdio)
+- ``--host TEXT``: Host for SSE/HTTP transport
+- ``--port INTEGER``: Port for SSE/HTTP transport
+
+mcp tools
+~~~~~~~~~
+
+List available MCP tools.
+
+.. code-block:: bash
+
+    crossref-local mcp tools
+
+list-apis
+~~~~~~~~~
+
+List Python APIs (requires scitex).
+
+.. code-block:: bash
+
+    crossref-local list-apis [OPTIONS]
+
+Options:
+
+- ``-v, --verbose``: Verbosity level (-v sig, -vv +doc, -vvv full)
+- ``-d, --max-depth INTEGER``: Max recursion depth
+- ``--json``: Output as JSON