### Clone and install dependencies

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DEVELOPMENT.md

Initial setup commands to clone the repository and install required packages.

```bash
git clone https://github.com/yeyuan98/biomcp-ts.git && cd biomcp-ts
npm install
```

--------------------------------

### Troubleshooting Commands

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

Various commands used to diagnose and resolve common installation or runtime issues.

```bash
npx biomcp --help
```

```bash
biomcp doctor
```

```bash
biomcp --version
```

```bash
rm -rf ~/.npm/_npx
```

```bash
%LocalAppData%\npm-cache\_npx
```

--------------------------------

### Configure biomcp in Claude Desktop

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/R-ANALYSIS.md

Example configuration for the Claude Desktop mcpServers settings to enable R analysis.

```json
{
  "mcpServers": {
    "biomcp": {
      "command": "npx",
      "args": ["-y", "-p", "biomcp@0.9", "-p", "webr@0.6", "biomcp"],
      "env": {
        "ANALYSIS_R": "1"
      }
    }
  }
}
```

--------------------------------

### Install and Diagnose biomcp-ts

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/README.md

Use these commands to diagnose the environment or run the MCP server directly.

```bash
npx -y biomcp doctor   # diagnose a machine: Node gate, config health, feature gates, peer deps
npx biomcp             # zero-config stdio MCP server (this is what MCP clients run); Node >= 22.13
```

--------------------------------

### Verify Installation Health

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

Run the doctor command to check for system health and identify potential blockers.

```bash
npx -y biomcp@0.9 doctor
```

--------------------------------

### MySQL Zero-Install Client Command

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Use this command array in your MCP client configuration to run biomcp with MySQL support without a local installation.

```json
["npx","-y","-p","biomcp@0.9","-p","mysql2@3","biomcp"]
```

--------------------------------

### Diagnose biomcp installation

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

Run the doctor command to check for blockers, environment issues, and configuration health. Use the --json flag for machine-readable output.

```bash
npx -y biomcp@0.9 doctor            # human-readable, exit 1 on blockers
npx -y biomcp@0.9 doctor --json     # machine-readable (schema_version: 1)
```

--------------------------------

### GET /api/patents/highlight/{guid}

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/patent/README.md

Retrieves detailed patent information including highlighted sections.

```APIDOC
## GET /api/patents/highlight/{guid}

### Description
Fetches patent details including claims, abstract, and description HTML.

### Method
GET

### Endpoint
/api/patents/highlight/{guid}?queryId={id}&source={type}&includeSections=true

### Parameters
#### Path Parameters
- **guid** (string) - Required - The unique identifier of the patent

#### Query Parameters
- **queryId** (string) - Required - ID of the query
- **source** (string) - Required - Type of source
- **includeSections** (boolean) - Required - Whether to include HTML sections
```

--------------------------------

### Invoke biomcp from a local installation

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/R-ANALYSIS.md

Use an absolute path to the bundle when running from a local node_modules directory to ensure peer dependency resolution.

```bash
mkdir biomcp-r && cd biomcp-r && npm install biomcp webr
# client command array:
["node", "<ABSOLUTE_PATH>/biomcp-r/node_modules/biomcp/dist/bundle.js"]
```

--------------------------------

### patent_get

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Get detailed information for a specific patent.

```APIDOC
## patent_get

### Description
Get patent details with per-section source fallback chains.

### Parameters
- **patent_id** (string) - Required - e.g. "US11027025B2"
- **sections** (array) - Optional - "core", "abstract", "claims", "citations", "family", "classifications", "all"
- **limit** (number) - Optional - 1-100, default 20
```

--------------------------------

### Implement REST Connection

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/connections/README.md

REST-specific connection implementation supporting GET and POST requests with automatic content parsing.

```ts
class RestConnection implements IConnection<string, unknown> {
  constructor(options: ConnectionOptions);
  request(path: string): Promise<unknown>;
  post(path: string, body: Record<string, unknown>): Promise<unknown>;
  batch(paths: string[]): Promise<unknown[]>;
  healthCheck(): Promise<boolean>;
  close(): void;
}
```

--------------------------------

### batchGet

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Retrieves data for multiple entities independently by dynamically importing the appropriate entity get function.

```APIDOC
batchGet(inputs: BatchGetInput[]): Promise<BatchGetResult[]>
```

--------------------------------

### disease_get

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Get detailed disease information by ID.

```APIDOC
## disease_get

### Description
Get detailed disease information by ID.

### Parameters
- **disease_id** (string) - Required
- **sections** (array) - Optional - "core" | "gene_associations" | "phenotypes" | "pathways" | "all"
- **limit** (number) - Optional - 1-100, default 20
```

--------------------------------

### geo_get

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Get the full SOFT record from the GEO SOFT viewer.

```APIDOC
## geo_get

### Description
Get the full SOFT record from the GEO SOFT viewer. GSE/GSM/GPL return SOFT records.

### Parameters
- **accession** (string) - Required - e.g. GSE183947
- **download** (boolean) - Optional - Default false
- **max_bytes** (number) - Optional - Min 1000000, default 52428800
```

--------------------------------

### Local Tree MySQL Execution Command

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Use this command structure when invoking a locally installed biomcp instance with mysql2 dependencies.

```json
["node","<ABSOLUTE_PATH>/biomcp-mysql/node_modules/biomcp/dist/bundle.js"]
```

--------------------------------

### pdb

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Access RCSB PDB to search structures, get metadata, or download files.

```APIDOC
## pdb

### Description
Access RCSB PDB: search structures (query), get metadata (pdb_id), download files (pdb_id + download).

### Parameters
- **query** (string) - Optional - Search mode
- **pdb_id** (string) - Optional - Get mode
- **sections** (array) - Optional - "polymer_entities", "ligands", "assembly", "experiment", "citation", "all"
- **download** (boolean) - Optional - Default false
- **format** (string) - Optional - "cif", "pdb" (default "cif")
- **limit** (number) - Optional - 1-50, default 10
- **offset** (number) - Optional - default 0
```

--------------------------------

### Batch Retrieval

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Retrieves multiple entities in a single batch operation by dynamically importing the appropriate entity get function.

```ts
batchGet(inputs: BatchGetInput[]): Promise<BatchGetResult[]>
```

```ts
BatchGetInput { entity: string; id: string; sections?: string[] }
BatchGetResult { entity: string; id: string; success: boolean; data?: unknown; error?: string }
```

--------------------------------

### Initialize Database Query Tool

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/scripts/external-databases/depmap/README.md

Use the npx command with environment variables to launch the read-only database interface.

```bash
DB_TYPE=sqlite DB_SQLITE_PATH=scripts/external-databases/depmap/dist/depmap-26Q1.db npx .
```

--------------------------------

### initializeBackend

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Initializes a database backend connection for the application.

```APIDOC
## initializeBackend(config: BackendConfig)

### Description
Initializes a database backend (MySQL or SQLite). For SQLite, it supports attaching additional read-only databases.

### Parameters
- **type** (string) - Required - The database type ('sqlite' or 'mysql')
- **host** (string) - Required - Database host
- **port** (number) - Required - Database port
- **database** (string) - Required - Path or name of the main database
- **attach** (string[]) - Optional - List of additional database files to attach (SQLite only)

### Example
```ts
await initializeBackend({
  type: 'sqlite',
  host: 'localhost',
  port: 0,
  database: '/data/bio.db',
  attach: ['/data/depmap-26Q1.db']
});
```
```

--------------------------------

### Initialize Database Backend

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Configures the database backend, supporting multiple SQLite files via the attach field.

```ts
await initializeBackend({
  type: 'sqlite',
  host: 'localhost',
  port: 0,
  database: '/data/bio.db',          // main
  attach: ['/data/depmap-26Q1.db'],  // read-only, alias 'depmap_26q1'
});
```

--------------------------------

### Initialize McpServer with Stdio Transport

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Bootstraps the MCP server instance and connects it via standard I/O transport. Ensure the VERSION constant is correctly imported from the project configuration.

```ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new McpServer({ name: 'biomcp', version: VERSION });
// VERSION is imported from src/version.ts and mirrors package.json
// register tool modules...
const transport = new StdioServerTransport();
await server.connect(transport);
```

--------------------------------

### Build and Test Commands

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/README.md

Standard Makefile commands for managing the project lifecycle, including compilation, testing, and cleanup.

```makefile
make                # Show available targets
make install        # Install dependencies
make build          # Compile and bundle into dist/bundle.js
make typecheck      # tsc --noEmit
make test           # Unit tests (fast, mocked, parallel)
make test-integration # Integration tests (live APIs, serial, ~4-5 min)
make test-all        # All tests combined
make clean          # Remove build artifacts
```

--------------------------------

### Configure Database Environment Variables

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Set these variables to define the database backend and connection details.

```bash
# MySQL
DB_TYPE=mysql DB_HOST=localhost DB_PORT=3306 DB_USER=bio_user DB_PASSWORD=… DB_DATABASE=bio

# SQLite (local file)
DB_TYPE=sqlite DB_SQLITE_PATH=/data/bio.db

# SQLite (multiple files: first = main, rest attached read-only)
DB_TYPE=sqlite DB_SQLITE_PATH=/data/bio.db,/data/depmap-26Q1.db
```

--------------------------------

### Run database integration tests

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DEVELOPMENT.md

Commands to configure and run integration tests against a live MySQL database.

```bash
BIOMCP_DB_IT_HOST=127.0.0.1 BIOMCP_DB_IT_PORT=3306 \
BIOMCP_DB_IT_USER=root BIOMCP_DB_IT_PASSWORD=secret BIOMCP_DB_IT_DATABASE=bio \
npm run test:integration

# throwaway server:
docker run --rm -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=secret -e MYSQL_DATABASE=bio mysql:8.4
```

--------------------------------

### POST /api/users/me/session

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/patent/README.md

Initializes a new session for PPUBS searches.

```APIDOC
## POST /api/users/me/session

### Description
Creates a new session for performing parallel searches. Requires a body value of -1 and a null X-Access-Token header.

### Method
POST

### Endpoint
/api/users/me/session

### Response
- **x-access-token** (header) - Token for subsequent requests
- **caseId** (body) - Identifier for the session
```

--------------------------------

### Run SQLite Integration Tests

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/__tests__/README.md

Provide a comma-separated list of SQLite database paths to execute integration tests.

```bash
BIOMCP_DB_IT_SQLITE_PATH=/data/bio.db,/data/depmap-26Q1.db npm run test:integration
```

--------------------------------

### Build and configure DepMap database

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Commands for staging, verifying, and building the DepMap SQLite database, followed by the environment configuration to launch the application with the new database.

```bash
make depmap-list RAW_DIR=/path/to/staged/files   # what to stage + verification status
make depmap-build RAW_DIR=/path/to/staged/files   # md5-verify + build the SQLite DB
```

```bash
DB_TYPE=sqlite DB_SQLITE_PATH=scripts/external-databases/depmap/dist/depmap-26Q1.db npx .
```

--------------------------------

### Build and List DepMap Data via Makefile

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/scripts/external-databases/depmap/README.md

Use these Makefile targets to check staging status or initiate the database build process.

```bash
make depmap-list RAW_DIR=/path/to/staged/files   # show staging status + what to fetch
make depmap-build RAW_DIR=/path/to/staged/files   # verify + build dist/depmap-<release>.db
```

--------------------------------

### Run test suites

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DEVELOPMENT.md

Commands to execute various test levels, including unit and integration tests.

```bash
make test              # Unit tests (fast, mocked)
make test-integration  # Integration tests (live APIs, ~60s)
make test-all          # Everything
make test-coverage     # Unit tests with coverage report
```

--------------------------------

### Run MySQL Integration Tests

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/__tests__/README.md

Set the required environment variables to execute MySQL integration tests against a live server.

```bash
BIOMCP_DB_IT_HOST=127.0.0.1 \
BIOMCP_DB_IT_PORT=3306 \
BIOMCP_DB_IT_USER=root \
BIOMCP_DB_IT_PASSWORD=secret \
BIOMCP_DB_IT_DATABASE=bio \
npm run test:integration
```

--------------------------------

### Execute Test Suites via NPM

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/__tests__/README.md

Standard commands for running different categories of tests within the project.

```bash
npm test                # Unit tests only (fast, mocked, parallel)
npm run test:integration # Integration tests (real APIs, serial, ~60s)
npm run test:all         # All tests combined
npm run test:coverage    # Unit tests with coverage
```

--------------------------------

### Enable R Analysis with Peer Dependencies

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/README.md

Command to run the application with the required webr peer dependency for R analysis features.

```bash
["npx","-y","-p","biomcp@0.9","-p","webr@0.6","biomcp"]
```

--------------------------------

### Directory Structure Overview

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Visual representation of the server source code organization.

```text
src/server/
  index.ts            Server bootstrap, McpServer + StdioServerTransport
  errors.ts           BioMCPError types, formatError, withErrorHandling, section helpers
  validation.ts       Zod schemas, validateInput, isValidEntityInput, getEntitySuggestions
  tools/
    gene.ts           7 gene tools (search, get, diseases, drugs, trials, articles, enrich)
    variant.ts        4 variant tools (search, get, oncokb, trials)
    drug.ts           3 drug tools (search, get, trials)
    disease.ts        4 disease tools (search, get, drugs, trials)
    article.ts        2 article tools (search, get)
    trial.ts          2 trial tools (search, get)
    utility.ts        2 utility tools (discover, batch_get)
    pdb.ts            1 PDB tool (search, get, download)
    patent.ts         2 patent tools (search, get)
    geo.ts            2 GEO tools (search, get + optional download)
    sra.ts            2 SRA tools (search, get)
    genbank.ts        3 GenBank tools (search, get, genes)
    gtex.ts            2 GTEx tools (expression, eqtl)
    ensembl.ts         4 Ensembl tools (lookup, homology, consequence, region)
    configure.ts       1 config meta tool (biomcp_configure — always registered; .biomcp.json + env observability)
    db.ts              3 database tools (optional, DB_TYPE)
    ranalysis.ts       4 R analysis tools (optional, ANALYSIS_R)
    biowasm.ts         8 biowasm analysis tools (optional, ANALYSIS_BIOWASM)
```

--------------------------------

### Configure Biomcp Client

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

Execute the configuration command within the client to verify that enabled features are running.

```bash
biomcp_configure
```

--------------------------------

### Database Directory Layout

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/scripts/external-databases/README.md

Standard directory structure for each external database integration.

```text
scripts/external-databases/<database>/
  build.ts      CLI entry point
  README.md     usage, schema docs, licensing
  raw/          staged source files (gitignored)
  dist/         built SQLite databases (gitignored)
```

--------------------------------

### Register Database Tools with McpServer

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Use this to integrate database tools into an existing McpServer instance.

```ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerDbTools } from 'biomcp/db';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });
registerDbTools(server);
```

--------------------------------

### Define project configuration in .biomcp.json

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/ENV-VARS.md

Optional configuration file for enabling features like biowasm analysis and database settings. This file is loaded at server startup and is overridden by environment variables.

```json
{
  "features": {
    "analysis_biowasm": { "enabled": true, "workers": 2 },
    "database": { "enabled": true, "type": "sqlite", "sqlite_path": ["data/geo.db"] }
  }
}
```

--------------------------------

### Running Agent Tests

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/agent-test/README.md

Commands to execute the test suite, filter specific tests, or list available tests.

```bash
node agent-test/run.mjs --list                          # index table, no runs
node agent-test/run.mjs                                 # full suite
node agent-test/run.mjs --only biowasm-q03-point-depth  # single test
node agent-test/run.mjs --filter 'biowasm-q0*' --reps 2 # glob + repetitions
```

--------------------------------

### Publish project versions

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DEVELOPMENT.md

Makefile targets for publishing the package to npm.

```bash
make publish        # clean + build + unit tests, then npm publish
make publish-alpha  # same, tagged alpha
```

--------------------------------

### Build and maintenance commands

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DEVELOPMENT.md

Makefile targets for managing the build process, type checking, and cleaning artifacts.

```bash
make              # Show available targets
make install      # Install dependencies
make build        # Compile and bundle into dist/bundle.js (+ dist/db.js)
make typecheck    # Type-check src/ + scripts/ without emitting
make clean        # Remove build artifacts
```

--------------------------------

### registerDbTools

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Registers database tools to an existing McpServer instance.

```APIDOC
## registerDbTools(server: McpServer)

### Description
Registers the database toolset to a provided McpServer instance to enable database interaction capabilities.

### Usage
```ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { registerDbTools } from 'biomcp/db';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });
registerDbTools(server);
```
```

--------------------------------

### Access Source Registry

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/connections/README.md

Static registry definitions and helper functions for retrieving connection configurations.

```ts
const SOURCE_REGISTRY: Record<string, ConnectionOptions>;
```

```ts
function getSourceConfig(sourceId: string): ConnectionOptions;
function getSourcesByProtocol(protocol: string): ConnectionOptions[];
function getSourcesRequiringAuth(): ConnectionOptions[];
function getSourcesWithOptionalAuth(): ConnectionOptions[];
```

--------------------------------

### OpenCode MCP configuration

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

Configuration format for the opencode.json file.

```jsonc
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "biomcp": {
      "type": "local",
      "command": ["npx", "-y", "-p", "biomcp@0.9", "-p", "webr@0.6", "biomcp"],
      "environment": {},
      "enabled": true,
      "timeout": 30000
    }
  }
}
```

--------------------------------

### Reproduce client invocation

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

Execute the doctor command with the exact environment variables and package parameters used by the client to ensure accurate diagnostics.

```bash
ANALYSIS_R=1 npx -y -p biomcp@0.9 -p webr@0.6 biomcp doctor
```

--------------------------------

### Manage Zenodo Publishing

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/agent-test/README.md

Commands for interacting with the Zenodo publishing script to manage drafts, releases, and script updates.

```bash
# Full usage: node agent-test/zenodo-publish.mjs [--sandbox|--prod] [--publish]
#   [--discard [--record <id>]] [--data-root DIR] [--verify-download]
#   [--record <id> --new-version] [--update-scripts] [--list]
node agent-test/zenodo-publish.mjs --sandbox            # sandbox draft rehearsal
node agent-test/zenodo-publish.mjs --prod               # prod draft (private, inspectable)
node agent-test/zenodo-publish.mjs --prod --publish     # IRREVERSIBLE public release
node agent-test/zenodo-publish.mjs --prod --publish --verify-download  # + full re-download sha256
node agent-test/zenodo-publish.mjs --prod --discard --record <id>   # remove a draft
node agent-test/zenodo-publish.mjs --update-scripts     # point the 10 scripts at the manifest record
node agent-test/zenodo-publish.mjs --update-scripts --record <new-id>  # …or at an explicit record
```

--------------------------------

### Agent Test Directory Layout

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/agent-test/README.md

The standard structure for test directories, including configuration files, resource archives, and output logs.

```text
agent-test/
├── README.md                  this file
├── run.mjs                    runner + objective grader (plain ESM, node:stdlib only)
├── <TEST-NAME>/
│   ├── test.json              spec: prompt, externalData pins, checks, timeout
│   ├── opencode.json          per-run MCP config (credential-free, env-substituted)
│   ├── resources.tar.bz2      archived small fixtures + expected/ + groundtruth/ (<= 1 MB)
│   └── resources.download.sh  optional: pinned downloader for big external fixtures
└── .runs/                     (gitignored) logs, per-rep result.json, summary,
                               provenance, and the default external-data root
```

--------------------------------

### Configure opencode.json

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/agent-test/README.md

Defines the minimal, credential-free configuration for the test runner. The runner injects environment variables for the bundle and data directory.

```json
{"$schema":"https://opencode.ai/config.json","mcp":{"biomcp":{"type":"local","command":["node","{env:AGENT_TEST_BUNDLE}"],"environment":{"ANALYSIS_BIOWASM":"1","ANALYSIS_BIOWASM_DATA_DIR":"{env:AGENT_TEST_DATA}"}}}}
```

--------------------------------

### Windows MCP configuration

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

Required configuration for Windows environments to handle npx as a .cmd shim.

```json
{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "-p", "biomcp@0.9", "-p", "webr@0.6", "biomcp"]
}
```

--------------------------------

### Claude Desktop MCP configuration

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

JSON configuration for the Claude Desktop client.

```json
{
  "mcpServers": {
    "biomcp": {
      "command": "npx",
      "args": ["-y", "-p", "biomcp@0.9", "-p", "webr@0.6", "biomcp"],
      "env": {}
    }
  }
}
```

--------------------------------

### Execute agent E2E tests

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DEVELOPMENT.md

Commands to list and run specific user-agent end-to-end tests.

```bash
node agent-test/run.mjs --list                        # index table
node agent-test/run.mjs --only biowasm-q03-point-depth
```

--------------------------------

### Invoke biomcp with webr via npx

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/R-ANALYSIS.md

Use this command as the client's command array to run biomcp with the required webr peer dependency.

```bash
npx -y -p biomcp@0.9 -p webr@0.6 biomcp   # client command array (plain argv, no shell)
```

--------------------------------

### Access Zenodo Mirror

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/agent-test/README.md

The URL pattern used to download fixture files from Zenodo without requiring authentication.

```text
https://zenodo.org/records/<record_id>/files/<name>?download=1
```

--------------------------------

### Implement GraphQL Connection

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/connections/README.md

GraphQL-specific connection implementation for executing queries and variables.

```ts
class GraphQLConnection implements IConnection<string, unknown> {
  constructor(options: ConnectionOptions, auth?: AuthConfig);
  request(query: string, variables?: Record<string, unknown>): Promise<unknown>;
  batch(queries: string[]): Promise<unknown[]>;
  healthCheck(): Promise<boolean>;
  close(): void;
}
```

--------------------------------

### Verify CI gates locally

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/development/CI.md

Execute the full suite of CI checks locally to ensure compliance before pushing changes. The smoke test requires a running node process to validate the bundle.

```bash
npm ci                        # 1. install
make typecheck                # 2. typecheck (src + scripts)
npm test                      # 3. unit tests
npm run build                 # 4. bundles
npm audit --audit-level=low   # 5. full audit (expect: 0)
req='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
out=$({ echo "$req"; sleep 2; } | timeout 15 node dist/bundle.js)
echo "$out" | grep -q '"serverInfo"' && echo SMOKE_OK   # 6. stdio smoke
```

--------------------------------

### Manage Connection Lifecycle

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/connections/README.md

Factory and manager class for handling connection creation and lifecycle operations.

```ts
class ConnectionManager {
  getConnection(sourceId: string): IConnection<any, any>;
  createConnection(config: ConnectionOptions): IConnection<any, any>;
  healthCheckAll(): Promise<Record<string, boolean>>;
  closeAll(): void;
  listConnections(): string[];
}

const connectionManager: ConnectionManager;
```

--------------------------------

### Enable R Analysis via Environment Variable

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/R-ANALYSIS.md

Set this environment variable to enable the R analysis feature.

```bash
ANALYSIS_R=1
```

--------------------------------

### analysis_biowasm_cli

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/BIOWASM-ANALYSIS.md

Executes a samtools, bedtools, or bcftools subcommand with a schema-validated argument array.

```APIDOC
## analysis_biowasm_cli

### Description
Executes a constrained bioinformatics subcommand (samtools, bedtools, or bcftools) using a schema-validated argument array. This interface avoids shell execution and provides structured input/output handling.

### Parameters
- **source** (object) - Required - Defines how data arrives: {content: string}, {artifact_id: string}, or {host_path: string}.
- **index** (string/object) - Optional - The index sidecar: "auto" (default), {content}, or {host_path}.
- **region** (object) - Optional - Structured {chrom, start, end} (1-based inclusive) for region queries.
- **projection** (object) - Optional - {fields, samples} for VCF queries to reduce context.
- **format** (string) - Optional - Output format: "table", "json", or "artifact".
- **top_n** (number) - Optional - Number of rows to return (≤ 200).
- **include_content** (boolean) - Optional - Whether to inline artifacts ≤ 2 MB as base64(gzip).

### Response
- **io_stats** (object) - Bytes read and elapsed time for the operation.
- **exit_code** (number) - The exit status of the command.
- **is_error** (boolean) - Flag indicating if the command failed.
- **data** (any) - The resulting output based on the requested format.
```

--------------------------------

### Enable Biowasm via Environment Variable

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/BIOWASM-ANALYSIS.md

Set this environment variable to enable the optional Biowasm analysis feature.

```bash
ANALYSIS_BIOWASM=1
```

--------------------------------

### analysis_r_session_info

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/R-ANALYSIS.md

Retrieves the runtime environment report.

```APIDOC
## analysis_r_session_info

### Description
Returns a runtime report including R/webR versions, package versions, memory usage, and mirror endpoint.
```

--------------------------------

### Data Flow Execution Sequence

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/README.md

Visual representation of the request lifecycle from LLM tool invocation to the final response assembly.

```text
1. LLM calls tool (e.g., gene_get with symbol="BRAF", sections=["pathways","protein"])
2. server/tools/gene.ts handler receives typed params
3. → entities/gene.ts geneGet("BRAF", ["pathways","protein"])
4. → connections/manager.ts getConnection("mygene")  →  RestConnection (cached)
5. → connections/rest.ts request("/gene/BRAF")  →  fetch upstream
6. → transform/gene.ts transformMyGeneResponse(raw)
7. → Parallel section fetches via Promise.allSettled + fetchWithTimeout(fn, 8000)
   Each section: getConnection(source) → request() → transform
8. Assemble: { symbol, name, summary, sections: { pathways: {...}, protein: {...} } }
9. Handler returns MCP text content to LLM
```

--------------------------------

### biomcp_configure

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Unified configuration surface over the .biomcp.json project config file and environment variables.

```APIDOC
## biomcp_configure

### Description
Unified configuration surface over the .biomcp.json project config file + env vars.

### Parameters
- **action** (string) - Optional - "status" | "set" | "reset" (default "status")
- **values** (record) - Optional
- **target** (string|array) - Optional
- **filter** (string) - Optional
- **dry_run** (boolean) - Optional
- **confirm_sensitive** (boolean) - Optional
```

--------------------------------

### Configure Biowasm in Claude Desktop

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/BIOWASM-ANALYSIS.md

Add the biomcp server configuration to your Claude Desktop settings with the ANALYSIS_BIOWASM environment variable enabled.

```json
{
  "mcpServers": {
    "biomcp": {
      "command": "npx",
      "args": ["-p", "biomcp", "biomcp"],
      "env": {
        "ANALYSIS_BIOWASM": "1"
      }
    }
  }
}
```

--------------------------------

### pdbDownload

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Downloads a PDB file in CIF or PDB format.

```APIDOC
## pdbDownload(pdbId: string, format?: 'cif' | 'pdb')

### Description
Downloads the structural file for a given PDB ID. Defaults to 'cif' format.
```

--------------------------------

### Canonical npx command for biomcp

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

The standard command to execute biomcp with all features enabled.

```json
["npx", "-y", "-p", "biomcp@0.9", "-p", "webr@0.6", "biomcp"]
```

--------------------------------

### Article Module Directory Structure

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Visual representation of the file organization within the article entity directory.

```text
article/
├── index.ts              # Re-exports all public API
├── types.ts              # Article, ArticleSearchOptions, ArticleResult, ArticleGetOptions
├── europepmc-shared.ts   # Shared EuropePMC helpers
├── semantic-scholar-queue.ts  # Global single-flight queue for ALL Semantic Scholar traffic
├── search/               # Search backends (5 sources)
│   ├── index.ts          # articleSearch() orchestrator + federatedSearch (20s per-backend throw timeout)
│   ├── dedup.ts          # deduplicateAndRank()
│   ├── pubmed.ts         # searchPubMed(), formatPubMedDate()
│   ├── europepmc.ts      # searchEuropePMC(), transformEuropePMC() (cursorMark deep pagination)
│   ├── semantic-scholar.ts # searchSemanticScholar(), transformSemanticScholar()
│   ├── pubtator.ts       # searchPubTator(), transformPubTator()
│   └── litsense.ts       # searchLitSense(), transformLitSense()
├── detail/               # Article get + sections
│   ├── index.ts          # articleGet() orchestrator (sections run via Promise.allSettled)
│   ├── id-resolution.ts  # parseArticleId(), resolveToPmid(), resolveDoiToPmid()
│   ├── open-access.ts    # fetchOpenAccess(), parseOaXml()
│   └── annotations.ts    # fetchAnnotations(), fetchCitationGraph()
├── citation/             # Citation providers
│   ├── index.ts          # getCitations() orchestrator (federated)
│   ├── types.ts          # ArticleId, CitationRecord, CitationCount, FederatedCitationResult
│   ├── cache.ts          # 10-minute federated result cache
│   ├── pubmed.ts         # PubMed elink-based provider (+ EFetch enrichment)
│   ├── europepmc.ts      # EuropePMC citations/references API
│   ├── semantic-scholar.ts # Semantic Scholar graph API
│   ├── crossref.ts       # Crossref count + backward references provider
│   └── opencitations.ts  # OpenCitations v2 DOI-based provider
└── transform/
    └── pubmed.ts         # parsePubMedXml()
```

--------------------------------

### db_list_tables

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Retrieves a list of tables and views across all configured databases, including metadata like engine, row count, and creation time.

```APIDOC
## db_list_tables

### Description
List tables and views across every configured database. Returns a structured list including database aliases, table counts, and per-table metadata.
```

--------------------------------

### Test Directory Structure

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/__tests__/README.md

Layout of the src/__tests__ directory, organizing tests by module and functionality.

```text
src/__tests__/
  helpers/
    mcp-harness.ts       # In-process MCP client harness (InMemoryTransport)
    assertions.ts        # Type-guard validators (expectGeneSearchResult, ...)
    retry.ts             # retryOnRateLimit for integration tests
  biowasm/               # biowasm analyzers, artifacts, engine, registry, schemas, validation
  config/
    handler.test.ts      # biomcp_configure brain: registry drift guards, loader precedence,
                         #   set/reset closed-set validation, masking, cwd refusal
    store.test.ts        # .biomcp.json persistence: atomic writes, symlink/size guards, git exclude
  connections/
    fetch-utils.test.ts
    graphql.test.ts
    manager.test.ts
    proxy.test.ts
    rate-limiter.test.ts
    registry.test.ts
    rest.test.ts
    retry.test.ts
  db/                    # db tools gating, env parsing, mysql translator, sqlite backend, validator
  entities/
    article.test.ts
    citation.test.ts
    citation/
      cache.test.ts
    cross-entity.test.ts
    dedup.test.ts
    disease.test.ts
    drug.test.ts
    gene.test.ts
    id-resolution.test.ts
    patent.test.ts
    pdb.test.ts
    pubmed-transform.test.ts
    trial.test.ts
    variant.test.ts
  integration/
    tools/               # 18 files — real API calls via the MCP harness
      article-tools.test.ts
      biowasm-engine.integration.test.ts
      biowasm-tools.integration.test.ts
      db-tools.test.ts
      disease-tools.test.ts
      drug-tools.test.ts
      ensembl-tools.test.ts
      genbank-tools.test.ts
      gene-tools.test.ts
      geo-tools.test.ts
      gtex-tools.test.ts
      patent-tools.test.ts
      pdb-tools.test.ts
      ranalysis-tools.integration.test.ts
      sra-tools.test.ts
      trial-tools.test.ts
      utility-tools.test.ts
      variant-tools.test.ts
    depmap/
      manifest.test.ts
  ranalysis/             # R engine, mirror, render, input validation
  scripts/
    depmap/              # ETL script unit tests (csv, datasets, ingest, manifest, staging)
  server/
    biowasm-tools.test.ts
    configure-tools.test.ts     # biomcp_configure MCP tool over a real McpServer (tmp cwd)
    ensembl-tools.test.ts
    errors.test.ts
    genbank-tools.test.ts
    geo-tools.test.ts
    gtex-tools.test.ts
    progress-forwarder.test.ts
    ranalysis-tools.test.ts
    sra-tools.test.ts
    tool-registration.test.ts   # Tool registration counts (mocked, unit)
    tool-utils.test.ts          # applyLimit, sliceArraysRecursive
    validation.test.ts
    version.test.ts
  transform/
    gene.test.ts
    pdb.test.ts
  wasmcore/              # shared wasm support core (assets, memwatch, progress, queue)
```

--------------------------------

### articleGet

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Retrieves detailed information for a specific article by its identifier.

```APIDOC
## articleGet(identifier: string, sections?: string[]): Promise<ArticleResult>

### Description
Fetches full details for an article based on a provided identifier (e.g., PMID, DOI). Optionally retrieves specific sections of the article content.

### Parameters
- **identifier** (string) - Required - The unique ID of the article.
- **sections** (string[]) - Optional - Specific sections to retrieve.
```

--------------------------------

### Codex CLI MCP configuration

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/AGENT-INSTALL.md

Commands and TOML configuration for adding biomcp to Codex.

```bash
codex mcp add biomcp -- npx -y -p biomcp@0.9 -p webr@0.6 biomcp
```

```toml
[mcp_servers.biomcp]
command = "npx"
args = ["-y", "-p", "biomcp@0.9", "-p", "webr@0.6", "biomcp"]

[mcp_servers.biomcp.env]
# NCBI_API_KEY = "…"
```

--------------------------------

### Define Connection Interfaces and Types

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/connections/README.md

Core type definitions and the IConnection interface for managing data source connections.

```ts
type ProtocolType = 'rest' | 'graphql';

type AuthDeliveryMethod =
  | { type: 'header'; name: string }
  | { type: 'bearer' }
  | { type: 'authorization'; prefix?: string }
  | { type: 'query-param'; name: string };

interface AuthConfig {
  envVar: string;
  required: boolean;
  delivery: AuthDeliveryMethod;
  fallbackRateLimitMs?: number;
  keyedRateLimitMs?: number;
}

interface RateLimitConfig {
  intervalMs: number;
  conditional?: boolean;
  fallbackRateLimitMs?: number;
  keyedRateLimitMs?: number;
}

interface ConnectionHandling {
  streaming?: boolean;
  timeoutMs?: number;
  batchable?: boolean;
  maxBatchSize?: number;
  contentType?: 'json' | 'xml' | 'text' | 'binary';
  staleHours?: number;
  headers?: Record<string, string>;
}

interface ConnectionOptions {
  sourceId: string;
  baseUrl: string;
  protocol: ProtocolType;
  auth?: AuthConfig;
  rateLimit: RateLimitConfig;
  handling?: ConnectionHandling;
}

interface IConnection<TRequest = string, TResponse = unknown> {
  readonly sourceId: string;
  readonly protocol: ProtocolType;
  effectiveRateLimitMs: number;
  request(req: TRequest, variables?: Record<string, unknown>): Promise<TResponse>;
  batch?(requests: TRequest[]): Promise<TResponse[]>;
  healthCheck(): Promise<boolean>;
  close(): void;
}

type AnyConnection = IConnection;
```

--------------------------------

### POST /api/searches/searchWithBeFamily

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/patent/README.md

Performs a patent search using the PPUBS search engine.

```APIDOC
## POST /api/searches/searchWithBeFamily

### Description
Executes a patent search. The 'sort' field is required in the request body. Valid sort values are 'score desc' and 'date_publ desc'.

### Method
POST

### Endpoint
/api/searches/searchWithBeFamily

### Parameters
#### Request Body
- **sort** (string) - Required - 'score desc' or 'date_publ desc'
- **start** (integer) - Optional - Pagination offset
- **databaseFilters** (object) - Optional - Filters for granted/applications
```

--------------------------------

### Direct Jest Execution

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/__tests__/README.md

Required command for invoking Jest directly to maintain ESM compatibility.

```bash
node --experimental-vm-modules node_modules/.bin/jest [args…]
```

--------------------------------

### Entity Module Interface Pattern

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/README.md

Standardized function signatures for entity search and retrieval operations across all modules.

```typescript
entitySearch(query, options?) → SearchResult[]
entityGet(id, sections?)      → { ...core, sections: Record<string, unknown> }
```

--------------------------------

### db_describe_table

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Retrieves the schema information for a specific table, including column names, types, nullability, and key constraints.

```APIDOC
## db_describe_table

### Description
Get column schema for a specified table. Accepts a table name or an alias.table format for attached databases.

### Parameters
- **table** (string) - Required - The name of the table to describe (optionally prefixed with database alias).
```

--------------------------------

### db_query

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Execute a read-only SQL SELECT query.

```APIDOC
## db_query

### Description
Execute a read-only SELECT query with named parameters. Restricted to SELECT/SHOW/DESCRIBE/EXPLAIN/WITH statements.

### Parameters
- **sql** (string) - Required - The SQL query string.
- **params** (object) - Optional - Named parameters for the query.
```

--------------------------------

### Configure Rate Limiting

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/connections/README.md

Rate limiter classes for managing request frequency based on configuration.

```ts
class TokenBucketRateLimiter {
  constructor(config: RateLimitConfig, hasKey?: boolean);
  acquire(): Promise<void>;
  updateRateLimit(newConfig: RateLimitConfig, hasKey: boolean): void;
}

class RateLimiterFactory {
  static create(config: RateLimitConfig, hasKey?: boolean): TokenBucketRateLimiter;
  static getEffectiveRate(baseRate: number, config: RateLimitConfig, hasKey: boolean): number;
}
```

--------------------------------

### drugGet(name: string, sections?: string[])

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Retrieves detailed drug information by name, optionally filtering by specific data sections.

```APIDOC
## drugGet

### Description
Resolves a drug name to a ChEMBL ID and retrieves detailed information. Supports sections: us_regulatory, eu_regulatory, who_regulatory, safety, targets, and indications.

### Signature
`drugGet(name: string, sections?: string[]): Promise<DrugResult>`
```

--------------------------------

### patent_search

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Search patents worldwide using various backends.

```APIDOC
## patent_search

### Description
Search patents worldwide. Backends include ppubs, ops, uspto_odp, and google_patents.

### Parameters
- **query** (string) - Required - Quote exact multi-word concepts
- **assignee** (string) - Optional
- **inventor** (string) - Optional
- **cpc** (string) - Optional - Full symbol e.g. "C12N15/11"
- **status** (string) - Optional - "granted", "application"
- **date_range** (string) - Optional - YYYY-MM-DD/YYYY-MM-DD
- **limit** (number) - Optional - 1-50, default 10
- **offset** (number) - Optional - default 0
- **source** (string) - Optional - "ops", "uspto_odp", "ppubs", "google_patents"
- **sort_by** (string) - Optional - "relevance", "recency"
- **seminal** (boolean) - Optional - Default true
```

--------------------------------

### db_query

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Executes a read-only SELECT query against the database using named parameters. It supports SELECT, SHOW, DESCRIBE, EXPLAIN, and read-only CTEs.

```APIDOC
## db_query

### Description
Execute a read-only SELECT query with named parameters (:name). This tool enforces read-only access and prevents destructive operations.

### Parameters
- **sql** (string) - Required - The SQL query string using named parameters.
- **params** (object) - Optional - A map of parameter names to values.

### Request Example
{
  "sql": "SELECT symbol FROM genes WHERE chromosome = :chr ORDER BY id LIMIT :n",
  "params": { "chr": "7", "n": 10 }
}
```

--------------------------------

### pdbGet

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Retrieves metadata for a specific PDB entry.

```APIDOC
## pdbGet(pdbId: string, sections?: string[])

### Description
Fetches PDB entry details. Supports specific sections like 'polymer_entities', 'ligands', 'assembly', 'experiment', or 'citation'.
```

--------------------------------

### Execute Cross-Database SQL Query

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Perform a JOIN operation across multiple attached SQLite databases using alias-qualified table names.

```sql
SELECT m.CellLineName, e.value
FROM depmap_26q1.gene_effect e JOIN depmap_26q1.models m ON m.model_id = e.model_id
WHERE e.gene_symbol = 'KRAS' ORDER BY e.value ASC LIMIT 10
```

--------------------------------

### genbank_get

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/server/README.md

Fetches a nucleotide record from GenBank.

```APIDOC
## genbank_get

### Description
Fetch a nucleotide record (esummary metadata + efetch text).

### Parameters
- **accession** (string) - Required - Versioned or bare accession.
- **format** (string) - Optional - 'genbank' or 'fasta', default 'genbank'.
- **seq_start** (number) - Optional - 1-based inclusive start.
- **seq_stop** (number) - Optional - 1-based inclusive stop.
- **strand** (number) - Optional - 1 or 2.
- **max_response_bytes** (number) - Optional - Default 30000000.
```

--------------------------------

### patentGet

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Retrieves detailed information for a specific patent by its publication number.

```APIDOC
## patentGet(publicationNumber: string, sections?: string[]): Promise<PatentResult>

### Description
Fetches detailed patent data for a given publication number, with optional filtering for specific sections.

### Parameters
- **publicationNumber** (string) - Required - The unique publication identifier for the patent.
- **sections** (string[]) - Optional - A list of specific sections to retrieve (e.g., core, abstract, claims, citations, family, classifications).
```

--------------------------------

### trialGet

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Retrieves detailed information for a specific clinical trial by its NCT ID.

```APIDOC
## trialGet(nctId: string, sections?: string[])

### Description
Fetches the full study record for a given NCT ID. Optional sections like 'eligibility', 'locations', or 'outcomes' can be specified.
```

--------------------------------

### Execute a read-only SQL query

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/docs/DATABASE.md

Use this JSON structure to perform read-only SELECT queries with named parameters.

```json
{
  "sql": "SELECT symbol FROM genes WHERE chromosome = :chr ORDER BY id LIMIT :n",
  "params": { "chr": "7", "n": 10 }
}
```

--------------------------------

### getGtexDatasets

Source: https://github.com/yeyuan98/biomcp-ts/blob/main/src/entities/README.md

Retrieves the list of available GTEx datasets.

```APIDOC
## getGtexDatasets()

### Description
Fetches available GTEx datasets from the metadata API.

### Returns
- **Promise<GTExDatasetInfo[]>**
```