Crystal MCP 服务器

使用 TypeScript 构建的专用模型上下文协议 (MCP) 服务器实现，为 AI 助手提供强大的工具来管理和处理晶体工件 - 用于复杂分析、代码和知识的结构化数据容器。

🔮 什么是水晶？

晶体是一种结构化数据容器，可以容纳复杂的分析结果、代码工件、数学公式和其他复杂内容。它们提供了一种标准化的方法，用于在不同的 AI 对话和上下文中存储、导出和重新导入复杂的工作成果。

Related MCP server: Vibe Coder MCP

🚀 功能

🛠️ 水晶管理工具

• import_crystal_spec - 导入晶体规范协议

• import_codex - 导入 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

使用智能文件名匹配导入 Codex 文件。Codex 文件包含机制感知、代理协议和概率模式的专用内容。

参数：

• spec_query （字符串）：法典的自然语言查询（例如，“机制意识 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

列出所有可用的水晶制品及其元数据。

返回：

• 晶体信息阵列包括：

  • 水晶ID（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

水晶存储格式

水晶制品以 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..."
}

协议规范文件

协议规范以.cp文件的形式存储在public/protocols/目录中。服务器支持灵活的命名约定：

常见的命名模式：

• 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 文件以.cx文件的形式存储在public/codex/中，包含用于机制意识、代理通信协议和高级 AI 交互模式的专门内容。

当前 Codex 文件：

• MECHANISM_AWARENESS_2.0.cx - 代理到代理传输协议和机制感知模式

Codex 文件功能：

• 机制意识：帮助人工智能代理了解自身操作模式的内容

• 智能体间通信：高级AI-to-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

法典匹配算法包括针对机制特定术语的增强评分：

• 机制术语：‘机制’、‘意识’、‘代理’、‘传输’、‘协议’、‘概率’、‘模式’获得奖励得分

• 版本匹配：精确的版本号识别

• 上下文相关性：针对法典内容模式进行优化的评分

• 灵活查询：处理部分匹配和各种查询公式

🧪 测试

该项目包括一个全面的测试客户端，可验证所有服务器功能：

npm run mcp:test

这将测试：

• 服务器连接

• 水晶进出口业务

• 规格加载

• Codex 导入功能

• 错误处理

🔧 开发

添加新的晶体规格

要添加新的晶体规范版本：

1. 在public/protocols/中创建规范文件：

   public/protocols/CRYSTALLIZATION_PROTOCOL_4.0.cp

2. 如果需要，请更新服务器代码中的默认版本。

添加新的 Codex 文件

要添加新的 codex 文件：

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 验证：添加基于规范版本的内容验证

3. 水晶变换：添加不同版本间水晶变换工具

4. 水晶搜索：添加水晶内容的搜索功能

5. 法典增强：添加法典创建和导出功能

6. 机制模式检测：实现机制感知模式的自动检测

7. 代理协议验证：添加代理通信协议验证

错误处理

该服务器包括全面的错误处理：

• 文件系统错误：妥善处理丢失的文件或目录

• JSON 解析错误：通过错误恢复进行安全解析

• 路径安全：防止项目边界外的访问

• UUID 验证：操作前验证水晶 ID

💡 用例

研究与分析

• 将复杂的分析结果导出为晶体

• 在不同的 AI 对话中共享分析

• 维护研究工作的版本历史

代码开发

• 将复杂的代码解决方案导出为晶体

• 导入经过验证的模式和实现

• 分享复杂的算法解决方案

知识管理

• 通过详细的解释来创造水晶

• 构建可重复使用的知识库

• 维护结构化文档

先进的人工智能交互

• 通过 codex 文件访问机制感知协议

• 实施先进的代理间通信模式

• 探索概率模式识别技术

• 应用语义操纵和注意力引导方法

📄 许可证

该项目已获得 MIT 许可。

🤝 贡献

欢迎贡献代码！欢迎提交 Pull 请求。

贡献特别有价值的领域：

• 上下文窗口集成用于自动检测

• 附加晶体规格版本

• 晶体验证和转换工具

• 增强的元数据和搜索功能

• 用于机制意识模式的新法典文件

• 代理通信协议开发

• 概率模式识别工具

📞 支持

如果您遇到任何问题或有疑问，请在项目存储库中打开一个问题。

使用模型上下文协议用❤️构建，专为水晶制品管理而设计。