Crystal MCP Server

크리스탈 MCP 서버

TypeScript로 구축된 특수한 모델 컨텍스트 프로토콜(MCP) 서버 구현으로, AI 보조자에게 복잡한 분석, 코드 및 지식을 위한 구조화된 데이터 컨테이너인 크리스탈 아티팩트를 관리하고 작업할 수 있는 강력한 도구를 제공합니다.

🔮 크리스탈이란 무엇인가요?

크리스탈은 복잡한 분석 결과, 코드 아티팩트, 수학적 공식 및 기타 정교한 콘텐츠를 저장할 수 있는 구조화된 데이터 컨테이너입니다. 다양한 AI 대화 및 컨텍스트에서 복잡한 작업 결과물을 저장하고, 내보내고, 다시 가져오는 표준화된 방법을 제공합니다.

🚀 특징

🛠️ 크리스탈 관리 도구

• import_crystal_spec - 크리스탈 사양 프로토콜 가져오기
• import_codex - 메커니즘 인식 및 에이전트 프로토콜을 위한 코덱스 파일 가져오기
• export_crystal - 자동 감지 기능을 사용하여 콘텐츠를 크리스탈 아티팩트로 내보내기
• import_crystal - UUID로 크리스탈 유물 가져오기 및 재구성
• list_crystals - 사용 가능한 모든 크리스탈 유물을 나열합니다.

🔧 주요 역량

• 자동 감지 : 대화 맥락에서 가치 있는 콘텐츠를 자동으로 감지하고 내보냅니다.
• 버전 제어 : 여러 크리스탈 사양 버전 지원
• UUID 관리 : 수정 유물을 위한 고유 식별 시스템
• 보안 스토리지 : 프로젝트 경계 내에서 안전한 파일 작업
• 메타데이터 추적 : 결정 생성 및 속성에 대한 포괄적인 추적

📋 필수 조건

• Node.js 18 이상
• npm 또는 yarn 패키지 관리자

🔧 설치

1. 종속성 설치:지엑스피1
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 클라이언트

서버는 stdio 전송을 통해 표준 MCP 프로토콜을 사용하므로 모든 MCP 클라이언트와 호환됩니다. 다음을 실행하세요.

MCP 클라이언트를 서버의 stdin/stdout에 연결합니다.

🛡️ 보안 기능

• 경로 보안 : 모든 파일 작업은 프로젝트 루트 디렉토리로 제한됩니다.
• UUID 생성 : nanoid를 이용한 안전한 고유 식별자 생성
• 오류 처리 : 포괄적인 오류 처리를 통해 정보 유출을 방지합니다.
• 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', '확률 패턴')

스마트 매칭 기능:

• Codex 특정 용어 : '메커니즘', '인식', '에이전트', '전송', '프로토콜', '확률', '패턴'과 같은 용어에 대한 향상된 매칭
• 버전 인식 : 지능형 버전 번호 매칭(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 파일로 저장됩니다.

프로토콜 사양 파일

프로토콜 사양은 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 파일은 .cx 파일로 public/codex/ 에 저장되며 메커니즘 인식, 에이전트 통신 프로토콜, 고급 AI 상호 작용 패턴에 대한 특수 콘텐츠를 포함합니다.

현재 코덱스 파일:

• MECHANISM_AWARENESS_2.0.cx - 에이전트 간 전송 프로토콜 및 메커니즘 인식 패턴

Codex 파일 기능:

• 메커니즘 인식 : AI 에이전트가 자신의 작업 패턴을 이해하는 데 도움이 되는 콘텐츠
• 에이전트 간 통신 : 고급 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. 필요한 경우 서버 코드의 기본 버전을 업데이트합니다 .

새로운 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 Validation : 사양 버전에 따른 콘텐츠 검증 추가
3. 크리스탈 변환 : 버전 간 크리스탈 변환을 위한 도구 추가
4. Crystal Search : Crystal 콘텐츠 전반에 걸쳐 검색 기능 추가
5. 코덱스 향상 : 코덱스 생성 및 내보내기 기능 추가
6. 메커니즘 패턴 감지 : 메커니즘 인식 패턴의 자동 감지를 구현합니다.
7. 에이전트 프로토콜 검증 : 에이전트 통신 프로토콜에 대한 검증을 추가합니다.

오류 처리

서버에는 포괄적인 오류 처리 기능이 포함되어 있습니다.

• 파일 시스템 오류 : 누락된 파일이나 디렉토리의 원활한 처리
• JSON 구문 분석 오류 : 오류 복구를 통한 안전한 구문 분석
• 경로 보안 : 프로젝트 경계 외부의 액세스를 방지합니다.
• UUID 검증 : 작업 전에 Crystal ID를 검증합니다.

💡 사용 사례

연구 및 분석

• 복잡한 분석 결과를 결정으로 내보내기
• 다양한 AI 대화에서 분석 공유
• 연구 작업의 버전 기록 유지

코드 개발

• 정교한 코드 솔루션을 결정으로 내보내기
• 검증된 패턴과 구현 가져오기
• 복잡한 알고리즘 솔루션 공유

지식 관리

• 자세한 설명으로 크리스탈을 만들어 보세요
• 재사용 가능한 지식 아티팩트 라이브러리 구축
• 구조화된 문서 유지

고급 AI 상호작용

• 코덱스 파일을 통해 접근 메커니즘 인식 프로토콜
• 고급 에이전트 간 커뮤니케이션 패턴 구현
• 확률 패턴 인식 기술 탐색
• 의미 조작 및 주의 유도 방법 적용

📄 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다.

🤝 기여하기

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

기여가 특히 가치 있는 분야:

• 자동 감지를 위한 컨텍스트 창 통합
• 추가 크리스탈 사양 버전
• 크리스탈 검증 및 변환 도구
• 향상된 메타데이터 및 검색 기능
• 메커니즘 인식 패턴을 위한 새로운 코덱스 파일
• 에이전트 통신 프로토콜 개발
• 확률 패턴 인식 도구

📞 지원

문제가 발생하거나 질문이 있는 경우 프로젝트 저장소에서 문제를 열어주세요.

모델 컨텍스트 프로토콜을 사용하여 ❤️로 구축되었으며, 크리스탈 아티팩트 관리를 위해 설계되었습니다.