시냅스 MCP 서버

Synapse 엔터티(데이터 세트, 프로젝트, 폴더, 파일, 테이블)와 해당 주석을 노출하고 OAuth2 인증을 지원하는 MCP(모델 컨텍스트 프로토콜) 서버입니다.

개요

이 서버는 모델 컨텍스트 프로토콜(MCP)을 통해 Synapse 엔터티와 해당 주석에 액세스하는 RESTful API를 제공합니다. 다음과 같은 작업을 수행할 수 있습니다.

Synapse로 인증
ID로 엔터티 검색
이름으로 엔터티 검색
엔티티 주석 가져오기
엔티티 자식 가져오기
다양한 기준에 따라 엔터티 쿼리
Synapse 테이블 쿼리
Croissant 메타데이터 형식으로 데이터 세트 가져오기

Related MCP server: SourceSync.ai MCP Server

설치

지엑스피1

PyPI에서 설치

# Install from PyPI
pip install synapse-mcp

용법

서버 시작

python server.py --host 127.0.0.1 --port 9000

이렇게 하면 기본 포트(9000)에서 MCP 서버가 시작됩니다.

CLI 사용

# Start the server using the CLI
synapse-mcp --host 127.0.0.1 --port 9000 --debug

명령줄 옵션

usage: server.py [-h] [--host HOST] [--port PORT] [--debug]

Run the Synapse MCP server with OAuth2 support

options:
  -h, --help       show this help message and exit
  --host HOST      Host to bind to
  --port PORT      Port to listen on
  --debug          Enable debug logging
  --server-url URL Public URL of the server (for OAuth2 redirect)

테스트 실행

# Run all tests with coverage
./run_tests.sh

# Or run pytest directly
python -m pytest

서버 테스트

python examples/client_example.py

인증 방법

환경 변수

서버는 다음과 같은 환경 변수를 지원합니다.

HOST : 바인딩할 호스트(기본값: 127.0.0.1)
PORT : 수신할 포트(기본값: 9000)
MCP_TRANSPORT : 사용할 전송 프로토콜(기본값: stdio)
- stdio : 로컬 개발을 위해 표준 입출력을 사용합니다.
- sse : 클라우드 배포를 위해 서버에서 보낸 이벤트 사용
MCP_SERVER_URL : 서버의 공개 URL(기본값: mcp://127.0.0.1:9000)
- OAuth2 리디렉션 및 서버 정보에 사용됨

서버는 두 가지 인증 방법을 지원합니다.

인증 토큰 : Synapse 인증 토큰을 사용하여 인증합니다.
OAuth2 : Synapse의 OAuth2 서버를 사용하여 인증
- Synapse에 OAuth2 클라이언트를 등록해야 합니다( https://www.synapse.org/#!PersonalAccessTokens:OAuth )

API 엔드포인트

서버 정보

GET /info - 서버 정보 가져오기

도구

GET /tools - 사용 가능한 도구 나열
POST /tools/authenticate - Synapse로 인증
POST /tools/get_oauth_url - OAuth2 인증 URL 가져오기
POST /tools/get_entity - ID 또는 이름으로 엔티티 가져오기
POST /tools/get_entity_annotations - 엔티티에 대한 주석 가져오기
POST /tools/get_entity_children - 컨테이너 엔티티의 자식 엔티티 가져오기
POST /tools/query_entities - 다양한 기준에 따라 엔터티 쿼리
POST /tools/query_table - Synapse 테이블 쿼리

자원

GET /resources - 사용 가능한 리소스 나열
GET /resources/entity/{id} - ID로 엔터티 가져오기
GET /resources/entity/{id}/annotations - 엔티티 주석 가져오기
GET /resources/entity/{id}/children - 엔터티 자식 가져오기
GET /resources/query/entities/{entity_type} - 유형별 엔터티 쿼리
GET /resources/query/entities/parent/{parent_id} - 부모 ID로 엔터티 쿼리
GET /resources/query/entities/name/{name} - 이름으로 엔터티 쿼리
GET /resources/query/table/{id}/{query} - SQL과 유사한 구문으로 테이블 쿼리

OAuth2 엔드포인트

GET /oauth/login - Synapse OAuth2 로그인 페이지로 리디렉션
GET /oauth/callback - Synapse에서 OAuth2 콜백 처리

예시

입증

서버를 사용하려면 실제 Synapse 자격 증명으로 인증해야 합니다.

import requests

# Authenticate with Synapse
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
    "email": "your-synapse-email@example.com",
    "password": "your-synapse-password"
})
result = response.json()
print(result)

# Alternatively, you can authenticate with an API key
response = requests.post("http://127.0.0.1:9000/tools/authenticate", json={
    "api_key": "your-synapse-api-key"
})

OAuth2 인증

1. 리디렉션 흐름(브라우저 기반)

사용자를 OAuth 로그인 URL로 안내합니다.

http://127.0.0.1:9000/oauth/login?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI

2. API 기반 흐름

프로그래밍 방식으로 사용하려면 먼저 권한 부여 URL을 가져와야 합니다.

import requests

# Get OAuth2 authorization URL
response = requests.post("http://127.0.0.1:9000/tools/get_oauth_url", json={
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "YOUR_REDIRECT_URI"
})
auth_url = response.json()["auth_url"]
# Redirect user to auth_url

엔티티 얻기

import requests

# Get an entity by ID
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456")  # Replace with a real Synapse ID
entity = response.json()
print(entity)

엔터티 주석 가져오기

import requests

# Get annotations for an entity
response = requests.get("http://127.0.0.1:9000/resources/entity/syn123456/annotations")  # Replace with a real Synapse ID
annotations = response.json()
print(annotations)

엔터티 쿼리

import requests

# Query for files in a project
response = requests.get("http://127.0.0.1:9000/resources/query/entities/parent/syn123456", params={  # Replace with a real Synapse ID
    "entity_type": "file"
})
files = response.json()
print(files)

테이블 쿼리

import requests

# Query a table
table_id = "syn123456"  # Replace with a real Synapse table ID
query = "SELECT * FROM syn123456 LIMIT 10"  # Replace with a real Synapse table ID
response = requests.get(f"http://127.0.0.1:9000/resources/query/table/{table_id}/{query}")
table_data = response.json()
print(table_data)

Croissant 형식으로 데이터 세트 가져오기

import requests
import json

# Get public datasets in Croissant format
response = requests.get("http://127.0.0.1:9000/resources/croissant/datasets")
croissant_data = response.json()

# Save to file
with open("croissant_metadata.json", "w") as f:
    json.dump(croissant_data, f, indent=2)

전개

도커

Docker를 사용하여 서버를 빌드하고 실행할 수 있습니다.

# Build the Docker image
docker build -t synapse-mcp .

# Run the container
docker run -p 9000:9000 -e SYNAPSE_OAUTH_CLIENT_ID=your_client_id -e SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret -e SYNAPSE_OAUTH_REDIRECT_URI=your_redirect_uri synapse-mcp
docker run -p 9000:9000 -e MCP_TRANSPORT=sse -e MCP_SERVER_URL=mcp://your-domain:9000 synapse-mcp

플라이아이오

fly.io에 배포:

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login to fly.io
flyctl auth login

# Launch the app
flyctl launch

# Set OAuth2 secrets
flyctl secrets set SYNAPSE_OAUTH_CLIENT_ID=your_client_id
flyctl secrets set SYNAPSE_OAUTH_CLIENT_SECRET=your_client_secret
flyctl secrets set SYNAPSE_OAUTH_REDIRECT_URI=https://your-app-name.fly.dev/oauth/callback
flyctl secrets set MCP_TRANSPORT=sse
flyctl secrets set MCP_SERVER_URL=mcp://your-app-name.fly.dev:9000

# Deploy
flyctl deploy

Claude Desktop과 통합

Synapse MCP 서버를 Claude Desktop과 통합하면 Claude가 대화에서 직접 Synapse 데이터에 액세스하여 작업할 수 있습니다.

설치 지침

먼저 저장소를 복제하고 요구 사항을 설치합니다.

# Clone the repository
git clone https://github.com/susheel/synapse-mcp.git
cd synapse-mcp

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

Synapse MCP 서버를 사용하도록 Claude Desktop을 구성하세요.
- 클로드 데스크톱 열기
- 클로드 메뉴를 클릭하고 "설정..."을 선택하세요.
- 왼쪽 막대에서 "개발자"를 클릭하세요
- "구성 편집"을 클릭하세요
- mcpServers 섹션에 다음 구성을 추가합니다.

"synapse-mcp": {
  "command": "python",
  "args": [
    "/path/to/synapse-mcp/server.py",
    "--host", "127.0.0.1",
    "--port", "9000"
  ]
}

구성 파일을 저장하고 Claude Desktop을 다시 시작하세요.
이제 Claude와의 대화에서 Synapse 데이터를 사용할 수 있습니다. 예:
- "Synapse에서 ID syn123456을 가진 엔티티를 가져옵니다."
- "Synapse 프로젝트 syn123456의 모든 파일 쿼리"
- "Synapse 엔티티 syn123456에 대한 주석 가져오기"

기여하다

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

특허

MIT

Synapse MCP Server