Crystal MCP Server

Сервер Crystal MCP

Специализированная реализация сервера Model Context Protocol (MCP), созданная с помощью TypeScript, которая предоставляет помощникам на основе ИИ мощные инструменты для управления и работы с артефактами кристаллов — структурированными контейнерами данных для сложного анализа, кода и знаний.

🔮 Что такое кристаллы?

Кристаллы — это структурированные контейнеры данных, которые могут содержать сложные результаты анализа, артефакты кода, математические формулы и другой сложный контент. Они предоставляют стандартизированный способ хранения, экспорта и повторного импорта сложных рабочих продуктов в различных разговорах и контекстах ИИ.

🚀 Особенности

🛠️ Инструменты управления кристаллами

• import_crystal_spec - Импорт протоколов спецификации кристаллов
• import_codex — импорт файлов кодекса для понимания механизмов и протоколов агентов
• export_crystal — экспортировать содержимое в виде кристаллических артефактов с автоматическим определением
• import_crystal — импорт и реконструкция кристаллических артефактов по UUID
• list_crystals — Список всех доступных кристаллических артефактов

🔧 Основные возможности

• Автоматическое определение : автоматическое определение и экспорт ценного контента из контекста разговора.
• Контроль версий : поддержка нескольких версий спецификаций кристаллов
• Управление UUID : уникальная система идентификации для кристаллических артефактов
• Безопасное хранилище : безопасные операции с файлами в пределах проекта
• Отслеживание метаданных : комплексное отслеживание создания и свойств кристаллов.

📋 Предварительные условия

• Node.js 18 или выше
• менеджер пакетов npm или yarn

🔧 Установка

1. Установить зависимости:
   npm install
2. Сборка сервера (необязательно):
   npm run mcp:build

🚀 Использование

Режим разработки

Запустите сервер в режиме разработки с горячей перезагрузкой:

Режим производства

Соберите и запустите сервер:

Тестирование

Проверьте работоспособность сервера:

🔌 Интеграция

Клод Десктоп

1. Скопируйте конфигурацию из claude-desktop-config.json в файл конфигурации Claude Desktop:Windows: %APPDATA%/Claude/claude_desktop_config.jsonmacOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonLinux: ~/.config/Claude/claude_desktop_config.json
2. Обновите путь в конфигурации, чтобы он указывал на каталог вашего проекта:
   { "mcpServers": { "crystal-mcp": { "command": "npm", "args": ["run", "mcp:dev"], "cwd": "/path/to/your/crystal-mcp-project" } } }
3. Перезапустите Claude Desktop , чтобы загрузить новый сервер.

Другие клиенты MCP

Сервер использует стандартный протокол MCP через stdio транспорт, что делает его совместимым с любым клиентом MCP. Просто выполните:

И подключите ваш MCP-клиент к stdin/stdout сервера.

🛡️ Функции безопасности

• Безопасность пути : все файловые операции ограничены корневым каталогом проекта.
• Генерация UUID : безопасная генерация уникального идентификатора с использованием nanoid
• Обработка ошибок : комплексная обработка ошибок предотвращает утечку информации.
• Проверка JSON : безопасный анализ JSON с устранением ошибок

🔍 Доступные инструменты

Управление спецификациями кристаллов

import_crystal_spec

Импортирует протокол спецификации кристалла, используя интеллектуальное сопоставление имен файлов.

Параметры:

• spec_query (строка): Запрос на естественном языке для спецификации (например, «временная кристаллизация 3.0», «базовая 2.0», «расширенная кристаллизация 4.0»)

Функции интеллектуального сопоставления:

• Гибкое именование : соответствие различным шаблонам и соглашениям об именах.
• Извлечение ключевых слов : анализирует запросы на естественном языке для определения типа и версии спецификации.
• Сопоставление версий : интеллектуальное сопоставление номеров версий (3.0, 2.1 и т. д.)
• Нечеткое соответствие : находит наилучшие совпадения даже при частичных или приблизительных запросах.
• Предложения : предоставляет полезные предложения, если точное совпадение не найдено.

Примеры:

Возврат:

• Содержимое спецификации, если найдено
• Информация о счете и имени файла
• Предложения по улучшению запросов, если совпадений не найдено
• Список доступных файлов спецификаций

import_codex

Импортирует файл кодекса с использованием интеллектуального сопоставления имен файлов. Файлы кодекса содержат специализированный контент для осведомленности о механизмах, протоколов агентов и вероятностных моделей.

Параметры:

• spec_query (string): Запрос на естественном языке для кодекса (например, «осведомленность о механизмах 2.0», «передача агентов 1.0», «вероятностные шаблоны»)

Функции интеллектуального сопоставления:

• Термины, специфичные для Кодекса : улучшенное соответствие для таких терминов, как «механизм», «осведомленность», «агент», «передача», «протокол», «вероятность», «паттерн».
• Распознавание версий : интеллектуальное сопоставление номеров версий (2.0, 3.1 и т. д.)
• Гибкие запросы : Соответствует частичным и приблизительным запросам
• Контекстная оценка : усовершенствованный алгоритм оценки, оптимизированный для содержимого кодекса
• Полезные предложения : Предоставляет руководство, когда точное совпадение не найдено.

Примеры:

Возврат:

• Полное содержание кодекса, если оно найдено
• Информация о счете и имени файла
• Предложения по улучшению запросов, если совпадений не найдено
• Список доступных файлов кодекса

Экспорт Кристаллов

export_crystal

Экспортирует контент как кристаллический артефакт. Может автоматически определять достойный кристалла контент из контекста разговора или использовать вручную предоставленный контент.

Параметры:

• title (строка, необязательно): Пользовательское название для кристалла
• spec_version (строка, по умолчанию: "3.0"): версия спецификации Crystal
• manual_content (строка, необязательно): Содержимое для экспорта (автоматически определяется, если не указано)

Пример:

Возврат:

• Crystal UUID для дальнейшего использования
• Информация о месте хранения
• Метаданные о кристалле

Импорт Кристаллов

import_crystal

Импортирует и реконструирует кристаллический артефакт по его UUID.

Параметры:

• crystal_id (строка): UUID импортируемого кристалла
• spec_version (строка, по умолчанию: "3.0"): Версия спецификации для реконструкции

Пример:

Листинг Кристаллов

list_crystals

Перечисляет все доступные кристаллические артефакты с метаданными.

Возврат:

• Массив кристаллической информации, включая:
  • Кристаллический идентификатор (UUID)
  • Заголовок
  • Спецификация версии
  • Временная метка создания
  • Размер файла
  • Статус ошибки (если есть)

Пример:

📁 Структура файла

Сервер Crystal MCP организует файлы следующим образом:

Формат хранения Crystal

Кристаллические артефакты хранятся в виде JSON-файлов со следующей структурой:

Файлы спецификации протокола

Спецификации протоколов хранятся в public/protocols/ как файлы .cp . Сервер поддерживает гибкие соглашения об именовании:

Распространенные шаблоны именования:

• CRYSTALLIZATION_TEMPORAL_3.0.cp - Протокол временной кристаллизации v3.0
• CRYSTALLIZATION_BASIC_2.0.cp - Базовый протокол кристаллизации v2.0
• CRYSTALLIZATION_ADVANCED_4.0.cp - Расширенный протокол кристаллизации v4.0

Примеры интеллектуального сопоставления:

• Запрос: "temporal crystallization 3.0" → Совпадения: CRYSTALLIZATION_TEMPORAL_3.0.cp
• Запрос: "basic 2.0" → Совпадения: CRYSTALLIZATION_BASIC_2.0.cp
• Запрос: "advanced crystallization 4.0" → Совпадения: CRYSTALLIZATION_ADVANCED_4.0.cp
• Запрос: "3.0 temporal" → Совпадения: CRYSTALLIZATION_TEMPORAL_3.0.cp

Алгоритм сопоставления учитывает:

• Ключевые слова : Извлекает значимые термины из вашего запроса.
• Версии : Соответствует номерам версий (3.0, 2.1 и т. д.)
• Частичные совпадения : находит наилучшие приближения для неполных запросов.
• Порядок слов : Гибкий порядок терминов запроса

Файлы Кодекса

Файлы Codex хранятся в public/codex/ в виде файлов .cx и содержат специализированный контент для осведомленности о механизмах, протоколов связи агентов и расширенных шаблонов взаимодействия ИИ.

Текущие файлы Кодекса:

• MECHANISM_AWARENESS_2.0.cx — протоколы передачи от агента к агенту и шаблоны осведомленности механизмов

Особенности файла Кодекса:

• Осведомленность о механизмах : контент, помогающий агентам ИИ понимать свои собственные шаблоны работы.
• Межагентная связь : протоколы для усовершенствованной связи между ИИ
• Распознавание вероятностных закономерностей : инструменты для понимания и работы с распределениями вероятностей
• Семантическая манипуляция : передовые методы навигации в семантическом пространстве

Примеры интеллектуального сопоставления:

• Запрос: "mechanism awareness 2.0" → Совпадения: MECHANISM_AWARENESS_2.0.cx
• Запрос: "mechanism awareness" → Совпадения: MECHANISM_AWARENESS_2.0.cx
• Запрос: "awareness 2.0" → Совпадения: MECHANISM_AWARENESS_2.0.cx

Алгоритм сопоставления кодекса включает улучшенную оценку терминов, специфичных для механизмов:

• Термины механизма : «механизм», «осведомленность», «агент», «передача», «протокол», «вероятность», «шаблон» получить бонусные баллы
• Сопоставление версий : точное распознавание номера версии
• Контекстная релевантность : оценка оптимизирована для шаблонов содержимого кодекса
• Гибкие запросы : обрабатывает частичные совпадения и различные формулировки запросов.

🧪 Тестирование

Проект включает в себя комплексный тестовый клиент, который проверяет все функциональные возможности сервера:

Это позволит проверить:

• Подключение к серверу
• Импортно-экспортные операции с кристаллами
• Загрузка спецификации
• Функция импорта Codex
• Обработка ошибок

🔧 Развитие

Добавление новых спецификаций кристаллов

Чтобы добавить новую версию спецификации кристалла:

1. Создайте файл спецификации в public/protocols/ :
   public/protocols/CRYSTALLIZATION_PROTOCOL_4.0.cp
2. При необходимости обновите версию по умолчанию в коде сервера.

Добавление новых файлов Кодекса

Чтобы добавить новый файл кодекса:

1. Создайте файл кодекса в public/codex/ :
   public/codex/AGENT_COMMUNICATION_3.0.cx public/codex/PROBABILITY_PATTERNS_1.5.cx
2. Используйте описательное наименование , которое соответствует вероятным запросам пользователей:
   • Включите ключевые термины, такие как МЕХАНИЗМ, ОСОЗНАННОСТЬ, АГЕНТ, ПЕРЕДАЧА и т. д.
   • Включите номера версий для лучшего соответствия
   • Используйте подчеркивания для разделения компонентов.
3. Инструмент import_codex автоматически обнаружит новые файлы без изменения кода.

Расширение функциональности Crystal

Сервер разработан с возможностью расширения. Ключевые области для улучшения:

1. Интеграция окна контекста : реализация фактического сканирования контекста для автоматического обнаружения
2. Crystal Validation : добавление проверки содержимого на основе версий спецификаций.
3. Преобразование кристаллов : добавлены инструменты для преобразования кристаллов между версиями.
4. Crystal Search : добавьте возможности поиска по всему контенту Crystal
5. Улучшение Кодекса : добавление возможностей создания и экспорта Кодекса.
6. Обнаружение закономерностей механизмов : внедрение автоматического обнаружения закономерностей осведомленности механизмов.
7. Проверка протокола агента : добавлена проверка протоколов связи агента.

Обработка ошибок

Сервер включает в себя комплексную обработку ошибок:

• Ошибки файловой системы : корректная обработка отсутствующих файлов или каталогов
• Ошибки анализа JSON : безопасный анализ с устранением ошибок
• Безопасность пути : предотвращает доступ за пределы границ проекта.
• Проверка UUID : проверяет идентификаторы кристаллов перед операциями.

💡 Варианты использования

Исследования и анализ

• Экспорт результатов комплексного анализа в виде кристаллов
• Поделитесь анализом в различных диалогах ИИ
• Ведение истории версий исследовательской работы

Разработка кода

• Экспортируйте сложные кодовые решения в виде кристаллов
• Импорт проверенных шаблонов и реализаций
• Поделитесь сложными алгоритмическими решениями

Управление знаниями

• Создавайте кристаллы из подробных объяснений
• Создавайте библиотеки повторно используемых артефактов знаний
• Ведение структурированной документации

Расширенное взаимодействие с ИИ

• Доступ к протоколам осведомленности механизма через файлы кодекса
• Внедрение расширенных моделей взаимодействия между агентами
• Изучите методы распознавания вероятностных образов
• Применяйте методы семантической манипуляции и управления вниманием

📄 Лицензия

Данный проект лицензирован по лицензии MIT.

🤝 Вклад

Вклады приветствуются! Пожалуйста, не стесняйтесь отправлять запрос на включение.

Области, в которых вклад будет особенно ценным:

• Интеграция контекстного окна для автоматического определения
• Дополнительные версии спецификаций кристаллов
• Инструменты проверки и преобразования кристаллов
• Расширенные возможности метаданных и поиска
• Новые файлы кодекса для шаблонов осведомленности о механизмах
• Разработка протокола связи с агентом
• Инструменты распознавания вероятностных образов

📞 Поддержка

Если у вас возникли какие-либо проблемы или есть вопросы, пожалуйста, создайте сообщение в репозитории проекта.

Создан с использованием ❤️ Model Context Protocol и предназначен для управления артефактами кристаллов.