inspirehep-mcp

Servidor MCP InspireHEP

Um servidor MCP que integra a literatura de física de altas energias do InspireHEP com LLMs. Pesquise artigos, explore citações, obtenha métricas de autores e gere referências formatadas.

Instalação

# Using pip
pip install inspirehep-mcp

# Or run directly with uvx (no install needed)
uvx inspirehep-mcp

git clone https://github.com/MohamedElashri/inspirehep-mcp.git
cd inspirehep-mcp
uv sync
uv run inspirehep-mcp

Implantação de endpoint remoto

O comando instalado permanece um servidor stdio por padrão, portanto as configurações existentes de desktop continuam funcionando. Para executá-lo nativamente como um endpoint MCP remoto, selecione o transporte Streamable HTTP:

INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" \
  INSPIREHEP_HTTP_RATE_LIMIT=60 \
  inspirehep-mcp --transport streamable-http --host 0.0.0.0 --port 8000

O endpoint MCP é http://localhost:8000/mcp e a sonda de saúde não autenticada é http://localhost:8000/health. PORT também é respeitado quando uma plataforma de hospedagem o injeta. Coloque o serviço atrás de HTTPS para implantação na internet.

Docker

As tags de versão publicam um contêiner no GitHub Container Registry. A imagem usa Streamable HTTP por padrão:

docker run --rm -p 8000:8000 \
  ghcr.io/mohamedelashri/inspirehep-mcp:latest

Para um nome de host público, adicione-o à lista de permissões de host:

docker run --rm -p 8000:8000 \
  -e INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" \
  -e INSPIREHEP_HTTP_RATE_LIMIT=60 \
  ghcr.io/mohamedelashri/inspirehep-mcp:latest

A imagem é executada como um usuário não root, possui uma verificação de saúde integrada e usa respostas JSON sem estado, para que réplicas não precisem de estado de sessão MCP compartilhado.

Docker Compose

O docker-compose.yml incluído pode compilar o checkout atual ou executar a imagem publicada:

# Local deployment
docker compose up --build -d

# Add the public hostname when deploying behind a domain
INSPIREHEP_ALLOWED_HOSTS="mcp.example.org" docker compose up -d

O serviço Compose é somente leitura, remove capacidades Linux, ativa no-new-privileges e mantém a verificação de saúde da imagem.

Limitação de taxa de entrada

As solicitações Streamable HTTP são limitadas por IP do cliente com um token bucket. O padrão é 60 solicitações por minuto com uma rajada de 20; /health está isento. Defina INSPIREHEP_HTTP_RATE_LIMIT=0 para desativá-lo.

As solicitações para /mcp são limitadas a 256 KiB. O servidor nativo também aceita no máximo 100 conexões ou tarefas concorrentes, fecha conexões keep-alive ociosas após 5 segundos e admite no máximo 32 falhas de cache pendentes da API INSPIRE. O excesso de trabalho upstream falha rapidamente em vez de se acumular na memória.

Por padrão, o limitador usa o endereço do peer direto e ignora cabeçalhos encaminhados. Ative INSPIREHEP_TRUST_PROXY_HEADERS somente quando um proxy reverso confiável sobrescrever X-Forwarded-For; caso contrário, os clientes podem escolher sua própria identidade de limitação de taxa. O limitador está na memória e é por processo, portanto, implantações com múltiplas réplicas também devem aplicar um limite compartilhado no proxy ou gateway.

[!IMPORTANT] As ferramentas somente leitura evitam risco de mutação, mas um endpoint público ainda pode ser usado para consumir seu poder de processamento e a cota da API upstream. Este servidor não adiciona autenticação. Use um proxy reverso com autenticação se o endpoint não deve estar aberto a todos, e mantenha um limite de taxa na borda para implantações distribuídas. Mantenha a proteção contra rebinding de DNS ativada e defina INSPIREHEP_ALLOWED_ORIGINS para clientes que enviam um cabeçalho Origin.

Integração

Claude Desktop / Cursor

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "inspirehep": {
      "command": "uvx",
      "args": ["inspirehep-mcp"]
    }
  }
}

Claude Code

Opção A: Usando a CLI

# Global scope (available across all projects)
claude mcp add --scope user inspirehep -- uvx inspirehep-mcp

# Project scope (shared via .mcp.json, checked into source control)
claude mcp add --scope project inspirehep -- uvx inspirehep-mcp

Opção B: Configuração manual

Para escopo global, adicione a ~/.claude.json:

{
  "mcpServers": {
    "inspirehep": {
      "command": "uvx",
      "args": ["inspirehep-mcp"]
    }
  }
}

Para escopo do projeto, crie .mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "inspirehep": {
      "command": "uvx",
      "args": ["inspirehep-mcp"]
    }
  }
}

CLI Antigravity

Abra o gerenciador MCP interativo com /mcp, ou configure o servidor manualmente. O Antigravity lê servidores MCP globais de ~/.gemini/config/mcp_config.json e servidores locais do workspace de .agents/mcp_config.json:

{
  "mcpServers": {
    "inspirehep": {
      "command": "uvx",
      "args": ["inspirehep-mcp"]
    }
  }
}

Ferramentas

Configuração

Todas as configurações via variáveis de ambiente (prefixo INSPIREHEP_):

Desenvolvimento

# Run tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=inspirehep_mcp --cov-report=term-missing

# Unit tests only (no network)
uv run pytest tests/test_utils.py tests/test_cache.py tests/test_errors.py \
  tests/test_config.py tests/test_rate_limit.py tests/test_server.py \
  tests/test_api_client_safety.py tests/test_tools_safety.py

LICENÇA

Este projeto é licenciado sob a Licença AGPL-3.0 — consulte o arquivo LICENSE para obter detalhes.