mcp-turso-cloud

mcp-turso-cloud

LLM을 위한 Turso 데이터베이스와의 통합을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 조직 수준 및 데이터베이스 수준 작업을 모두 처리하는 2단계 인증 시스템을 구현하여 LLM에서 직접 Turso 데이터베이스를 쉽게 관리하고 쿼리할 수 있도록 합니다.

특징

🏢 조직 수준 운영

• 데이터베이스 목록 : Turso 조직의 모든 데이터베이스를 확인하세요.
• 데이터베이스 생성 : 사용자 정의 가능한 옵션으로 새 데이터베이스를 생성합니다.
• 데이터베이스 삭제 : 조직에서 데이터베이스를 제거합니다.
• 데이터베이스 토큰 생성 : 특정 데이터베이스에 대한 인증 토큰을 생성합니다.

💾 데이터베이스 수준 작업

• 테이블 목록 : 특정 데이터베이스의 모든 테이블 보기
• 읽기 전용 쿼리 실행 : SELECT 및 PRAGMA 쿼리(읽기 전용 작업)를 실행합니다.
• 쿼리 실행 : 잠재적으로 파괴적인 SQL 쿼리(INSERT, UPDATE, DELETE 등)를 실행합니다.
• 테이블 설명 : 데이터베이스 테이블에 대한 스키마 정보 가져오기
• 벡터 검색 : SQLite 벡터 확장을 사용하여 벡터 유사성 검색을 수행합니다.

⚠️ 중요: 쿼리 실행 보안 ⚠️

이 서버는 읽기 전용 데이터베이스 작업과 파괴적 데이터베이스 작업 간에 보안 중심 분리를 구현합니다.

• SELECT 및 PRAGMA 쿼리(안전하고 읽기 전용 작업)에 대해 execute_read_only_query 사용합니다.
• 데이터를 수정하는 INSERT, UPDATE, DELETE, CREATE, DROP 및 기타 작업에 대해 execute_query 사용하세요.

이러한 분리를 통해 다양한 권한 수준과 승인 요구 사항이 허용됩니다.

• 읽기 전용 작업은 여러 컨텍스트에서 자동 승인될 수 있습니다.
• 파괴적인 작업에는 안전을 위한 명시적인 승인이 필요할 수 있습니다.

SQL 쿼리를 승인하기 전에 항상 주의 깊게 읽고 검토하세요! 이는 특히 데이터를 수정하거나 삭제할 수 있는 파괴적인 작업의 경우 매우 중요합니다. 각 쿼리가 어떤 작업을 하는지 충분히 이해한 후 실행을 허용하세요.

2단계 인증 시스템

서버는 정교한 인증 시스템을 구현합니다.

1. 조직 수준 인증
   • Turso 플랫폼 API 토큰을 사용합니다.
   • 데이터베이스와 조직 수준의 운영을 관리합니다.
   • Turso 대시보드를 통해 획득
2. 데이터베이스 수준 인증
   • 데이터베이스별 토큰을 사용합니다
   • 조직 토큰을 사용하여 자동 생성됨
   • 성능을 위해 캐시되고 필요에 따라 회전됨

구성

이 서버를 사용하려면 MCP 클라이언트를 통한 구성이 필요합니다. 다음은 다양한 환경에 대한 예시입니다.

클라인/클로드 데스크톱 구성

Cline/Claude Desktop MCP 설정에 다음을 추가하세요.

지엑스피1

WSL 구성을 사용한 Claude Desktop

WSL 환경의 경우 Claude Desktop 구성에 다음을 추가하세요.

환경 변수

서버에는 다음과 같은 환경 변수가 필요합니다.

• TURSO_API_TOKEN : Turso 플랫폼 API 토큰(필수)
• TURSO_ORGANIZATION : Turso 조직 이름(필수)
• TURSO_DEFAULT_DATABASE : 아무것도 지정되지 않은 경우 사용할 기본 데이터베이스(선택 사항)
• TOKEN_EXPIRATION : 생성된 데이터베이스 토큰의 만료 시간(선택 사항, 기본값: '7d')
• TOKEN_PERMISSION : 생성된 토큰에 대한 권한 수준(선택 사항, 기본값: 'full-access')

API

서버는 다음과 같이 범주별로 구성된 MCP 도구를 구현합니다.

조직 도구

목록_데이터베이스

Turso 조직의 모든 데이터베이스를 나열합니다.

매개변수: 없음

응답 예시:

데이터베이스 생성

조직 내에 새로운 데이터베이스를 만듭니다.

매개변수:

• name (문자열, 필수): 새 데이터베이스의 이름
• group (문자열, 선택 사항): 데이터베이스를 할당할 그룹
• regions (문자열[], 선택 사항): 데이터베이스를 배포할 지역

예:

데이터베이스 삭제

조직의 데이터베이스를 삭제합니다.

매개변수:

• name (문자열, 필수): 삭제할 데이터베이스의 이름

예:

데이터베이스 토큰 생성

특정 데이터베이스에 대한 새로운 토큰을 생성합니다.

매개변수:

• database (문자열, 필수): 데이터베이스 이름
• expiration (문자열, 선택 사항): 토큰 만료 시간
• permission (문자열, 선택 사항): 권한 수준('전체 액세스' 또는 '읽기 전용')

예:

데이터베이스 도구

리스트_테이블

데이터베이스의 모든 테이블을 나열합니다.

매개변수:

• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

읽기 전용 쿼리 실행

데이터베이스에 대해 읽기 전용 SQL 쿼리(SELECT, PRAGMA)를 실행합니다.

매개변수:

• query (문자열, 필수): 실행할 SQL 쿼리(SELECT 또는 PRAGMA여야 함)
• params (객체, 선택 사항): 쿼리 매개변수
• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

실행_쿼리

데이터베이스에 대해 잠재적으로 파괴적인 SQL 쿼리(INSERT, UPDATE, DELETE, CREATE 등)를 실행합니다.

매개변수:

• query (문자열, 필수): 실행할 SQL 쿼리(SELECT 또는 PRAGMA일 수 없음)
• params (객체, 선택 사항): 쿼리 매개변수
• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

설명_테이블

테이블에 대한 스키마 정보를 가져옵니다.

매개변수:

• table (문자열, 필수): 테이블 이름
• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

벡터 검색

SQLite 벡터 확장을 사용하여 벡터 유사성 검색을 수행합니다.

매개변수:

• table (문자열, 필수): 테이블 이름
• vector_column (문자열, 필수): 벡터를 포함하는 열
• query_vector (숫자[], 필수): 유사성 검색을 위한 쿼리 벡터
• limit (숫자, 선택 사항): 최대 결과 수(기본값: 10)
• database (문자열, 선택 사항): 데이터베이스 이름(제공되지 않으면 컨텍스트 사용)

예:

개발

설정

1. 저장소를 복제합니다
2. 종속성 설치:

3. 프로젝트를 빌드하세요:

4. 개발 모드에서 실행:

출판

1. package.json의 버전 업데이트
2. 프로젝트를 빌드하세요:

3. npm에 게시:

문제 해결

API 토큰 문제

인증 오류가 발생하는 경우:

1. Turso API 토큰이 유효하고 필요한 권한이 있는지 확인하세요.
2. 귀하의 조직 이름이 올바른지 확인하세요
3. 토큰이 만료되지 않았는지 확인하세요

데이터베이스 연결 문제

데이터베이스에 연결하는 데 문제가 있는 경우:

1. 조직에 데이터베이스가 있는지 확인하세요
2. API 토큰이 데이터베이스에 액세스할 수 있는지 확인하세요.
3. 데이터베이스 이름이 올바르게 입력되었는지 확인하세요.

기여하다

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

특허

MIT 라이센스 - 자세한 내용은 LICENSE 파일을 참조하세요.

감사의 말

기반으로 구축됨:

• 모델 컨텍스트 프로토콜
• 투르소 데이터베이스
• libSQL