Hub-Equity MCP

Fundamentos de XBRL de la SEC y europeo (ESEF) en un solo vocabulario de conceptos, cada cifra con su presentación y la etiqueta del emisor, enmiendas y reexpresiones silenciosas rastreadas. Servidor stdio de solo lectura, Python.

GitHubPrueba este MCPPatrocinado

Documentación

hub-equity-mcp

Datos financieros XBRL estandarizados para agentes LLM. Un servidor de Protocolo de Contexto de Modelo (MCP) que expone hechos financieros normalizados de presentaciones de la SEC de EE. UU. (EDGAR) y ESEF europeas a Claude Desktop, Cursor y cualquier cliente compatible con MCP.

Hub-Equity sirve presentaciones estandarizadas ESEF europeas junto con datos de la SEC de EE. UU. a través de un vocabulario de conceptos hub consistente, de modo que un agente puede solicitar REVENUE o TOTAL_ASSETS y obtener un valor comparable y vinculado a la fuente, ya sea que el emisor presente ante la SEC o bajo ESEF.

Madurez. La API REST pública detrás de este conector opera en producción y alimenta el chat propio de Hub-Equity. El paquete sigue Versionado Semántico; mantiene el clasificador Beta mientras su base de instalación sea joven.

Por qué

Un vocabulario para dos regímenes. Los conceptos us-gaap de la SEC y ifrs-full de ESEF se asignan a un único conjunto estandarizado de códigos hub, de modo que la comparación entre emisores y entre taxonomías funciona de inmediato.
Cada número está vinculado a su fuente. Los hechos llevan su presentación, período y procedencia, para que un agente pueda citar en lugar de adivinar.
Consciente de reexpresiones. Enmiendas explícitas y reexpresiones silenciosas (una cifra que una presentación posterior reimprimió de forma diferente, sin enmienda presentada), cada cambio con la presentación que lo originó.
Solo lectura y mundo cerrado. Cada herramienta anuncia readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false según la especificación MCP, para que los clientes puedan razonar sobre seguridad y almacenamiento en caché sin introspección.
Sin credenciales de base de datos. El paquete publicado solo se comunica con la API REST pública (https://api.hub-equity.com) a través de HTTPS. Nunca incluye ni requiere una clave de base de datos.

Instalación

pipx run hub-equity-mcp

pipx run (o uvx hub-equity-mcp) descarga e inicia el servidor en un entorno aislado; pip install hub-equity-mcp también funciona. Requiere Python 3.12 o superior.

Autenticación y acceso

El servidor solo se comunica con la API REST pública, que requiere una clave hubq_ (variable de entorno HUBEQUITY_API_KEY).

Clave gratuita. Crea una cuenta y una clave en un minuto en https://hub-equity.com/settings/api-keys.. Ofrece el conjunto básico de herramientas (búsqueda de entidades, hechos normalizados, series temporales, segmentos, filtro, calificación de calidad de datos, conversión de divisas y más).
Plan de pago. Desbloquea las herramientas premium (diferencias de reexpresión, árboles de cálculo, comparación entre períodos, comparación entre emisores, verificaciones de validación, conceptos de extensión) y aumenta el límite de tasa. Consulta la tabla a continuación.

El paquete publicado nunca accede directamente a la base de datos, solo a la API REST.

Configura tu cliente

Claude Desktop

Agrega a claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

Sin HUBEQUITY_API_KEY, cada llamada a herramienta responde HUBEQUITY_API_KEY is not set con el enlace a una clave gratuita.

Cursor

Agrega a .cursor/mcp.json (raíz del proyecto) o a la configuración global de MCP de Cursor:

{
  "mcpServers": {
    "hub-equity": {
      "command": "pipx",
      "args": ["run", "hub-equity-mcp"],
      "env": {
        "HUBEQUITY_API_KEY": "INSERT_YOUR_API_KEY"
      }
    }
  }
}

Variables de entorno

HUBEQUITY_API_KEY (obligatoria): una clave hubq_. Una clave gratuita abre las herramientas básicas; un plan de pago abre las herramientas premium y el límite de tasa más alto.
HUBEQUITY_API_URL (opcional): el valor predeterminado es https://api.hub-equity.com. https:// se aplica siempre que se establezca una clave (el servidor se niega a enviar la clave Bearer en texto plano a un host que no sea de bucle local).

Capacidades

Tipo	Qué
Herramientas	Herramientas de solo lectura: descubrimiento, hechos, series temporales, segmentos, verificaciones forenses (tabla a continuación)
Recursos	Catálogo hub, esquema de estados, catálogo de niveles, guías de uso, instantánea de cobertura
Prompts	Plantillas analíticas (lista a continuación)
API de finalización	Autocompletado `{hub_code}`

Herramientas

El catálogo de niveles legible por máquina se sirve como recurso (hub-equity://catalog/tool-tiers). Las herramientas gratuitas cubren descubrimiento e identidad; las herramientas Pro, disponibles en todo plan de pago (Builder, Team, Enterprise), añaden profundidad forense (árboles de cálculo, diferencias de reexpresión en enmiendas y reexpresiones silenciosas, comparación entre períodos, comparación entre emisores, resultados de validación, conceptos de extensión). El nivel de una herramienta refleja el endpoint REST que llama: el endpoint de cada herramienta Pro requiere el alcance facts.premium en el servidor, y los límites gratuitos (get_fact_decomposition profundidad 1 sin componentes de consolidación ni cortes dimensionales, screen_companies 20 resultados sin el filtro de calidad, get_segments ejes sin miembros, roll_up_metric el valor sin su regla) los aplica la API, no solo este paquete.

Herramienta	Nivel	Qué hace
`find_entity(query)`	Gratuita	Busca por nombre, ticker o CIK. Devuelve el `entity_id` que necesitan otras herramientas.
`get_fact(entity_id, hub_concept_code, fiscal_year, fiscal_period_type?)`	Gratuita	Un valor normalizado más su fuente de presentación.
`get_fact_decomposition(entity_id, fiscal_year, hub_concept_code? or qname?, depth?)`	Gratuita (profundidad 1, solo linkbase) / Pro (profundidad 2-3)	Consolidación hub, hijos del linkbase de cálculo XBRL y desglose dimensional. Gratuita: la capa de linkbase, sin los componentes de consolidación ni los cortes dimensionales.
`search_concept(query)`	Gratuita	Resuelve un código hub a partir de una etiqueta o un código parcial.
`list_hubs(category?, include_non_primary?, limit?)`	Gratuita	Enumera el catálogo hub estandarizado por categoría.
`get_entity_profile(entity_id)`	Gratuita	Sector, auditor, empleados, fin de año fiscal, presentaciones recientes.
`get_metric_history(entity_id, hub_concept_code, n_years?)`	Gratuita	Serie temporal de N años con crecimiento interanual y CAGR.
`get_segments(entity_id, hub_concept_code, fiscal_year)`	Gratuita (limitada)	Desglose dimensional de eje/miembro (segmento, geografía). Gratuita: los ejes sin sus miembros; Pro: cada miembro.
`get_amendments(entity_id, fiscal_year?)`	Gratuita	Resumen de reexpresión 10-K/A: cada enmienda, sus cambios por concepto (50 por enmienda).
`get_silent_restatements(entity_id, fiscal_year?)`	Gratuita	Reexpresiones silenciosas: cifras que una presentación posterior reimprimió de forma diferente en sus columnas comparativas, sin enmienda presentada, agrupadas por la presentación que las reveló (50 cambios por presentación).
`compare_entities(entity_ids, hub_concept_codes, fiscal_year)`	Pro (hasta 10x10)	Matriz de comparación entre emisores en un período, alineada por año calendario. Acepta UUID, tickers o `TICKER.MIC`.
`roll_up_metric(entity_id, hub_concept_code, fiscal_year)`	Gratuita (limitada)	Calcula un valor a partir de hijos con signo cuando no está etiquetado directamente. Gratuita: el valor; Pro: la regla y las contribuciones con signo detrás.
`convert_currency(amount, from_currency, to_currency, date?, rate_type?)`	Gratuita	Conversión de divisas con tipo de referencia del BCE (cierre, promedio YTD, promedio del año anterior).
`screen_companies(country?, sector?, min_revenue?, ..., sort_by?, limit?)`	Gratuita (límite 20, sin filtro de calidad) / Pro (mayor)	Filtra el universo de emisores por metadatos, ingresos, auditoría y calidad de datos.
`get_amendment_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)`	Pro	Diferencias 10-K/A por concepto: materialidad, filtros de tipo y concepto, etiqueta, delta absoluto, ambas presentaciones como fuentes.
`get_silent_restatement_diff(entity_id, fiscal_year?, hub_concept_code?, min_diff_pct?, kind_filter?)`	Pro	La misma diferencia en las reexpresiones silenciosas.
`get_calculation_tree(filing_id, link_role?)`	Pro	Linkbase de cálculo de la presentación: cada total y sus componentes, signo declarado junto al signo que respaldan los valores presentados.
`compare_filings(entity_id, fiscal_year_a, fiscal_year_b, hub_concept_codes?)`	Pro	Comparación entre períodos de la misma entidad con indicadores de nuevo / eliminado / cambio de signo / reexpresión.
`get_extension_concepts(entity_id, status_filter?, limit?)`	Pro	qnames específicos del emisor declarados fuera de las taxonomías estándar.
`get_data_quality_grade(entity_id)`	Gratuita	Calificación de A+ a D (o ninguna), las dos puertas y los recuentos detrás, frescura, desglose directo vs. derivado.
`get_validation_results(filing_id?, entity_id?, fiscal_year?, status_filter?)`	Pro	Verificaciones contables XBRL y del linkbase de cálculo.

Recursos

URI	Tipo	Propósito
`hub-equity://catalog/hubs`	json	Catálogo hub estandarizado completo con etiquetas EN/FR y categoría.
`hub-equity://catalog/categories`	json	Recuentos hub por categoría.
`hub-equity://catalog/tool-tiers`	markdown	Catálogo de herramientas gratuitas vs. Pro y condiciones de acceso.
`hub-equity://schema/financial-statements`	markdown	Estructura de estados y reglas de lectura.
`hub-equity://catalog/hub/{hub_code}`	template	Entrada de catálogo reenviada para un hub.
`hub-equity://entity/{entity_id}/profile`	template	Instantánea completa de entidad.
`hub-equity://prompts/best-practices`	markdown	Guía de indicaciones del sistema para integraciones de cliente. Cárgalo antes de llamar a cualquier herramienta.
`hub-equity://prompts/tool-usage-examples`	markdown	Ejemplos de pocas muestras por herramienta (buenos y contraejemplos).
`hub-equity://prompts/data-coverage`	json	Instantánea de conjunto de datos en vivo (recuentos de emisores y presentaciones, fuentes, taxonomías, rango de años fiscales). Caché de 24 h.

Prompts

Ocho plantillas analíticas: peer_comparison, quality_of_earnings, restatement_audit, sector_overview, valuation_screen, goodwill_impairment_risk, working_capital_diagnostic, cash_flow_consistency.

Para desarrolladores de clientes

Antes de llamar a cualquier herramienta, obtén hub-equity://prompts/best-practices e inyecta el markdown en tu indicación del sistema. Esto hace que tu cliente siga las mismas reglas de enrutamiento de herramientas, citación de fuentes y fidelidad numérica que el chat propio de Hub-Equity.

# Pseudo-code for a typical MCP client integration
session = mcp.connect("hub-equity-mcp")
best_practices = session.read_resource("hub-equity://prompts/best-practices")
system_prompt = "You are an assistant ...\n\n" + best_practices
# now call session.call_tool("find_entity", {"query": "AAPL"}) etc.

Límites de tasa

Modo	Límite	Notas
Clave gratuita	120 solicitudes / minuto	Herramientas básicas.
Clave Builder	300 solicitudes / minuto	Herramientas premium desbloqueadas.
Clave Team	600 solicitudes / minuto	Herramientas premium desbloqueadas.
Clave Enterprise	1 000 solicitudes / minuto	Negociable.

El depósito es por clave de API.

Ante un 429 por minuto, el cliente reintenta con retroceso exponencial (hasta 3 veces) antes de lanzar RateLimitExceeded. Una asignación diaria o mensual agotada se lanza de inmediato, con el mensaje de la API.

Solución de problemas

Síntoma	Causa	Solución
`429 Too Many Requests` / `RateLimitExceeded`	Límite de tasa alcanzado (120/min con clave gratuita, 300 a 1 000/min con clave de pago)	Cambia a un plan de pago o reduce la expansión de llamadas a herramientas. El cliente ya retrocede hasta 3 veces.
`HUBEQUITY_API_KEY is not set` en cada llamada a herramienta	Sin clave en el bloque `env` del cliente	Establece `HUBEQUITY_API_KEY`; una clave gratuita toma un minuto en https://hub-equity.com/settings/api-keys.
`HubEquityRestError: HTTP 401`	Una clave `hubq_` inválida, caducada o revocada (`INVALID_API_KEY`)	Crea una nueva clave en https://hub-equity.com/settings/api-keys.
`HubEquityRestError: HTTP 403`	El espacio de trabajo de la clave está en el plan gratuito y la llamada necesita una herramienta Pro, o un límite gratuito (`depth > 1`, `limit > 20`, `min_quality_grade`)	Mejora el plan o mantente dentro de los límites gratuitos.
`RateLimitExceeded` cuyo cuerpo lleva `DAILY_QUOTA_EXCEEDED` / `MONTHLY_QUOTA_EXCEEDED`	La asignación de volumen del espacio de trabajo está agotada (Gratis 200 al día / 5 000 al mes, Builder 50 000, Team 500 000 al mes); se lanza de inmediato, sin reintento	Espera a `resets_on` o mejora el plan.
Errores de conexión o tiempo de espera	Problema de red para llegar a `api.hub-equity.com`, o un `HUBEQUITY_API_URL` incorrecto	Verifica la conectividad; confirma que `HUBEQUITY_API_URL` (si está establecido) apunte a un host `https://` accesible.
`ValueError: HUBEQUITY_API_URL must use https://`	Hay una clave establecida pero la URL es `http://` en texto plano en un host que no es de bucle local	Usa `https://` o desestablece `HUBEQUITY_API_URL` para volver a la API predeterminada.
El servidor no aparece en Claude Desktop o Cursor	Error de JSON de configuración, o `pipx` no está en el PATH del cliente	Valida el JSON; usa la ruta absoluta de `pipx` (o `uvx`) si el cliente no puede resolverla.

Ejecutar localmente

python -m hub_equity_mcp.server

O manéjalo de forma interactiva con el inspector de MCP:

npx @modelcontextprotocol/inspector python -m hub_equity_mcp.server

El inspector lista cada herramienta, recurso y prompt y te permite llamar a cada uno.

Desarrollo

pip install -e '.[dev]'
pytest tests/

Las pruebas son herméticas: las pruebas de herramientas simulan la API REST con respx, por lo que no se necesita un backend en vivo.

Licencia

Apache-2.0. Consulta LICENSE y NOTICE. Este conector es un cliente abierto a la API REST pública de Hub-Equity; el acceso a datos premium sigue restringido por clave de API, plan y límites de tasa en el lado del servicio.