Tags: genomoncology/biomcp
Tags
GitHub Issue 72 (#73) * Fix BioMCP Pydantic AI integration for streamable HTTP mode ## Problem The streamable HTTP mode was not working with Pydantic AI's MCPServerStreamableHTTP client. The /mcp endpoint was returning 404 errors, preventing AI agents from connecting to BioMCP's biomedical research tools. ## Root Cause Both worker mode and streamable_http mode were incorrectly using the same SSE-based worker implementation. The streamable_http mode was not actually using FastMCP's native streamable HTTP app, which properly implements the MCP protocol's /mcp endpoint. ## Solution - Changed streamable_http mode to use FastMCP's streamable_http_app() method - Added health endpoint to the Starlette app for monitoring - Fixed type annotations for proper mypy compatibility - Moved health endpoint definition in worker mode to prevent route conflicts ## Changes - Updated server.py to properly differentiate between worker and streamable_http modes - Added comprehensive Pydantic AI integration tests - Created documentation guide for Pydantic AI integration - Fixed worker.py health endpoint ordering issue ## Testing Verified all three transport modes work correctly: - STDIO mode: subprocess-based local development - Worker mode: SSE-based legacy HTTP deployments - Streamable HTTP mode: MCP-compliant production deployments Successfully tested with real biomedical data retrieval including article searches, clinical trials, gene information, and drug data. Fixes #72 * Fix test failures and dependency issues in gh-issue-72 - Make FastAPI and Starlette imports conditional to avoid ImportError when worker dependencies aren't installed - Add proper error messages directing users to install with [worker] extra - Add Starlette as explicit dependency in worker optional-dependencies to resolve deptry warnings - Add Any type hint for app variable to fix mypy type checking errors - Remove non-existent [mcp] extra from pydantic-ai dependency - Exclude spike directory from deptry scanning to avoid false positives These changes ensure tests pass without requiring worker dependencies while maintaining proper type safety and dependency management. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * Skip worker mode tests when FastAPI/Starlette not installed Add conditional skipping for tests that require worker mode dependencies (FastAPI and Starlette). This prevents test failures in CI environments where only base dependencies are installed. - Add worker_dependencies_available() helper function - Add requires_worker pytest mark for conditional skipping - Apply skip marker to all tests that start worker mode servers - Tests now skip gracefully with informative message when dependencies missing This allows the test suite to pass in GitHub Actions CI without requiring the optional [worker] dependencies to be installed. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]> * #72 * #72 * #72 * #69 --------- Co-authored-by: Claude <[email protected]> Co-authored-by: Justin Yeakley <[email protected]>
Fix Windows compatibility and update Docker documentation (#59) * Fix Windows compatibility and update Docker documentation - Fix fcntl import error on Windows (Issue #57) - Added conditional import with try/except for fcntl module - File locking now only applies on Unix systems - Windows users get full functionality without file locking - Refactored cache functions to reduce complexity - Add Docker build instructions to README (Issue #58) - Added `docker build` command before `docker run` - Clarifies that biomcp:latest is a local build, not from Docker Hub * Fix Windows compatibility and update Docker documentation - Fix fcntl import error on Windows (Issue #57) - Added conditional import with try/except for fcntl module - File locking now only applies on Unix systems - Windows users get full functionality without file locking - Refactored cache functions to reduce complexity - Add Docker build instructions to README (Issue #58) - Added `docker build` command before `docker run` - Clarifies that biomcp:latest is a local build, not from Docker Hub --------- Co-authored-by: Justin Yeakley <[email protected]>
Add comprehensive OpenFDA integration with 12 new tools (#56) * feat: Add comprehensive OpenFDA integration with 12 new tools Implements full OpenFDA API integration providing access to FDA regulatory data for drug safety, device events, approvals, recalls, and shortages. New Modules: - adverse_events.py: Search/retrieve drug adverse event reports (FAERS) - device_events.py: Search/retrieve device malfunction reports (MAUDE) - drug_labels.py: Search/retrieve FDA drug labels (SPL) - drug_approvals.py: Search/retrieve drug approval records (Drugs@FDA) - drug_recalls.py: Search/retrieve drug recall notices (Enforcement) - drug_shortages.py: Search/retrieve drug shortage data with 24hr caching Key Features: - 12 new MCP tools (6 searchers + 6 getters) for AI agent integration - Flexible API key support via parameter, env var (OPENFDA_API_KEY), or none - Smart device search with wildcard matching (no hardcoding) - Robust handling of polymorphic FDA fields (string/list types) - Genomics device filtering for precision medicine focus - Rate limiting: 40 req/min (no key) or 240 req/min (with key) CLI Enhancements: - New 'biomcp openfda' command with 6 subcommands - All commands support --api-key parameter - Pagination support with --page and --limit Documentation: - Added openfda-prompts.md with 30+ example prompts - Updated MCP tools reference (now 35 tools total) - Comprehensive API key usage examples - Integration patterns for complex safety analyses Testing & Quality: - All quality checks passing (ruff, mypy, pre-commit) - MCP integration tests updated for new tool count - API key priority handling verified - Endpoint registry updated with FDA endpoints This integration enables comprehensive FDA regulatory data access for drug safety assessment, post-market surveillance, and treatment planning in precision oncology workflows. * feat: Add comprehensive OpenFDA integration with 12 new tools Implements full OpenFDA API integration providing access to FDA regulatory data for drug safety, device events, approvals, recalls, and shortages. New Modules: - adverse_events.py: Search/retrieve drug adverse event reports (FAERS) - device_events.py: Search/retrieve device malfunction reports (MAUDE) - drug_labels.py: Search/retrieve FDA drug labels (SPL) - drug_approvals.py: Search/retrieve drug approval records (Drugs@FDA) - drug_recalls.py: Search/retrieve drug recall notices (Enforcement) - drug_shortages.py: Search/retrieve drug shortage data with 24hr caching Key Features: - 12 new MCP tools (6 searchers + 6 getters) for AI agent integration - Flexible API key support via parameter, env var (OPENFDA_API_KEY), or none - Smart device search with wildcard matching (no hardcoding) - Robust handling of polymorphic FDA fields (string/list types) - Genomics device filtering for precision medicine focus - Rate limiting: 40 req/min (no key) or 240 req/min (with key) CLI Enhancements: - New 'biomcp openfda' command with 6 subcommands - All commands support --api-key parameter - Pagination support with --page and --limit Documentation: - Added openfda-prompts.md with 30+ example prompts - Updated MCP tools reference (now 35 tools total) - Comprehensive API key usage examples - Integration patterns for complex safety analyses Testing & Quality: - All quality checks passing (ruff, mypy, pre-commit) - MCP integration tests updated for new tool count - API key priority handling verified - Endpoint registry updated with FDA endpoints This integration enables comprehensive FDA regulatory data access for drug safety assessment, post-market surveillance, and treatment planning in precision oncology workflows. * feat: Add comprehensive OpenFDA integration with 12 new tools Implements full OpenFDA API integration providing access to FDA regulatory data for drug safety, device events, approvals, recalls, and shortages. New Modules: - adverse_events.py: Search/retrieve drug adverse event reports (FAERS) - device_events.py: Search/retrieve device malfunction reports (MAUDE) - drug_labels.py: Search/retrieve FDA drug labels (SPL) - drug_approvals.py: Search/retrieve drug approval records (Drugs@FDA) - drug_recalls.py: Search/retrieve drug recall notices (Enforcement) - drug_shortages.py: Search/retrieve drug shortage data with 24hr caching Key Features: - 12 new MCP tools (6 searchers + 6 getters) for AI agent integration - Flexible API key support via parameter, env var (OPENFDA_API_KEY), or none - Smart device search with wildcard matching (no hardcoding) - Robust handling of polymorphic FDA fields (string/list types) - Genomics device filtering for precision medicine focus - Rate limiting: 40 req/min (no key) or 240 req/min (with key) CLI Enhancements: - New 'biomcp openfda' command with 6 subcommands - All commands support --api-key parameter - Pagination support with --page and --limit Documentation: - Added openfda-prompts.md with 30+ example prompts - Updated MCP tools reference (now 35 tools total) - Comprehensive API key usage examples - Integration patterns for complex safety analyses Testing & Quality: - All quality checks passing (ruff, mypy, pre-commit) - MCP integration tests updated for new tool count - API key priority handling verified - Endpoint registry updated with FDA endpoints This integration enables comprehensive FDA regulatory data access for drug safety assessment, post-market surveillance, and treatment planning in precision oncology workflows. * feat: Add comprehensive OpenFDA integration with 12 new tools Implements full OpenFDA API integration providing access to FDA regulatory data for drug safety, device events, approvals, recalls, and shortages. New Modules: - adverse_events.py: Search/retrieve drug adverse event reports (FAERS) - device_events.py: Search/retrieve device malfunction reports (MAUDE) - drug_labels.py: Search/retrieve FDA drug labels (SPL) - drug_approvals.py: Search/retrieve drug approval records (Drugs@FDA) - drug_recalls.py: Search/retrieve drug recall notices (Enforcement) - drug_shortages.py: Search/retrieve drug shortage data with 24hr caching Key Features: - 12 new MCP tools (6 searchers + 6 getters) for AI agent integration - Flexible API key support via parameter, env var (OPENFDA_API_KEY), or none - Smart device search with wildcard matching (no hardcoding) - Robust handling of polymorphic FDA fields (string/list types) - Genomics device filtering for precision medicine focus - Rate limiting: 40 req/min (no key) or 240 req/min (with key) CLI Enhancements: - New 'biomcp openfda' command with 6 subcommands - All commands support --api-key parameter - Pagination support with --page and --limit Documentation: - Added openfda-prompts.md with 30+ example prompts - Updated MCP tools reference (now 35 tools total) - Comprehensive API key usage examples - Integration patterns for complex safety analyses Testing & Quality: - All quality checks passing (ruff, mypy, pre-commit) - MCP integration tests updated for new tool count - API key priority handling verified - Endpoint registry updated with FDA endpoints This integration enables comprehensive FDA regulatory data access for drug safety assessment, post-market surveillance, and treatment planning in precision oncology workflows. * feat: Add comprehensive OpenFDA integration with 12 new tools Implements full OpenFDA API integration providing access to FDA regulatory data for drug safety, device events, approvals, recalls, and shortages. New Modules: - adverse_events.py: Search/retrieve drug adverse event reports (FAERS) - device_events.py: Search/retrieve device malfunction reports (MAUDE) - drug_labels.py: Search/retrieve FDA drug labels (SPL) - drug_approvals.py: Search/retrieve drug approval records (Drugs@FDA) - drug_recalls.py: Search/retrieve drug recall notices (Enforcement) - drug_shortages.py: Search/retrieve drug shortage data with 24hr caching Key Features: - 12 new MCP tools (6 searchers + 6 getters) for AI agent integration - Flexible API key support via parameter, env var (OPENFDA_API_KEY), or none - Smart device search with wildcard matching (no hardcoding) - Robust handling of polymorphic FDA fields (string/list types) - Genomics device filtering for precision medicine focus - Rate limiting: 40 req/min (no key) or 240 req/min (with key) CLI Enhancements: - New 'biomcp openfda' command with 6 subcommands - All commands support --api-key parameter - Pagination support with --page and --limit Documentation: - Added openfda-prompts.md with 30+ example prompts - Updated MCP tools reference (now 35 tools total) - Comprehensive API key usage examples - Integration patterns for complex safety analyses Testing & Quality: - All quality checks passing (ruff, mypy, pre-commit) - MCP integration tests updated for new tool count - API key priority handling verified - Endpoint registry updated with FDA endpoints This integration enables comprehensive FDA regulatory data access for drug safety assessment, post-market surveillance, and treatment planning in precision oncology workflows. * feat: Add comprehensive OpenFDA integration with 12 new tools Implements full OpenFDA API integration providing access to FDA regulatory data for drug safety, device events, approvals, recalls, and shortages. New Modules: - adverse_events.py: Search/retrieve drug adverse event reports (FAERS) - device_events.py: Search/retrieve device malfunction reports (MAUDE) - drug_labels.py: Search/retrieve FDA drug labels (SPL) - drug_approvals.py: Search/retrieve drug approval records (Drugs@FDA) - drug_recalls.py: Search/retrieve drug recall notices (Enforcement) - drug_shortages.py: Search/retrieve drug shortage data with 24hr caching Key Features: - 12 new MCP tools (6 searchers + 6 getters) for AI agent integration - Flexible API key support via parameter, env var (OPENFDA_API_KEY), or none - Smart device search with wildcard matching (no hardcoding) - Robust handling of polymorphic FDA fields (string/list types) - Genomics device filtering for precision medicine focus - Rate limiting: 40 req/min (no key) or 240 req/min (with key) CLI Enhancements: - New 'biomcp openfda' command with 6 subcommands - All commands support --api-key parameter - Pagination support with --page and --limit Documentation: - Added openfda-prompts.md with 30+ example prompts - Updated MCP tools reference (now 35 tools total) - Comprehensive API key usage examples - Integration patterns for complex safety analyses Testing & Quality: - All quality checks passing (ruff, mypy, pre-commit) - MCP integration tests updated for new tool count - API key priority handling verified - Endpoint registry updated with FDA endpoints This integration enables comprehensive FDA regulatory data access for drug safety assessment, post-market surveillance, and treatment planning in precision oncology workflows. --------- Co-authored-by: Justin Yeakley <[email protected]>
Documentation Restructure (#55) * ## Overview Implemented comprehensive documentation restructuring plan to create a cleaner, two-level navigation hierarchy organized around user journeys rather than technical categories. ## New Structure - **Getting Started**: Quick setup guides for CLI, Claude Desktop, and API keys - **Concepts**: Core BioMCP philosophy including Deep Researcher persona and Think tool - **User Guides**: Consolidated references for CLI, MCP tools, and IDE integration - **How-to Guides**: Task-oriented guides for common workflows - **Backend Services Reference**: Technical details for all integrated APIs - **Developer Guides**: Deployment, testing, and contribution guidelines ## Major Changes ### Content Consolidation - Merged 4 separate CLI docs (articles, health, trials, variants) into single comprehensive guide - Consolidated 3 policy documents into unified policies.md - Combined multiple API references into organized backend services section - Integrated scattered tutorials into relevant guides ### New Documentation - Created comprehensive guides by merging related content: - `02-the-deep-researcher-persona.md`: Philosophy + methodology + implementation - `03-sequential-thinking-with-the-think-tool.md`: Extracted critical Think tool usage - `01-command-line-interface.md`: All CLI commands in one reference - `02-mcp-tools-reference.md`: Complete MCP tools documentation - `06-search-nci-organizations-and-interventions.md`: New NCI features guide ### Content Migration - Moved blog post "What is BioMCP?" to concepts section - Integrated AlphaGenome setup into backend reference + how-to guide - Moved Python SDK and Cursor IDE docs into IDE integration guide - Preserved specialized tutorials in "Examples and Prompts" section ### Navigation Improvements - Shallow two-level hierarchy for easier navigation - Logical grouping by user intent and workflow - Clear progression from beginner to advanced topics - Removed deep nesting and redundant categories ## Technical Details - Fixed all broken internal links after reorganization - Updated image paths for moved content - Created Python scripts for automated cleanup and link fixing - Ensured clean documentation build with no warnings ## Files Changed - Modified: mkdocs.yml (complete navigation restructure) - Modified: docs/index.md (updated links) - Created: 15+ new consolidated guide files - Created: cleanup and migration scripts - Moved/Merged: 30+ documentation files This restructuring significantly improves documentation discoverability and provides a better user experience while maintaining all existing content. * ⏺ Restructure and improve documentation for production readiness - Simplified navigation structure from 10 to 5 top-level sections - Removed expandable/collapsible navigation in favor of clean sections display - Fixed code block horizontal scrolling issues across all documentation - Converted grid card layouts to stacked format for better readability - Removed all emojis from headers for professional appearance - Made documentation more concise, especially the overview page - Fixed broken anchor links and embedded ASCII diagrams inline - Removed unnecessary sections (migrations, breaking changes, feedback) - Synced outdated docs changelog with main CHANGELOG.md (v0.4.0 → v0.6.2) - Added CSS improvements for code block wrapping and responsive design - Improved overall user experience with cleaner, flatter navigation The documentation now provides optimal onboarding, clear navigation paths, and professional presentation suitable for production deployment. * ⏺ Restructure and improve documentation for production readiness - Simplified navigation structure from 10 to 5 top-level sections - Removed expandable/collapsible navigation in favor of clean sections display - Fixed code block horizontal scrolling issues across all documentation - Converted grid card layouts to stacked format for better readability - Removed all emojis from headers for professional appearance - Made documentation more concise, especially the overview page - Fixed broken anchor links and embedded ASCII diagrams inline - Removed unnecessary sections (migrations, breaking changes, feedback) - Synced outdated docs changelog with main CHANGELOG.md (v0.4.0 → v0.6.2) - Added CSS improvements for code block wrapping and responsive design - Improved overall user experience with cleaner, flatter navigation The documentation now provides optimal onboarding, clear navigation paths, and professional presentation suitable for production deployment. * ⏺ Restructure and improve documentation for production readiness - Simplified navigation structure from 10 to 5 top-level sections - Removed expandable/collapsible navigation in favor of clean sections display - Fixed code block horizontal scrolling issues across all documentation - Converted grid card layouts to stacked format for better readability - Removed all emojis from headers for professional appearance - Made documentation more concise, especially the overview page - Fixed broken anchor links and embedded ASCII diagrams inline - Removed unnecessary sections (migrations, breaking changes, feedback) - Synced outdated docs changelog with main CHANGELOG.md (v0.4.0 → v0.6.2) - Added CSS improvements for code block wrapping and responsive design - Improved overall user experience with cleaner, flatter navigation The documentation now provides optimal onboarding, clear navigation paths, and professional presentation suitable for production deployment. * ⏺ Restructure and improve documentation for production readiness - Simplified navigation structure from 10 to 5 top-level sections - Removed expandable/collapsible navigation in favor of clean sections display - Fixed code block horizontal scrolling issues across all documentation - Converted grid card layouts to stacked format for better readability - Removed all emojis from headers for professional appearance - Made documentation more concise, especially the overview page - Fixed broken anchor links and embedded ASCII diagrams inline - Removed unnecessary sections (migrations, breaking changes, feedback) - Synced outdated docs changelog with main CHANGELOG.md (v0.4.0 → v0.6.2) - Added CSS improvements for code block wrapping and responsive design - Improved overall user experience with cleaner, flatter navigation The documentation now provides optimal onboarding, clear navigation paths, and professional presentation suitable for production deployment. --------- Co-authored-by: Justin Yeakley <[email protected]>
Clinicaltrialsapi (#53) * Add NCI Clinical Trials Search API integration Integrates the National Cancer Institute's Clinical Trials Search API to provide enhanced cancer trial search capabilities alongside existing ClinicalTrials.gov support. ## New Features ### Core NCI Integration - Added dual source support for trial search/getter (ClinicalTrials.gov + NCI) - Implemented NCI API key handling via environment variable or parameter - Added advanced trial filters: biomarkers, prior therapy, brain metastases ### New NCI-Specific Tools (6 MCP tools + CLI commands) - **Organizations**: Search/get cancer centers, hospitals, research institutions - **Interventions**: Search/get drugs, devices, procedures, biologicals - **Biomarkers**: Search trial eligibility biomarkers (reference genes, branches) - **Diseases**: Search NCI's controlled vocabulary of cancer conditions ### API Features - Real-time access to NCI's curated cancer trials database - Support for all NCI API parameters and filters - Automatic cBioPortal integration for gene searches - Proper parameter mapping (org_city, org_state_or_province, etc.) - Comprehensive error handling for Elasticsearch limits ### Documentation - Added NCI tutorial with example prompts: `docs/tutorials/nci-prompts.md` - Created API parameter reference: `docs/api-changes/nci-api-parameters.md` - Updated CLAUDE.md with NCI usage instructions and parameter notes ### CLI Integration ```bash # New commands biomcp organization search "MD Anderson" --api-key YOUR_KEY biomcp intervention search pembrolizumab --type Drug --api-key YOUR_KEY biomcp biomarker search --name "PD-L1" --api-key YOUR_KEY biomcp disease search melanoma --source nci --api-key YOUR_KEY # Enhanced trial commands biomcp trial search --condition melanoma --source nci --api-key YOUR_KEY biomcp trial get NCT04280705 --source nci --api-key YOUR_KEY Requires NCI API key from: https://clinicaltrialsapi.cancer.gov/ * Add NCI Clinical Trials Search API integration Integrates the National Cancer Institute's Clinical Trials Search API to provide enhanced cancer trial search capabilities alongside existing ClinicalTrials.gov support. ## New Features ### Core NCI Integration - Added dual source support for trial search/getter (ClinicalTrials.gov + NCI) - Implemented NCI API key handling via environment variable or parameter - Added advanced trial filters: biomarkers, prior therapy, brain metastases ### New NCI-Specific Tools (6 MCP tools + CLI commands) - **Organizations**: Search/get cancer centers, hospitals, research institutions - **Interventions**: Search/get drugs, devices, procedures, biologicals - **Biomarkers**: Search trial eligibility biomarkers (reference genes, branches) - **Diseases**: Search NCI's controlled vocabulary of cancer conditions ### API Features - Real-time access to NCI's curated cancer trials database - Support for all NCI API parameters and filters - Automatic cBioPortal integration for gene searches - Proper parameter mapping (org_city, org_state_or_province, etc.) - Comprehensive error handling for Elasticsearch limits ### Documentation - Added NCI tutorial with example prompts: `docs/tutorials/nci-prompts.md` - Created API parameter reference: `docs/api-changes/nci-api-parameters.md` - Updated CLAUDE.md with NCI usage instructions and parameter notes ### CLI Integration ```bash # New commands biomcp organization search "MD Anderson" --api-key YOUR_KEY biomcp intervention search pembrolizumab --type Drug --api-key YOUR_KEY biomcp biomarker search --name "PD-L1" --api-key YOUR_KEY biomcp disease search melanoma --source nci --api-key YOUR_KEY # Enhanced trial commands biomcp trial search --condition melanoma --source nci --api-key YOUR_KEY biomcp trial get NCT04280705 --source nci --api-key YOUR_KEY Requires NCI API key from: https://clinicaltrialsapi.cancer.gov/ * Add NCI Clinical Trials Search API integration Integrates the National Cancer Institute's Clinical Trials Search API to provide enhanced cancer trial search capabilities alongside existing ClinicalTrials.gov support. ## New Features ### Core NCI Integration - Added dual source support for trial search/getter (ClinicalTrials.gov + NCI) - Implemented NCI API key handling via environment variable or parameter - Added advanced trial filters: biomarkers, prior therapy, brain metastases ### New NCI-Specific Tools (6 MCP tools + CLI commands) - **Organizations**: Search/get cancer centers, hospitals, research institutions - **Interventions**: Search/get drugs, devices, procedures, biologicals - **Biomarkers**: Search trial eligibility biomarkers (reference genes, branches) - **Diseases**: Search NCI's controlled vocabulary of cancer conditions ### API Features - Real-time access to NCI's curated cancer trials database - Support for all NCI API parameters and filters - Automatic cBioPortal integration for gene searches - Proper parameter mapping (org_city, org_state_or_province, etc.) - Comprehensive error handling for Elasticsearch limits ### Documentation - Added NCI tutorial with example prompts: `docs/tutorials/nci-prompts.md` - Created API parameter reference: `docs/api-changes/nci-api-parameters.md` - Updated CLAUDE.md with NCI usage instructions and parameter notes ### CLI Integration ```bash # New commands biomcp organization search "MD Anderson" --api-key YOUR_KEY biomcp intervention search pembrolizumab --type Drug --api-key YOUR_KEY biomcp biomarker search --name "PD-L1" --api-key YOUR_KEY biomcp disease search melanoma --source nci --api-key YOUR_KEY # Enhanced trial commands biomcp trial search --condition melanoma --source nci --api-key YOUR_KEY biomcp trial get NCT04280705 --source nci --api-key YOUR_KEY Requires NCI API key from: https://clinicaltrialsapi.cancer.gov/ --------- Co-authored-by: Justin Yeakley <[email protected]>
PreviousNext