seahorse-mcp-server

Seahorse API Gateway를 MCP(Model Context Protocol)로 노출하는 stdio 서버입니다.

이 문서는 PyPI에서 설치한 사용자를 위한 가이드입니다.
즉, 이 저장소에 접근하지 않아도 pip install만으로 사용할 수 있는 흐름을 기준으로 설명합니다.

무엇을 제공하나요?

• 설치 후 seahorse-mcp-server 실행 명령 제공
• TABLE/STORAGE endpoint 설정 여부에 따라 Tool 자동 노출
• MCP 권장 응답 형식(content + structuredContent + isError) 지원

지원 환경

• Python: >=3.9
• OS: Linux (wheel에 네이티브 바이너리 포함)

1) 설치

python -m pip install --upgrade seahorse-mcp-server

설치 확인:

seahorse-mcp-server --help

2) 필수/선택 환경 변수

주의:

• SEAHORSE_TABLE_ENDPOINT/SEAHORSE_STORAGE_ENDPOINT는 base URL을 넣어야 합니다.
  (예: https://xxxx.api.seahorse.dnotitia.ai)
• 최소 하나의 endpoint(TABLE 또는 STORAGE)가 설정되어야 서버가 시작됩니다.

endpoint 발급 안내:

• endpoint와 API 키는 Seahorse Console에서 회원가입 후 발급할 수 있습니다.

3) 가장 빠른 실행 예시

TABLE + STORAGE 모두 사용하는 경우:

export SEAHORSE_API_KEY="shsk_xxx"
export SEAHORSE_TABLE_ENDPOINT="https://your-table-endpoint.api.seahorse.dnotitia.ai"
export SEAHORSE_STORAGE_ENDPOINT="https://your-storage-endpoint.api.seahorse.dnotitia.ai"
export SEAHORSE_VERIFY_SSL="true"

seahorse-mcp-server

TABLE만 사용하는 경우:

export SEAHORSE_API_KEY="shsk_xxx"
export SEAHORSE_TABLE_ENDPOINT="https://your-table-endpoint.api.seahorse.dnotitia.ai"

seahorse-mcp-server

4) MCP 클라이언트 연동

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "seahorse": {
      "command": "seahorse-mcp-server",
      "args": [],
      "env": {
        "SEAHORSE_API_KEY": "shsk_xxx",
        "SEAHORSE_TABLE_ENDPOINT": "https://your-table-endpoint.api.seahorse.dnotitia.ai",
        "SEAHORSE_STORAGE_ENDPOINT": "https://your-storage-endpoint.api.seahorse.dnotitia.ai",
        "SEAHORSE_VERIFY_SSL": "true"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "seahorse": {
      "command": "seahorse-mcp-server",
      "args": [],
      "env": {
        "SEAHORSE_API_KEY": "shsk_xxx",
        "SEAHORSE_TABLE_ENDPOINT": "https://your-table-endpoint.api.seahorse.dnotitia.ai",
        "SEAHORSE_STORAGE_ENDPOINT": "https://your-storage-endpoint.api.seahorse.dnotitia.ai",
        "SEAHORSE_VERIFY_SSL": "true"
      }
    }
  }
}

5) 어떤 Tool이 노출되나요?

endpoint 설정에 따라 자동으로 결정됩니다.

• TABLE endpoint 설정 시:
  • search, get_adjacent_chunks
  • get_schema, get_indexed_count, scan_data, update_data, delete_data, insert_data
• STORAGE endpoint 설정 시:
  • upload_object, list_objects, search_objects, get_object_info
  • delete_object, delete_objects, download_object

6) STORAGE 사용 시 참고

• download_object는 파일을 SEAHORSE_TEMP_DIR 아래에 저장합니다.
• upload_object는 SEAHORSE_TEMP_DIR 기준 파일 경로를 입력으로 받습니다.
• 기본 temp 경로는 /tmp/seahorse-temp-files 입니다.

7) 문제 해결

TABLE endpoint is not configured / STORAGE endpoint is not configured

• 해당 endpoint 환경 변수가 빠졌거나 오타가 있는 경우입니다.

TLS/인증서 오류

• 운영 환경에서는 SEAHORSE_VERIFY_SSL=true 권장
• 개발 환경에서만 제한적으로 false 사용

실행 파일 경로를 직접 지정하고 싶은 경우

런처가 사용할 바이너리를 강제로 지정할 수 있습니다.

export SEAHORSE_MCP_SERVER_BIN="/custom/path/seahorse-mcp-server"
seahorse-mcp-server --help

8) 업그레이드/삭제

# 업그레이드
python -m pip install --upgrade seahorse-mcp-server

# 삭제
python -m pip uninstall seahorse-mcp-server