Metadata-Version: 2.4
Name: hectofinancial-mcp-server
Version: 0.3.0
Summary: 헥토파이낸셜 결제 서비스 연동 문서를 검색하고 조회할 수 있는 MCP 서버입니다. 공식 가이드를 AI와 함께 빠르게 탐색하여 정확한 결제 시스템 구축을 지원합니다.
Author-email: hectofinancial <pg_dev@hecto.co.kr>
License: MIT
Project-URL: Homepage, https://developers.hectofinancial.co.kr
Project-URL: Repository, https://github.com/Hecto-Financial/hectofinancial-mcp-server
Project-URL: Bug Tracker, https://github.com/Hecto-Financial/hectofinancial-mcp-server/issues
Requires-Python: <4.0,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.28.1
Requires-Dist: fastmcp<3.0,>=2.9.2
Requires-Dist: mistune>=3.0.0
Requires-Dist: certifi>=2024.0.0
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=2.0.0; extra == "semantic"
Requires-Dist: numpy>=1.24.0; extra == "semantic"
Dynamic: license-file

# 헥토파이낸셜 MCP 서버

헥토파이낸셜 결제 연동 문서를 AI가 직접 검색·분석할 수 있는 MCP 서버입니다.  
공식 개발자 포털의 최신 문서를 자동으로 가져와 Claude, Cursor, VS Code 등에서 바로 활용할 수 있습니다.

## 🛠️ 제공 도구

| 도구 | 설명 |
|------|------|
| `search_docs` | 키워드·카테고리 기반 문서 검색 (BM25 + 시맨틱 혼합) |
| `list_docs` | 전체 문서 목록 조회 (카테고리·언어 필터, 페이지네이션) |
| `get_docs` | 문서 ID 또는 파일명으로 전체 내용 조회 |
| `search_error_code` | 오류코드(4자리) 원인·설명 즉시 반환 |
| `get_api_endpoint` | 자연어 쿼리로 API URL·HTTP 메서드 추출 |
| `get_api_params` | API 요청·응답 파라미터 테이블 조회 |

## 🚀 시작하기

[uv](https://docs.astral.sh/uv/) 설치 후 아래 클라이언트 설정을 추가하세요.

### Cursor

**[원클릭 설정](cursor://anysphere.cursor-deeplink/mcp/install?name=hectofinancial-mcp-server&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJoZWN0b2ZpbmFuY2lhbC1tY3Atc2VydmVyQGxhdGVzdCJdfQo=)** 또는 `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "hecto-financial": {
      "command": "uvx",
      "args": ["hectofinancial-mcp-server@latest"]
    }
  }
}
```

### VS Code

**[원클릭 설정](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22hectofinancial-mcp-server%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22hectofinancial-mcp-server%40latest%22%5D%7D)** 또는 `settings.json`:

```json
{
  "mcp": {
    "servers": {
      "hectofinancial-mcp-server": {
        "command": "uvx",
        "args": ["hectofinancial-mcp-server@latest"]
      }
    }
  }
}
```

### Claude Desktop

`~/.claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hecto-financial": {
      "command": "uvx",
      "args": ["hectofinancial-mcp-server@latest"]
    }
  }
}
```

## 💬 사용 예시

```
"신용카드 빌키 정기결제 구현 방법 알려줘"
"가상계좌 입금 통보 처리는 어떻게 해?"
"결제승인 API 요청 파라미터 보여줘"
"0031 오류 원인이 뭐야?"
"What is the API endpoint for virtual account payment?"
```

## ✨ 주요 기능

- **최신 문서 자동 갱신** — 시작 시 헥토파이낸셜 개발자 포털에서 최신 문서를 가져오고 로컬에 캐싱
- **한국어·영어 동시 지원** — 560개 이상 문서, `language` 파라미터로 필터링
- **시맨틱 검색** — BM25 + 다국어 임베딩 모델 혼합으로 의미 기반 검색 (`[semantic]` 옵션)

### 시맨틱 검색 활성화 (선택)

```json
{
  "mcpServers": {
    "hecto-financial": {
      "command": "uvx",
      "args": ["hectofinancial-mcp-server[semantic]@latest"]
    }
  }
}
```

## 📄 License

MIT License
