Metadata-Version: 2.4
Name: biotools-mcp
Version: 0.1.0
Summary: Verified bioinformatics tools for AI agents — sequence utilities + statistics, backed by BioPython/scipy, exposed as an MCP server, companion Skill, and Python package.
Author-email: Madhusudan Kulkarni <96856144+madhusudan-kulkarni@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,bioinformatics,biopython,mcp,scipy,sequence-analysis,statistics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: biopython>=1.84
Requires-Dist: mcp>=2.0.0
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.0
Requires-Dist: scipy>=1.12
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# biotools-mcp

**Verified bioinformatics tools for AI agents** — sequence utilities + statistics, backed by
BioPython/scipy, exposed as an MCP server, companion Skill, and Python package.

MIT · public · benchmarked.

> Research agents hallucinate bioinformatics math. This project builds the missing layer:
> battle-tested scientific computation wrapped in a clean, verified, agent-native surface.

## What's inside

- **Sequence utilities** — GC content, reverse complement, translation, ORF finding, motif
  scanning, sequence stats (BioPython-backed; ORF finder + motif-overlap are custom, verified
  against independent references).
- **Statistics** — descriptive stats, t-test, chi-square, Mann–Whitney U, correlation
  (scipy-backed, reference-vector tested against published/R values).
- **MCP server** — stdio + streamable HTTP, 11 action-oriented tools
  (`seq_gc_content`, `stats_t_test`, …), pydantic v2 schemas with structured output.
- **Companion Skill** — agentskills.io spec: when to use which tool, input requirements,
  and what **not** to do.

Every tool is reference-vector tested against published values (GenBank records, R `t.test`
output, Mendel's 1866 pea counts, Anscombe's quartet) — **never** against the wrapper itself.

## Install

Requires Python 3.11+.

```bash
# Install as a standalone CLI (MCP server entry point)
uv tool install biotools-mcp

# Or run without installing
uvx biotools-mcp
```

As a library:

```bash
uv add biotools-mcp
```

```python
from biotools_mcp.seq import gc_content
from biotools_mcp.stats import t_test

print(gc_content("ATGGCCATTGTAATGGGCCGCTGAAAGGGTGCCCGATAG").gc_percent)  # 56.4103
print(t_test([1, 2, 3], [4, 5, 6]).statistic)                          # -3.6742
```

## MCP configuration

Point your agent at the server over stdio:

**Claude Code** (`.mcp.json`):

```json
{
  "mcpServers": {
    "biotools-mcp": {
      "command": "uvx",
      "args": ["biotools-mcp"]
    }
  }
}
```

**Cursor** — Settings → MCP → Add:

```json
{
  "mcpServers": {
    "biotools-mcp": {
      "command": "uvx",
      "args": ["biotools-mcp"]
    }
  }
}
```

**Codex / Gemini CLI** — same `mcpServers` block in the agent's MCP config file.

**Streamable HTTP** (for remote use):

```bash
uvx biotools-mcp --transport streamable-http
```

## Tools

| Tool | Description |
|---|---|
| `seq_gc_content` | GC content as a percentage (ambiguous bases excluded) |
| `seq_reverse_complement` | Reverse complement (IUPAC-aware, DNA/RNA) |
| `seq_translate` | Translate to protein (NCBI tables, incl. mitochondrial) |
| `seq_orf_finder` | Open reading frames, forward strand, frames 0–2 |
| `seq_motif_scan` | IUPAC motif scanning with bracket groups + overlap policy |
| `seq_stats` | Length, mono/di composition, GC skew |
| `stats_describe` | Descriptive statistics (n, mean, median, var, skew, kurtosis) |
| `stats_t_test` | Student/Welch two-sample t-test with Cohen's d |
| `stats_chi_square` | Chi-square test of independence (Yates optional) |
| `stats_mann_whitney` | Mann-Whitney U test (exact/asymptotic) |
| `stats_correlation` | Pearson or Spearman correlation |

## Benchmarks

Wedge subset of BioAgent Bench + BioTaskBench (sequence utilities + statistics) run against
the tools and published in [benchmarks/results.md](benchmarks/results.md). Every task in the
subset runs — failures are published alongside passes.

**Current: 15/15 passed (100%)** — pinned harness, see the results file for task-level detail.

## Companion Skill

The [skills/biotools-mcp](skills/biotools-mcp/SKILL.md) skill (agentskills.io spec) teaches
agents the tool inventory, when to use which tool, input requirements, and what **not** to do
(never compute GC/translation/t-tests by hand). Load it into any skills-compatible agent.

## Development

```bash
uv sync --extra dev
uv run pytest          # reference-vector test suite
uv run python benchmarks/harness.py --suite all   # regenerate benchmark results
uvx ruff check src tests benchmarks
```

CI runs lint + tests on Python 3.11/3.12; a nightly workflow regenerates the benchmark table.

## License

MIT — see [LICENSE](LICENSE).
