Capacities MCP Enhanced
Un servidor MCP mejorado para la API 2.0 de Capacities con CRUD completo, edición precisa de bloques, soporte de Markdown, carga de archivos y agrupación de claves API.
Documentación
Capacities MCP Enhanced — API 2.0 para Agentes de IA
El servidor MCP oficial apesta, es hora de hacer uno nuevo.
Construido para la nueva Capacities API 2.0 con soporte nativo de CRUD a nivel de bloque preciso.
Capacities MCP aporta acceso rico de lectura y escritura a su base de conocimiento a través de un servidor amigable para agentes. Los agentes pueden descubrir sus tipos de objetos, comprender propiedades personalizadas, crear contenido pulido, hacer ediciones precisas, guardar recursos web y trabajar con Notas diarias.
✨ Por qué Capacities MCP Enhanced
- ✍️ Creación de bloques estructurados y Markdown — combine flujos de trabajo rápidos de Markdown con edición de bloques nativa de Capacities en un solo servidor.
- 🧩 CRUD completo con Capacities API 2.0 — objetos, propiedades personalizadas, colecciones, bloques, enlaces web, tareas, etiquetas y Notas diarias.
- 🤖 Diseñado para agentes autónomos — descubrimiento de esquemas en vivo, respuestas consistentes, herramientas enfocadas e información clara de recuperación.
- 📤 Subidas de archivos MCP amigables para agentes — soporte para subidas de archivos múltiples y grandes con informes de progreso MCP integrados, transferencias en streaming, verificación de subidas y seguimiento de trabajos de larga duración.
- 🔑 Agrupación de claves API — distribuya solicitudes entre múltiples claves API, mejore el rendimiento bajo límites de velocidad y proporcione acceso API resiliente para cargas de trabajo de alto volumen.
- 🔒 Operaciones de objetos seguras para concurrencia — las lecturas del mismo objeto pueden ejecutarse de forma concurrente, mientras que las escrituras usan un bloqueo exclusivo y esperan automáticamente a las lecturas activas u otras escrituras; los objetos diferentes proceden de forma concurrente.
- 🎨 Contenido enriquecido fiel — encabezados, bloques anidados, cuadrículas, conmutadores, tareas, enlaces, referencias a entidades, colores, código y matemáticas.
- 📚 Habilidad de mejores prácticas incluida — se incluye una guía completa de operación para agentes, para que un modelo pueda usar el servidor correctamente sin conocer Capacities de antemano.
🚀 Inicio rápido
Requisitos
- Node.js 20+ o Bun 1.3+
- Una o más claves API personales de la nueva Capacities API con los permisos que necesite
Instalación
Configure su cliente MCP para usar el servidor Capacities MCP:
Genere un token en Capacities → Configuración → Capacities API → Generar nuevo token. Los nuevos tokens API comienzan con cap-api-.
Se recomienda configurar al menos 3 tokens con el mismo espacio y permisos para evitar errores de límite de velocidad.
Claude Code
{
"mcpServers": {
"capacities": {
"command": "npx",
"args": ["--yes", "capacities-mcp-enhanced@latest"],
"env": {
"CAPACITIES_API_TOKEN": "cap-api-key-1,cap-api-key-2;cap-api-key-3"
}
}
}
}
Hermes Agent
mcp_servers:
capacities:
command: "npx"
args:
- "--yes"
- "capacities-mcp-enhanced@latest"
env:
CAPACITIES_API_TOKEN: "cap-api-key-1,cap-api-key-2;cap-api-key-3"
supports_parallel_tool_calls: true
Instalar las habilidades incluidas (Opcional)
Al instalar la habilidad de Mejores Prácticas de Capacities MCP, su agente puede aprender el flujo de trabajo completo, esquemas de contenido estrictos, patrones seguros de mutación, recuperación de límites de velocidad y errores comunes.
npx skills add nyrest/capacities-mcp-enhanced
🧰 Qué pueden hacer los agentes
| Categoría | Herramienta | Qué hace |
|---|---|---|
| Descubrir y leer | inspect_space | Descubra estructuras, propiedades, etiquetas y opciones de escritura disponibles. |
| Descubrir y leer | search_objects | Encuentre objetos por título, opcionalmente dentro de estructuras seleccionadas. |
| Descubrir y leer | list_objects | Liste resúmenes de objetos paginados por cursor según estructura, etiqueta o colección. |
| Descubrir y leer | get_object | Lea un objeto completo como contenido estructurado o Markdown. |
| Crear objetos | create_object | Cree una Página, Tarea, Etiqueta u objeto personalizado con contenido estructurado. |
| Crear objetos | create_object_markdown | Cree un objeto a partir de un documento Markdown. |
| Crear objetos | create_object_from_url | Guarde un recurso web con notas estructuradas. |
| Crear objetos | create_object_from_url_markdown | Guarde un recurso web con notas Markdown. |
| Actualizar contenido | update_object | Actualice títulos, propiedades tipadas y colecciones. |
| Actualizar contenido | append_content | Agregue bloques estructurados a un objeto. |
| Actualizar contenido | append_content_markdown | Agregue contenido Markdown a un objeto. |
| Actualizar contenido | update_block | Edite con precisión un bloque existente. |
| Actualizar contenido | delete_block | Elimine un bloque y su contenido anidado. |
| Actualizar contenido | delete_object | Mueva un objeto a la papelera o elimínelo permanentemente cuando se solicite explícitamente. |
| Notas diarias | append_daily_note | Agregue bloques estructurados a la Nota diaria de hoy o a una con fecha. |
| Notas diarias | append_daily_note_markdown | Agregue Markdown a la Nota diaria de hoy o a una con fecha. |
| Subidas de medios | upload_files | Transmita uno o más archivos locales a objetos multimedia de Capacities con verificación de lectura. |
| Subidas de medios | manage_upload_job | Inspeccione, espere o cancele un trabajo de subida en segundo plano en proceso. |
search_objects es descubrimiento solo por título. Use list_objects cuando ya conozca una estructura, UUID de etiqueta o UUID de colección y necesite listar miembros; siga nextCursor mientras hasMore sea verdadero, luego pase los IDs de objetos seleccionados a get_object para obtener el contenido completo.
upload_files acepta solo rutas de archivo locales absolutas; las rutas relativas, directorios y archivos vacíos se rechazan. Los trabajos de subida en segundo plano viven solo en el proceso MCP actual y conservan el estado terminal por un tiempo limitado.
Variables de entorno y opciones de configuración compatibles
| Configuración | Requerido | Predeterminado | Descripción |
|---|---|---|---|
CAPACITIES_API_TOKEN | Sí, a menos que cada llamada proporcione apiToken | — | Una clave API o un grupo de claves separadas por comas/puntos y comas. Las claves deben pertenecer al mismo espacio y usar los mismos permisos. |
CAPACITIES_MCP_READBACK | No | true | Establézcalo en false para deshabilitar la lectura de confirmación ordinaria de mutaciones. La verificación de reversión permanece habilitada. Valores aceptados: true, false. |
La configuración por llamada se expone a través del argumento opcional apiToken en todas las herramientas. Anula CAPACITIES_API_TOKEN para esa llamada y acepta la misma sintaxis de grupo de claves.
⚙️ Grupo de claves API y límites de velocidad
CAPACITIES_API_TOKEN y la opción por llamada apiToken aceptan múltiples claves API separadas por , o ;. Las claves se seleccionan con programación round-robin de forma independiente para cada endpoint, omitiendo las claves marcadas actualmente como limitadas por velocidad.
Todas las claves en un grupo deben pertenecer al mismo espacio y tener los mismos permisos. Se recomiendan al menos 3 claves; use instancias separadas del servidor MCP para múltiples espacios.
En 429, el grupo cambia inmediatamente a otra clave que no esté limitada por velocidad. El error se devuelve solo cuando todas las claves están limitadas. No se realiza espera, retroceso exponencial ni reintento entre grupos.
🚅 Concurrencia y escrituras seguras
Las lecturas del mismo objeto pueden ejecutarse de forma concurrente. Una mutación obtiene un bloqueo exclusivo del objeto, por lo que espera a las lecturas activas y otras escrituras; las lecturas que llegan durante una escritura también esperan. Las operaciones para objetos diferentes proceden de forma concurrente. Esto protege el ciclo completo de lectura → mutación → lectura de confirmación contra condiciones de carrera de última escritura ganadora.
El SDK de Capacities no expone configuración de cancelación/tiempo de espera de solicitudes, por lo que las llamadas ordinarias respaldadas por SDK no usan una carrera de tiempo de espera insegura del lado del cliente. La subida de medios multiparte es la única ruta HTTP directa: conserva la cancelación nativa de AbortSignal, progreso explícito por parte, conmutación por error de claves agrupadas y verificación de lectura independiente del SDK.
🛠️ Desarrollo
bun run lint
bun run typecheck
bun test
bun run build
bun run verify:tools
La compuerta final de lanzamiento local es:
npm run release:check
npm publish --dry-run --access public
npm publish --dry-run valida el paquete sin publicarlo. La publicación real requiere además una cuenta npm autenticada.
Las pruebas de API en vivo están disponibles a través de bun run test:live cuando se configura un token de prueba dedicado.