Crystal MCP Server

Crystal MCP 服务器

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

🔮 什么是水晶？

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

🚀 功能

🛠️ 水晶管理工具

• 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

🚀 使用方法

开发模式

使用热重载以开发模式运行服务器：

生产模式

构建并运行服务器：

测试

测试服务器功能：

🔌 集成

克劳德桌面

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

使用智能文件名匹配导入 Codex 文件。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 服务器按如下方式组织文件：

水晶存储格式

水晶制品以 JSON 文件形式存储，其结构如下：

协议规范文件

协议规范以.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

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

• 机制术语：‘机制’、‘意识’、‘代理’、‘传输’、‘协议’、‘概率’、‘模式’获得奖励得分
• 版本匹配：精确的版本号识别
• 上下文相关性：针对法典内容模式进行优化的评分
• 灵活查询：处理部分匹配和各种查询公式

🧪 测试

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

这将测试：

• 服务器连接
• 水晶进出口业务
• 规格加载
• 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 请求。

贡献特别有价值的领域：

• 上下文窗口集成用于自动检测
• 附加晶体规格版本
• 晶体验证和转换工具
• 增强的元数据和搜索功能
• 用于机制意识模式的新法典文件
• 代理通信协议开发
• 概率模式识别工具

📞 支持

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

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