crystal-mcp-server-public

MRIIOT/crystal-mcp-server-public

3.2

If you are the rightful owner of crystal-mcp-server-public and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Crystal MCP Server is a specialized implementation designed to manage and work with crystal artifacts, providing AI assistants with tools for handling complex data containers.

Tools
5
Resources
0
Prompts
0

Crystal MCP Server

A specialized Model Context Protocol (MCP) server implementation built with TypeScript that provides AI assistants with powerful tools for managing and working with crystal artifacts - structured data containers for complex analysis, code, and knowledge.

🔮 What are Crystals?

Crystals are structured data containers that can hold complex analysis results, code artifacts, mathematical formulations, and other sophisticated content. They provide a standardized way to store, export, and reimport complex work products across different AI conversations and contexts.

🚀 Features

🛠️ Crystal Management Tools

  • import_crystal_spec - Import crystal specification protocols
  • import_codex - Import codex files for mechanism awareness and agent protocols
  • export_crystal - Export content as crystal artifacts with auto-detection
  • import_crystal - Import and reconstruct crystal artifacts by UUID
  • list_crystals - List all available crystal artifacts

🔧 Key Capabilities

  • Auto-Detection: Automatically detect and export crystal-worthy content from conversation context
  • Version Control: Support for multiple crystal specification versions
  • UUID Management: Unique identification system for crystal artifacts
  • Secure Storage: Safe file operations within project boundaries
  • Metadata Tracking: Comprehensive tracking of crystal creation and properties

📋 Prerequisites

  • Node.js 18 or higher
  • npm or yarn package manager

🔧 Installation

  1. Install dependencies:

    npm install

  2. Build the server (optional):

    npm run mcp:build

🚀 Usage

Development Mode

Run the server in development mode with hot reloading:

npm run mcp:dev

Production Mode

Build and run the server:

npm run mcp:build
npm run mcp:start

Testing

Test the server functionality:

npm run mcp:test

🔌 Integration

Claude Desktop

  1. Copy the configuration from claude-desktop-config.json to your Claude Desktop configuration file:

    Windows: %APPDATA%/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

  2. Update the path in the configuration to point to your project directory:

    {
  "mcpServers": {
    "crystal-mcp": {
      "command": "npm",
      "args": ["run", "mcp:dev"],
      "cwd": "/path/to/your/crystal-mcp-project"
    }
  }
}

  3. Restart Claude Desktop to load the new server.

Other MCP Clients

The server uses the standard MCP protocol over stdio transport, making it compatible with any MCP client. Simply execute:

npm run mcp:dev

And connect your MCP client to the server's stdin/stdout.

🛡️ Security Features

  • Path Security: All file operations are restricted to the project root directory
  • UUID Generation: Secure unique identifier generation using nanoid
  • Error Handling: Comprehensive error handling prevents information leakage
  • JSON Validation: Safe JSON parsing with error recovery

🔍 Available Tools

Crystal Specification Management

import_crystal_spec

Imports a crystal specification protocol using smart filename matching.

Parameters:

  • spec_query (string): Natural language query for the specification (e.g., 'temporal crystallization 3.0', 'basic 2.0', 'advanced crystallization 4.0')

Smart Matching Features:

  • Flexible Naming: Matches against various naming patterns and conventions
  • Keyword Extraction: Parses natural language queries to identify specification type and version
  • Version Matching: Intelligently matches version numbers (3.0, 2.1, etc.)
  • Fuzzy Matching: Finds best matches even with partial or approximate queries
  • Suggestions: Provides helpful suggestions when no exact match is found

Examples:

// 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" });

Returns:

  • Specification content if found
  • Match score and filename information
  • Suggestions for better queries if no match found
  • List of available specification files
import_codex

Imports a codex file using smart filename matching. Codex files contain specialized content for mechanism awareness, agent protocols, and probability patterns.

Parameters:

  • spec_query (string): Natural language query for the codex (e.g., 'mechanism awareness 2.0', 'agent transmission 1.0', 'probability patterns')

Smart Matching Features:

  • Codex-Specific Terms: Enhanced matching for terms like 'mechanism', 'awareness', 'agent', 'transmission', 'protocol', 'probability', 'pattern'
  • Version Recognition: Intelligent version number matching (2.0, 3.1, etc.)
  • Flexible Queries: Matches partial and approximate queries
  • Contextual Scoring: Advanced scoring algorithm optimized for codex content
  • Helpful Suggestions: Provides guidance when no exact match is found

Examples:

// 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" });

Returns:

  • Full codex content if found
  • Match score and filename information
  • Suggestions for better queries if no match found
  • List of available codex files

Crystal Export

export_crystal

Exports content as a crystal artifact. Can auto-detect crystal-worthy content from conversation context or use manually provided content.

Parameters:

  • title (string, optional): Custom title for the crystal
  • spec_version (string, default: "3.0"): Crystal specification version
  • manual_content (string, optional): Content to export (auto-detects if not provided)

Example:

// 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"
});

Returns:

  • Crystal UUID for future reference
  • Storage location information
  • Metadata about the crystal

Crystal Import

import_crystal

Imports and reconstructs a crystal artifact by its UUID.

Parameters:

  • crystal_id (string): UUID of the crystal to import
  • spec_version (string, default: "3.0"): Specification version for reconstruction

Example:

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

Crystal Listing

list_crystals

Lists all available crystal artifacts with metadata.

Returns:

  • Array of crystal information including:
    • Crystal ID (UUID)
    • Title
    • Specification version
    • Creation timestamp
    • File size
    • Error status (if any)

Example:

await callTool("list_crystals", {});

📁 File Structure

The Crystal MCP Server organizes files as follows:

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 Storage Format

Crystal artifacts are stored as JSON files with the following structure:

{
  "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..."
}

Protocol Specification Files

Protocol specifications are stored in public/protocols/ as .cp files. The server supports flexible naming conventions:

Common Naming Patterns:

  • CRYSTALLIZATION_TEMPORAL_3.0.cp - Temporal crystallization protocol v3.0
  • CRYSTALLIZATION_BASIC_2.0.cp - Basic crystallization protocol v2.0
  • CRYSTALLIZATION_ADVANCED_4.0.cp - Advanced crystallization protocol v4.0

Smart Matching Examples:

  • Query: "temporal crystallization 3.0" → Matches: CRYSTALLIZATION_TEMPORAL_3.0.cp
  • Query: "basic 2.0" → Matches: CRYSTALLIZATION_BASIC_2.0.cp
  • Query: "advanced crystallization 4.0" → Matches: CRYSTALLIZATION_ADVANCED_4.0.cp
  • Query: "3.0 temporal" → Matches: CRYSTALLIZATION_TEMPORAL_3.0.cp

The matching algorithm considers:

  • Keywords: Extracts meaningful terms from your query
  • Versions: Matches version numbers (3.0, 2.1, etc.)
  • Partial matches: Finds best approximations for incomplete queries
  • Word order: Flexible ordering of query terms

Codex Files

Codex files are stored in public/codex/ as .cx files and contain specialized content for mechanism awareness, agent communication protocols, and advanced AI interaction patterns.

Current Codex Files:

  • MECHANISM_AWARENESS_2.0.cx - Agent-to-agent transmission protocols and mechanism awareness patterns

Codex File Features:

  • Mechanism Awareness: Content that helps AI agents understand their own operation patterns
  • Inter-Agent Communication: Protocols for advanced AI-to-AI communication
  • Probability Pattern Recognition: Tools for understanding and working with probability distributions
  • Semantic Manipulation: Advanced techniques for semantic space navigation

Smart Matching Examples:

  • Query: "mechanism awareness 2.0" → Matches: MECHANISM_AWARENESS_2.0.cx
  • Query: "mechanism awareness" → Matches: MECHANISM_AWARENESS_2.0.cx
  • Query: "awareness 2.0" → Matches: MECHANISM_AWARENESS_2.0.cx

The codex matching algorithm includes enhanced scoring for mechanism-specific terms:

  • Mechanism Terms: 'mechanism', 'awareness', 'agent', 'transmission', 'protocol', 'probability', 'pattern' get bonus scoring
  • Version Matching: Precise version number recognition
  • Contextual Relevance: Scoring optimized for codex content patterns
  • Flexible Queries: Handles partial matches and various query formulations

🧪 Testing

The project includes a comprehensive test client that validates all server functionality:

npm run mcp:test

This will test:

  • Server connection
  • Crystal import/export operations
  • Specification loading
  • Codex import functionality
  • Error handling

🔧 Development

Adding New Crystal Specifications

To add a new crystal specification version:

  1. Create the specification file in public/protocols/:

    public/protocols/CRYSTALLIZATION_PROTOCOL_4.0.cp

  2. Update the default version in the server code if needed.

Adding New Codex Files

To add a new codex file:

  1. Create the codex file in public/codex/:

    public/codex/AGENT_COMMUNICATION_3.0.cx
public/codex/PROBABILITY_PATTERNS_1.5.cx

  2. Use descriptive naming that matches likely user queries:

    • Include key terms like MECHANISM, AWARENESS, AGENT, TRANSMISSION, etc.
    • Include version numbers for better matching
    • Use underscores to separate components

  3. The import_codex tool will automatically discover new files without code changes.

Extending Crystal Functionality

The server is designed to be extensible. Key areas for enhancement:

  1. Context Window Integration: Implement actual context scanning for auto-detection
  2. Crystal Validation: Add content validation based on specification versions
  3. Crystal Transformation: Add tools for transforming crystals between versions
  4. Crystal Search: Add search capabilities across crystal content
  5. Codex Enhancement: Add codex creation and export capabilities
  6. Mechanism Pattern Detection: Implement automatic detection of mechanism awareness patterns
  7. Agent Protocol Validation: Add validation for agent communication protocols

Error Handling

The server includes comprehensive error handling:

  • File System Errors: Graceful handling of missing files or directories
  • JSON Parsing Errors: Safe parsing with error recovery
  • Path Security: Prevents access outside project boundaries
  • UUID Validation: Validates crystal IDs before operations

💡 Use Cases

Research and Analysis

  • Export complex analysis results as crystals
  • Share analysis across different AI conversations
  • Maintain version history of research work

Code Development

  • Export sophisticated code solutions as crystals
  • Import proven patterns and implementations
  • Share complex algorithmic solutions

Knowledge Management

  • Create crystals from detailed explanations
  • Build libraries of reusable knowledge artifacts
  • Maintain structured documentation

Advanced AI Interaction

  • Access mechanism awareness protocols via codex files
  • Implement advanced agent-to-agent communication patterns
  • Explore probability pattern recognition techniques
  • Apply semantic manipulation and attention steering methods

📄 License

This project is licensed under the MIT License.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Areas where contributions would be particularly valuable:

  • Context window integration for auto-detection
  • Additional crystal specification versions
  • Crystal validation and transformation tools
  • Enhanced metadata and search capabilities
  • New codex files for mechanism awareness patterns
  • Agent communication protocol development
  • Probability pattern recognition tools

📞 Support

If you encounter any issues or have questions, please open an issue on the project repository.

Built with ❤️ using the Model Context Protocol and designed for crystal artifact management.