@biocontext7/mcp

TypeScript MCP server for biocontext7 — bioinformatics tool discovery and documentation.

Works like Context7 but for bioinformatics: search 47,000+ tools and pull their docs straight into your Claude context.

Quick Start

Claude Code (one-liner)

claude mcp add biocontext7 -- npx -y @biocontext7/mcp@latest

Run directly

npx @biocontext7/mcp

Tools

The server exposes five MCP tools:

| Tool | Description | |------|-------------| | resolve-library-id | Search for bioinformatics tools by name or keyword | | get-library-docs | Fetch documentation for a specific tool by ID | | find-skills | Semantic skill search over 47K+ tools with quality scoring | | recommend-tools | Get ranked tool recommendations for analysis tasks | | report-snippet-quality | Report snippet helpfulness for relevance feedback |

resolve-library-id

Search for bioinformatics tools by name or keyword. Returns matched tool IDs with metadata.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Search query (e.g. "STAR", "alignment", "RNA-seq") |

Example request:

{
  "query": "sequence alignment"
}

Example response:

Found 5 tool(s) matching "sequence alignment":

- **STAR** (ID: `star`, v2.7.11b): Spliced Transcripts Alignment to a Reference [42 doc snippets, 8 examples]
- **BWA** (ID: `bwa`, v0.7.18): Burrows-Wheeler Aligner [31 doc snippets, 5 examples]
- **Bowtie2** (ID: `bowtie2`, v2.5.3): Fast short read aligner [28 doc snippets, 6 examples]

get-library-docs

Fetch documentation for a specific bioinformatics tool by ID. Supports topic filtering, version selection, and token budget control.

Parameters:

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | id | string | Yes | — | Tool ID from resolve-library-id (e.g. "star", "bwa") | | topic | string | No | — | Topic filter to narrow documentation (e.g. "2-pass alignment") | | mode | "chunks" \| "document" | No | "chunks" | "chunks" returns ranked snippets via BM25/semantic search; "document" returns full source documents in original order | | maxTokens | integer | No | 5000 | Maximum tokens to return (min: 1000). Highest-relevance snippets first. | | token_budget | integer | No | — | Deprecated alias for maxTokens. Use maxTokens instead; when both are provided, token_budget takes precedence. | | version | string | No | latest | Version to fetch docs for (e.g. "3.20" for Bioconductor) | | chunk_size | integer | No | 2000 | Max characters per snippet (min: 500, max: 4000) |

Example request:

{
  "id": "star",
  "topic": "2-pass alignment",
  "maxTokens": 3000
}

Example response:

# STAR (v2.7.11b)

Spliced Transcripts Alignment to a Reference

## Documentation

STAR's 2-pass alignment mode improves sensitivity for novel splice junction detection...

---

For 2-pass alignment, use --twopassMode Basic which performs a first pass to discover junctions...

## Code Examples

\```
STAR --runThreadN 8 --genomeDir /path/to/index --readFilesIn sample_R1.fq.gz sample_R2.fq.gz \
     --twopassMode Basic --outSAMtype BAM SortedByCoordinate
\```

find-skills

Semantic skill search over 47K+ tools with quality scoring (bc7score). Returns ranked results with install commands, health signals, and EDAM annotations. This is the most powerful single-call search tool — it combines discovery, scoring, and actionable install info.

Skills returned by this tool are auto-compiled from live documentation via the skill compiler pipeline — not hand-crafted prompts. The pipeline crawls upstream sources (ReadTheDocs, Bioconductor vignettes, GitHub READMEs), segments tutorials into workflow-specific references, and compiles them into structured SKILL.md files with content-hash versioning for incremental updates.

Parameters:

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | task_description | string | Yes | — | The bioinformatics task you need tools for | | top_k | integer | No | 5 | Number of results (max: 20) | | include_docs | boolean | No | false | Include documentation snippets | | include_install | boolean | No | true | Include install commands | | compact | boolean | No | true | Compact results optimized for LLM context | | platform | string | No | — | Target platform (e.g. "darwin-arm64", "linux-x86_64") | | token_budget | integer | No | 3000 | Maximum tokens for the response (min: 500, max: 10000) |

Example request:

{
  "task_description": "single-cell RNA-seq clustering and visualization",
  "top_k": 3,
  "compact": true,
  "platform": "linux-x86_64"
}

Example response:

Found 127 matching tools (showing top 3):

### Scanpy (Gold)
ID: `scanpy` | bc7score: 92 | relevance: 0.95
Single-cell analysis in Python — clustering, visualization, differential expression
**EDAM:** Single-cell analysis, Clustering, Dimensionality reduction
**Install** (recommended: pip):
  pip: `pip install scanpy`
  conda: `conda install -c bioconda scanpy`
**Health:** active | 2100 stars | last commit: 2025-12-15

---

### Seurat (Gold)
ID: `seurat` | bc7score: 89 | relevance: 0.91
R toolkit for single-cell genomics...

recommend-tools

Get opinionated, ranked tool recommendations for a bioinformatics analysis task. Returns top 3 tools with justification, benchmark references, installation difficulty, compute requirements, and community adoption signals.

Covers 10 analysis patterns: bulk RNA-seq DE, scRNA-seq clustering, variant calling, spatial deconvolution, ChIP/ATAC-seq peaks, genome assembly, metagenomics, protein structure, variant annotation, long-read analysis.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | Analysis task description (e.g. "bulk RNA-seq differential expression") | | pattern | string | No | Explicit analysis pattern ID to skip query matching (e.g. "spatial_deconvolution") |

Example request:

{
  "query": "For 10x Visium spatial data, what tool for deconvolution?"
}

report-snippet-quality

Report whether a documentation snippet was helpful or unhelpful. Unhelpful snippets are penalized in subsequent retrievals within the session, improving relevance over time.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | chunk_id | integer | Yes | The chunk_id from a get-library-docs response | | helpful | boolean | Yes | Whether the snippet was helpful | | session_id | string | No | Session identifier for scoped feedback | | query | string | No | Original query that returned this snippet |

Typical Workflow

Two-step: search then docs

1. resolve-library-id("RNA-seq alignment")
   → Returns: star, hisat2, bwa, ...

2. get-library-docs(id="star", topic="2-pass", maxTokens=3000)
   → Returns: documentation snippets + code examples

Single-call: find-skills

1. find-skills(task_description="single-cell RNA-seq clustering", compact=true)
   → Returns: ranked tools with install commands, scores, and health signals

find-skills is the recommended entry point for most use cases — it returns everything needed to evaluate and install tools in a single call, optimized for LLM context windows.

Token Usage

The server is designed to minimize token consumption in LLM contexts:

| Feature | Description | |---------|-------------| | Compact mode | find-skills defaults to compact: true, returning concise results optimized for LLM context | | Token budgets | get-library-docs and find-skills accept maxTokens / token_budget to control response size | | Structured JSON | get-library-docs returns structuredContent metadata (snippet count, total tokens, truncation status) alongside text | | Chunk size control | get-library-docs accepts chunk_size (500–4000 chars) to tune snippet granularity | | Call limits | Max 3 calls per tool per question to prevent runaway usage |

Comparison with Context7

| | biocontext7 | Context7 | |---|-------------|----------| | Domain | Bioinformatics (47K+ tools) | General-purpose (all libraries) | | Tools | 5 (search, docs, skills, recommend, feedback) | 2 (resolve, get-docs) | | Skill search | find-skills — single-call with install + scoring | N/A | | Recommendations | recommend-tools — benchmark-backed | N/A | | Platform filtering | platform parameter on find-skills | N/A | | Compact mode | Default on find-skills | N/A | | Relevance feedback | report-snippet-quality loop | N/A | | EDAM ontology | Semantic operation/topic annotations | N/A | | Version selection | version parameter on get-library-docs | N/A |

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "biocontext7": {
      "command": "npx",
      "args": ["-y", "@biocontext7/mcp@latest"]
    }
  }
}

Claude Code

One-liner install:

claude mcp add biocontext7 -- npx -y @biocontext7/mcp@latest

Or add manually to your .mcp.json:

{
  "mcpServers": {
    "biocontext7": {
      "command": "npx",
      "args": ["-y", "@biocontext7/mcp@latest"]
    }
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | BIOCONTEXT7_API_URL | Backend API base URL | https://api.biocontext7.com | | BIOCONTEXT7_API_KEY | API key for authentication | — | | PORT | Port for SSE/HTTP transports | 3100 | | MCP_RATE_LIMIT_STORE | Rate-limit backend (memory or redis) | memory | | MCP_RATE_LIMIT_REDIS_URL | Redis URL when MCP_RATE_LIMIT_STORE=redis | — | | MCP_RATE_LIMIT_KEY_PREFIX | Optional counter key prefix | biocontext7:mcp:ratelimit |

Transport Modes

# stdio (default) — for local Claude usage
npx @biocontext7/mcp

# SSE transport — for streaming clients
npx @biocontext7/mcp --transport sse

# HTTP transport — for remote deployment
npx @biocontext7/mcp --transport http

HTTP Endpoints

When running in HTTP or SSE transport mode, the following endpoints are available:

| Endpoint | Auth | Description | |----------|------|-------------| | /mcp | Anonymous / API key / OAuth | Main MCP endpoint for tool calls | | /mcp/oauth | OAuth JWT only | OAuth-protected MCP endpoint | | /health | None | Health check | | /.well-known/oauth-protected-resource | None | RFC 9728 resource metadata (requires OAuth config) | | /.well-known/oauth-authorization-server | None | RFC 8414 authorization server metadata proxy (requires OAuth config) |

Rate Limiting

Rate limiting is enforced on MCP tool endpoints (/mcp, /mcp/oauth, /messages) with health checks excluded.

Default Limits

| Tier | Requests/minute | Requests/hour | Scope | |------|-----------------|---------------|-------| | anonymous | 100 | 1,000 | Per IP | | free (API key) | 300 | 3,000 | Per IP + per API key | | pro | 1,000 | 10,000 | Per IP + per API key | | enterprise | 5,000 | 50,000 | Per IP + per API key |

All MCP responses include:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset
• X-RateLimit-Tier

When a limit is exceeded, the server returns 429 with:

• Retry-After header
• JSON body with error, retry_after, window, and identifier metadata

OAuth Discovery Flow

When OAuth is enabled, the MCP server supports standards-compliant client discovery:

1. A client sends a request to /mcp/oauth without credentials
2. The server returns 401 with a WWW-Authenticate: Bearer resource_metadata="<url>" header (RFC 9728)
3. The client fetches /.well-known/oauth-protected-resource to discover the authorization server
4. The client fetches /.well-known/oauth-authorization-server to discover authorization and token endpoints
5. The client completes the OAuth flow and retries with a valid JWT

OAuth Environment Variables

| Variable | Description | |----------|-------------| | OAUTH_JWKS_URI | JWKS endpoint for JWT validation | | OAUTH_ISSUER | Expected JWT issuer | | OAUTH_AUDIENCE | Expected JWT audience (optional) | | OAUTH_AUTH_SERVER | Authorization server URL | | MCP_AUTH_REQUIRED | Require auth on /mcp (default: false) |

Programmatic Usage

import { createServer } from "@biocontext7/mcp/server";
import type { ClientConfig } from "@biocontext7/mcp/types";

const server = createServer({ baseUrl: "https://api.example.com" });

Exports

| Path | Exports | |------|---------| | @biocontext7/mcp | Default entry point | | @biocontext7/mcp/client | Biocontext7Client HTTP client | | @biocontext7/mcp/server | createServer factory | | @biocontext7/mcp/types | Shared TypeScript types |

Local Development

cd packages/mcp
pnpm install
pnpm build
pnpm test        # vitest run
pnpm dev         # tsc --watch
pnpm lint        # tsc --noEmit

Publishing

cd packages/mcp
npm publish

The prepublishOnly script runs clean && build automatically before publish. The package is configured with publishConfig.access: "public" for the @biocontext7 scope.