Crystal MCP Server

Servidor Crystal MCP

Una implementación de servidor de Protocolo de contexto de modelo (MCP) especializada creada con TypeScript que proporciona a los asistentes de IA herramientas poderosas para administrar y trabajar con artefactos de cristal: contenedores de datos estructurados para análisis, código y conocimiento complejos.

🔮¿Qué son los Cristales?

Los cristales son contenedores de datos estructurados que pueden albergar resultados de análisis complejos, artefactos de código, formulaciones matemáticas y otro contenido sofisticado. Ofrecen una forma estandarizada de almacenar, exportar y reimportar productos de trabajo complejos en diferentes conversaciones y contextos de IA.

🚀 Características

🛠️ Herramientas de gestión de cristales

• import_crystal_spec - Importar protocolos de especificación de cristales
• import_codex - Importa archivos codex para reconocimiento de mecanismos y protocolos de agentes
• export_crystal - Exportar contenido como artefactos de cristal con detección automática
• import_crystal - Importa y reconstruye artefactos de cristal por UUID
• list_crystals - Lista todos los artefactos de cristal disponibles

🔧 Capacidades clave

• Detección automática : detecta y exporta automáticamente contenido valioso del contexto de conversación
• Control de versiones : Compatibilidad con múltiples versiones de especificaciones de cristal
• Gestión UUID : sistema de identificación único para artefactos de cristal
• Almacenamiento seguro : Operaciones de archivos seguras dentro de los límites del proyecto
• Seguimiento de metadatos : seguimiento completo de la creación y las propiedades de los cristales

📋 Requisitos previos

• Node.js 18 o superior
• gestor de paquetes npm o yarn

🔧 Instalación

1. Instalar dependencias:
   npm install
2. Construir el servidor (opcional):
   npm run mcp:build

🚀 Uso

Modo de desarrollo

Ejecute el servidor en modo de desarrollo con recarga en caliente:

Modo de producción

Construya y ejecute el servidor:

Pruebas

Pruebe la funcionalidad del servidor:

🔌 Integración

Escritorio de Claude

1. Copie la configuración de claude-desktop-config.json a su archivo de configuración de Claude Desktop:Windows: %APPDATA%/Claude/claude_desktop_config.jsonmacOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonLinux: ~/.config/Claude/claude_desktop_config.json
2. Actualice la ruta en la configuración para que apunte al directorio de su proyecto:
   { "mcpServers": { "crystal-mcp": { "command": "npm", "args": ["run", "mcp:dev"], "cwd": "/path/to/your/crystal-mcp-project" } } }
3. Reinicie Claude Desktop para cargar el nuevo servidor.

Otros clientes de MCP

El servidor utiliza el protocolo MCP estándar sobre el transporte stdio, lo que lo hace compatible con cualquier cliente MCP. Simplemente ejecute:

Y conecta tu cliente MCP al stdin/stdout del servidor.

🛡️ Funciones de seguridad

• Seguridad de ruta : todas las operaciones con archivos están restringidas al directorio raíz del proyecto
• Generación de UUID : Generación segura de identificadores únicos mediante nanoid
• Manejo de errores : El manejo integral de errores evita la fuga de información
• Validación de JSON : análisis seguro de JSON con recuperación de errores

🔍 Herramientas disponibles

Gestión de especificaciones de Crystal

import_crystal_spec

Importa un protocolo de especificación de cristal mediante coincidencia inteligente de nombres de archivo.

Parámetros:

• spec_query (cadena): consulta en lenguaje natural para la especificación (por ejemplo, 'cristalización temporal 3.0', 'básica 2.0', 'cristalización avanzada 4.0')

Funciones de coincidencia inteligente:

• Nombres flexibles : Coincide con varios patrones y convenciones de nombres
• Extracción de palabras clave : analiza consultas en lenguaje natural para identificar el tipo y la versión de la especificación.
• Coincidencia de versiones : coincide de forma inteligente con los números de versión (3.0, 2.1, etc.)
• Coincidencia difusa : encuentra las mejores coincidencias incluso con consultas parciales o aproximadas
• Sugerencias : proporciona sugerencias útiles cuando no se encuentra una coincidencia exacta

Ejemplos:

Devoluciones:

• Contenido de la especificación si se encuentra
• Información sobre la puntuación del partido y el nombre del archivo
• Sugerencias para realizar mejores consultas si no se encuentra ninguna coincidencia
• Lista de archivos de especificaciones disponibles

import_codex

Importa un archivo códice mediante coincidencia inteligente de nombres de archivo. Los archivos códice contienen contenido especializado para el reconocimiento de mecanismos, protocolos de agentes y patrones de probabilidad.

Parámetros:

• spec_query (cadena): consulta en lenguaje natural para el códice (por ejemplo, 'conocimiento del mecanismo 2.0', 'transmisión del agente 1.0', 'patrones de probabilidad')

Funciones de coincidencia inteligente:

• Términos específicos del Codex : coincidencia mejorada para términos como «mecanismo», «conciencia», «agente», «transmisión», «protocolo», «probabilidad», «patrón».
• Reconocimiento de versiones : coincidencia inteligente de números de versión (2.0, 3.1, etc.)
• Consultas flexibles : Coincide con consultas parciales y aproximadas
• Puntuación contextual : Algoritmo de puntuación avanzado optimizado para el contenido del códice
• Sugerencias útiles : Proporciona orientación cuando no se encuentra una coincidencia exacta

Ejemplos:

Devoluciones:

• Contenido completo del códice si se encuentra
• Información sobre la puntuación del partido y el nombre del archivo
• Sugerencias para realizar mejores consultas si no se encuentra ninguna coincidencia
• Lista de archivos de códice disponibles

Exportación de cristales

export_crystal

Exporta contenido como un artefacto de cristal. Puede detectar automáticamente contenido relevante para cristal en el contexto de la conversación o usar contenido proporcionado manualmente.

Parámetros:

• title (cadena, opcional): título personalizado para el cristal
• spec_version (cadena, valor predeterminado: "3.0"): Versión de la especificación de Crystal
• manual_content (cadena, opcional): Contenido a exportar (detecta automáticamente si no se proporciona)

Ejemplo:

Devoluciones:

• UUID de Crystal para referencia futura
• Información de ubicación de almacenamiento
• Metadatos sobre el cristal

Importación de cristales

import_crystal

Importa y reconstruye un artefacto de cristal por su UUID.

Parámetros:

• crystal_id (cadena): UUID del cristal a importar
• spec_version (cadena, valor predeterminado: "3.0"): Versión de especificación para la reconstrucción

Ejemplo:

Listado de cristales

list_crystals

Enumera todos los artefactos de cristal disponibles con metadatos.

Devoluciones:

• Conjunto de información sobre cristales que incluye:
  • Identificación de cristal (UUID)
  • Título
  • Versión de especificación
  • Marca de tiempo de creación
  • Tamaño del archivo
  • Estado de error (si lo hay)

Ejemplo:

📁 Estructura de archivos

El servidor Crystal MCP organiza los archivos de la siguiente manera:

Formato de almacenamiento de cristal

Los artefactos de cristal se almacenan como archivos JSON con la siguiente estructura:

Archivos de especificación de protocolo

Las especificaciones de protocolo se almacenan en public/protocols/ como archivos .cp . El servidor admite convenciones de nomenclatura flexibles:

Patrones de nombres comunes:

• CRYSTALLIZATION_TEMPORAL_3.0.cp - Protocolo de cristalización temporal v3.0
• CRYSTALLIZATION_BASIC_2.0.cp - Protocolo básico de cristalización v2.0
• CRYSTALLIZATION_ADVANCED_4.0.cp - Protocolo de cristalización avanzado v4.0

Ejemplos de coincidencia inteligente:

• Consulta: "temporal crystallization 3.0" → Resultados: CRYSTALLIZATION_TEMPORAL_3.0.cp
• Consulta: "basic 2.0" → Resultados: CRYSTALLIZATION_BASIC_2.0.cp
• Consulta: "advanced crystallization 4.0" → Resultados: CRYSTALLIZATION_ADVANCED_4.0.cp
• Consulta: "3.0 temporal" → Coincidencias: CRYSTALLIZATION_TEMPORAL_3.0.cp

El algoritmo de emparejamiento considera:

• Palabras clave : extrae términos significativos de su consulta
• Versiones : Coincide con los números de versión (3.0, 2.1, etc.)
• Coincidencias parciales : encuentra las mejores aproximaciones para consultas incompletas
• Orden de palabras : ordenación flexible de los términos de consulta

Archivos del códice

Los archivos Codex se almacenan en public/codex/ como archivos .cx y contienen contenido especializado para el conocimiento de mecanismos, protocolos de comunicación de agentes y patrones avanzados de interacción de IA.

Archivos del Codex actuales:

• MECHANISM_AWARENESS_2.0.cx - Protocolos de transmisión de agente a agente y patrones de conocimiento del mecanismo

Características del archivo Codex:

• Conciencia del mecanismo : contenido que ayuda a los agentes de IA a comprender sus propios patrones de operación
• Comunicación entre agentes : Protocolos para la comunicación avanzada entre IA
• Reconocimiento de patrones de probabilidad : herramientas para comprender y trabajar con distribuciones de probabilidad
• Manipulación semántica : técnicas avanzadas para la navegación en el espacio semántico

Ejemplos de coincidencia inteligente:

• Consulta: "mechanism awareness 2.0" → Resultados: MECHANISM_AWARENESS_2.0.cx
• Consulta: "mechanism awareness" → Resultados: MECHANISM_AWARENESS_2.0.cx
• Consulta: "awareness 2.0" → Resultados: MECHANISM_AWARENESS_2.0.cx

El algoritmo de coincidencia de códice incluye una puntuación mejorada para términos específicos del mecanismo:

• Términos de mecanismo : 'mecanismo', 'conciencia', 'agente', 'transmisión', 'protocolo', 'probabilidad', 'patrón' obtienen una puntuación adicional
• Coincidencia de versiones : reconocimiento preciso del número de versión
• Relevancia contextual : Puntuación optimizada para patrones de contenido del códice
• Consultas flexibles : maneja coincidencias parciales y varias formulaciones de consulta

🧪 Pruebas

El proyecto incluye un cliente de prueba integral que valida toda la funcionalidad del servidor:

Esto pondrá a prueba:

• Conexión al servidor
• Operaciones de importación/exportación de cristales
• Carga de especificaciones
• Funcionalidad de importación del códice
• Manejo de errores

🔧 Desarrollo

Adición de nuevas especificaciones de cristal

Para agregar una nueva versión de especificación de cristal:

1. Cree el archivo de especificaciones en public/protocols/ :
   public/protocols/CRYSTALLIZATION_PROTOCOL_4.0.cp
2. Actualice la versión predeterminada en el código del servidor si es necesario.

Agregar nuevos archivos de códice

Para agregar un nuevo archivo de códice:

1. Crea el archivo codex en public/codex/ :
   public/codex/AGENT_COMMUNICATION_3.0.cx public/codex/PROBABILITY_PATTERNS_1.5.cx
2. Utilice nombres descriptivos que coincidan con las posibles consultas de los usuarios:
   • Incluya términos clave como MECANISMO, CONCIENCIA, AGENTE, TRANSMISIÓN, etc.
   • Incluya números de versión para una mejor coincidencia
   • Utilice guiones bajos para separar componentes
3. La herramienta import_codex descubrirá automáticamente nuevos archivos sin cambios en el código.

Ampliación de la funcionalidad del cristal

El servidor está diseñado para ser extensible. Áreas clave de mejora:

1. Integración de la ventana de contexto : implemente el escaneo de contexto real para la detección automática
2. Validación de Crystal : agregue validación de contenido según las versiones de especificación
3. Transformación de cristales : agrega herramientas para transformar cristales entre versiones
4. Crystal Search : agregue capacidades de búsqueda en todo el contenido de Crystal
5. Mejora del códice : añadir capacidades de creación y exportación de códices
6. Detección de patrones de mecanismos : Implemente la detección automática de patrones de reconocimiento de mecanismos
7. Validación del protocolo del agente : agregue validación para los protocolos de comunicación del agente

Manejo de errores

El servidor incluye un manejo integral de errores:

• Errores del sistema de archivos : manejo elegante de archivos o directorios faltantes
• Errores de análisis de JSON : análisis seguro con recuperación de errores
• Seguridad de ruta : evita el acceso fuera de los límites del proyecto
• Validación de UUID : valida los identificadores de cristal antes de las operaciones

💡 Casos de uso

Investigación y análisis

• Exportar resultados de análisis complejos como cristales
• Compartir análisis en diferentes conversaciones de IA
• Mantener el historial de versiones del trabajo de investigación

Desarrollo de código

• Exportar soluciones de código sofisticadas como cristales
• Importar patrones e implementaciones probados
• Compartir soluciones algorítmicas complejas

Gestión del conocimiento

• Crea cristales a partir de explicaciones detalladas.
• Construir bibliotecas de artefactos de conocimiento reutilizables
• Mantener la documentación estructurada

Interacción avanzada con IA

• Protocolos de reconocimiento de mecanismos de acceso a través de archivos de códice
• Implementar patrones avanzados de comunicación de agente a agente
• Explorar técnicas de reconocimiento de patrones de probabilidad
• Aplicar métodos de manipulación semántica y de dirección de la atención.

📄 Licencia

Este proyecto está licenciado bajo la licencia MIT.

🤝 Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Áreas en las que las contribuciones serían particularmente valiosas:

• Integración de la ventana de contexto para la detección automática
• Versiones de especificaciones de cristal adicionales
• Herramientas de validación y transformación de cristales
• Metadatos mejorados y capacidades de búsqueda
• Nuevos archivos de códice para patrones de reconocimiento de mecanismos
• Desarrollo del protocolo de comunicación del agente
• Herramientas de reconocimiento de patrones de probabilidad

📞 Soporte

Si encuentra algún problema o tiene preguntas, abra un problema en el repositorio del proyecto.

Creado con ❤️ utilizando el Protocolo de Contexto de Modelo y diseñado para la gestión de artefactos de cristal.