Smithsonian Open Access

Um servidor MCP para interagir com a coleção de Acesso Aberto do Smithsonian.

GitHub
10
Experimente este MCPPatrocinado

Documentação

Servidor MCP Smithsonian Open Access

npm version NPM Downloads Docker

Um servidor Model Context Protocol (MCP) que fornece a assistentes de IA acesso às coleções de Open Access da Smithsonian Institution. Este servidor permite que ferramentas de IA como o Claude Desktop pesquisem, explorem e analisem mais de 3 milhões de objetos de coleção dos museus nacionais da América.

Início Rápido

Opção 1: Instalação via npm/npx (Mais Fácil)

O pacote npm inclui gerenciamento automático de dependências Python e funciona em todas as 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

Opção 2: Configuração Automatizada (Recomendado para usuários Python)

O script de configuração aprimorado agora inclui:

  • ✅ Validação de chave de API - Testa sua chave antes de salvar
  • ✅ Instalação de serviço - Instalação automática como serviço do sistema
  • ✅ Configuração do Claude Desktop - Configuração automática
  • ✅ Verificações de integridade - Verifica se tudo funciona macOS/Linux:
chmod +x config/setup.sh
config/setup.sh

Windows:

config\setup.ps1

Opção 3: Configuração Manual

  1. Obtenha a Chave de API: api.data.gov/signup (gratuita)
  2. Instale: uv pip install -r config/requirements.txt
  3. Configure: Copie .env.example para .env e defina sua chave de API
  4. Teste: python examples/test-api-connection.py

Verifique a Configuração

Execute o script de verificação para checar sua instalação:

python scripts/verify-setup.py

Recursos

Funcionalidade Principal

  • Pesquisa em Coleções: Mais de 3 milhões de objetos em 24 museus Smithsonian
  • Detalhes de Objetos: Metadados completos, descrições e procedência
  • Status em Exposição - Encontre objetos atualmente em exposição física
  • Acesso a Imagens: Imagens de alta resolução (licenciadas CC0 quando disponíveis)
  • Informações dos Museus: Navegue por todas as instituições Smithsonian
  • Estatísticas das Coleções: Métricas abrangentes com detalhamento por museu (estimativas baseadas em amostragem)

Integração com IA

  • 16 Ferramentas MCP: Descoberta inteligente, pesquisa abrangente, consultas específicas por museu, status de exposição, acesso a dados contextuais e descoberta proativa de tipos de coleção
  • Descoberta Proativa: Novas ferramentas ajudam assistentes de IA a entender o escopo da API e os tipos de objetos disponíveis antes de pesquisar, evitando confusão entre materiais de arquivo e de museu
  • Contexto Inteligente: Fontes de dados contextuais para assistentes de IA, incluindo estatísticas aprimoradas
  • Metadados Ricos: Informações completas de objetos e detalhes de exposições
  • Planejamento de Exposições - Ferramentas para encontrar e explorar objetos atualmente em exposição
  • Análise de Coleções: Estatísticas por museu com precisão baseada em amostragem
  • Compatível com Múltiplos Modelos: Funciona bem com modelos de IA avançados e mais simples através de interfaces de ferramentas simplificadas

Validação de URL e Anti-Advinhação

  • Solução Mais Fácil: Use search_and_get_first_url() para pesquisa em uma etapa + recuperação de URL validada
  • Uso Obrigatório de Ferramenta: O LLM deve usar a ferramenta get_object_url() para qualquer recuperação de URL - a construção manual falha devido à sensibilidade a maiúsculas/minúsculas
  • Identificadores Flexíveis: Suporta Números de Acesso (F1900.47), IDs de Registro (fsg_F1900.47) e IDs Internos (ld1-...)
  • Validação de URL: Seleciona automaticamente o record_link autoritativo em vez de identificadores de API, lidando com sensibilidade a maiúsculas/minúsculas

Integração

Claude Desktop

Opção 1: Usando npm/npx (Recomendado)

  1. Configure (claude_desktop_config.json):
{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "npx",
      "args": ["-y", "@molanojustin/smithsonian-mcp"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_key_here"
      }
    }
  }
}

Opção 2: Usando instalação Python

  1. Configure (claude_desktop_config.json):
{
  "mcpServers": {
    "smithsonian_open_access": {
      "command": "python",
      "args": ["-m", "smithsonian_mcp.server"],
      "env": {
        "SMITHSONIAN_API_KEY": "your_key_here"
      }
    }
  }
}
  1. Teste: Pergunte ao Claude "Quais museus Smithsonian estão disponíveis?"

Integração com mcpo (MCP Orchestrator)

mcpo é um orquestrador MCP que converte múltiplos servidores MCP em endpoints OpenAPI/HTTP, ideal para combinar vários serviços em um único serviço systemd.

Instalação

# Install mcpo
uvx mcpo

# Or using uvx
uvx mcpo --help

Configuração

Crie um arquivo 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"]
    }
  }
}

Executando com 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

Serviço Systemd

Crie /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

Solução de Problemas com mcpo

Consulte TROUBLESHOOTING.md para solução de problemas detalhada do mcpo, incluindo:

  • Soluções para ModuleNotFoundError
  • Erros de conexão fechada
  • Conflitos de porta
  • Problemas de configuração de caminho

VS Code

  1. Abra o Workspace: code .vscode/smithsonian-mcp-workspace.code-workspace
  2. Execute Tarefas: Depure, teste e desenvolva o servidor MCP
  3. Claude Code: Desenvolvimento assistido por IA com dados Smithsonian

Dados Disponíveis

  • 19 Museus: NMNH, NPG, SAAM, NASM, NMAH e outros
  • Mais de 3 Milhões de Objetos: Itens de coleção digitalizados
  • Conteúdo CC0: Materiais de domínio público para uso comercial
  • Metadados Ricos: Criadores, datas, materiais, dimensões
  • Imagens de Alta Resolução: Fotografia profissional

Precisão de Dados e Amostragem

As estatísticas de coleção para objetos com imagens usam metodologia de amostragem para fornecer estimativas precisas:

  • Tamanho da Amostra: Até 1000 objetos por consulta para significância estatística
  • Metodologia: Conta os objetos realmente retornados em vez de depender de totais de API potencialmente problemáticos
  • Cobertura: Inclui detalhamentos por museu com amostragem individual para cada instituição
  • Transparência: Todas as contagens amostradas são claramente marcadas como "(est.)" nas saídas

Esta abordagem garante métricas confiáveis, respeitando os limites de taxa da API e evitando o bug de filtragem rowCount da API Smithsonian.

Limitações Atuais da API

URLs de Imagem Indisponíveis: A API Smithsonian Open Access atualmente não fornece URLs de imagem ou dados de mídia em respostas de conteúdo detalhado. Embora a API de pesquisa possa filtrar objetos por tipo de mídia (por exemplo, online_media_type:Images), as URLs reais das imagens não estão incluídas nos dados detalhados do objeto retornados pela API de conteúdo. Isso parece ser uma mudança na API desde que a documentação disponível foi publicada.

  • Objetos aparecerão como tendo 0 imagens mesmo quando filtrados por conteúdo de imagem
  • As estatísticas de imagem são estimativas baseadas em filtragem de pesquisa, não na disponibilidade real de mídia
  • O sistema lida graciosamente com essa limitação e continua fornecendo todos os outros metadados

Escopo da API: Coleções Diversas de Museus: A API Smithsonian Open Access fornece acesso a coleções diversas em 24 museus Smithsonian, com cada museu tendo tipos distintos de objetos refletindo suas áreas de foco únicas. As ferramentas de descoberta agora identificam corretamente coleções específicas de museus com inteligência abrangente de tipos de objetos coletada através de amostragem sistemática.

  • SAAM (Arte Americana): Pinturas, artes decorativas, esculturas, desenhos
  • NASM (Ar e Espaço): Aeronaves, aviônicos, naves espaciais, equipamentos de aviação
  • NMAH (História Americana): Artefatos históricos, invenções, objetos culturais
  • CHNDM (Museu de Design): Objetos de design, têxteis, móveis, gráficos
  • Use ferramentas de descoberta (get_museum_collection_types, check_museum_has_object_type) para explorar coleções disponíveis
  • A coleção de cada museu reflete sua missão institucional e expertise

Ferramentas MCP

Pesquisa e Descoberta

  • simple_explore - Amostragem diversificada inteligente entre museus e tipos de objetos (recomendado para descoberta geral)
  • continue_explore - Obtenha mais resultados sobre o mesmo tópico evitando duplicatas
  • search_collections - Pesquisa avançada com filtros (prioriza resultados específicos do museu quando unit_code é especificado)
  • search_and_get_first_url - Opção mais fácil: Pesquise e obtenha URL validada em uma etapa (evita construção manual de URL)
  • get_object_details - Informações detalhadas do objeto
  • get_object_url - Obtenha URLs de objetos validadas com suporte a identificadores flexíveis (OBRIGATÓRIO: nunca construa URLs manualmente)
  • search_by_unit - Pesquisas específicas por museu
  • get_objects_on_view - Encontre objetos atualmente em exposição física
  • check_object_on_view - Verifique se um objeto específico está em exibição
  • get_museum_collection_types - Obtenha lista abrangente de tipos de objetos disponíveis em cada museu (baseada em amostragem sistemática de coleções)
  • check_museum_has_object_type - Verifique se um museu específico tem objetos de um tipo particular (por exemplo, pinturas, esculturas)

Informação e Contexto

  • get_smithsonian_units - Liste todos os museus
  • get_collection_statistics - Métricas de coleção com detalhamento por museu
  • get_search_context - Obtenha resultados de pesquisa como dados de contexto
  • get_object_context - Obtenha informações detalhadas do objeto como contexto
  • get_units_context - Obtenha lista de unidades como dados de contexto
  • get_stats_context - Obtenha estatísticas de coleção como contexto (inclui estimativas baseadas em amostragem)
  • get_on_view_context - Obtenha objetos atualmente em exposição como contexto

Casos de Uso

Pesquisa e Educação

  • Pesquisa Acadêmica: Investigação acadêmica em múltiplas etapas
  • Planejamento de Aulas: Criação de conteúdo educacional
  • Análise de Objetos: Estudo aprofundado de objetos culturais
  • Recuperação de URL: Obtenha URLs validadas de páginas web de objetos (com proteção anti-advinhação)

Curadoria e Exposição

  • Planejamento de Exposições: Seleção temática de objetos e planejamento de visitantes
  • Planejamento de Visitas: Descubra o que está atualmente em exibição antes de visitar
  • Pesquisa de Exposições: Estude tendências e exibições atuais
  • Desenvolvimento de Coleções: Análise de lacunas e aquisição
  • Humanidades Digitais: Projetos de análise em larga escala

Desenvolvimento

  • Aplicativos Culturais: Aplicações usando dados de museus
  • Ferramentas Educacionais: Plataformas de aprendizagem interativas
  • Integração de API: Fluxos de trabalho de desenvolvimento profissional

Requisitos

Para instalação via npm/npx:

  • Node.js 16.0 ou superior
  • Python 3.10 ou superior (detectado automaticamente e dependências gerenciadas)
  • Chave de API de api.data.gov (gratuita)
  • Conexão com a internet para acesso à API

Para instalação Python:

  • Python 3.10 ou superior
  • Chave de API de api.data.gov (gratuita)
  • Conexão com a internet para acesso à API

Testes

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

Gerenciamento de Serviço

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

Solução de Problemas

Para orientação detalhada de solução de problemas, incluindo:

  • Problemas comuns de configuração
  • Problemas de inicialização de serviço
  • Validação de chave de API
  • Problemas de conexão com Claude Desktop
  • Erros de importação de módulo
  • Problemas específicos de plataforma

Consulte TROUBLESHOOTING.md.

Documentação

Documentação Disponível

  • README.md - Guia principal de configuração e uso (este arquivo)
  • TROUBLESHOOTING.md - Solução de problemas abrangente e problemas comuns
  • Exemplos - Cenários de uso do mundo real no diretório examples/
  • Scripts - Scripts de configuração e utilitários no diretório scripts/

Referência Principal

  • Referência da API: Documentação completa de ferramentas e recursos neste README
  • Guia de Implantação: Opções de implantação em produção incluídas nas instruções de configuração
  • Guia de Integração: Instruções de configuração do Claude Desktop e mcpo neste README

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Execute os testes
  5. Envie um pull request

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos

  • Smithsonian Institution pelas coleções Open Access
  • api.data.gov pela infraestrutura da API
  • Equipe FastMCP pelo framework MCP
  • Comunidade Model Context Protocol