Metadata-Version: 2.4
Name: seahorse-mcp-server
Version: 0.1.0
Summary: Seahorse MCP server launcher with bundled Rust binary
Author: Dnotitia
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: requires-python
Dynamic: summary

# 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) 설치

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

설치 확인:

```bash
seahorse-mcp-server --help
```

## 2) 필수/선택 환경 변수

| 변수 | 필수 | 설명 |
|---|---|---|
| `SEAHORSE_API_KEY` | 예 | Seahorse API 키 |
| `SEAHORSE_TABLE_ENDPOINT` | 조건부 | TABLE Tool 사용 시 필요 |
| `SEAHORSE_STORAGE_ENDPOINT` | 조건부 | STORAGE Tool 사용 시 필요 |
| `SEAHORSE_VERIFY_SSL` | 아니오 | 기본 `true`, 사설 인증서 환경에서만 `false` 고려 |
| `SEAHORSE_MCP_LOG_LEVEL` | 아니오 | 기본 `info` (`trace/debug/info/warn/error`) |
| `SEAHORSE_TEMP_DIR` | 아니오 | 기본 `/tmp/seahorse-temp-files` |

주의:

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

endpoint 발급 안내:

- endpoint와 API 키는 [Seahorse Console](https://console.seahorse.dnotitia.ai/)에서 회원가입 후 발급할 수 있습니다.

## 3) 가장 빠른 실행 예시

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

```bash
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만 사용하는 경우:

```bash
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`)

```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`)

```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` 사용

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

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

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

## 8) 업그레이드/삭제

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

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