scifinder-route-mcp
The scifinder-route-mcp server indexes, searches, and manages reaction-step-level chemical synthesis routes extracted from SciFinder exports, with support for document ingestion, LLM-powered extraction, vector search, compound registry, and operational management.
Document Ingestion & Management
Register, upload, and scan inbox for SciFinder exports (PDF, HTML, MHTML, RTF, RDF, TXT, MD)
Reparse documents from scratch, clearing previously extracted reactions
Parse Job Management
Queue files for asynchronous extraction; track, list, retry individual or all failed jobs
Reaction Step Search & Retrieval
Search by text, reagents, solvents, document ID, or confidence threshold
Retrieve full step details and source provenance
Semantic similarity search via vector embeddings
Compound Registry
Search by name, CAS, SMILES, or InChIKey; view metadata and linked reactions
Merge duplicate compound records
Recognize chemical structures from images via external endpoints (MolScribe, DECIMER, OSRA)
Vector Index Management
Rebuild embeddings index and check coverage/status
DOI Verification & Evaluation
Record agent/browser DOI verification results
Export gold-set JSONL, compute regression metrics, and view latest evaluation status
Configuration Management
View, update, validate, and hot-reload configuration (async jobs, integrations, security) without container restarts
Operational & Maintenance
Health check, storage usage reporting, SQLite backup, evidence/cache cleanup (with dry-run), and integration endpoint testing (LLM, embedding, OCR, document parser, PostgreSQL)
Integrates with OpenAI-compatible APIs for LLM-based extraction of reaction steps and generating embeddings for semantic search, using configurable endpoints for chat completions and embeddings.
Allows use of PostgreSQL as the primary database backend with optional pgvector support for vector storage and similarity search, including connectivity status and fallback to SQLite.
Provides optional Redis as a queue backend for durable job processing, configurable via queue.redis_url as an alternative to the default SQLite queue.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@scifinder-route-mcp scan inbox for new SciFinder exports"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
scifinder-route-mcp
NAS-hosted MCP server for indexing and searching reaction-step-level synthesis routes from local SciFinder exports. It is designed to run long-term on Docker/NAS with a read-only inbox, durable SQLite queue fallback, optional external OCR/LLM/vector/parser/structure-recognition APIs, and an operational Admin Web UI for trusted LAN/VPN deployments.
GHCR visibility note: if anonymous pull fails, open GitHub → Packages →
scifinder-route-mcp→ Package settings → Change visibility → Public. The compose file is already configured forghcr.io/kettly1260/scifinder-route-mcp:latest.
Quick Start With Prebuilt Image
The published Docker image targets both linux/amd64 and linux/arm64.
git clone https://github.com/kettly1260/scifinder-route-mcp.git
cd scifinder-route-mcp
cp .env.example .env
mkdir -p nas-data nas-inbox
docker compose -f docker-compose.image.yml up -dThen open:
Admin Web UI: http://<nas-host>:8001/
MCP HTTP: http://<nas-host>:8000/mcp
Legacy SSE: http://<nas-host>:8000/ssePut SciFinder exports into nas-inbox, then click Scan Inbox in the Admin Web UI or call the MCP scan_inbox tool. Supported import formats are .pdf, .rtf, .rdf, .html, .htm, .mhtml, .mht, .md, .markdown, and .txt. The image compose file uses image: only and does not build locally.
Do not expose the Admin Web UI directly to the public internet. Use a trusted LAN/VPN or a reverse proxy with TLS and authentication. The Python default Admin bind address is 127.0.0.1; the Docker compose profiles explicitly bind 0.0.0.0 for NAS access.
Related MCP server: ketcher-mcp-server
Local Build Deployment
docker compose up -d --buildPersistent paths:
./nas-data -> /data
./nas-inbox -> /inbox (read-only in the container)
./nas-data/uploads -> /data/uploads (HTTP upload and sidecar staging)Parsing is asynchronous in the NAS profile. Jobs are stored durably in SQLite; after a container restart, interrupted running jobs are re-queued. Poll get_parse_job_status or list_parse_jobs until completion.
Environment and Runtime Config
Copy .env.example to .env. Docker-level settings such as published ports, volumes, container network, and restart policy belong in .env/Compose only. The Admin Web UI never edits Docker files and never controls host Docker.
Hot application config is read from /data/config.yaml; copy config.example.yaml to ./nas-data/config.yaml if desired. Hot-reloadable sections include:
server.async_jobs, server.max_workers, server.storage_backend
queue.backend, queue.redis_url
security.allow_external_paths, security.token, security.users
ingest.scan_extensions, ingest.upload_extensions, ingest.upload_max_bytes,
ingest.reject_file_type_mismatch, ingest.extract_visual_evidence
integrations.*
extraction.llm_schema_version, extraction.llm_prompt_profile, extraction.llm_cost_limit_usd
thresholds.verification_confidence_threshold
retention.evidence_retention_days, retention.cache_retention_days
security.upload_av_scan_enabled, security.upload_av_engine,
security.upload_av_endpoint, security.upload_av_fail_closedUse MCP tools get_config, update_config, validate_config, and reload_config, or use the Admin Web UI.
MCP Transport
Docker deployments default to adaptive MCP transport mode:
SCIFINDER_ROUTE_TRANSPORT=auto
SCIFINDER_ROUTE_MCP_PATH=/mcp
SCIFINDER_ROUTE_SSE_PATH=/sseIn auto mode, the same container and port expose both MCP endpoints:
http://<nas-host>:8000/mcp Streamable HTTP for modern MCP clients
http://<nas-host>:8000/sse Legacy SSE for older MCP clients/mcp handles MCP JSON-RPC requests such as initialize, tools/list, and tools/call; GET /mcp behavior is provided by FastMCP according to the MCP Streamable HTTP transport. /sse is retained for older clients that have not moved to Streamable HTTP.
For debugging or strict compatibility, force a single transport explicitly:
SCIFINDER_ROUTE_TRANSPORT=http
SCIFINDER_ROUTE_MCP_PATH=/mcpor:
SCIFINDER_ROUTE_TRANSPORT=sse
SCIFINDER_ROUTE_SSE_PATH=/sseAdmin Web UI
The Admin Web UI provides operational controls for:
- health/status cards and mounted storage diagnostics
- token-protected config changes
- queue status, recent jobs, failed-job retry
- HTTP upload endpoint for sidecar/client upload
- LLM endpoint/model/enable toggle, schema version, prompt profile, cost limit
- embedding endpoint/model, vector rebuild, vector index status and errors
- OCR endpoint/model, OCR backlog status
- document parser endpoint/model, parser fallback and endpoint health
- structure recognition endpoint/model health
- PostgreSQL URL/backend status with SQLite fallback
- DOI low-confidence queue count
- evaluation latest metrics
- SQLite backup, retention dry-run cleanup, NAS storage usage
- compound registry count and search via MCPSecret fields in the UI are not prefilled. Leaving token, Redis URL, or PostgreSQL URL blank preserves the current value; entering a value replaces it. Docker-owned settings such as published ports, volume mounts, and container networks remain in .env/Compose.
MCP Tools
Implemented tools:
health_check
get_config
update_config
validate_config
reload_config
scan_inbox
register_document
upload_document
upload_document_content
get_parse_job_status
list_parse_jobs
retry_parse_job
retry_failed_jobs
search_reaction_steps
get_reaction_step
get_reaction_provenance
record_doi_verification
reparse_document
export_evaluation_set
compute_evaluation_metrics
get_evaluation_status
rebuild_vector_index
get_vector_index_status
semantic_search_reaction_steps
search_compounds
get_compound
merge_compounds
search_by_smiles
recognize_structure_image
backup_database
get_storage_usage
cleanup_evidence_cache
test_integration_endpoint
list_export_batches
get_export_batch
unlink_document_from_batchFeature Matrix
Area | Status | Notes |
Docker/NAS adaptive MCP service | Implemented | Default |
Single-transport override | Implemented | Set |
GHCR multi-arch image workflow | Implemented |
|
Read-only inbox scanning | Implemented |
|
HTTP upload staging | Implemented |
|
Sidecar watcher | Implemented |
|
Durable queue | Implemented | SQLite queue is default; restart recovery and retry tools. Redis is optional/degraded via config status, not required. |
SQLite storage | Implemented | Source documents, jobs, reaction steps, provenance, DOI verification, vector rows, compounds, metrics. |
PostgreSQL backend | Runnable degraded integration |
|
pgvector | Optional/degraded | SQLite stores embeddings as JSON and cosine-searches them; Postgres/pgvector reports endpoint/backend status. |
PDF/HTML/MHTML/text parsing | Implemented | Built-in parser remains fallback. |
External document parser | Implemented |
|
OCR worker | Implemented adapter |
|
Rule extraction | Implemented | Candidate blocks and structured fields. |
LLM JSON structuring | Implemented adapter | OpenAI-compatible |
Embedding/vector index | Implemented adapter | OpenAI-compatible |
Compound registry | Implemented | CAS/SMILES/InChIKey text extraction, alias registry, reaction roles; RDKit optional. |
Image structure recognition | Implemented adapter |
|
Multi-user authorization | Implemented |
|
Evaluation metrics | Implemented | JSONL gold-set metrics and latest metric status. |
Backup/retention | Implemented | SQLite backup, storage usage, evidence/cache cleanup dry-run. |
Endpoint health checks | Implemented | LLM, embedding, OCR, parser, structure recognition, Postgres. |
External API Schemas
All external services are optional. If a service is not configured or fails, the server returns a degraded/skipped/error status instead of crashing the process.
Embedding endpoint: POST <endpoint>/embeddings
{"model":"bge-m3","input":["text"]}Expected response can be OpenAI-like:
{"data":[{"embedding":[0.1,0.2]}]}LLM endpoint: POST <endpoint>/chat/completions, OpenAI-compatible. The assistant content must be strict JSON with reaction-step fields.
OCR endpoint: POST <endpoint>/ocr
{"model":"mineru-layout","file_path":"/data/uploads/file.pdf"}Expected response:
{"text":"OCR text", "confidence":0.85}Document parser endpoint: POST <endpoint>/parse
{"model":"parser-name","file_path":"/data/uploads/file.pdf"}Expected response:
{"file_type":"pdf","title":"...","doi":"10....","chunks":[{"text":"...","page_number":1,"parser_name":"external","parser_version":"1"}]}Built-in document OCR/parser providers:
paddleocr_vl: submits the local file as multipart to an AI Studio PaddleOCR-VL job endpoint such ashttps://paddleocr.aistudio-app.com/api/v2/ocr/jobs, polls the job, and reads the provider result JSON.mineru: submits the local file as multipart to<endpoint>/file_parsewithreturn_md=true, then imports returned Markdown/text into parsed chunks.
Provider fallback chains can be configured with single-provider compatibility fields or ordered lists:
integrations:
ai_providers:
- id: paddleocr
name: PaddleOCR AI Studio
format: paddleocr_vl
endpoint: https://paddleocr.aistudio-app.com/api/v2/ocr/jobs
api_key: ${PADDLEOCR_TOKEN}
enabled_models: [PaddleOCR-VL-1.6]
- id: mineru
name: MinerU
format: mineru
endpoint: https://mineru.example/api
api_key: ${MINERU_TOKEN}
enabled_models: [mineru]
ocr_provider_ids: [paddleocr, mineru]
document_parser_provider_ids: [mineru, paddleocr]
document_parser_fallback: trueStructure recognition endpoint: POST <endpoint>/recognize
{"model":"decimer","image_path":"/data/evidence/page1.png"}Expected response:
{"structures":[{"smiles":"CCO","confidence":0.7}]}Sidecar Watcher
Create sidecar.yaml on a client machine:
watch_dir: /path/to/scifinder/exports
server_url: http://nas-host:8001
token: change-me
include_patterns:
- "*.pdf"
- "*.html"
settle_seconds: 3
upload_mode: http
poll_seconds: 2Run:
scifinder-route-sidecar sidecar.yamlThe sidecar polls by default and does not require watchdog, making it suitable for Windows/macOS/Linux clients.
Authorization
Legacy single-token mode:
SCIFINDER_ROUTE_TOKEN=change-meMulti-user token mode:
SCIFINDER_ROUTE_USERS=alice:viewer-token:viewer,bob:operator-token:operator,root:admin-token:adminRoles:
viewer search/read/status
operator scan/reparse/retry/vector/evaluation/integration tests
admin config/backup/cleanup/secret operationsDevelopment
python -m pytest -qOptional Docker check:
docker compose build
docker compose -f docker-compose.image.yml configAvailable Tools
32 toolsbackup_databaseC
Create a SQLite database backup, or report Postgres backup guidance.
Inputs: output_path, token. Returns: object
cleanup_evidence_cacheC
Clean generated evidence/cache files without deleting source documents.
Inputs: dry_run, max_age_days, token. Returns: object
compute_evaluation_metricsC
Compute regression metrics from a gold-set JSONL file.
Inputs: gold_set_path (required), token. Returns: object
export_evaluation_setC
Export extracted reaction steps as JSONL for manual labeling and regression checks.
Inputs: output_path, limit, token. Returns: object
get_compoundC
Return compound metadata, aliases, and linked reactions.
Inputs: compound_id (required), token. Returns: object
get_configA
Return the effective application config. Secrets are masked unless include_secrets is true.
Inputs: include_secrets, token. Returns: object
get_evaluation_statusC
Return the latest evaluation metrics.
Inputs: token. Returns: object
get_parse_job_statusC
Return parse job status, stage, and error details.
Inputs: job_id (required), token. Returns: object
get_reaction_provenanceC
Return source text/page/parser provenance for a reaction step.
Inputs: reaction_step_id (required), token. Returns: result
get_reaction_stepC
Return one structured reaction step.
Inputs: reaction_step_id (required), token. Returns: object
get_storage_usageC
Return NAS data/upload/evidence storage usage.
Inputs: token. Returns: object
get_vector_index_statusB
Return vector index coverage, model, and last error.
Inputs: token. Returns: object
health_checkB
Return server health, configured paths, and indexed object counts.
Inputs: token. Returns: object
list_parse_jobsC
List recent parse jobs, optionally filtered by status.
Inputs: status, limit, token. Returns: result
merge_compoundsB
Merge source compound aliases/reaction links into a target compound.
Inputs: source_compound_id (required), target_compound_id (required), token. Returns: object
rebuild_vector_indexC
Generate embeddings for reaction steps using the configured embedding endpoint.
Inputs: limit, token. Returns: object
recognize_structure_imageC
Send an image region to a configured MolScribe/DECIMER/OSRA-style endpoint and register candidate SMILES.
Inputs: image_path (required), reaction_step_id, token. Returns: object
record_doi_verificationC
Record DOI source verification performed by an agent or browser workflow.
Inputs: reaction_step_id (required), doi (required), verified_fields (required), paper_title, +4 more. Returns: object
register_documentB
Register and parse a local SciFinder export file already visible to the server.
Inputs: file_path (required), reparse, token. Returns: object
reload_configB
Reload hot application config from config.yaml without restarting the container.
Inputs: token. Returns: object
reparse_documentC
Clear extracted reactions for a document and parse it again.
Inputs: document_id (required), token. Returns: object
retry_failed_jobsC
Retry recent failed parse jobs.
Inputs: limit, token. Returns: object
retry_parse_jobB
Retry a failed or completed parse job by moving it back to the durable queue.
Inputs: job_id (required), token. Returns: object
scan_inboxB
Scan the NAS inbox for supported SciFinder exports and queue/register new files.
Inputs: reparse, limit, token. Returns: object
search_by_smilesB
Normalize a SMILES string when RDKit is available, then search compounds.
Inputs: smiles (required), limit, token. Returns: result
search_compoundsB
Search the compound registry by name, CAS, SMILES, or InChIKey.
Inputs: query, limit, token. Returns: result
search_reaction_stepsB
Search extracted reaction steps by text and structured condition filters.
Inputs: query, reagent, solvent, document_id, +3 more. Returns: result
semantic_search_reaction_stepsC
Search reaction steps semantically using the configured embedding endpoint.
Inputs: query (required), limit, token. Returns: result
test_integration_endpointB
Test one configured integration endpoint: llm, embedding, ocr, document_parser, structure_recognition, postgres.
Inputs: kind (required), token. Returns: object
update_configB
Merge hot-reloadable application config updates into config.yaml and reload them.
Inputs: updates (required), token. Returns: object
upload_documentC
Copy a server-visible file into the upload area, then register and parse it.
Inputs: source_path (required), filename, reparse, token. Returns: object
validate_configB
Validate the current application config and report settings that require container restart.
Inputs: token. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Each tool has a specific, well-defined purpose. Document ingestion, compound/reaction searching, evaluation, and config/health tools are clearly separated without overlap. An agent can easily distinguish between e.g., search_compounds and search_by_smiles, or between list_parse_jobs and get_parse_job_status.
All tool names follow a consistent snake_case verb_noun pattern (e.g., backup_database, get_compound, search_reaction_steps). There is no mixing of cases or inconsistent verb forms, making the naming predictable and clear.
With 32 tools, the set is too large for typical MCP server coherence. While the domain is complex, many tools could be consolidated (e.g., multiple get_ and search_ tools). The count exceeds the 25+ threshold for 'too many' and may overwhelm agents.
The tool surface covers the full lifecycle: document ingestion, parsing, compound/reaction search, evaluation, config management, and maintenance. Minor gaps exist (e.g., no explicit delete for documents or compounds), but core workflows are well-supported and no dead ends are apparent.
Maintenance
Related MCP Connectors
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Token-free MCP server for structured RevoGrid Core, Pro, and Enterprise knowledge retrieval.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.38 npmMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Ketcher chemical structure editor integration, enabling SMILES/MOL/InChI conversion, image generation, molecular property calculation, and validation.MIT
- AlicenseAqualityBmaintenanceMCP server for local knowledge management with Markdown and PDF indexing using SQLite FTS5.513 npm2MIT
- AlicenseAqualityDmaintenanceMCP server that enables local hybrid semantic and keyword search over private PDF, DOCX, Markdown, and text documents without sending data to embedding APIs.95,381 npmMIT