aspro-mcp

Un servidor de Model Context Protocol que expone la API REST de Aspro.Cloud a clientes LLM (Claude Desktop, Claude Code, etc.). El servidor incluye la especificación OpenAPI integrada, por lo que el modelo puede descubrir módulos, entidades y métodos por sí mismo y llamarlos de forma segura.

Características

• Autodescriptivo. El modelo explora la API mediante aspro_list_modules → aspro_list_entities → aspro_list_methods → aspro_describe, y solo entonces realiza aspro_call — no es necesario memorizar endpoints.

• Búsqueda por subcadena en módulos, entidades, métodos, rutas, descripciones y etiquetas.

• POSTs form-urlencoded por defecto (el tipo de contenido esperado por Aspro), con manejo de arrays y objetos anidados.

• Sustitución de parámetros de ruta para /get/{id}, /update/{id}, /delete/{id} y similares.

• Configuración por inquilino (tenant) mediante ASPRO_COMPANY (subdominio) o ASPRO_BASE_URL completa.

Instalación

git clone https://github.com/bssth/aspro-mcp.git
cd aspro-mcp
npm install
npm run build

Requiere Node.js ≥ 18.

Configuración

Copia el archivo de ejemplo .env y rellénalo:

cp .env.example .env

ASPRO_COMPANY=your_company        # the {company} part of https://{company}.aspro.cloud
ASPRO_API_KEY=your_api_key_here   # passed as ?api_key=... on every request
# ASPRO_BASE_URL=...              # optional; overrides the URL built from ASPRO_COMPANY
# ASPRO_TIMEOUT_MS=30000          # optional; default 30s

Obtén una clave de API en tu cuenta de Aspro.Cloud en Ajustes → Integraciones → API.

Conexión con un cliente

Claude Desktop / Claude Code

Añade el servidor a tu configuración de MCP:

{
  "mcpServers": {
    "aspro": {
      "command": "node",
      "args": ["/absolute/path/to/aspro-mcp/dist/index.js"]
    }
  }
}

El servidor lee su archivo .env desde la raíz del proyecto, independientemente del directorio de trabajo desde el que el cliente lo inicie.

Otros clientes MCP

Cualquier cliente que utilice MCP a través de stdio puede ejecutar node dist/index.js (o npm start).

Herramientas expuestas

El flujo recomendado es search/list_* → describe → call.

Desarrollo

npm run dev      # tsc --watch
npm run build    # tsc
npm run smoke    # offline: exercises the spec indexer and URL builder

La prueba de humo (smoke test) no accede a la red: comprueba que la especificación OpenAPI integrada se analiza correctamente, que las operaciones se pueden describir y que el constructor de URL genera URLs bien formadas.

Estructura del proyecto

src/
  index.ts    MCP server (tool registration + entry point)
  config.ts   .env loading and validation
  client.ts   HTTP client (URL building, form-urlencoded POSTs, timeouts)
  spec.ts    OpenAPI indexer (modules / entities / methods / search / describe)
  smoke.ts    offline smoke test
spec/
  openapi.json  bundled Aspro.Cloud OpenAPI spec

Notas de seguridad

• La clave de API se lee del entorno y se añade a cada solicitud como ?api_key=.... Nunca subas el archivo .env al control de versiones.

• El servidor no tiene una lista de permitidos (allowlist): una vez configurado, puede llamar a cualquier endpoint que describa la especificación (incluidos los destructivos como /delete/{id}). Utiliza una clave de API dedicada con los permisos mínimos necesarios.

• Trata la salida de las herramientas como no confiable: las entidades de Aspro (valores de campos personalizados, descripciones, etc.) pueden contener contenido proporcionado por el usuario.

Contribuciones

Las incidencias y PRs son bienvenidas. Por favor, ejecuta npm run build && npm run smoke antes de enviar cambios.

Licencia

MIT — ver LICENSE.

aspro-mcp es un conector de terceros no oficial y no está afiliado a Aspro.Cloud.