quickfile-mcp

Servidor MCP para la API REST de Quickfile v2. Multi-cuenta, con aislamiento de secretos.

Características

• 45 herramientas -- una por operationId de la API, generadas a partir del spec.json incrustado.

• Multi-cuenta -- configura varias cuentas de Quickfile; cada herramienta acepta un parámetro account.

• Ambos modos de autenticación -- tokens Bearer personales estáticos y OAuth 2.0 (auto-refresco + persistencia rotativa del token de refresco).

• Aislamiento de secretos -- los tokens viven en accounts.json (ignorado por git), nunca expuestos al agente de IA. Los esquemas de las herramientas exponen solo un selector account + parámetros de endpoint.

Related MCP server: iikoServer MCP Server

Configuración

1. npm install

2. cp accounts.example.json accounts.json y completa las credenciales de la cuenta.

3. npm run build

4. Configura tu cliente MCP (Claude Desktop, etc.):

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

El servidor lee accounts.json desde el directorio de trabajo (o la variable de entorno QF_ACCOUNTS_FILE para una ruta personalizada). El material de token OAuth (accessToken, refreshToken, expiresAt) vive en un tokens.json interno separado (o QF_TOKENS_FILE) que el servidor gestiona; nunca lo editas manualmente.

Autenticación

Token estático (cuenta propia)

Genera un token Bearer personal en QuickFile: Configuración de la cuenta -> Integración de terceros -> API. En accounts.json, establece "type": "static" y "token": "<your token>".

OAuth (aplicación de socio)

1. Registra una aplicación en QuickFile para obtener clientId / clientSecret. Colócalos en accounts.json con "type": "oauth".

2. Completa el flujo de autorización OAuth e intercambio de tokens fuera de banda (una pequeña CLI o pegado manual) para obtener el primer accessToken, refreshToken y expiresAt.

3. Inicializa tokens.json una vez:

{ "beta": { "accessToken": "...", "refreshToken": "...", "expiresAt": 0 } }

Después de esto, nunca tocas tokens.json; el servidor auto-refresca los tokens de acceso que expiran y persiste el token de refresco rotado de nuevo en él.

Selección de cuenta

Cada herramienta acepta un parámetro account opcional (enumeración de etiquetas configuradas). Omítelo para usar defaultAccount de accounts.json.

Referencia de la API

Esquemas completos de endpoints: src/spec.json (Swagger 2.0, 45 rutas). Fuente: Documentación de la API de Quickfile.