rnacentral-mcp-server 0.1.0__tar.gz

rnacentral_mcp_server-0.1.0/.gemini/settings.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "rnacentral-search": {
+      "command": "/Users/agreen/code/rnacentral-mcp-server/.venv/bin/python",
+      "args": [
+        "/Users/agreen/code/rnacentral-mcp-server/rnacentral_sequence_search/server.py"
+      ]
+    }
+  }
+}

rnacentral_mcp_server-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: Build and deploy docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Sync docs dependencies
+        run: uv sync --extra docs
+
+      - name: Build HTML
+        run: uv run sphinx-build -b html docs docs/_build/html
+
+      - name: Disable Jekyll
+        run: touch docs/_build/html/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

rnacentral_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+
+## Generated documentation stuff
+docs/_build

rnacentral_mcp_server-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

rnacentral_mcp_server-0.1.0/.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  commands:
+    - asdf plugin add uv
+    - asdf install uv latest
+    - asdf global uv latest
+    - uv sync --extra docs
+    - uv run sphinx-build -b html docs $READTHEDOCS_OUTPUT/html
+
+sphinx:
+  configuration: docs/conf.py

rnacentral_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RNAcentral
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rnacentral_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: rnacentral-mcp-server
+Version: 0.1.0
+Summary: An MCP server for RNAcentral, providing RNA sequence search, ID mapping, genomic context, and 2D structures.
+Project-URL: Homepage, https://github.com/RNAcentral/rnacentral-mcp-server
+Author-email: Andrew Green <agreen@ebi.ac.uk>
+License: MIT License
+        
+        Copyright (c) 2026 RNAcentral
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: bioinformatics,mcp,model-context-protocol,rna,rnacentral
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.11.18
+Requires-Dist: click>=8.1.8
+Requires-Dist: mcp[cli]>=1.8.0
+Provides-Extra: docs
+Requires-Dist: linkify-it-py>=2.0; extra == 'docs'
+Requires-Dist: myst-parser>=2.0; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# RNAcentral MCP Server
+
+[![Documentation](https://img.shields.io/badge/docs-github%20pages-blue)](https://rnacentral.github.io/rnacentral-mcp-server/)
+
+This is an MCP server that provides a comprehensive interface to the RNAcentral database, allowing for complex searches, sequence mapping, genomic analysis, and metadata retrieval for non-coding RNA sequences.
+
+📖 **Full documentation:** <https://rnacentral.github.io/rnacentral-mcp-server/> — installation guides for Claude Desktop / Claude Code / other MCP clients, per-tool reference, and examples.
+
+## Features
+
+- **Comprehensive Search**: Query RNAcentral using natural language or filters (RNA type, taxon, expert database). Combines EBI Search and RNAcentral API data for enriched metadata (Rfam hits, GO annotations).
+- **Sequence Search**: Search for RNA sequences across multiple databases to find identical or similar entries.
+- **Bidirectional ID Mapping**: Map between RNAcentral URS IDs and external database identifiers (miRBase, Ensembl, HGNC, etc.) with automatic taxonomy resolution.
+- **Bulk Sequence Export**: Export search results in FASTA or Parquet formats, ideal for downstream analysis or machine learning datasets.
+- **Genomic Overlap (Ensembl)**: Find non-coding RNAs overlapping specific genomic coordinates or gene symbols using Ensembl's GraphQL integration.
+- **2D Structure Diagrams**: Retrieve secondary structure (2D) diagrams in SVG format for RNAs with known or predicted folds.
+- **Literature Summaries**: Access AI-generated literature summaries for RNA sequences to understand their biological context.
+
+## Prerequisites
+
+- Python 3.10 or higher
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+## Installation
+
+1. Set up a Python environment:
+
+```bash
+# Using uv (recommended)
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Add dependencies
+uv add "mcp[cli]" aiohttp
+```
+
+2. Install the package in editable mode:
+
+```bash
+uv pip install -e .
+```
+
+## Running the Server
+
+### Development Mode (with MCP Inspector)
+
+```bash
+mcp dev rnacentral_sequence_search/server.py
+```
+
+This will start the server and open the MCP Inspector, allowing you to test the server interactively.
+
+### Using with Claude Desktop
+
+To install the server in Claude Desktop, add this to your `claude_desktop_config.json`. You can optionally specify a `--log-dir` to save logs to a specific directory:
+
+```json
+{
+  "mcpServers": {
+    "rnacentral": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/rnacentral/rnacentral-mcp-server.git",
+        "run-server",
+        "--log-dir",
+        "/Users/YOUR_USERNAME/logs/rnacentral"
+      ]
+    }
+  }
+}
+```
+
+### Direct Execution
+
+You can run the server directly using Python. Use the `--log-dir` argument to specify where to save log files:
+
+```bash
+python rnacentral_sequence_search/server.py --log-dir ./logs
+```
+
+Or using the installed script:
+
+```bash
+run-server --log-dir ./logs
+```
+
+## Usage Examples
+
+Once the server is running, you can interact with various tools:
+
+### Bidirectional ID Mapping
+
+Map an external ID to RNAcentral and see all cross-references:
+
+```
+Tool: map_rna_id
+Arguments:
+{
+  "identifier": "MIMAT0000062",
+  "taxon": "Homo sapiens"
+}
+```
+
+### Genomic Overlap
+
+Find ncRNAs overlapping a specific gene in human:
+
+```
+Tool: get_overlapping_ncrnas
+Arguments:
+{
+  "species": "human",
+  "gene_symbol": "HOTAIR"
+}
+```
+
+### 2D Structure Retrieval
+
+Get the secondary structure diagram for a specific URS ID:
+
+```
+Tool: get_secondary_structure_svg
+Arguments:
+{
+  "urs_id": "URS0000049E57"
+}
+```
+
+### Bulk Sequence Export
+
+Export a set of sequences matching a search query for machine learning:
+
+```
+Tool: export_sequences
+Arguments:
+{
+  "query": "lncRNA",
+  "taxon": "9606",
+  "format": "parquet",
+  "max_length": 500
+}
+```
+
+### Literature Summaries
+
+Get a summary of the known biological role of an RNA:
+
+```
+Tool: get_rna_description
+Arguments:
+{
+  "rna_id": "mmu-mir-191"
+}
+```
+
+## Notes
+
+- The server handles complex queries by orchestrating multiple upstream APIs (EBI Search, RNAcentral, Ensembl).
+- Sequence searches poll for results with a timeout to handle varying server loads.
+- The 2D structure SVG can be used for direct visualization in supporting clients.
+- For very large exports, use the `export_sequences` tool which uses specialized microservices for efficiency.

rnacentral_mcp_server-0.1.0/diagnose_bug.py

@@ -0,0 +1,24 @@
+import asyncio
+import aiohttp
+from rnacentral_sequence_search.utils import resolve_taxid, resolve_gene_coordinates
+from rnacentral_sequence_search.overlap import fetch_overlapping_ncrnas
+
+async def main():
+    async with aiohttp.ClientSession() as session:
+        print("Testing resolve_taxid for 'human'...")
+        taxon_id = await resolve_taxid(session, "human")
+        print(f"Taxon ID: {taxon_id}")
+        
+        if taxon_id:
+            print(f"Testing fetch_overlapping_ncrnas for BRCA2 in human...")
+            try:
+                result = await fetch_overlapping_ncrnas(species="human", gene_symbol="BRCA2")
+                print("\nResult summary:")
+                print(result[:500] + "...")
+            except Exception as e:
+                print(f"Caught exception: {e}")
+                import traceback
+                traceback.print_exc()
+
+if __name__ == "__main__":
+    asyncio.run(main())

rnacentral_mcp_server-0.1.0/docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal Sphinx Makefile — run via `uv run` so the docs extras are picked up.
+
+SPHINXBUILD   ?= uv run sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help html clean livehtml
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
+
+html:
+	@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html"
+
+clean:
+	rm -rf "$(BUILDDIR)"
+
+livehtml:
+	uv run sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html"

rnacentral_mcp_server-0.1.0/docs/conf.py

@@ -0,0 +1,29 @@
+"""Sphinx configuration for the RNAcentral MCP Server documentation."""
+
+project = "RNAcentral MCP Server"
+author = "RNAcentral"
+copyright = "2026, RNAcentral"
+release = "0.1.0"
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_copybutton",
+]
+
+source_suffix = {".md": "markdown", ".rst": "restructuredtext"}
+master_doc = "index"
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "linkify",
+    "substitution",
+]
+
+html_theme = "sphinx_rtd_theme"
+html_title = "RNAcentral MCP Server"
+html_static_path = ["_static"]
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

rnacentral_mcp_server-0.1.0/docs/examples.md

@@ -0,0 +1,13 @@
+# Examples
+
+This section is a placeholder — real worked examples will be added here showing
+end-to-end applications of the tools (prompts used, resulting tool calls, and
+the outputs the LLM produced).
+
+Planned topics:
+
+- Identifying novel ncRNAs overlapping a GWAS locus.
+- Building a training set of tRNA sequences for a structure-prediction model.
+- Cross-mapping a miRBase panel to RNAcentral for integration with another
+  dataset.
+- Inspecting a 2D structure alongside its literature summary.

rnacentral_mcp_server-0.1.0/docs/index.md

@@ -0,0 +1,30 @@
+# RNAcentral MCP Server
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the
+[RNAcentral](https://rnacentral.org) database — non-coding RNA sequences, cross-references,
+genomic context, 2D structures, and literature summaries — as tools your LLM can call.
+
+The server orchestrates several upstream APIs (EBI Search, RNAcentral REST, Ensembl GraphQL,
+the sequence-search and export microservices) so the model can answer a single question with
+a single tool call instead of chaining raw HTTP requests.
+
+```{toctree}
+:maxdepth: 2
+:caption: Getting started
+
+installation
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Tool reference
+
+tools/index
+```
+
+```{toctree}
+:maxdepth: 1
+:caption: Examples
+
+examples
+```

rnacentral_mcp_server-0.1.0/docs/installation.md

@@ -0,0 +1,92 @@
+# Installation
+
+## Prerequisites
+
+- Python 3.10 or newer
+- [uv](https://docs.astral.sh/uv/) (recommended) — used throughout this project for
+  dependency and environment management
+
+## Installing the server
+
+Clone the repository and sync dependencies:
+
+```bash
+git clone https://github.com/rnacentral/rnacentral-mcp-server.git
+cd rnacentral-mcp-server
+uv sync
+```
+
+This creates a `.venv/` and installs the server plus its runtime dependencies. The
+console script `run-server` becomes available inside that environment.
+
+## Connecting the server to your LLM
+
+The server speaks the Model Context Protocol over stdio, so any MCP-capable client
+can launch it. The examples below cover the most common clients — if you're using
+something different, point it at the same `uvx ... run-server` command.
+
+### Claude Desktop
+
+Add the server to `claude_desktop_config.json` (on macOS:
+`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "rnacentral": {
+      "command": "uvx",
+      "args": [
+        "--from",
+        "git+https://github.com/rnacentral/rnacentral-mcp-server.git",
+        "run-server",
+        "--log-dir",
+        "/Users/YOUR_USERNAME/logs/rnacentral"
+      ]
+    }
+  }
+}
+```
+
+`--log-dir` is optional; pass it if you want on-disk logs for debugging.
+
+Restart Claude Desktop and the `rnacentral` tools should appear in the tool picker.
+
+### Claude Code
+
+Register the server with `claude mcp add`:
+
+```bash
+claude mcp add rnacentral -- uvx --from \
+  git+https://github.com/rnacentral/rnacentral-mcp-server.git run-server
+```
+
+### Other MCP clients
+
+Any client that launches an MCP server over stdio works. The command to run is:
+
+```bash
+uvx --from git+https://github.com/rnacentral/rnacentral-mcp-server.git run-server
+```
+
+Or, from a local clone:
+
+```bash
+uv run run-server --log-dir ./logs
+```
+
+## Development mode
+
+Run the server under the MCP Inspector to try tools interactively:
+
+```bash
+uv run mcp dev rnacentral_sequence_search/server.py
+```
+
+## Building these docs locally
+
+```bash
+uv sync --extra docs
+uv run sphinx-build -b html docs docs/_build/html
+```
+
+Or, from inside `docs/`, `make html`.

rnacentral_mcp_server-0.1.0/docs/tools/export_sequences.md

@@ -0,0 +1,32 @@
+# `export_sequences`
+
+Bulk export of RNA sequences matching a query. Unlike {doc}`query_rnacentral`,
+which returns a handful of enriched hits for a human reader, this tool streams
+the full result set through the RNAcentral export microservice and returns it in
+a format suitable for downstream processing — FASTA for bioinformatics tools,
+Parquet for ML pipelines.
+
+## Arguments
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `query` | `str` | yes | Free-text search term. |
+| `rna_type` | `str` | no | Restrict to an RNA type (e.g. `"miRNA"`, `"lncRNA"`). |
+| `taxon` | `str` | no | Scientific name (preferred) or NCBI Taxonomy ID. |
+| `expert_db` | `str` | no | Source database filter. |
+| `has_secondary_structure` | `bool` | no | Only include RNAs with a known 2D structure. |
+| `min_length` | `int` | no | Minimum sequence length in nucleotides. |
+| `max_length` | `int` | no | Maximum sequence length in nucleotides. |
+| `format` | `str` | no | `"fasta"` (default) or `"parquet"`. |
+
+## Returns
+
+For `fasta`, a string of FASTA records. For `parquet`, a path (or URL) to the
+generated file returned by the export service.
+
+## Notes
+
+- The export service handles pagination internally; there is no client-side
+  `limit`. Narrow the query with the filter arguments if you don't want every
+  match.
+- Long-running exports may take tens of seconds for large result sets.

rnacentral_mcp_server-0.1.0/docs/tools/get_overlapping_ncrnas.md

@@ -0,0 +1,29 @@
+# `get_overlapping_ncrnas`
+
+Find non-coding RNAs that overlap a genomic region. The region can be specified
+either as explicit coordinates or as a gene symbol, in which case the tool uses
+Ensembl's GraphQL API to resolve the symbol to coordinates first.
+
+## Arguments
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `species` | `str` | yes | Common name (e.g. `"human"`, `"mouse"`) or scientific name (`"homo_sapiens"`). |
+| `chromosome` | `str` | conditional | Chromosome name — `"1"`, `"X"`, `"chr1"`. |
+| `start` | `int` | conditional | Start coordinate (1-based, inclusive). |
+| `end` | `int` | conditional | End coordinate (1-based, inclusive). |
+| `gene_symbol` | `str` | conditional | Gene symbol (e.g. `"BRCA2"`, `"HOTAIR"`). |
+
+You must supply **either** `gene_symbol` **or** the full `chromosome` / `start` /
+`end` triple. Mixing the two is not supported; the tool returns an error if
+neither is given.
+
+## Returns
+
+A markdown list of overlapping RNAcentral entries with URS IDs, RNA type,
+genomic coordinates, strand, and source database.
+
+## Upstream services
+
+- Ensembl GraphQL API for `gene_symbol` → coordinates resolution.
+- RNAcentral REST API for the overlap query.

rnacentral_mcp_server-0.1.0/docs/tools/get_rna_description.md

@@ -0,0 +1,23 @@
+# `get_rna_description`
+
+Return a literature-derived summary of an RNA's known biological role. The
+summary comes from RNAcentral's literature-summary pipeline, which aggregates
+published mentions of the RNA into a short natural-language description.
+
+## Arguments
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `rna_id` | `str` | yes | An RNA identifier recognised by RNAcentral (e.g. `"mmu-mir-191"`, a miRBase name, or a URS ID). |
+
+## Returns
+
+A plain-text description. If no summary is available for the given ID, the tool
+returns a message indicating so rather than raising.
+
+## Good to know
+
+- Summaries exist primarily for well-studied RNAs (miRNAs, lncRNAs with named
+  entries, etc.). Novel or poorly-annotated RNAs often have no summary.
+- The summary is generated from the literature — treat it as a pointer to
+  primary sources, not as a definitive statement.

rnacentral_mcp_server-0.1.0/docs/tools/get_secondary_structure_svg.md

@@ -0,0 +1,24 @@
+# `get_secondary_structure_svg`
+
+Return the 2D secondary-structure diagram for a given URS ID as SVG. The SVG comes
+from RNAcentral's structure service (R2DT or curated layouts, depending on the
+entry) and can be rendered directly by MCP clients that support image content.
+
+## Arguments
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `urs_id` | `str` | yes | The RNAcentral URS ID (e.g. `"URS0000049E57"`). The taxon suffix (`_9606`) is optional. |
+
+## Returns
+
+The SVG document as a string. If the entry has no 2D structure available, the
+tool returns an explanatory message rather than raising.
+
+## Tips
+
+- Not every RNAcentral entry has a 2D structure. Pre-filter with
+  `query_rnacentral(..., has_secondary_structure=True)` if you need to guarantee
+  a hit.
+- Large or complex structures produce large SVGs — clients that inline the
+  payload in the chat transcript may truncate it.

rnacentral_mcp_server-0.1.0/docs/tools/index.md

@@ -0,0 +1,28 @@
+# Tool reference
+
+The server registers seven MCP tools. Each page below documents a tool's purpose,
+arguments, return shape, and the upstream service it talks to.
+
+```{toctree}
+:maxdepth: 1
+
+query_rnacentral
+search_sequence
+map_rna_id
+export_sequences
+get_overlapping_ncrnas
+get_secondary_structure_svg
+get_rna_description
+```
+
+## Tool summary
+
+| Tool | Purpose |
+| --- | --- |
+| [`query_rnacentral`](query_rnacentral.md) | Text/metadata search over RNAcentral with enriched results |
+| [`search_sequence`](search_sequence.md) | Similarity search by raw RNA sequence |
+| [`map_rna_id`](map_rna_id.md) | Bidirectional mapping between URS IDs and external DB IDs |
+| [`export_sequences`](export_sequences.md) | Bulk export of matching sequences (FASTA or Parquet) |
+| [`get_overlapping_ncrnas`](get_overlapping_ncrnas.md) | Find ncRNAs overlapping genomic coordinates or a gene |
+| [`get_secondary_structure_svg`](get_secondary_structure_svg.md) | Retrieve the 2D structure diagram for a URS ID |
+| [`get_rna_description`](get_rna_description.md) | AI-generated literature summary for an RNA |