IMSLP
Lee IMSLP, la Biblioteca Musical Petrucci: obras, partituras, ediciones, derechos de autor. Sin clave de API.
Documentación
mcp-imslp
IMSLP, el Proyecto Internacional de Partituras Musicales, también se llama la Biblioteca Musical Petrucci. Es una biblioteca gratuita de música clásica dirigida por voluntarios, que contiene las partituras, las partes, los arreglos y las grabaciones de obras cuyos derechos de autor han expirado, junto con lo que sus páginas dicen sobre cada compositor. Revisa los derechos de autor de cada partitura para Canadá, los Estados Unidos y la Unión Europea por separado, y publica sus páginas bajo CC BY-SA 4.0.
Este servidor conecta un cliente de chat a esa biblioteca. Puedes buscar las obras y las personas que cataloga, leer una obra con su número de opus, su tonalidad, su instrumentación y el año en que fue escrita, hojear las ediciones que tiene una obra con sus editores, editores y términos de derechos de autor, leer lo que la biblioteca dice sobre un compositor, y navegar por un género, una tonalidad o una instrumentación. Lee la biblioteca y enlaza a ella, y no necesita clave API ni cuenta.
Instalación
Instalación en un clic
Claude Code
claude mcp add imslp -- npx -y mcp-imslp
Claude Desktop, Cursor y cualquier cliente que use el formato de configuración estándar
{
"mcpServers": {
"imslp": {
"command": "npx",
"args": ["-y", "mcp-imslp"]
}
}
}
Se requiere Node 24 o posterior, y no es necesario establecer ninguna variable de entorno.
Con Docker
{
"mcpServers": {
"imslp": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-imslp:1.0.1"]
}
}
}
-i mantiene abierto stdin, que es por donde viaja el protocolo, y -t se omite porque una TTY reescribe el flujo. El contenedor necesita HTTPS saliente hacia imslp.org, y nada más: sin volumen, sin puerto, sin credencial.
Paquete, sin npm
Descarga mcp-imslp-1.0.1.mcpb desde la última versión y ábrelo. Un cliente que admita paquetes MCP lo instala por sí solo, sin npm y sin archivo de configuración que editar. El paquete lleva sus dependencias, por lo que no se descarga nada en el momento de la instalación.
Lo que puedes preguntar
- "¿Qué tiene IMSLP de los nocturnos de Chopin?"
- "Léeme la página de Erik Satie y dime cuándo vivió."
- "Enumera las ediciones de Clair de lune de Debussy, con quién publicó cada una."
- "¿La edición Henle de esa pieza es de uso libre en los Estados Unidos?"
- "Muéstrame obras para violonchelo solo en la biblioteca."
El camino habitual va de una búsqueda a una obra: search_works nombra la página de una obra, y get_work lee esa página. Lo mismo ocurre con una persona, desde search_people hasta get_person o list_person_works.
Herramientas
| Herramienta | Qué hace |
|---|---|
search_works | Encuentra la página de una obra por título, compositor o palabras en la página. |
search_people | Encuentra la categoría bajo la que se archiva a un compositor, editor, arreglista o intérprete. |
get_work | Lee una obra: sus facetas, sus secciones y sus términos de derechos de autor. |
list_work_files | Recorre las ediciones que tiene una obra, con sus archivos. |
list_person_works | Lee las obras que la biblioteca archiva bajo una persona. |
get_person | Lee lo que la biblioteca tiene sobre una persona. |
browse_category | Lee las obras archivadas bajo un género, una tonalidad o una instrumentación. |
Una obra se identifica por el título de su página, escrito Work (Composer), como en Nocturnes, Op.9 (Chopin, Frédéric). Una persona se identifica por una categoría, escrita Category:Surname, Forename. Ambos provienen de una búsqueda, y el prefijo Category: puede omitirse.
La biblioteca titula una obra en el idioma que usó su compositor, por lo que Die Zauberflöte encuentra la ópera donde The Magic Flute encuentra las páginas escritas sobre ella. Una respuesta escasa para una obra famosa es señal de que el título está en otro idioma.
search_works
Busca en las páginas de las obras palabras que aparezcan en cualquier parte de ellas, por lo que un título, un compositor o una dedicatoria encuentran las obras que las contienen.
| Argumento | Tipo | Obligatorio | Qué hace |
|---|---|---|---|
query | cadena, de 1 a 300 caracteres | sí | Qué buscar en las páginas de las obras. |
limit | entero, de 1 a 50, predeterminado 10 | no | Filas a servir. |
offset | entero, 0 o más, predeterminado 0 | no | Filas a omitir, usando el next_offset de una respuesta anterior. |
A cambio: filas que llevan page, que get_work toma; work y composer, leídos de ese título; page_url; snippet, las palabras alrededor de la coincidencia; size_bytes, words y last_edited tal como las indica la biblioteca. El sobre lleva returned, has_more y next_offset, que es el desplazamiento desde el que continuar. total es siempre null: la biblioteca no publica un recuento de lo que coincidió en una búsqueda. composer es null en un título escrito fuera de la forma Work (Composer), y snippet es null en una fila que la búsqueda resumió sin nada.
search_people
Encuentra a los compositores, editores, arreglistas e intérpretes por nombre. La biblioteca escribe un nombre a su manera, apellido primero, por lo que buscar encuentra a una persona donde adivinar la ortografía no llega a nada.
| Argumento | Tipo | Obligatorio | Qué hace |
|---|---|---|---|
query | cadena, de 1 a 300 caracteres | sí | El nombre a buscar entre las personas de la biblioteca. |
limit | entero, de 1 a 50, predeterminado 10 | no | Filas a servir. |
offset | entero, 0 o más, predeterminado 0 | no | Filas a omitir, usando el next_offset de una respuesta anterior. |
A cambio: filas que llevan category, que get_person y list_person_works toman; name sin el prefijo; page_url; snippet; y redirect_to. Una fila con un redirect_to representa otra categoría y no contiene obras propias, así que sigue la categoría que nombra. El sobre es el que search_works devuelve, y total es null aquí por la misma razón.
get_work
Lee una obra: su título y títulos alternativos, el compositor, los números de opus y catálogo, el año de composición y de primera publicación, la dedicatoria, la tonalidad, el idioma, el libretista, la instrumentación, los movimientos, el estreno, el estilo y el período.
| Argumento | Tipo | Obligatorio | Qué hace |
|---|---|---|---|
page | cadena, de 1 a 300 caracteres | uno de dos | El título de la página, escrito Work (Composer). |
pageid | entero, positivo | uno de dos | El id de página que devolvió una búsqueda, como alternativa a page. |
A cambio: cada faceta anterior, cada una null cuando la página la deja vacía, y cada una en la redacción que usó la página, por lo que ca.1830 permanece ca.1830. Junto a ellas vienen genre_categories, que browse_category toma; external_links y authorities, los registros de la obra en VIAF, LCCN, WorldCat, BNF y GND; sections, con el número de entradas que el sitio cuenta en cada uno; y copyright_summary, una entrada por declaración distinta, con el número de ediciones que la contienen. editions contiene cada edición con sus archivos, y se convierte en null con editions_truncated verdadero cuando la obra tiene más de cinco, que list_work_files luego recorre. redirected_from nombra el título solicitado cuando llevó hasta aquí, y pageid es null para una obra identificada por título.
list_work_files
Lee las partituras y las grabaciones de una obra, edición por edición. Una edición es un conjunto de archivos publicados bajo un conjunto de términos: el editor, el editor y la declaración de derechos de autor pertenecen a la edición, y los archivos están debajo. Un bloque de grabaciones lleva intérpretes y ninguna declaración de derechos de autor.
| Argumento | Tipo | Obligatorio | Qué hace |
|---|---|---|---|
page | cadena, de 1 a 300 caracteres | uno de dos | El título de la página, escrito Work (Composer). |
pageid | entero, positivo | uno de dos | El id de página que devolvió una búsqueda, como alternativa a page. |
section | cadena, de 1 a 80 caracteres | no | Una sección de la página, en su propia redacción: Scores, Parts, Recordings, Arrangements and Transcriptions. Coincide sin distinguir mayúsculas. |
limit | entero, de 1 a 100, predeterminado 10 | no | Ediciones a servir. |
offset | entero, 0 o más, predeterminado 0 | no | Ediciones a omitir. |
A cambio: editions, cada una con su section, publisher_info, editor, copyright y files. Un archivo lleva imslp_id, description, format y format_code, pages, size_bytes, downloads, rating, uploader, uploaded_on, los sigla y el nombre de la biblioteca que lo escaneó, y blocked, que es verdadero mientras IMSLP revisa los derechos de autor de ese archivo. downloads es null en una entrada que no imprime contador, y rating es null cuando nadie ha votado. Junto a ellos vienen editions_on_page, editions_in_section, returned, has_more y sections. Un section que no coincide con nada regresa con las secciones que la página sí tiene, por lo que una restricción nunca se lee como una obra sin partituras.
list_person_works
Lee las obras que la biblioteca archiva bajo una persona: lo que escribió un compositor, y también lo que se le atribuye a un editor, un arreglista o un intérprete.
| Argumento | Tipo | Obligatorio | Qué hace |
|---|---|---|---|
category | cadena, de 1 a 300 caracteres | sí | La categoría de la persona, escrita Category:Surname, Forename. |
limit | entero, de 1 a 100, por defecto 25 | no | Filas a servir. |
cursor | cadena, de 1 a 500 caracteres | no | El cursor que nombró una respuesta anterior, devuelto tal como se dio. |
A cambio: filas que llevan page, work, composer, pageid y page_url,
con has_more y cursor para continuar. total es siempre null: la biblioteca
no publica un recuento de lo que contiene una categoría. Una categoría que la biblioteca no tiene
responde igual que una vacía, así que una respuesta sin filas es motivo para comprobar
la ortografía con search_people.
get_person
Lee lo que la biblioteca guarda sobre una persona: el nombre tal como lo imprime su página, las fechas de vida que indica, los otros nombres bajo los que la archiva, los registros que contienen un registro de ella y las direcciones que señala fuera del sitio.
| Argumento | Tipo | Obligatorio | Qué hace |
|---|---|---|---|
category | cadena, de 1 a 300 caracteres | sí | La categoría de la persona, escrita Category:Surname, Forename. |
A cambio: category, catalogued_as con el apellido primero, name como la
página lo imprime, life_dates en la redacción que usó la página, alternative_names
y aliases como líneas publicadas, authorities con el registro y el
identificador en VIAF, LCCN, WorldCat, BNF y GND, external_links, y
page_url. life_dates es null en una página que no indica ninguno. Esto lee a la persona;
list_person_works lee las obras.
browse_category
Lee las obras archivadas bajo una categoría: un género, una tonalidad, una instrumentación o un
período. get_work devuelve estos nombres para una obra bajo genre_categories,
y pasar uno de ellos llega a una categoría que la biblioteca tiene.
| Argumento | Tipo | Obligatorio | Qué hace |
|---|---|---|---|
category | cadena, de 1 a 300 caracteres | sí | La categoría a leer, en la redacción de la biblioteca: For piano, Nocturnes, B-flat minor. |
limit | entero, de 1 a 100, por defecto 25 | no | Filas a servir. |
cursor | cadena, de 1 a 500 caracteres | no | El cursor que nombró una respuesta anterior, devuelto tal como se dio. |
A cambio: las filas que list_person_works devuelve, con el mismo has_more y
cursor, y total en null. La biblioteca lee una categoría a la vez, así que una
pregunta que nombre tanto un género como un instrumento se responde navegando por uno de
ellos y leyendo el otro de cada obra con get_work.
Estado de derechos de autor
Una partitura en IMSLP lleva un estado por jurisdicción, y la biblioteca revisa
Canadá, Estados Unidos y la Unión Europea. Un archivo que lea
Public Domain - Non-PD US es libre en Canadá y la Unión Europea y
protegido en Estados Unidos. Este servidor informa el estado tal como se publica, por
jurisdicción, bajo copyright_summary en una obra y bajo copyright en una
edición, con restrictions nombrando los lugares que una declaración excluye. Un
restrictions vacío no dice nada sobre los países que IMSLP deja fuera de su revisión.
Configuración
Toda variable es opcional. Configúralas en el bloque env de la configuración de tu cliente.
| Variable | Predeterminado | Qué hace |
|---|---|---|
IMSLP_USER_AGENT | la identidad del proyecto | Nombra tu aplicación. La identidad del proyecto se añade para que IMSLP pueda contactar a una persona. |
IMSLP_MIN_INTERVAL_MS | 2500 | Intervalo entre dos solicitudes, de 2000 a 60000. Una cifra por debajo del mínimo se rechaza y se usa esta. |
IMSLP_TIMEOUT_MS | 30000 | Plazo para una solicitud, de 1000 a 120000. |
IMSLP_MAX_RETRIES | 3 | Intentos tras un fallo transitorio, de 0 a 10. |
IMSLP_CACHE_TTL_MS | 900000 | Cuánto tiempo permanece una página en memoria, de 0 a 86400000. |
IMSLP_CACHE_MAX_ENTRIES | 100 | Páginas retenidas en memoria a la vez, de 0 a 10000. |
IMSLP_LOG_LEVEL | error | silent, error, info o debug, escritos en stderr. |
Un valor fuera de su rango vuelve al predeterminado, y la razón se escribe en stderr.
Errores
Cada fallo lleva uno de seis códigos, un mensaje y, donde ayuda, una pista que nombra el siguiente movimiento.
| Código | Qué pasó | Qué hacer |
|---|---|---|
not_found | IMSLP respondió, y la página solicitada no existe. | Comprueba el título con search_works. |
invalid_input | Los argumentos se rechazaron antes de enviar cualquier solicitud. | Lee el mensaje, que nombra el argumento. |
rate_limited | IMSLP pidió a este cliente que se ralentizara. | Espera el número de segundos que nombre la pista y vuelve a llamar con los mismos argumentos. La obra sigue en la biblioteca. |
parse_failure | La página se cargó y faltaba el contenido esperado. | Repórtalo en el rastreador de problemas. |
network_error | La solicitud no se completó. | Inténtalo de nuevo en breve. |
timeout | La solicitud superó su plazo. | Aumenta IMSLP_TIMEOUT_MS, o pide menos filas. |
Como biblioteca
La capa que lee IMSLP se publica por separado, con su ritmo, su caché y sus errores, y sin protocolo adjunto.
import { ImslpClient } from "mcp-imslp/client";
const client = new ImslpClient();
const { data, cached } = await client.getWork({ page: "Nocturnes, Op.9 (Chopin, Frédéric)" });
console.log(data.title, data.copyright_summary, cached);
renderPage, getWork, search, categoryMembers y getPerson responden cada una
a { data, cached }, y lanzan un ImslpError que lleva uno de los seis códigos. El
mínimo de dos segundos entre solicitudes también se mantiene aquí.
Ritmo y atribución
IMSLP publica Crawl-delay: 2 en su robots.txt, así que las solicitudes salen de una en una
con al menos dos segundos entre ellas, y ese mínimo se mantiene sin importar cómo esté
configurado el servidor. El User-Agent siempre termina con la identidad del proyecto y
una dirección donde se pueda contactar a una persona.
Las lecturas pasan por la API de MediaWiki en /api.php y por el punto de listado
que IMSLP documenta en su propia página IMSLP:API. El robots.txt desautoriza
/index.php, /images/, /imglnks/, /wiki/File:, /works y /library/,
y este servidor no construye ninguna dirección bajo ninguno de ellos: devuelve el enlace a
la página de la obra, que es lo que una respuesta acredita.
La biblioteca publica sus páginas bajo CC BY-SA 4.0, así que cualquier cosa mostrada desde este servidor acredita a IMSLP y enlaza la página de la que proviene.
Privacidad
Este servidor no recopila nada sobre ti y no envía nada a su autor. Se ejecuta
en tu máquina, contacta a imslp.org y nada más, guarda sus respuestas en memoria
mientras se ejecuta y no escribe nada en disco.
PRIVACY.md indica qué lleva una solicitud y qué ajustes cambian
cualquier parte de ello.
Desarrollo
npm install
npm run build:fixtures
npm test
npm run check
Las pruebas se ejecutan contra accesorios generados y no hacen ninguna solicitud de red. La suite en vivo,
npm run test:live, hace una solicitud por ruta y se ejecuta cada noche contra el
propio sitio.
Contribuciones
Las incidencias y las solicitudes de extracción son bienvenidas en el repositorio. Consulta CONTRIBUTING.md.
Licencia
MIT, consulta LICENSE. El catálogo y las páginas pertenecen a IMSLP y sus colaboradores, publicados bajo CC BY-SA 4.0.
mcp-imslp (français)
IMSLP, el International Music Score Library Project, también se llama la Petrucci Music Library. Es una biblioteca libre de música clásica mantenida por voluntarios, que reúne las partituras, las partes separadas, los arreglos y las grabaciones de las obras de dominio público, con lo que sus páginas dicen de cada compositor. Verifica los derechos de cada partitura para Canadá, Estados Unidos y la Unión Europea por separado, y publica sus páginas bajo CC BY-SA 4.0.
Este servidor conecta un cliente de conversación con esa biblioteca. Se puede buscar las obras y las personas que cataloga, leer una obra con su número de opus, su tonalidad, su instrumentación y su año de composición, explorar las ediciones de una obra con sus editores y sus condiciones de derechos, leer lo que la biblioteca dice de un compositor, y explorar un género, una tonalidad o una instrumentación. Lee la biblioteca y devuelve hacia ella, sin clave de API ni cuenta.
Instalación
Instalación en un clic
Claude Code
claude mcp add imslp -- npx -y mcp-imslp
Claude Desktop, Cursor y cualquier cliente con formato de configuración estándar
{
"mcpServers": {
"imslp": {
"command": "npx",
"args": ["-y", "mcp-imslp"]
}
}
}
Se necesita Node 24 o más reciente, y no hay que rellenar ninguna variable de entorno.
Con Docker
{
"mcpServers": {
"imslp": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/smeet666/mcp-imslp:1.0.1"]
}
}
}
-i mantiene la entrada estándar abierta, que es el canal del protocolo, y -t se
omite porque un TTY reescribe el flujo. El contenedor necesita acceso HTTPS
saliente hacia imslp.org, y nada más: sin volúmenes, sin puertos, sin
identificadores.
Bundle, sin npm
Descarga mcp-imslp-1.0.1.mcpb desde
la última publicación
y ábrelo. Un cliente que gestione bundles MCP lo instala solo, sin npm y
sin archivo de configuración que modificar. El bundle lleva sus dependencias, así que
no se descarga nada en la instalación.
Lo que se puede pedir
- « ¿Qué tiene IMSLP de los nocturnos de Chopin? »
- « Léeme la página de Erik Satie y dime cuándo vivió. »
- « Enumera las ediciones del Claro de luna de Debussy, con quién publicó cada una. »
- « ¿Está libre la edición Henle de esta pieza en los Estados Unidos? »
- « Muéstrame obras para violonchelo solo en la biblioteca. »
El camino ordinario va de una búsqueda a una obra: search_works nombra la página
de una obra, y get_work lee esa página. Lo mismo ocurre con una persona, de
search_people hacia get_person o list_person_works.
Las herramientas
| Herramienta | Lo que hace |
|---|---|
search_works | Encuentra la página de una obra por su título, su compositor o sus palabras. |
search_people | Encuentra la categoría bajo la cual una persona está clasificada. |
get_work | Lee una obra: sus características, sus secciones y sus derechos. |
list_work_files | Recorre las ediciones de una obra, con sus archivos. |
list_person_works | Lee las obras que la biblioteca clasifica bajo una persona. |
get_person | Lee lo que la biblioteca contiene sobre una persona. |
browse_category | Lee las obras clasificadas bajo un género, una tonalidad, una formación. |
Una obra se aborda por el título de su página, escrito Œuvre (Compositeur), como
Nocturnes, Op.9 (Chopin, Frédéric). Una persona se aborda por una categoría,
escrita Category:Nom, Prénom. Ambos provienen de una búsqueda, y el prefijo
Category: puede omitirse.
La biblioteca titula una obra en el idioma de su compositor, por lo tanto
Die Zauberflöte encuentra la ópera allí donde La Flûte enchantée encuentra las páginas
escritas sobre ella. Una respuesta escasa sobre una obra famosa es señal de un
título en otro idioma.
search_works
Busca en las páginas de las obras las palabras que figuran en ellas, dondequiera que estén: un título, un compositor o una dedicatoria encuentran las obras que los llevan.
| Argumento | Tipo | Requerido | Lo que hace |
|---|---|---|---|
query | cadena, 1 a 300 caracteres | sí | Lo que se busca en las páginas de las obras. |
limit | entero, 1 a 50, defecto 10 | no | Líneas a servir. |
offset | entero, 0 o más, defecto 0 | no | Líneas a saltar, con el next_offset de una respuesta anterior. |
En retorno: líneas que llevan page, que get_work retoma; work y
composer, leídos sobre ese título; page_url; snippet, las palabras alrededor de la
correspondencia; size_bytes, words y last_edited tal como la biblioteca
los publica. El sobre lleva returned, has_more y next_offset, el offset
desde donde retomar. total vale siempre null: la biblioteca no publica ningún
conteo de lo que una búsqueda ha encontrado. composer vale null sobre un título escrito
fuera de la forma Œuvre (Compositeur), y snippet vale null sobre una línea
que la búsqueda no ha resumido con nada.
search_people
Encuentra a los compositores, editores, arreglistas e intérpretes por su nombre. La biblioteca escribe un nombre a su manera, apellido primero, por lo tanto la búsqueda encuentra a una persona allí donde una ortografía adivinada no alcanza nada.
| Argumento | Tipo | Requerido | Lo que hace |
|---|---|---|---|
query | cadena, 1 a 300 caracteres | sí | El nombre buscado entre las personas de la biblioteca. |
limit | entero, 1 a 50, defecto 10 | no | Líneas a servir. |
offset | entero, 0 o más, defecto 0 | no | Líneas a saltar, con el next_offset de una respuesta anterior. |
En retorno: líneas que llevan category, que get_person y
list_person_works retoman; name sin el prefijo; page_url; snippet;
y redirect_to. Una línea que lleva un redirect_to sirve en lugar de otra
categoría y no contiene ninguna obra, por lo tanto siga la categoría que nombra.
El sobre es el de search_works, y total allí vale null por la misma
razón.
get_work
Lee una obra: su título y sus títulos alternativos, el compositor, los números de opus y de catálogo, el año de composición y el de primera publicación, la dedicatoria, la tonalidad, el idioma, el libretista, la instrumentación, los movimientos, la creación, el estilo y el período.
| Argumento | Tipo | Requerido | Lo que hace |
|---|---|---|---|
page | cadena, 1 a 300 caracteres | uno de los dos | El título de la página, escrito Œuvre (Compositeur). |
pageid | entero, positivo | uno de los dos | El identificador de página devuelto por una búsqueda. |
En retorno: cada una de las características anteriores, null cuando la página la
deja vacía, y en los términos de la página, por lo tanto ca.1830 permanece ca.1830.
Al lado vienen genre_categories, que browse_category retoma;
external_links y authorities, los avisos de la obra en VIAF, LCCN,
WorldCat, BNF y GND; sections, con el número de entradas que el sitio
cuenta en cada una; y copyright_summary, una entrada por mención distinta,
con el número de ediciones que la llevan. editions contiene cada edición y
sus archivos, y pasa a null con editions_truncated en verdadero más allá de cinco
ediciones, que list_work_files recorre entonces. redirected_from nombra el título
solicitado cuando ha llevado aquí, y pageid vale null para una obra abordada por
su título.
list_work_files
Lee las partituras y las grabaciones de una obra, edición por edición. Una edición es un conjunto de archivos publicados bajo las mismas condiciones: el editor, el revisor y la mención de derechos pertenecen a la edición, y los archivos se ordenan debajo. Un bloque de grabaciones lleva intérpretes y ninguna mención de derechos.
| Argumento | Tipo | Requerido | Lo que hace |
|---|---|---|---|
page | cadena, 1 a 300 caracteres | uno de los dos | El título de la página, escrito Œuvre (Compositeur). |
pageid | entero, positivo | uno de los dos | El identificador de página devuelto por una búsqueda. |
section | cadena, 1 a 80 caracteres | no | Una sección de la página, en sus propios términos: Scores, Parts, Recordings, Arrangements and Transcriptions. La mayúscula se ignora. |
limit | entero, 1 a 100, defecto 10 | no | Ediciones a servir. |
offset | entero, 0 o más, defecto 0 | no | Ediciones a saltar. |
En retorno: editions, cada una con su section, su publisher_info, su
editor, su copyright y sus files. Un archivo lleva imslp_id,
description, format y format_code, pages, size_bytes, downloads,
rating, uploader, uploaded_on, el siglario y el nombre de la biblioteca que lo ha
digitalizado, y blocked, verdadero mientras IMSLP verifica los derechos de ese archivo.
downloads vale null sobre una entrada sin contador, y rating vale null
cuando nadie ha votado. Vienen también editions_on_page,
editions_in_section, returned, has_more y sections. Una section que no
corresponde a nada regresa con las secciones que la página contiene, por lo tanto una
restricción nunca se lee como una obra sin partitura.
list_person_works
Lee las obras que la biblioteca clasifica bajo una persona: lo que un compositor ha escrito, y también aquello sobre lo que un revisor, un arreglista o un intérprete está acreditado.
| Argumento | Tipo | Requerido | Lo que hace |
|---|---|---|---|
category | cadena, 1 a 300 caracteres | sí | La categoría de la persona, escrita Category:Nom, Prénom. |
limit | entero, 1 a 100, defecto 25 | no | Líneas a servir. |
cursor | cadena, 1 a 500 caracteres | no | El cursor nombrado por una respuesta anterior, dado tal cual. |
En retorno: líneas que llevan page, work, composer, pageid y
page_url, con has_more y cursor para continuar. total vale siempre
null: la biblioteca no publica ningún conteo de lo que contiene una categoría.
Una categoría que no contiene responde como una categoría vacía, por lo tanto una
respuesta sin línea invita a verificar la ortografía con search_people.
get_person
Lee lo que la biblioteca contiene sobre una persona: el nombre tal como su página lo imprime, las fechas de vida que indica, los otros nombres bajo los cuales la clasifica, los registros que tienen un aviso sobre ella, y las direcciones hacia las cuales remite fuera del sitio.
| Argumento | Tipo | Requerido | Lo que hace |
|---|---|---|---|
category | cadena, 1 a 300 caracteres | sí | La categoría de la persona, escrita Category:Nom, Prénom. |
En retorno: category, catalogued_as con el apellido primero, name tal
como la página lo imprime, life_dates en los términos de la página,
alternative_names y aliases como líneas publicadas, authorities con el
registro y el identificador en VIAF, LCCN, WorldCat, BNF y GND,
external_links, y page_url. life_dates vale null sobre una página que no
indica ninguna. Esta herramienta lee a la persona; list_person_works lee las obras.
browse_category
Lee las obras clasificadas bajo una categoría: un género, una tonalidad, una
instrumentación o un período. get_work devuelve estos nombres para una obra bajo
genre_categories, y volver a dar uno alcanza una categoría que la biblioteca
contiene.
| Argumento | Tipo | Requisito | Qué hace |
|---|---|---|---|
category | cadena, de 1 a 300 caracteres | sí | La categoría a leer, en los términos de la biblioteca: For piano, Nocturnes, B-flat minor. |
limit | entero, de 1 a 100, por defecto 25 | no | Líneas a servir. |
cursor | cadena, de 1 a 500 caracteres | no | El cursor nombrado por una respuesta anterior, devuelto tal cual. |
En retorno: las líneas que devuelve list_person_works, con los mismos
has_more y cursor, y total a null. La biblioteca lee una categoría a
la vez, por lo que una pregunta que nombre un género y un instrumento se responde
recorriendo uno y leyendo el otro en cada obra con get_work.
El estado de derechos
Una partitura lleva en IMSLP un estado por jurisdicción, y la biblioteca
verifica Canadá, Estados Unidos y la Unión Europea. Un archivo marcado
Public Domain - Non-PD US es libre en Canadá y en la Unión Europea, y
protegido en Estados Unidos. Este servidor devuelve el estado tal como se publica,
jurisdicción por jurisdicción, bajo copyright_summary para una obra y bajo
copyright para una edición, con restrictions que nombra los lugares que una
mención excluye. Un restrictions vacío no afirma nada sobre los países que IMSLP
deja fuera de su verificación.
Configuración
Cada variable es opcional. Se colocan en el bloque env de la
configuración del cliente.
| Variable | Por defecto | Qué hace |
|---|---|---|
IMSLP_USER_AGENT | la identidad del proyecto | Nombra su aplicación. La identidad del proyecto se añade para que IMSLP pueda contactar a una persona. |
IMSLP_MIN_INTERVAL_MS | 2500 | Intervalo entre dos solicitudes, de 2000 a 60000. Un valor por debajo del mínimo se rechaza en favor de este. |
IMSLP_TIMEOUT_MS | 30000 | Tiempo de espera de una solicitud, de 1000 a 120000. |
IMSLP_MAX_RETRIES | 3 | Intentos después de un fallo pasajero, de 0 a 10. |
IMSLP_CACHE_TTL_MS | 900000 | Duración durante la cual una página permanece en memoria, de 0 a 86400000. |
IMSLP_CACHE_MAX_ENTRIES | 100 | Páginas guardadas en memoria a la vez, de 0 a 10000. |
IMSLP_LOG_LEVEL | error | silent, error, info o debug, escrito en la salida de error. |
Un valor fuera de su rango cae en el valor por defecto, y la razón se escribe en la salida de error.
Errores
Cada fallo lleva uno de los seis códigos, un mensaje, y cuando ayuda una indicación del siguiente paso.
| Código | Qué sucedió | Qué hacer |
|---|---|---|
not_found | IMSLP respondió, y la página solicitada está ausente. | Verifique el título con search_works. |
invalid_input | Los argumentos fueron rechazados antes de cualquier solicitud. | Lea el mensaje, que nombra el argumento. |
rate_limited | IMSLP pide a este cliente que se ralentice. | Espere los segundos indicados y vuelva a llamar con los mismos argumentos. La obra sigue en la biblioteca. |
parse_failure | La página cargó y el contenido esperado está ausente. | Repórtelo en el seguimiento de incidentes. |
network_error | La solicitud no se completó. | Reintente en breve. |
timeout | La solicitud superó su tiempo de espera. | Aumente IMSLP_TIMEOUT_MS, o solicite menos líneas. |
Como biblioteca
La capa que lee IMSLP se publica sola, con su ritmo, su caché y sus errores, sin protocolo adjunto.
import { ImslpClient } from "mcp-imslp/client";
const client = new ImslpClient();
const { data, cached } = await client.getWork({ page: "Nocturnes, Op.9 (Chopin, Frédéric)" });
console.log(data.title, data.copyright_summary, cached);
renderPage, getWork, search, categoryMembers y getPerson responden
cada uno { data, cached }, y lanzan una ImslpError que lleva uno de los seis códigos.
El mínimo de dos segundos entre dos solicitudes también se aplica aquí.
Ritmo y atribución
IMSLP publica Crawl-delay: 2 en su robots.txt, por lo que las solicitudes salen una
a una con al menos dos segundos entre ellas, y este mínimo se mantiene sin importar
la configuración. El User-Agent siempre termina con la identidad del
proyecto y una dirección para contactar a una persona.
Las lecturas pasan por la API MediaWiki /api.php y por el punto de entrada
que IMSLP documenta en su página IMSLP:API. El robots.txt prohíbe /index.php,
/images/, /imglnks/, /wiki/File:, /works y /library/, y este servidor no
construye ninguna dirección bajo esas rutas: devuelve el enlace de la página de
la obra, que es lo que una respuesta acredita.
La biblioteca publica sus páginas bajo CC BY-SA 4.0, por lo que todo lo que este servidor devuelve atribuye a IMSLP y reenvía a la página original.
Privacidad
Este servidor no recopila nada sobre usted y no envía nada a su autor. Se ejecuta en
su máquina, solo contacta a imslp.org, guarda sus respuestas en memoria mientras
se ejecuta, y no escribe nada en el disco. PRIVACY.md dice qué
lleva una solicitud y qué ajustes cambian eso.
Desarrollo
npm install
npm run build:fixtures
npm test
npm run check
Las pruebas se ejecutan sobre fixtures generados y no emiten ninguna solicitud.
La suite en vivo, npm run test:live, emite una solicitud por ruta y se ejecuta
cada noche contra el sitio mismo.
Contribuir
Los tickets y las propuestas de modificación son bienvenidos en el repositorio. Ver CONTRIBUTING.md.
Licencia
MIT, ver LICENSE. El catálogo y las páginas pertenecen a IMSLP y a sus contribuyentes, publicados bajo CC BY-SA 4.0.