ncbi-sequence-fetch

Files (1)

• SKILL.md

SKILL.md (first lines)

# NCBI Sequence Fetch

## Prerequisites

1.  **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
    `uv` is installed and on PATH.
2.  **User Notification**: If LICENSE_NOTIFICATION.txt does not already exist in
    this skill directory then (1) prominently notify the user to check the terms
    at https://www.ncbi.nlm.nih.gov/ and
    https://www.ncbi.nlm.nih.gov/home/about/policies/, then (2) create the file
    recording the notification text and timestamp.
3.  **`.env` file**: Make sure the `.env` file exists in your home directory.
    Create one if it does not exist.
4.  **`NCBI_API_KEY`** (optional): Raises the NCBI rate limit from 3 to 10
    requests/second. The skill works without it, but a key is recommended if the
    user plans many queries or encounters a 429 error. The user can obtain one
    for free by registering at https://www.ncbi.nlm.nih.gov/account/settings/.
    If the variable is missing from `.env`, do NOT ask the user to paste it into
    the chat (this would leak the key into the agent's context). Instead, give
    the user this command — **substituting `ENV_FILE` with the resolved literal
    path to the `.env` file**:

    ```bash
    printf "Enter NCBI API key (typing hidden): " && read -s key && echo && echo "NCBI_API_KEY=$key" >> "ENV_FILE" && echo "Saved."
    ```

    The scripts load credentials automatically via `dotenv`. **NEVER** read,
    print, or inspect the `.env` file or its variables (e.g. no `cat`, `grep`,
    `echo`, `printenv`, or `os.environ.get` on keys). Credentials must stay out
    of the agent's context.

## Core Rules

-   **Use the Wrapper**: ALWAYS execute the provided helper scripts to query the
    database rather than accessing the database directly. The scripts
    automatically enforce the required rate limit gracefully.
-   **API Key Support**: If the user provides an `NCBI_API_KEY` in their
    environment, the query speed limits are automatically increased
    significantly.
-   **Notification**: If this skill is used, ensure this is mentioned in the
    output.

## Overview

Wraps NCBI's Entrez E-utilities (efetch, esearch, elink, esummary) for
retrieving protein and nucleotide sequences. Provides 10 subcommands covering
the full range of sequence retrieval workflows:

-   `fetch-protein` — Direct protein accession lookup (GenPept, RefSeq)
-   `fetch-nucleotide` — Direct nucleotide accession lookup
-   `cds-translate` — Fetch CDS and translate to protein (3 methods)
-   `search` — Free-text search of any NCBI database
-   `elink` — Follow cross-database links (PubMed→Protein, etc.)
-   `gene-protein` — Search protein by gene name + organism
-   `locus-protein` — Search protein by locus tag + organism
-   `pubmed-proteins` — Find proteins linked to a PubMed article
-   `patent-search` — Extract protein sequences from patents
-   `organism-length` — Last-resort search by organism + exact AA length

## Utility Scripts

**`scripts/ncbi_fetch.py`** — Single script with subcommands.

All subcommands write structured JSON output. Use `--output FILE` to save to a
file, or omit it to print to stdout. A human-readable summary is always printed
to stdout.

### 1. Fetch Protein by Accession

Fetches protein FASTA from NCBI by accession (XP_, NP_, GenPept, etc.)

```bash
uv run scripts/ncbi_fetch.py fetch-protein XP_022033624 -o /tmp/result.json
uv run scripts/ncbi_fetch.py fetch-protein NP_001234567 ABC12345.1
```

### 2. Fetch Nucleotide by Accession

Fetches nucleotide FASTA from NCBI by accession.

```bash
uv run scripts/ncbi_fetch.py fetch-nucleotide MK034466 -o /tmp/result.json
```

### 3. CDS Translate

Fetches a CDS/nucleotide accession and translates to protein sequence. Tries
three approaches in order: 1. NCBI's pre-translated CDS protein (`fasta_cds_aa`)
2. GenBank XML CDS annotation translations 3. Raw nucleotide → 6-frame ORF
finding

```bash
uv run scripts/ncbi_fetch.py cds-translate MK034466 -o /tmp/result.json
uv run scripts/ncbi_fetch.py cds-translate HQ662330 --target-length 1043
```

If the accession is a **genomic record** (not mRNA/CDS), the tool will report
`is_genomic: true` so you can fall back to a homology-based approach instead.

### 4. Search Any Database

Free-text search using Entrez query syntax. Supports all NCBI databases.

```bash
# Search protein database
uv run scripts/ncbi_fetch.py search "WRR4B[Gene Name] AND Arabidopsis[Organism]" \
  --database protein --retmax 5 --fetch-sequences

# Search nucleotide database
uv run scripts/ncbi_fetch.py search "Rz2[Gene Name] AND Beta vulgaris[Organism]" \
  --database nuccore --retmax 10

# Search with patent filter
uv run scripts/ncbi_fetch.py search "disease resistance AND Solanum[Organism] AND patent[Properties]" \
  --database protein --fetch-sequences

# Search by sequence length
uv run scripts/ncbi_fetch.py search '"Oryza sativa"[Organism] AND 1043[SLEN]' \
  --database protein --fetch-sequences --retmax 50

From MarceloClaro/OpenCode_Ecosystem, MIT.

More from MarceloClaro/OpenCode_Ecosystem