Hugging Face MCP GOD Mode

Un servidor Model Context Protocol (MCP) completo y poderoso para Hugging Face que permite operaciones CRUD completas en Spaces y Datasets.

🚀 Características

Spaces (Espacios)

• ✅ Crear spaces con diferentes SDKs (Streamlit, Gradio, FastAPI, Docker, Static)
• ✅ Leer detalles de spaces específicos
• ✅ Listar todos tus spaces
• ✅ Actualizar metadatos (descripción, privacidad)
• ✅ Eliminar spaces
• ✅ Subir archivos a spaces

Datasets

• ✅ Crear datasets con tags y configuración
• ✅ Leer detalles de datasets específicos
• ✅ Listar todos tus datasets
• ✅ Actualizar metadatos (descripción, privacidad, tags)
• ✅ Eliminar datasets
• ✅ Subir archivos a datasets

📋 Requisitos

• Node.js 18+
• npm o yarn
• Token de API de Hugging Face

🔧 Instalación

Opción 1: Con NPX (Recomendado - No requiere instalación)

# Ejecutar directamente sin instalar
npx @zkarmor/hf-mcp-godmode

Opción 2: Instalación Global

# Instalar como comando global
npm install -g @zkarmor/hf-mcp-godmode

# Ejecutar
hf-mcp-godmode

Opción 3: Instalación Local

cd hf-mcp-godmode
npm install

⚙️ Configuración

1. Copia el archivo .env.example a .env:

cp .env.example .env

2. Edita .env y agrega tu token de Hugging Face:

HF_API_TOKEN=hf_your_token_here
HF_API_BASE_URL=https://huggingface.co/api
HF_INFERENCE_API_URL=https://api-inference.huggingface.co

🏗️ Construcción

npm run build

🚀 Ejecución

npm start

📝 Herramientas Disponibles

Spaces Tools

hf_create_space

Crea un nuevo space en Hugging Face.

Parámetros:

• name (requerido): Nombre del space
• sdk (requerido): Tipo de SDK - docker, static, streamlit, gradio, fastapi
• description: Descripción del space
• private: Si es privado (default: false)

Ejemplo:

{
  "name": "mi-awesome-app",
  "sdk": "streamlit",
  "description": "Mi aplicación Streamlit increíble",
  "private": false
}

hf_get_space

Obtiene detalles de un space específico.

Parámetros:

• space_id (requerido): ID del space en formato username/space-name

hf_list_spaces

Lista todos tus spaces.

Parámetros:

• limit: Número máximo de spaces a retornar (default: 50)

hf_update_space

Actualiza metadatos de un space.

Parámetros:

• space_id (requerido): ID del space
• description: Nueva descripción
• private: Cambiar privacidad

hf_delete_space

Elimina un space.

Parámetros:

• space_id (requerido): ID del space

hf_upload_to_space

Sube archivos a un space.

Parámetros:

• space_id (requerido): ID del space
• file_path (requerido): Ruta local del archivo
• repo_path: Ruta en el repositorio (opcional)

Datasets Tools

hf_create_dataset

Crea un nuevo dataset en Hugging Face.

Parámetros:

• name (requerido): Nombre del dataset
• description: Descripción del dataset
• private: Si es privado (default: false)
• tags: Array de tags

Ejemplo:

{
  "name": "mi-dataset-genial",
  "description": "Dataset de entrenamiento para NLP",
  "tags": ["text-classification", "spanish", "benchmark"],
  "private": false
}

hf_get_dataset

Obtiene detalles de un dataset específico.

Parámetros:

• dataset_id (requerido): ID del dataset en formato username/dataset-name

hf_list_datasets

Lista todos tus datasets.

Parámetros:

• limit: Número máximo de datasets a retornar (default: 50)

hf_update_dataset

Actualiza metadatos de un dataset.

Parámetros:

• dataset_id (requerido): ID del dataset
• description: Nueva descripción
• private: Cambiar privacidad
• tags: Nuevos tags

hf_delete_dataset

Elimina un dataset.

Parámetros:

• dataset_id (requerido): ID del dataset

hf_upload_to_dataset

Sube archivos a un dataset.

Parámetros:

• dataset_id (requerido): ID del dataset
• file_path (requerido): Ruta local del archivo
• repo_path: Ruta en el repositorio (opcional)

🔐 Seguridad

• El token de API se carga desde variables de entorno
• Nunca commits .env a control de versiones
• Usa tokens con permisos específicos (no tokens generales)

📚 Estructura del Proyecto

hf-mcp-godmode/
├── src/
│   ├── index.ts              # Servidor MCP principal
│   ├── tools/
│   │   ├── spaces.ts         # Herramientas para Spaces
│   │   └── datasets.ts       # Herramientas para Datasets
│   └── utils/
│       └── hf-client.ts      # Cliente de Hugging Face
├── dist/                     # Código compilado
├── package.json
├── tsconfig.json
└── .env.example

🛠️ Desarrollo

Para desarrollo con hot reload:

npm run dev

📦 Integración con Claude/AI

Este MCP puede integrarse con Claude o cualquier cliente MCP compatible agregando la configuración en tu cline_mcp_config.json o equivalente:

{
  "mcpServers": {
    "hf-godmode": {
      "command": "node",
      "args": ["/ruta/a/hf-mcp-godmode/dist/index.js"],
      "env": {
        "HF_API_TOKEN": "tu_token_aqui"
      }
    }
  }
}

🚨 Limitaciones Actuales

• La API de Hugging Face puede tener límites de tasa (rate limiting)
• Algunos endpoints pueden estar en versión beta
• Los permisos dependen del token de API proporcionado

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add some AmazingFeature')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📄 Licencia

MIT

📞 Soporte

Para problemas o preguntas:

1. Revisa la documentación de Hugging Face: https://huggingface.co/docs
2. Consulta los issues del proyecto
3. Crea un nuevo issue con detalles específicos

🔮 Próximas Mejoras

• [ ] Soporte para Models CRUD
• [ ] Operaciones de Git (commit, push, pull)
• [ ] Gestión de colecciones
• [ ] Webhooks
• [ ] Integración con MLOps
• [ ] Descarga de datasets
• [ ] Búsqueda avanzada
• [ ] Configuración de permisos granulares