Metadata-Version: 2.4
Name: uniprot-mcp
Version: 0.1.0
Summary: Model Context Protocol server that surfaces UniProtKB data as MCP resources, tools, and prompts.
Author-email: Jose Duarte <josepipe0909@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/josefdc/Uniprot-MCP
Project-URL: Repository, https://github.com/josefdc/Uniprot-MCP
Project-URL: Documentation, https://github.com/josefdc/Uniprot-MCP#readme
Project-URL: Issues, https://github.com/josefdc/Uniprot-MCP/issues
Keywords: mcp,uniprot,bioinformatics,llm,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=1.19.0
Requires-Dist: pydantic>=2.12.3
Requires-Dist: starlette>=0.48.0
Requires-Dist: tenacity>=9.1.2
Requires-Dist: uvicorn>=0.38.0
Requires-Dist: prometheus-client>=0.20.0
Dynamic: license-file

# UniProt MCP Server

mcp-name: io.github.josefdc/uniprot-mcp

The UniProt MCP server exposes curated UniProtKB data as Model Context Protocol
(MCP) resources, tools, and prompts. It allows MCP-compatible agents to fetch
protein entries, sequences, Gene Ontology annotations, and identifier mappings
from the UniProt REST API through a consistent, typed interface.

## Features

- **Protocols**: Supports both stdio (development) and streamable HTTP (remote
  deployments with proper CORS headers).
- **Resources**: `uniprot://uniprotkb/{accession}` provides raw entry JSON;
  `uniprot://help/search` documents query syntax.
- **Tools**: Structured outputs for `fetch_entry`, `get_sequence`,
  `search_uniprot`, and `map_ids` (with progress notifications).
- **Prompts**: Built-in prompt for summarising a UniProt accession.
- **Retries & resilience**: Tenacity-based retries for 429/5xx responses,
  progress reporting for long-running mapping tasks, and defensive parsing of
  UniProt payloads.

## Installation

```bash
pip install uniprot-mcp
```

## Quickstart

### Stdio server (development / MCP Inspector)

```bash
uniprot-mcp
```

This launches the stdio transport (the same entry point MCP Inspector uses).

### Streamable HTTP server

```bash
uniprot-mcp-http --host 0.0.0.0 --port 8000
```

The server exposes a health check at `/healthz` and the MCP endpoint at `/mcp`.
Browser clients can read the `Mcp-Session-Id` response header because the
server is configured with permissive CORS defaults.
If `prometheus-client` is installed (included by default), metrics are served at `/metrics`.

## Available MCP primitives

### Resources

- `uniprot://uniprotkb/{accession}` – returns raw UniProtKB entry JSON.
- `uniprot://help/search` – simple usage guide for `search_uniprot`.

### Tools

| Tool | Description |
| --- | --- |
| `fetch_entry(accession, fields=None)` | Fetch a UniProtKB entry and return a typed payload (`Entry`). Versioned entries require `fetch_entry_flatfile`. |
| `get_sequence(accession)` | Fetch minimal sequence metadata (`Sequence`). |
| `search_uniprot(query, size=10, reviewed_only=False, fields=None, sort=None, include_isoform=False)` | Search UniProtKB and return a list of hits (`SearchHit`). |
| `map_ids(from_db, to_db, ids)` | Submit/poll UniProt ID mapping jobs with progress reporting (`MappingResult`). |
| `fetch_entry_flatfile(accession, version, format="txt")` | Return a historical flatfile (txt or fasta) for a UniProt entry version. |

### Prompts

- **Summarize Protein** – prompts an agent to summarise a UniProt accession,
  optionally including organism, GO annotations, and notable features.

## Environment variables and CLI flags

| Variable | Default | Description |
| --- | --- | --- |
| `UNIPROT_ENABLE_FIELDS` | unset | When set, the server requests minimal field subsets from UniProt (reduces payload size). |
| `MCP_HTTP_HOST` | `0.0.0.0` | Bind host for `uniprot-mcp-http` (can also use `--host`). |
| `MCP_HTTP_PORT` | `8000` | Bind port for `uniprot-mcp-http` (or `--port`). |
| `MCP_HTTP_LOG_LEVEL` | `info` | Log level for uvicorn (or `--log-level`). |
| `MCP_HTTP_RELOAD` | `0` | Enable auto-reload for `uniprot-mcp-http` when set to `1/true` (or pass `--reload`). |
| `UNIPROT_LOG_LEVEL` | `info` | Application log level (`debug`, `info`, `warning`, `error`). |
| `UNIPROT_LOG_FORMAT` | `plain` | Log output format (`plain` or `json`). |
| `UNIPROT_MAX_CONCURRENCY` | `8` | Maximum concurrent outbound UniProt requests. |
| `MCP_CORS_ALLOW_ORIGINS` | `*` | Override CORS origins (comma-separated) for HTTP transport. |
| `MCP_CORS_ALLOW_METHODS` | `GET,POST,DELETE` | Allowed methods for CORS preflight. |
| `MCP_CORS_ALLOW_HEADERS` | `*` | Allowed request headers for CORS. |

Every HTTP response includes `X-Request-Id`. Forward this header in client requests to correlate logs across transports.

## Development

The project is managed with [uv](https://docs.astral.sh/uv/).

```bash
# Install dependencies
uv sync --group dev

# Lint & format check
uv tool run ruff check .
uv tool run ruff format --check .

# Type check
uv tool run mypy src

# Run tests (with coverage)
uv run pytest --maxfail=1 --cov=uniprot_mcp --cov-report=term-missing

# Launch stdio server for local inspection
uv run uniprot-mcp

# Launch HTTP server with auto-reload
uv run python -m uvicorn uniprot_mcp.http_app:app --reload
```

## Publishing & MCP Registry

1. Build artifacts: `uv build`
2. Publish to PyPI: `uv publish --token $PYPI_TOKEN`
3. Prepare/validate `server.json` (see `docs/registry.md` for the schema link).
4. Use [`mcp-publisher`](https://github.com/modelcontextprotocol/registry) to
   publish the server metadata, optionally linking a remote HTTP deployment.

## Support & Compatibility

- Python 3.11 and 3.12 are tested in CI.
- External dependencies are pinned via `uv.lock`.
- Issues and feature requests: [GitHub Issues](https://github.com/josefdc/Uniprot-MCP/issues)

## License

Distributed under the MIT License. See `LICENSE` for details.
