Сервер Crystal MCP

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

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

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

Related MCP server: Vibe Coder MCP

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

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

• 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

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

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

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

npm run mcp:dev

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

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

npm run mcp:build
npm run mcp:start

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

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

npm run mcp:test

🔌 Интеграция

Клод Десктоп

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. Просто выполните:

npm run mcp:dev

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

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

• Безопасность пути : все файловые операции ограничены корневым каталогом проекта.

• Генерация UUID : безопасная генерация уникального идентификатора с использованием nanoid

• Обработка ошибок : комплексная обработка ошибок предотвращает утечку информации.

• Проверка JSON : безопасный анализ JSON с устранением ошибок

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

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

import_crystal_spec

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

Параметры:

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

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

• Гибкое именование : соответствие различным шаблонам и соглашениям об именах.

• Извлечение ключевых слов : анализирует запросы на естественном языке для определения типа и версии спецификации.

• Сопоставление версий : интеллектуальное сопоставление номеров версий (3.0, 2.1 и т. д.)

• Нечеткое соответствие : находит наилучшие совпадения даже при частичных или приблизительных запросах.

• Предложения : предоставляет полезные предложения, если точное совпадение не найдено.

Примеры:

// These queries will match "CRYSTALLIZATION_TEMPORAL_3.0.cp"
await callTool("import_crystal_spec", { spec_query: "temporal crystallization 3.0" });
await callTool("import_crystal_spec", { spec_query: "temporal 3.0" });
await callTool("import_crystal_spec", { spec_query: "3.0 temporal" });

// Will match "CRYSTALLIZATION_BASIC_2.0.cp"
await callTool("import_crystal_spec", { spec_query: "basic crystallization 2.0" });
await callTool("import_crystal_spec", { spec_query: "basic 2.0" });

Возврат:

• Содержимое спецификации, если найдено

• Информация о счете и имени файла

• Предложения по улучшению запросов, если совпадений не найдено

• Список доступных файлов спецификаций

import_codex

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

Параметры:

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

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

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

• Распознавание версий : интеллектуальное сопоставление номеров версий (2.0, 3.1 и т. д.)

• Гибкие запросы : Соответствует частичным и приблизительным запросам

• Контекстная оценка : усовершенствованный алгоритм оценки, оптимизированный для содержимого кодекса

• Полезные предложения : Предоставляет руководство, когда точное совпадение не найдено.

Примеры:

// These queries will match "MECHANISM_AWARENESS_2.0.cx"
await callTool("import_codex", { spec_query: "mechanism awareness 2.0" });
await callTool("import_codex", { spec_query: "mechanism awareness" });
await callTool("import_codex", { spec_query: "awareness 2.0" });

// Future codex files might match these patterns:
await callTool("import_codex", { spec_query: "agent transmission protocol" });
await callTool("import_codex", { spec_query: "probability patterns 1.0" });

Возврат:

• Полное содержание кодекса, если оно найдено

• Информация о счете и имени файла

• Предложения по улучшению запросов, если совпадений не найдено

• Список доступных файлов кодекса

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

export_crystal

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

Параметры:

• title (строка, необязательно): Пользовательское название для кристалла

• spec_version (строка, по умолчанию: "3.0"): версия спецификации Crystal

• manual_content (строка, необязательно): Содержимое для экспорта (автоматически определяется, если не указано)

Пример:

// Auto-detect from context
await callTool("export_crystal", { 
  title: "My Analysis Crystal",
  spec_version: "3.0"
});

// Manual content
await callTool("export_crystal", { 
  title: "Custom Crystal",
  manual_content: "Your crystal content here"
});

Возврат:

• Crystal UUID для дальнейшего использования

• Информация о месте хранения

• Метаданные о кристалле

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

import_crystal

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

Параметры:

• crystal_id (строка): UUID импортируемого кристалла

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

Пример:

await callTool("import_crystal", { 
  crystal_id: "abc123def456",
  spec_version: "3.0"
});

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

list_crystals

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

Возврат:

• Массив кристаллической информации, включая:

  • Кристаллический идентификатор (UUID)

  • Заголовок

  • Спецификация версии

  • Временная метка создания

  • Размер файла

  • Статус ошибки (если есть)

Пример:

await callTool("list_crystals", {});

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

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

crystal-mcp/
├── src/
│   ├── mcp-server.ts           # Main Crystal MCP server implementation
│   ├── test-client.ts          # Test client for validation
│   └── main.ts                # Original application entry point
├── public/
│   ├── crystals/               # Stored crystal artifacts (*.crystal files)
│   ├── codex/                  # Codex files for mechanism awareness (*.cx files)
│   └── protocols/              # Crystal specification protocols (*.cp files)
├── claude-desktop-config.json  # Claude Desktop configuration
└── README.md                   # This file

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

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

{
  "id": "unique-crystal-uuid",
  "title": "Crystal Title",
  "spec_version": "3.0",
  "created_at": "2025-05-26T10:30:00.000Z",
  "auto_detected": false,
  "content": "The actual crystal content..."
}

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

Спецификации протоколов хранятся в 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

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

• Термины механизма : «механизм», «осведомленность», «агент», «передача», «протокол», «вероятность», «шаблон» получить бонусные баллы

• Сопоставление версий : точное распознавание номера версии

• Контекстная релевантность : оценка оптимизирована для шаблонов содержимого кодекса

• Гибкие запросы : обрабатывает частичные совпадения и различные формулировки запросов.

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

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

npm run mcp:test

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

• Подключение к серверу

• Импортно-экспортные операции с кристаллами

• Загрузка спецификации

• Функция импорта 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 и предназначен для управления артефактами кристаллов.