oncofiles

Upload a medical document to persistent storage.

The filename should follow the standard convention: YYYYMMDD_PatientName_Institution_Category_DescriptionEN.ext (e.g. 20260227_PatientName_NOU_Labs_BloodResultsBeforeCycle2.pdf)

Legacy formats (space+dash, underscore-separated) are also accepted and auto-parsed. Separators: underscores only. Description: English, CamelCase.

Args: content: Base64-encoded file content. filename: Document filename in standard or legacy format. mime_type: MIME type of the document.

List all stored medical documents with metadata.

Returns documents ordered by date (newest first).

Search medical documents by text, institution, category, or date range.

Multi-term queries (e.g. "CEA labs") use AND semantics — all terms must match somewhere. Results are ranked by relevance when text is provided: filename/description matches rank highest, then AI summaries, then tags.

Args: text: Search query (searches filename, institution, description, AI summary, tags, and structured metadata). Multiple words are AND-ed together. institution: Filter by institution code (e.g. NOUonko, OUSA). category: Filter by category (labs, report, imaging, pathology, genetics, surgery, surgical_report, prescription, referral, discharge, discharge_summary, chemo_sheet, vaccination, dental, preventive, other). date_from: Filter from this date (YYYY-MM-DD). date_to: Filter to this date (YYYY-MM-DD). limit: Maximum results to return (max 200). offset: Skip this many results (for pagination).

Get a document's metadata and file_id for Claude to analyze.

Returns the file_id that can be used to reference the document in conversation.

Args: file_id: The Anthropic Files API file_id.

Get a document's metadata by its integer database ID.

Use this when you have the numeric document ID (e.g. from search results or lab values).

Args: doc_id: The integer database ID of the document.

Soft-delete a document (moves to trash, recoverable for 30 days).

The document is hidden from all listings and searches but can be restored using restore_document. Files API copy is also deleted.

Args: file_id: The Anthropic Files API file_id to delete.

Restore a soft-deleted document from trash.

Args: doc_id: The local document ID to restore.

List soft-deleted documents in trash.

Args: limit: Maximum results to return (default 50, max 200).

Detect potential duplicate documents based on original filename and file size.

Returns groups of documents that share the same original_filename + size_bytes. Each group contains 2+ documents. Useful for cleanup after repeated imports.

Get the version history chain for a document.

Returns all versions (current and previous) ordered newest first. Works with any document ID in the chain — will find the full history.

Args: doc_id: The integer database ID of any document in the version chain.

Get documents cross-referenced with the given document.

Returns related documents found by shared visit dates, diagnoses, or explicit references. Each result includes the relationship type and a confidence score.

Args: doc_id: The integer database ID of the document.

Update the category of a document.

Use this to recategorize documents (e.g. from 'other' to 'reference').

Args: doc_id: The integer database ID of the document. category: New category (labs, report, imaging, pathology, genetics, surgery, surgical_report, prescription, referral, discharge, discharge_summary, chemo_sheet, vaccination, dental, preventive, reference, advocate, other).

Download a document and return its content for Claude to read.

Returns the actual file content (image or PDF) inline so Claude can see and analyze it directly.

Args: file_id: The Anthropic Files API file_id.

Analyze recent lab results with oncology context.

Downloads lab documents and returns them inline for Claude to read, along with patient context for interpreting results under chemotherapy.

Note: Each lab document is 100KB-2MB. Keep limit low to avoid large responses.

Args: file_id: Specific lab file_id to analyze. If omitted, fetches the most recent labs. limit: Maximum number of lab documents to include (default 3).

Compare lab results over time to identify trends.

Two modes:

• Specific: provide file_id_a and file_id_b to compare two specific lab sets.

• Date range: provide date_from/date_to to compare all labs in a period.

Note: Each lab document is 100KB-2MB. Keep limit reasonable.

Args: file_id_a: First lab file_id (optional). file_id_b: Second lab file_id (optional). date_from: Start date for range query (YYYY-MM-DD). date_to: End date for range query (YYYY-MM-DD). limit: Maximum number of lab documents to include (default 10).

Save a diary entry to the conversation archive.

Use this to log summaries, decisions, progress notes, questions, or any narrative content from conversations about the oncology journey.

Args: title: Short title for the entry. content: Markdown body with the full entry text. entry_date: Date the entry is about (YYYY-MM-DD). Defaults to today. entry_type: Type of entry: summary, decision, progress, question, note. tags: Comma-separated tags (e.g. "chemo,FOLFOX,cycle-3"). document_ids: Comma-separated document IDs referenced (e.g. "3,15"). participant: Who created this: claude.ai, claude-code, oncoteam.

Search the conversation archive by text, type, date, or tags.

Returns entries with truncated content (500 chars). Use get_conversation for full text of a specific entry.

Args: text: Full-text search query. entry_type: Filter by type: summary, decision, progress, question, note. participant: Filter by participant: claude.ai, claude-code, oncoteam. date_from: Filter from this date (YYYY-MM-DD). date_to: Filter to this date (YYYY-MM-DD). tags: Comma-separated tags to filter by (all must match). limit: Maximum results to return.

Get the full content of a single conversation entry by ID.

Args: entry_id: The conversation entry ID.

Get a unified chronological timeline merging documents and conversation entries.

This is the complete view of the oncology journey — documents and diary entries interleaved by date. Useful for book writing, doctor sharing, or reviewing history.

Args: date_from: Start date (YYYY-MM-DD). date_to: End date (YYYY-MM-DD). limit: Maximum items per type (default 200).

Set a persistent key-value pair for an agent.

Upserts: creates the key if new, updates if it already exists.

Args: key: State key name (e.g. "last_briefing_date", "treatment_protocol"). value: JSON string value to store. agent_id: Agent identifier (default: oncoteam).

Get a persistent state value by key.

Returns {value: null} if the key does not exist.

Args: key: State key name. agent_id: Agent identifier (default: oncoteam).

List all persistent state keys for an agent.

Args: agent_id: Agent identifier (default: oncoteam). limit: Maximum number of states to return (default 100, max 500).

Record a treatment milestone (chemo cycle, surgery, scan result, etc.).

Args: event_date: Date of the event (YYYY-MM-DD). event_type: Type of event (e.g. chemo, surgery, scan, consult, side_effect). title: Short title for the event. notes: Optional longer description or notes. metadata: Optional JSON string with extra structured data.

List treatment events, optionally filtered by type and date range.

Returns events in reverse chronological order.

Args: event_type: Filter by event type (e.g. chemo, surgery). date_from: Filter from this date (YYYY-MM-DD). date_to: Filter to this date (YYYY-MM-DD). limit: Maximum results to return.

Get full details of a treatment event by ID.

Args: event_id: The treatment event ID.

Delete a treatment event by ID. Use for removing contaminated/test data.

Args: event_id: The treatment event ID to delete.

Update a treatment event's title, notes, or metadata.

Args: event_id: The treatment event ID to update. title: New title (optional). notes: New notes (optional). metadata: New metadata JSON string (optional).

Save a research article or clinical trial found by an agent.

Deduplicates by source+external_id — if a duplicate is found, returns the existing entry without error.

Args: source: Source name (e.g. pubmed, clinicaltrials). external_id: External identifier (e.g. PMID, NCT number). title: Article or trial title. summary: Brief summary or abstract excerpt. tags: JSON array of tags (e.g. '["FOLFOX","mCRC"]'). raw_data: Full raw data (abstract, JSON, etc.) for reference.

Search saved research entries by text and/or source.

Args: text: Search in title, summary, and tags. source: Filter by source (e.g. pubmed, clinicaltrials). limit: Maximum results to return.

List saved research entries, optionally filtered by source.

Args: source: Filter by source (e.g. pubmed, clinicaltrials). limit: Maximum results to return.

Log an agent tool call to the activity audit trail (append-only).

Args: session_id: Session identifier. agent_id: Agent that made the call (e.g. oncoteam). tool_name: Name of the tool that was called. input_summary: Brief summary of the input parameters. output_summary: Brief summary of the output. duration_ms: How long the call took in milliseconds. status: Result status (ok, error, timeout). error_message: Error details if status is not ok. tags: JSON array of tags (e.g. '["research","pubmed"]').

Search the activity log with filters.

Args: session_id: Filter by session. agent_id: Filter by agent. tool_name: Filter by tool name. status: Filter by status (ok, error, timeout). date_from: Filter from this date (YYYY-MM-DD). date_to: Filter to this date (YYYY-MM-DD). text: Search in input/output summaries. limit: Maximum results to return.

Get aggregated activity statistics by tool and status.

Args: session_id: Filter by session. agent_id: Filter by agent. date_from: Filter from this date (YYYY-MM-DD). date_to: Filter to this date (YYYY-MM-DD).

Get the Google OAuth authorization URL for the user to visit.

Returns a URL that the user should open in their browser to authorize Google Drive access. After authorization, Google redirects to the callback URL which stores the tokens automatically.

Exchange an OAuth authorization code for tokens and store them.

Args: code: The authorization code from the Google OAuth redirect.

Check if the user has valid Google Drive OAuth tokens.

Set the Google Drive folder to sync with.

Detects the folder owner's email and stores it for automatic permission sharing. When the service account creates files/folders, it grants writer access to the original folder owner so they can see the files.

Args: folder_id: The Google Drive folder ID to use as the sync root.

Run full bidirectional Google Drive sync (runs in background).

Returns immediately with status. Use gdrive_sync_status to check progress and get the result when done.

1. Imports new/changed files from GDrive (GDrive wins on conflicts)

2. Exports documents to organized category/year-month folders

3. Exports manifest + metadata markdown files

Args: dry_run: Preview changes without syncing. enhance: Run AI summary/tag generation on new files (default True).

Check the status of the last or current GDrive sync.

Returns whether a sync is currently running, and the result of the last completed sync (if any).

Import files from Google Drive into oncofiles.

Walks category/year-month subfolders, detects new and changed files, downloads them, uploads to Files API, and stores metadata.

Args: dry_run: Preview changes without importing. enhance: Run AI summary/tag generation on new/changed files (default True).

Export documents from oncofiles to Google Drive.

Uploads documents to organized category/year-month folders with manifest and metadata markdown files.

Args: dry_run: Preview changes without exporting.

Grant writer access to all files/folders in the sync root (one-off fix).

Use this after initial sync when files were created by the service account and are invisible to the folder owner. Also updates the stored owner_email for automatic sharing on future uploads.

Args: email: Email to grant access to. If omitted, detects from folder owner.

Create the folder structure in a GDrive root folder (patient-type-aware).

Idempotent: checks for existing folders by name before creating. Handles both bilingual and legacy EN-only folder names (renames old to bilingual). Oncology patients skip general-only folders; general patients skip oncology-only.

Args: root_folder_id: The Google Drive folder ID to create subfolders in.

Export the full database as a JSON manifest (on-demand).

Returns the manifest JSON with all documents, conversations, treatment events, research entries, and agent state.

Run AI enhancement (summary + tags) on documents.

If document_ids is omitted, processes all documents that haven't been enhanced yet.

Args: document_ids: Comma-separated document IDs to enhance. If omitted, enhances all unprocessed.

Extract and store structured medical metadata from a document.

Uses AI to analyze the document text and extract findings, diagnoses, medications, providers, and a patient-friendly summary. Results are persisted in the structured_metadata column.

Args: document_id: The local document ID to extract metadata from.

Backfill structured_metadata for all documents that have AI summaries but no metadata.

Scans for documents where ai_processed_at is set but structured_metadata is empty, then extracts structured metadata from cached OCR text. Useful after adding the structured_metadata column to an existing database.

Fetch clinical trials from ClinicalTrials.gov and store in research_entries.

Searches the ClinicalTrials.gov API v2 for matching studies and saves them to the research_entries table (deduplicates by NCT number).

Args: condition: Medical condition to search for (e.g. "colorectal cancer"). keywords: Additional search terms (e.g. "FOLFOX", "immunotherapy"). status: Trial status filter (RECRUITING, ACTIVE_NOT_RECRUITING, COMPLETED). location_country: Country filter (e.g. "United States", "Slovakia"). phase: Phase filter (PHASE1, PHASE2, PHASE3, PHASE4). limit: Maximum number of trials to fetch (default 20).

Store parsed lab values from a document for trend tracking.

Includes deduplication checks:

• If document_id already has stored values, returns skipped (unless force=True to update/replace).

• If another document has values for the same lab_date, warns about collision (stores anyway but flags it).

Standardized parameter names: WBC, ABS_NEUT, ABS_LYMPH, PLT, HGB, ANC, ALT, AST, GMT, ALP, BILIRUBIN, CREATININE, eGFR, CEA, CA19_9, SII, NE_LY_RATIO

Args: document_id: Source document ID (should be a labs document). lab_date: Date of the lab test (YYYY-MM-DD). values: JSON array of objects, each with: parameter, value, unit, and optionally reference_low, reference_high, flag. Example: [{"parameter": "WBC", "value": 6.8, "unit": "10^9/L", "reference_low": 4.0, "reference_high": 10.0, "flag": ""}] force: If True, store even if document already has values (replaces existing via INSERT OR REPLACE).

Retrieve stored lab values for trend analysis.

Returns values sorted chronologically (oldest first) for plotting trends.

Args: parameter: Filter by parameter name (e.g. PLT, SII, CEA). If None, returns all. date_from: Filter from this date (YYYY-MM-DD). date_to: Filter to this date (YYYY-MM-DD). limit: Maximum results to return.

Lab safety check against thresholds appropriate for the patient type.

For oncology patients: mFOLFOX6 pre-cycle thresholds (NCCN + SmPC). For general patients: standard health reference ranges (EU/WHO/ESC).

For each safety parameter, returns:

• The threshold (min or max) with source/guideline reference

• The patient's most recent value with date and source document

• Safety status: green (safe), red (unsafe), yellow (borderline ±10%)

• Clickable gdrive_url to verify the source lab document

Get the full pre-cycle checklist for mFOLFOX6 with source references.

Returns all checklist sections (lab safety, toxicity, VTE, general) with guideline source URLs for each item. Lab items include the patient's latest value and safety status.

Args: cycle_number: Current cycle number (for display context).

Get structured time series data for one or more lab parameters.

Returns chronological values with reference ranges, units, and computed deltas (absolute change and % change between consecutive measurements). Designed for Oncoteam and MCP clients to build trend charts and analysis.

Args: parameters: Comma-separated parameter names (e.g. "CEA,CA19_9" or "PLT"). date_from: Start date filter (YYYY-MM-DD). Optional. date_to: End date filter (YYYY-MM-DD). Optional.

Compare lab values between two dates side-by-side.

Returns all parameters measured on both dates with change direction, absolute delta, percentage change, and out-of-range flags.

Args: date_a: First date (YYYY-MM-DD), typically the earlier measurement. date_b: Second date (YYYY-MM-DD), typically the later measurement.

Get a summary of the latest value for every tracked lab parameter.

Returns status (normal/high/low), trend direction (rising/falling/stable), days since last measurement, and computed indices (SII, Ne/Ly ratio). Designed as a quick overview for clinical decision support.

Get EU preventive care screening compliance for a general health patient.

Evaluates which screenings (colonoscopy, dental, ophthalmology, PSA, etc.) are up-to-date, due soon, overdue, or never done — based on patient age, sex, and treatment_events history.

Only available for patients with patient_type="general" in their context. Requires date_of_birth and sex in patient context.

Returns a compliance report with actionable screening status for each applicable protocol.

Export a structured document package for consultations or second opinions.

Assembles all documents grouped by category with metadata, treatment events timeline, and structured metadata. Returns JSON that Oncoteam can render as PDF, email, or share link.

Args: include_metadata: Include AI summaries and structured metadata (default True). include_timeline: Include treatment events timeline (default True).

Rename documents from old naming conventions to the standard format.

Standard format: YYYYMMDD_PatientName_Institution_Category_DescriptionEN.ext

In dry_run mode (default), returns a preview of proposed renames without making any changes. Set dry_run=False to execute the rename.

Args: dry_run: If True (default), only preview changes. Set False to execute. en_descriptions: Optional JSON object mapping doc_id → English description (e.g. '{"15": "BloodResultsPreCycle3", "42": "CTAbdomen"}'). If not provided, keeps existing descriptions.

Get the current patient clinical context.

Returns structured patient data including diagnosis, biomarkers, treatment, metastases, comorbidities, and excluded therapies.

Update specific fields in the patient clinical context.

Merges the provided updates into the current context. Nested dicts (like biomarkers, treatment, physicians) are merged recursively. Persisted to database for durability.

Args: updates_json: JSON object with fields to update. Example: '{"treatment": {"current_cycle": 3}}'

List all available patients.

Shows active patients with their slug, name, document count, and patient type. Use select_patient to switch to a different patient.

Switch to a different patient for this connection.

After calling this, all subsequent tool calls will use the selected patient's data. The selection persists across requests.

Args: patient_slug: Patient slug or UUID (e.g. 'q1b', 'e5g').

Detect and fix GDrive folder structure issues.

Scans for: unknown folders, root-level files not in any category folder, empty managed folders, and stale backup folders.

Args: dry_run: If True (default), report issues without making changes. If False, move files, rename folders, and clean up backups.

Validate and fix document categories by comparing with AI-detected document types.

Checks each document's category against its structured_metadata.document_type. Reports mismatches and optionally corrects them.

Args: dry_run: If True (default), report mismatches without fixing. If False, update categories and move GDrive files.

Analyze activity logs for errors, slow tools, and improvement opportunities.

Scans the audit trail for patterns: recurring errors, slow operations, failed storage, and usage trends. Returns actionable findings that can be used to create GitHub improvement issues.

Args: days: Number of days to analyze (default 7).

Get system health overview: sync history, document counts, resource usage, and errors.

Returns a comprehensive status report useful for monitoring and debugging. Includes 7-day sync statistics, recent sync runs, memory usage, and document counts.

Get per-document status matrix showing OCR, AI, metadata, sync, and rename state.

Returns a table of documents with their processing status at each pipeline stage. Use filters to find documents that need attention.

Args: filter: Filter documents — 'all', 'missing_ocr', 'missing_ai', 'missing_metadata', 'not_synced', 'not_renamed', 'incomplete' (any gap). limit: Maximum documents to return (max 200).

Get pipeline operations status: scheduled jobs, stage counts, and sync history.

Shows which automated processes run, their schedule, last results, and how many documents are at each pipeline stage (OCR → AI → metadata → sync → rename).

List all registered MCP tools with their descriptions and parameter schemas.

Returns the complete tool inventory for discovery and documentation. Useful for agents to understand available capabilities.

Run a read-only SQL query against the production database.

Use this for monitoring, debugging, and ad-hoc analysis. Only SELECT/WITH queries are allowed — mutations are blocked.

Args: sql: SQL query (SELECT only). Tables: documents, activity_log, conversations, treatment_events, research_entries, lab_values, document_pages, agent_state, patient_context, schema_migrations. limit: Max rows to return (default 50, max 200).

Get a single prompt log entry with full prompts and raw response.

Returns the complete AI call record including system prompt, user prompt, raw AI response, token counts, and timing. Use search_prompt_log to find entries.

Args: entry_id: The prompt log entry ID.

Search prompt logs — all AI calls made during document processing.

Returns a list of prompt log entries (without full prompts for brevity). Use get_prompt_log_entry to see full prompts and responses for a specific entry.

Args: call_type: Filter by type: 'ocr', 'summary_tags', 'structured_metadata', 'filename_description'. document_id: Filter by document ID. status: Filter by status ('ok' or 'error'). date_from: Filter from date (YYYY-MM-DD). date_to: Filter to date (YYYY-MM-DD). text: Search in prompts and responses. limit: Max results (1-200, default 50).

Show which Google services are connected and entry counts.

Returns the status of Drive, Gmail, and Calendar integrations, including whether each is authorized and how many entries are stored.

Start Gmail authorization flow. Returns a URL the user must visit.

After visiting the URL and completing Google's consent screen, Gmail read access will be enabled. Call integration_status() to verify.

WARNING: This grants read access to ALL emails in the Gmail account.

Start Calendar authorization flow. Returns a URL the user must visit.

After visiting the URL and completing Google's consent screen, Calendar read access will be enabled. Call integration_status() to verify.

WARNING: This grants read access to ALL events in Google Calendar.

Search stored email entries by text, date, sender, or medical relevance.

Args: query: Text to search in subject, body snippet, and sender. date_from: Filter from this date (YYYY-MM-DD). date_to: Filter to this date (YYYY-MM-DD). sender: Filter by sender email or name (partial match). is_medical: Filter to medical emails only when True. limit: Maximum results to return.

Get full details of a stored email entry by ID.

Args: email_entry_id: The email entry ID.

Search stored calendar entries by text, date, or medical relevance.

Args: query: Text to search in summary and description. date_from: Filter from this date (YYYY-MM-DD). date_to: Filter to this date (YYYY-MM-DD). is_medical: Filter to medical events only when True. limit: Maximum results to return.

Get full details of a stored calendar entry by ID.

Args: calendar_entry_id: The calendar entry ID.