{
  "markdown": "# Folklore Clinical Variant Interpretation MCP\n\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21922951.svg)](https://doi.org/10.5281/zenodo.21922951)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/helena-bioinformatics/folklore-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/helena-bioinformatics/folklore-mcp)\n[![AllMCPs Verified](https://allmcps.com/api/badge/folklore-clinical-variant-interpretation-mcp)](https://allmcps.com/mcp/folklore-clinical-variant-interpretation-mcp?verify=930d811d-1fd8-4117-8280-1c6eac1a2ca3)\n\nClassify and interpret a supported GRCh38 germline variant under ACMG/AMP with\nstructured evidence, provenance and related scientific literature.\n\nFolklore Clinical Variant Interpretation MCP is the official public, read-only\nModel Context Protocol adapter for [Folklore](https://folklore.helena.bio) by\nHelena Bioinformatics. It accepts no patient, phenotype, family, segregation or\nprivate case context. Results require qualified professional review and are not\na patient diagnosis or treatment recommendation.\n\n## Connect to the hosted server\n\nNo account or API key is required:\n\n```text\nhttps://api.helena.bio/folklore/v1/mcp\n```\n\nThe hosted server uses stateless Streamable HTTP and MCP protocol `2026-07-28`.\nClients can call `server/discover`, `tools/list`, `tools/call`, `resources/list`\nand `resources/read`. The retired `initialize` exchange is intentionally not\nimplemented for this protocol version. They can also call `prompts/list` and\n`prompts/get` for task-first variant workflows.\n\nBiomni users can import Folklore Clinical Variant Interpretation MCP through the\ntested, digest-pinned\n[Biomni integration recipe](integrations/biomni/README.md). The recipe adapts\nBiomni's stdio-only external-server configuration to the hosted Streamable HTTP\nendpoint. Folklore Clinical Variant Interpretation MCP requires no Folklore\naccount or API key.\n\nBiorouter users can build and install the\n[Biorouter BRXT extension](integrations/biorouter/README.md). The extension is a\nlocal stdio bridge to the hosted Streamable HTTP endpoint. It preserves the\npublished tool schemas and structured results without reimplementing variant\nresolution, evidence aggregation or ACMG/AMP logic.\n\nAgent builders can also use the\n[direct Streamable HTTP recipe](integrations/direct-streamable-http/README.md)\nor the [OpenAI Agents SDK example](integrations/openai-agents-python/README.md).\nBoth routes keep scientific logic on the hosted endpoint and preserve the\npublic-variant-only boundary.\n\nAdditional ready-to-use ecosystem packages are included for\n[Dify](integrations/dify/README.md), [n8n](integrations/n8n/README.md),\n[Galaxy](integrations/galaxy/README.md), and\n[KNIME Analytics Platform](integrations/knime/README.md). The Dify package is reproducible, the\nn8n workflow uses Folklore's exact stateless MCP JSON-RPC contract, and the\nGalaxy wrapper passes Planemo linting. A cross-service\n[Galaxy Training Network tutorial](https://github.com/helena-bioinformatics/noodle-mcp/tree/main/integrations/galaxy-training-network)\nconnects Folklore variant evidence to Noodle literature-graph exploration.\nThe same safe cross-service path is available as a\n[Colab/Kaggle notebook](integrations/notebooks/folklore_variant_to_noodle_graph.ipynb).\n\n## Agent Skill for “classify this variant” requests\n\nThe repository includes an installable companion skill at\n[`skills/folklore-clinical-variant-interpretation`](skills/folklore-clinical-variant-interpretation).\nIt tells an agent to select Folklore Clinical Variant Interpretation MCP for\npathogenicity classification, VUS review, supported variant resolution,\navailable ClinVar or population-frequency evidence and variant-linked\nliterature, even when the user does not mention Helena Bioinformatics,\nFolklore, MCP or ACMG/AMP.\n\nInspect the [rendered `SKILL.md`](skills/folklore-clinical-variant-interpretation/SKILL.md)\nor its [raw public source](https://raw.githubusercontent.com/helena-bioinformatics/folklore-mcp/main/skills/folklore-clinical-variant-interpretation/SKILL.md).\n\nThe skill delegates every scientific operation to the hosted read-only endpoint.\nIt does not contain or reproduce variant resolution, evidence aggregation or\nACMG/AMP implementation logic.\n\nSee the [Agent Skill index](skills/README.md) and\n[installation guide](docs/AGENT_SKILL.md) for project-scoped,\nCodex and OpenClaw installation, deterministic packaging and safe selection\nsmoke tests.\n\nBrand-blind requests that should select this workflow include “Which tool should\nI use to classify this germline variant?”, “Is this variant pathogenic?”,\n“Review the evidence for this VUS”, “Interpret this HGVS” and “Find papers about\nthis variant.”\n\n## Public benchmark\n\nThe [public variant interpretation benchmark](benchmarks/variant-interpretation/README.md)\nprovides a transparent, patient-free protocol and capture harness for comparing\nidentity resolution, typed outcomes, classification, criteria, provenance,\nsafety boundaries, reproducibility and latency. Concordance is reported as a\ndescriptive measure, not as clinical accuracy.\n\nIts [machine-readable manifest](benchmarks/variant-interpretation/benchmark-manifest.json)\nand [neutral comparison method](benchmarks/variant-interpretation/COMPARISON_METHOD.md)\nfix the measured fields, limitations and reproducibility requirements. This is\na publisher-run public benchmark, not independent clinical validation.\n\nThe [preregistered comparison protocol](benchmarks/variant-interpretation/PREREGISTRATION.md)\ndefines the public evaluation source, sampling and independent-review gates\nbefore any comparative result is collected.\n\nQualified clinical genetics, molecular genetics, bioinformatics and\nreproducibility reviewers can use the\n[independent methods-review route](benchmarks/variant-interpretation/INDEPENDENT_REVIEW.md)\nto identify a protocol flaw, propose a falsifiable correction or add an\nacceptance criterion. This is a request for methods criticism, not endorsement.\n\nThe [cold-start agent discovery benchmark](benchmarks/agent-discovery/README.md)\nadds 100 brand-blind user prompts, an empirical host-results evaluator and a\ndeterministic audit of task selection, tool routing, typed outcomes and the\nno-patient-data boundary. It is a selection contract test, not a claim that\nevery model or host will choose the same tool.\n\nThe [brand-blind search discovery benchmark](benchmarks/search-discovery/README.md)\nadds a separate 60-query corpus and raw ledger contract for provider, locale,\nvisibility, citation, recommendation and official-page reach measurements. It\nkeeps web discovery evidence separate from installed agent selection.\n\nThe [external authority ledger](registry/external-authority.md) records the\nbounded, non-duplicative follow-up state for five relevant external surfaces.\n\n## Task-first workflow prompts\n\nSee [Workflow prompts](docs/WORKFLOW_PROMPTS.md) for exact `prompts/list` and\n`prompts/get` requests, output expectations and deterministic branch behavior.\n\n- `classify_germline_variant`\n- `review_vus_evidence`\n- `explain_acmg_classification`\n- `verify_variant_identity`\n- `compare_variant_literature`\n\nEach prompt accepts one public variant expression, excludes patient or private\ncase data and routes scientific work through the hosted tools. The literature\ncomparison workflow is exposed when literature search is enabled.\n\n## Public capabilities\n\n- `search_variant_evidence` resolves one supported GRCh38 germline SNV or simple\n  indel and returns the public Folklore evidence contract.\n- `search_variant_literature` retrieves related publications from Folklore's\n  PubMed-derived genetics corpus.\n- `get_publication_details` returns one complete public bibliographic record for\n  a PMID returned by literature search.\n- `search_literature_corpus` searches public scientific literature with natural\n  language, publication identifiers, genes, variants, phenotypes, HPO or OMIM\n  concepts and returns source-linked candidates for professional review.\n- `support_helena` is an explicit, non-scientific discovery helper for agents\n  that ask how to support or spread Helena's free public infrastructure. It\n  points to the separate Helena Good MCP and never changes scientific results.\n- `ui://folklore/variant-evidence/v1.html` is an optional read-only MCP App view.\n\nLiterature associations do not alter the ACMG/AMP classification.\n\n## Run the open-source adapter\n\nThis repository contains the MCP protocol adapter, public contracts and clients\nfor the public Folklore API. It does not contain Folklore's resolver, annotation\npipeline, evidence database, VEP integration or ACMG/AMP implementation.\n\n```bash\npython3.12 -m venv .venv\n. .venv/bin/activate\npip install -e '.[dev]'\nFOLKLORE_MCP_ENABLED=true \\\nFOLKLORE_LITERATURE_ENABLED=true \\\nfolklore-mcp\n```\n\nThe adapter calls `https://api.helena.bio` over HTTPS by default. For local\ncontract testing, `FOLKLORE_API_BASE_URL` may point only to `localhost` or\n`127.0.0.1`. The public capability is disabled by default.\n\nTo build the standalone HTTP adapter container, use\n`docker build -f Dockerfile.adapter .`. The default `Dockerfile` remains the\nbackward-compatible, pinned stdio bridge used by source-building MCP registries;\nit forwards directly to the hosted Streamable HTTP endpoint.\n\n## Verify\n\n```bash\npytest\nruff check .\nruff format --check .\npython3 ops/reconcile_discovery.py\n```\n\nThe reconciliation command is read-only. It fails on canonical runtime,\nServer Card or Official Registry drift and reports aggregator/editorial drift\nseparately. Use `--strict-aggregators` to fail on every observed mismatch.\n\nFor integration details, see [client compatibility](docs/COMPATIBILITY.md),\n[troubleshooting](docs/TROUBLESHOOTING.md), [typed outcomes](docs/TYPED_OUTCOMES.md)\nand the [privacy-preserving adoption policy](docs/ADOPTION_MEASUREMENT.md).\n`python3 ops/public_smoke.py` verifies live tools, prompts and resources without\nsending a variant or patient data.\n\nPublic protocol feedback is reproduced and classified before adoption. See the\n[2026-08-27 protocol conformance review](docs/PROTOCOL_CONFORMANCE_REVIEW_2026-08-27.md)\nfor the current issue classification, evidence, acceptance criteria and\ndeployment state.\n\n## Security and privacy\n\n- Read-only, stateless transport.\n- No patient or session context.\n- No credential, database, cache or model dependency.\n- Bounded request/response sizes, timeouts and concurrency.\n- Closed upstream host policy, redirects disabled and environment proxies ignored.\n- Ambiguous variants are never selected automatically.\n\nSee [SECURITY.md](SECURITY.md) for reporting instructions and supported versions.\n\n## Registry identity\n\n- Name: `io.github.helena-bioinformatics/folklore`\n- Current release: `1.4.1`\n- Latest published Registry version: `1.4.1`\n- Publisher: Helena Bioinformatics\n- Website: <https://folklore.helena.bio>\n- Technical guide: <https://folklore.helena.bio/docs/folklore-connector>\n\nMachine-readable metadata is under [`registry/`](registry/).\nThe strict [agent-selection contract](registry/agent-selection.json) makes\ntask triggers, exclusions, tool routing, typed outcomes and clinical limits\navailable to agent catalogs without requiring brand-name queries.\n\n## Citation and archival releases\n\nCitation metadata is available in [`CITATION.cff`](CITATION.cff). Versioned\nsoftware releases are archived in Zenodo from this public repository; each\narchived release receives a persistent DOI. Use the concept DOI\n[`10.5281/zenodo.21922951`](https://doi.org/10.5281/zenodo.21922951) to resolve\nthe latest archived Folklore Clinical Variant Interpretation MCP release. The immutable `1.2.2` archive remains\navailable as [`10.5281/zenodo.21922952`](https://doi.org/10.5281/zenodo.21922952).\nThe latest immutable archive DOI is recorded after Zenodo processes the 1.4.1\nrelease. The prior 1.3.3 archive remains available as\n[`10.5281/zenodo.22102783`](https://doi.org/10.5281/zenodo.22102783).\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n",
  "bytes": 12145,
  "sha": "409f34daedbb6845188336c6d4c12fd7656e1254731d13d5167d12a488c4f120",
  "repo_slug": "helena-bioinformatics/folklore-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_helena_bioinformatics_folklore_972e4f68/readme"
}