Smithsonian Open Access

Un servidor MCP para interactuar con la colección de acceso abierto del Smithsonian.

Documentación

Servidor MCP de Smithsonian Open Access

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona a los asistentes de IA acceso a las colecciones de Acceso Abierto de la Institución Smithsonian. Este servidor permite que herramientas de IA como Claude Desktop busquen, exploren y analicen más de 3 millones de objetos de colección de los museos nacionales de Estados Unidos.

Inicio Rápido

Opción 1: Instalación con npm/npx (La más fácil)

El paquete npm incluye gestión automática de dependencias de Python y funciona en todas las plataformas:

# Install globally
npm install -g @molanojustin/smithsonian-mcp

# Or run directly with npx (no installation needed)
npx -y @molanojustin/smithsonian-mcp

# Set your API key
export SMITHSONIAN_API_KEY=your_key_here

# Start the server
smithsonian-mcp

Opción 2: Configuración Automatizada (Recomendada para usuarios de Python)

El script de configuración mejorado ahora incluye:

✅ Validación de clave API - Prueba tu clave antes de guardarla
✅ Instalación de servicio - Instalación automática como servicio del sistema
✅ Configuración de Claude Desktop - Configuración automática
✅ Comprobaciones de salud - Verifica que todo funcione macOS/Linux:

chmod +x config/setup.sh
config/setup.sh

Windows:

config\setup.ps1

Opción 3: Configuración Manual

Obtén una clave API: api.data.gov/signup (gratis)
Instala: uv pip install -r config/requirements.txt
Configura: Copia .env.example a .env y establece tu clave API
Prueba: python examples/test-api-connection.py

Verificar la Configuración

Ejecuta el script de verificación para comprobar tu instalación:

python scripts/verify-setup.py

Características

Funcionalidad Principal

Búsqueda en Colecciones: Más de 3 millones de objetos en 24 museos del Smithsonian
Detalles de Objetos: Metadatos completos, descripciones y procedencia
Estado de Exhibición - Encuentra objetos actualmente en exhibición física
Acceso a Imágenes: Imágenes de alta resolución (con licencia CC0 cuando estén disponibles)
Información de Museos: Explora todas las instituciones del Smithsonian
Estadísticas de Colecciones: Métricas completas con desgloses por museo (estimaciones basadas en muestreo)

Integración con IA

16 Herramientas MCP: Descubrimiento inteligente, búsqueda exhaustiva, consultas específicas por museo, estado de exhibición, acceso a datos contextuales y descubrimiento proactivo de tipos de colección
Descubrimiento Proactivo: Las nuevas herramientas ayudan a los asistentes de IA a comprender el alcance de la API y los tipos de objetos disponibles antes de buscar, evitando confusiones entre materiales de archivo y de museo
Contexto Inteligente: Fuentes de datos contextuales para asistentes de IA, incluyendo estadísticas mejoradas
Metadatos Enriquecidos: Información completa de objetos y detalles de exhibiciones
Planificación de Exhibiciones - Herramientas para encontrar y explorar objetos actualmente exhibidos
Analíticas de Colecciones: Estadísticas por museo con precisión basada en muestreo
Compatible con Múltiples Modelos: Funciona bien tanto con modelos de IA avanzados como con modelos más simples mediante interfaces de herramientas simplificadas

Validación de URL y Anti-Advinación

Solución Más Fácil: Usa search_and_get_first_url() para búsqueda en un solo paso y recuperación de URL validada
Uso Obligatorio de Herramientas: El LLM debe usar la herramienta get_object_url() para cualquier recuperación de URL - la construcción manual falla debido a la sensibilidad de mayúsculas
Identificadores Flexibles: Admite Números de Acceso (F1900.47), IDs de Registro (fsg_F1900.47) e IDs Internos (ld1-...)
Validación de URL: Selecciona automáticamente el record_link autoritativo sobre los identificadores de API, maneja la sensibilidad de mayúsculas

Integración

Claude Desktop

Opción 1: Usando npm/npx (Recomendado)

Configura (claude_desktop_config.json):

{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "npx",
      "args": ["-y", "@molanojustin/smithsonian-mcp"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_key_here"
      }
    }
  }
}

Opción 2: Usando instalación de Python

Configura (claude_desktop_config.json):

{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "python",
      "args": ["-m", "smithsonian_mcp.server"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_key_here"
      }
    }
  }
}

Prueba: Pregunta a Claude "¿Qué museos del Smithsonian están disponibles?"

Integración con mcpo (Orquestador MCP)

mcpo es un orquestador de MCP que convierte múltiples servidores MCP en endpoints OpenAPI/HTTP, ideal para combinar múltiples servicios en un solo servicio systemd.

Instalación

# Install mcpo
uvx mcpo

# Or using uvx
uvx mcpo --help

Configuración

Crea un archivo examples/mcpo-config.json:

{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "python",
      "args": ["-m", "smithsonian_mcp.main"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_api_key_here"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "time": {
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=America/New_York"]
    }
  }
}

Ejecución con mcpo

# Start mcpo with hot-reload
mcpo --config examples/mcpo-config.json --port 8000 --hot-reload

# With API key authentication
mcpo --config examples/mcpo-config.json --port 8000 --api-key "your_secret_key"

# Access endpoints:
# - Smithsonian: http://localhost:8000/smithsonian_open_access
# - Memory: http://localhost:8000/memory
# - Time: http://localhost:8000/time
# - API docs: http://localhost:8000/docs

Servicio Systemd

Crea /etc/systemd/system/mcpo.service:

[Unit]
Description=MCP Orchestrator Service
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/your/config
Environment=PATH=/path/to/venv/bin
ExecStart=/path/to/venv/bin/mcpo --config examples/mcpo-config.json --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Enable and start service
sudo systemctl enable mcpo
sudo systemctl start mcpo
sudo systemctl status mcpo

Solución de Problemas con mcpo

Consulta TROUBLESHOOTING.md para obtener una solución detallada de problemas con mcpo, incluyendo:

Soluciones para ModuleNotFoundError
Errores de conexión cerrada
Conflictos de puertos
Problemas de configuración de rutas

VS Code

Abre el Espacio de Trabajo: code .vscode/smithsonian-mcp-workspace.code-workspace
Ejecuta Tareas: Depura, prueba y desarrolla el servidor MCP
Claude Code: Desarrollo asistido por IA con datos del Smithsonian

Datos Disponibles

19 Museos: NMNH, NPG, SAAM, NASM, NMAH, y más
Más de 3 Millones de Objetos: Artículos de colección digitalizados
Contenido CC0: Materiales de dominio público para uso comercial
Metadatos Enriquecidos: Creadores, fechas, materiales, dimensiones
Imágenes de Alta Resolución: Fotografía profesional

Precisión de Datos y Muestreo

Las estadísticas de colecciones para objetos con imágenes utilizan metodología de muestreo para proporcionar estimaciones precisas:

Tamaño de Muestra: Hasta 1000 objetos por consulta para significancia estadística
Metodología: Cuenta los objetos realmente devueltos en lugar de depender de totales de API potencialmente defectuosos
Cobertura: Incluye desgloses por museo con muestreo individual para cada institución
Transparencia: Todos los conteos muestreados están claramente marcados como "(est.)" en los resultados

Este enfoque garantiza métricas confiables mientras respeta los límites de tasa de la API y evita el error de filtrado de rowCount de la API del Smithsonian.

Limitaciones Actuales de la API

URLs de Imágenes No Disponibles: La API de Acceso Abierto del Smithsonian actualmente no proporciona URLs de imágenes ni datos de medios en las respuestas de contenido detallado. Aunque la API de búsqueda puede filtrar objetos por tipo de medio (por ejemplo, online_media_type:Images), las URLs reales de imágenes no están incluidas en los datos detallados de objetos devueltos por la API de contenido. Esto parece ser un cambio en la API desde que se publicó la documentación disponible.

Los objetos se mostrarán con 0 imágenes incluso cuando se filtren por contenido de imagen
Las estadísticas de imágenes son estimaciones basadas en el filtrado de búsqueda, no en la disponibilidad real de medios
El sistema maneja esta limitación con elegancia y continúa proporcionando todos los demás metadatos

Alcance de la API: Colecciones de Museos Diversas: La API de Acceso Abierto del Smithsonian proporciona acceso a colecciones diversas en 24 museos del Smithsonian, con cada museo teniendo tipos de objetos distintos que reflejan sus áreas de enfoque únicas. Las herramientas de descubrimiento ahora identifican correctamente colecciones específicas de museos con inteligencia integral de tipos de objetos recopilada mediante muestreo sistemático.

SAAM (Arte Americano): Pinturas, artes decorativas, esculturas, dibujos
NASM (Aire y Espacio): Aeronaves, aviónica, naves espaciales, equipo de aviación
NMAH (Historia Americana): Artefactos históricos, inventos, objetos culturales
CHNDM (Museo de Diseño): Objetos de diseño, textiles, muebles, gráficos
Usa las herramientas de descubrimiento (get_museum_collection_types, check_museum_has_object_type) para explorar las colecciones disponibles
La colección de cada museo refleja su misión institucional y experiencia

Herramientas MCP

Búsqueda y Descubrimiento

simple_explore - Muestreo inteligente y diverso en museos y tipos de objetos (recomendado para descubrimiento general)
continue_explore - Obtén más resultados sobre el mismo tema evitando duplicados
search_collections - Búsqueda avanzada con filtros (prioriza resultados específicos de museos cuando se especifica unit_code)
search_and_get_first_url - Opción más fácil: Busca y obtén URL validada en un solo paso (previene la construcción manual de URLs)
get_object_details - Información detallada de objetos
get_object_url - Obtén URLs de objetos validadas con soporte de identificadores flexibles (OBLIGATORIO: nunca construyas URLs manualmente)
search_by_unit - Búsquedas específicas de museos
get_objects_on_view - Encuentra objetos actualmente en exhibición física
check_object_on_view - Verifica si un objeto específico está en exhibición
get_museum_collection_types - Obtén una lista completa de tipos de objetos disponibles en cada museo (basada en muestreo sistemático de colecciones)
check_museum_has_object_type - Verifica si un museo específico tiene objetos de un tipo particular (por ejemplo, pinturas, esculturas)

Información y Contexto

get_smithsonian_units - Lista todos los museos
get_collection_statistics - Métricas de colecciones con desgloses por museo
get_search_context - Obtén resultados de búsqueda como datos de contexto
get_object_context - Obtén información detallada de objetos como contexto
get_units_context - Obtén lista de unidades como datos de contexto
get_stats_context - Obtén estadísticas de colecciones como contexto (incluye estimaciones basadas en muestreo)
get_on_view_context - Obtén objetos actualmente exhibidos como contexto

Casos de Uso

Investigación y Educación

Investigación Académica: Investigación académica en múltiples pasos
Planificación de Lecciones: Creación de contenido educativo
Análisis de Objetos: Estudio profundo de objetos culturales
Recuperación de URLs: Obtén URLs validadas de páginas web de objetos (con protección anti-advinación)

Curaduría y Exhibición

Planificación de Exhibiciones: Selección temática de objetos y planificación de visitantes
Planificación de Visitas: Encuentra lo que está actualmente en exhibición antes de visitar
Investigación de Exhibiciones: Estudia tendencias y exhibiciones actuales
Desarrollo de Colecciones: Análisis de brechas y adquisiciones
Humanidades Digitales: Proyectos de análisis a gran escala

Desarrollo

Aplicaciones Culturales: Aplicaciones que utilizan datos de museos
Herramientas Educativas: Plataformas de aprendizaje interactivo
Integración de API: Flujos de trabajo de desarrollo profesional

Requisitos

Para instalación con npm/npx:

Node.js 16.0 o superior
Python 3.10 o superior (detección automática y gestión de dependencias)
Clave API de api.data.gov (gratis)
Conexión a Internet para acceso a la API

Para instalación con Python:

Python 3.10 o superior
Clave API de api.data.gov (gratis)
Conexión a Internet para acceso a la API

Pruebas

Usando npm/npx:

# Test API connection
smithsonian-mcp --test

# Run MCP server
smithsonian-mcp

# Show help
smithsonian-mcp --help

Usando Python:

# Test API connection
python examples/test-api-connection.py

# Run MCP server
python -m smithsonian_mcp.server

# Run test suite
pytest tests/

# Run on-view functionality tests
pytest tests/test_on_view.py -v

# Run basic tests
pytest tests/test_basic.py -v

# Verify complete setup
python scripts/verify-setup.py

# VS Code Tasks (if using workspace)
# - Test MCP Server
# - Run Tests
# - Format Code
# - Lint Code

Gestión de Servicios

Linux (systemd)

# Start service
systemctl --user start smithsonian-mcp

# Stop service
systemctl --user stop smithsonian-mcp

# Check status
systemctl --user status smithsonian-mcp

# Enable on boot
systemctl --user enable smithsonian-mcp

macOS (launchd)

# Load service
launchctl load ~/Library/LaunchAgents/com.smithsonian.mcp.plist

# Unload service
launchctl unload ~/Library/LaunchAgents/com.smithsonian.mcp.plist

# Check status
launchctl list | grep com.smithsonian.mcp

Windows

# Start service
Start-Service SmithsonianMCP

# Stop service
Stop-Service SmithsonianMCP

# Check status
Get-Service SmithsonianMCP

Solución de Problemas

Para obtener orientación detallada sobre solución de problemas, incluyendo:

Problemas comunes de configuración
Problemas de inicio de servicios
Validación de claves API
Problemas de conexión con Claude Desktop
Errores de importación de módulos
Problemas específicos de plataforma

Consulta TROUBLESHOOTING.md.

Documentación

Documentación Disponible

README.md - Guía principal de configuración y uso (este archivo)
TROUBLESHOOTING.md - Solución integral de problemas y problemas comunes
Ejemplos - Escenarios de uso del mundo real en el directorio examples/
Scripts - Scripts de configuración y utilidades en el directorio scripts/

Referencia Clave

Referencia de API: Documentación completa de herramientas y recursos en este README
Guía de Implementación: Opciones de implementación de producción incluidas en las instrucciones de configuración
Guía de Integración: Instrucciones de configuración de Claude Desktop y mcpo en este README

Contribuciones

Haz un fork del repositorio
Crea una rama de características
Realiza tus cambios
Ejecuta las pruebas
Envía una solicitud de extracción (pull request)

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

Institución Smithsonian por las colecciones de Acceso Abierto
api.data.gov por la infraestructura de API
Equipo de FastMCP por el marco de trabajo MCP
Comunidad de Protocolo de Contexto de Modelo