psimodpy

Python library for parsing and querying the PSI-MOD protein modification ontology.

• Zero core dependencies
• Bundled PSI-MOD data (2,116 entries) — works offline out of the box
• Typed, immutable data models (py.typed / PEP 561)
• TSV/CSV export and round-trip OBO writer
• Optional FastAPI / Model Context Protocol server (pip install psimodpy[server])

Online Viewer

Click Me!

The same database is also reachable as a hosted REST + MCP service — see HTTP API and MCP Server below.

Installation

pip install psimodpy

Or with uv:

uv add psimodpy

Requires Python 3.12+. No third-party dependencies.

Quick Start

import psimodpy

# Load the bundled PSI-MOD database
db = psimodpy.load()

# Lookup by ID
entry = db[46]  # O-phospho-L-serine
print(entry.name)       # "O-phospho-L-serine"
print(entry.diff_mono)  # 79.966331
print(entry.origin)     # AminoAcid.SER

# Lookup by name (case-insensitive)
entry = db.get_by_name("O-phospho-L-serine")

# Also accepts MOD:NNNNN format
entry = db.get_by_id("MOD:00046")

# Search across names, definitions, and synonyms
results = db.search("phospho")

# Find all modifications for an amino acid
ser_mods = db.get_by_origin("S")

# Filter entries
slim = db.filter(slim_only=True, include_obsolete=False)

# Formula parsing
print(entry.dict_diff_formula)      # {'C': 0, 'H': 0, 'N': 0, 'O': 3, 'P': 1}
print(entry.proforma_diff_formula)  # 'O3P'

Exporting to TSV/CSV

# Write all entries to a tab-separated file
db.write_tsv("psimod.tsv")

# Or CSV
db.write_tsv("psimod.csv", delimiter=",")

# Standalone function
from psimodpy import write_tsv
write_tsv(db, "psimod.tsv")

The TSV includes one row per entry. Dynamic synonym columns (e.g. synonym_psi_mod_label, synonym_omssa_label) are added for each SynonymType found in the data.

Writing back to OBO format

# Round-trip: write entries back to PSI-MOD OBO format
db.write_obo("out/psi-mod.obo")

# Re-parse — identical entry count and field values
db2 = psimodpy.parse_obo("out/psi-mod.obo")

# Standalone function; pass original header lines for a faithful round-trip
from psimodpy import write_obo
write_obo(db, "out/psi-mod.obo", header_lines=db.header_lines)

HTTP API and MCP Server

The optional [server] extra ships a FastAPI app that exposes the same database over a JSON REST API and over the Model Context Protocol so language-model tools can query PSI-MOD directly.

pip install psimodpy[server]
uvicorn psimodpy.server.app:app --reload

REST endpoints

Full entry payloads include references parsed from definition_ref into {type, accession, value} objects and a typed origin object (either {type: "amino_acid", code} or {type: "crosslink", sites}). Search responses contain just {id, accession, name, mass_mono, is_obsolete} to keep token cost low; call /api/entries/{id} on any hit for the full record.

MCP server

The same FastAPI app mounts an MCP endpoint at POST /mcp with these tools:

Tool responses use MCP's structured-output mechanism: the server emits an outputSchema per tool in tools/list and returns both structuredContent (typed Pydantic instance) and content (text fallback) on tools/call, so LLM clients can parse the response without re-reading the JSON string.

Configure your MCP-aware client to point at http://localhost:8000/mcp (or wherever you deploy the app). Example with the Anthropic CLI:

claude mcp add psi-mod http://localhost:8000/mcp --transport http

API Overview

Loading

PsiModDatabase

PsiModEntry

Each entry provides: id, name, definition, definition_ref, synonyms, is_a, relationships, origin, diff_mono, diff_avg, diff_formula, mass_mono, mass_avg, formula, term_spec, source, formal_charge, xref_unimod, xref_uniprot_ptm, xref_gnome, xref_remap, in_slim_subset, is_obsolete.

Computed properties: dict_diff_formula, dict_formula, proforma_diff_formula.

Each Synonym has: value, type (SynonymType), scope (e.g. "EXACT", "RELATED").

Data Types

• AminoAcid — single-letter amino acid codes
• Crosslink — multi-residue or MOD-referenced origins
• Synonym / SynonymType — typed synonyms
• Relationship / RelationshipType — directed relationships
• TermSpec — positional specificity
• Source — modification origin

Development

just install   # install dependencies with uv
just lint      # ruff check
just format    # ruff format
just ty        # ty type check
just test      # pytest
just check     # lint + type check + test

Related Projects

License

MIT