Crystal MCP Server

Crystal MCP サーバー

TypeScript で構築された特殊なモデル コンテキスト プロトコル (MCP) サーバー実装。AI アシスタントに、複雑な分析、コード、知識のための構造化データ コンテナーであるクリスタル アーティファクトを管理および操作するための強力なツールを提供します。

🔮 クリスタルとは何ですか?

クリスタルは、複雑な分析結果、コード成果物、数式、その他の高度なコンテンツを保持できる構造化データコンテナです。クリスタルは、さまざまなAI会話やコンテキストにわたって複雑な成果物を保存、エクスポート、再インポートするための標準化された方法を提供します。

🚀 機能

🛠️ クリスタル管理ツール

• 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生成:ナノイドを使った安全な固有識別子生成
• エラー処理: 包括的なエラー処理により情報漏洩を防止
• JSON 検証: エラー回復機能を備えた安全な JSON 解析

🔍 利用可能なツール

結晶仕様管理

import_crystal_spec

スマートなファイル名マッチングを使用してクリスタル仕様プロトコルをインポートします。

パラメータ:

• spec_query (文字列): 仕様の自然言語クエリ（例：「temporal crystallization 3.0」、「basic 2.0」、「advanced crystallization 4.0」）

スマートマッチング機能:

• 柔軟な命名: さまざまな命名パターンや規則に適合
• キーワード抽出:自然言語クエリを解析して仕様の種類とバージョンを識別します
• バージョン マッチング: バージョン番号 (3.0、2.1 など) をインテリジェントにマッチングします。
• あいまい一致: 部分的または近似的なクエリでも最適な一致を見つけます
• 候補: 完全に一致するものが見つからない場合に役立つ候補を表示します

例:

戻り値:

• 見つかった場合の仕様内容
• 一致スコアとファイル名情報
• 一致するものが見つからない場合のより良いクエリの提案
• 利用可能な仕様ファイルのリスト

import_codex

スマートファイル名マッチングを使用してコーデックスファイルをインポートします。コーデックスファイルには、メカニズム認識、エージェントプロトコル、確率パターンに関する専門的なコンテンツが含まれています。

パラメータ:

• spec_query (文字列): コーデックスの自然言語クエリ (例: 「メカニズム認識 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

利用可能なすべてのクリスタル アーティファクトをメタデータとともに一覧表示します。

戻り値:

• 以下を含む結晶情報の配列:
  • クリスタルID（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ファイルとして保存され、メカニズム認識、エージェント通信プロトコル、高度な AI 相互作用パターンに関する特殊なコンテンツが含まれています。

現在のコーデックスファイル:

• MECHANISM_AWARENESS_2.0.cx - エージェント間の伝送プロトコルとメカニズム認識パターン

Codex ファイルの機能:

• メカニズム認識：AIエージェントが自身の動作パターンを理解するのに役立つコンテンツ
• エージェント間通信：高度なAI間通信のためのプロトコル
• 確率パターン認識：確率分布を理解し、扱うためのツール
• セマンティック操作：セマンティック空間ナビゲーションの高度な技術

スマートマッチングの例:

• クエリ: "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/に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検証: 操作前にクリスタルIDを検証します

💡 ユースケース

調査と分析

• 複雑な解析結果を結晶としてエクスポートする
• さまざまな AI 会話間で分析を共有する
• 研究作業のバージョン履歴を維持する

コード開発

• 洗練されたコードソリューションをクリスタルとしてエクスポート
• 実証済みのパターンと実装をインポートする
• 複雑なアルゴリズムソリューションを共有する

ナレッジマネジメント

• 詳細な説明から結晶を作成する
• 再利用可能な知識成果物のライブラリを構築する
• 構造化されたドキュメントを維持する

高度なAIインタラクション

• コーデックスファイルによるメカニズム認識プロトコルへのアクセス
• 高度なエージェント間通信パターンを実装する
• 確率パターン認識技術を探る
• 意味操作と注意誘導法を適用する

📄 ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています。

🤝 貢献する

貢献を歓迎します！お気軽にプルリクエストを送信してください。

貢献が特に価値のある分野:

• 自動検出のためのコンテキストウィンドウの統合
• 追加のクリスタル仕様バージョン
• 結晶検証および変換ツール
• 強化されたメタデータと検索機能
• メカニズム認識パターンの新しいコーデックスファイル
• エージェント通信プロトコルの開発
• 確率パターン認識ツール

📞 サポート

問題が発生した場合や質問がある場合は、プロジェクト リポジトリで問題を開いてください。

モデル コンテキスト プロトコルを使用して ❤️ で構築され、クリスタル アーティファクト管理用に設計されています。