WIND 주식 지수 기초 데이터 MCP 서비스

이것은 Oracle 테이블 WIND_IMP.AINDEXDESCRIPTION의 주식형 지수 기초 정보를 로컬 및 LAN 에이전트에 제공하는 읽기 전용 MCP 서비스입니다.

현재 두 가지 도구를 제공합니다:

• get_index_by_code(code): S_INFO_CODE로 정확히 조회합니다(예: 000300);

• search_indices_by_name(name, limit=20): 지수 이름 조각으로 검색하며 최대 100개를 반환합니다.

이 서비스는 SQL을 허용하지 않으며 데이터베이스 쓰기 작업을 제공하지 않습니다. 쿼리는 고정 SQL과 Oracle 바인드 매개변수를 사용합니다.

실행 환경

• Windows 10/11;

• Python 3.11 이상;

• 접근 가능한 Oracle 호스트, 포트 및 Service Name이 준비되어 있어야 합니다;

• 첫 버전은 python-oracledb Thin 모드를 사용하므로 Oracle Client를 설치할 필요가 없습니다.

Related MCP server: index-valuation

설치

PowerShell에서 실행하세요:

Set-Location 'D:\1.Project\19.CodexProject\9.MCP'
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e '.[dev]'

.env.example을 .env로 복사하고 실제 구성을 입력하세요. 이 머신에는 이미 실행 가능한 .env가 생성되어 있습니다. 이 파일은 .gitignore에 의해 제외되므로 버전 관리 저장소에 포함되지 않습니다.

로컬 stdio 모드

수동으로 시작하면 프로세스는 MCP 클라이언트가 표준 입력을 통해 메시지를 보낼 때까지 대기합니다:

.\.venv\Scripts\python.exe -m index_mcp.run_stdio

Codex는 프로젝트 수준 또는 사용자 수준 config.toml을 사용합니다. 다음 구성은 Codex가 로컬 서비스를 직접 시작하게 합니다:

[mcp_servers.wind_index]
command = 'D:\1.Project\19.CodexProject\9.MCP\.venv\Scripts\python.exe'
args = ["-m", "index_mcp.run_stdio"]
cwd = 'D:\1.Project\19.CodexProject\9.MCP'
required = true
default_tools_approval_mode = "auto"

구성을 저장한 후 Codex를 재시작하고 /mcp에서 wind_index를 확인하세요. Codex 공식 문서는 Codex의 데스크톱, CLI 및 IDE 확장이 MCP 구성을 공유하며 stdio와 Streamable HTTP를 지원한다고 설명합니다: Codex MCP 문서.

LAN HTTP 모드

서비스 시작:

Set-Location 'D:\1.Project\19.CodexProject\9.MCP'
.\.venv\Scripts\python.exe -m index_mcp.run_http

현재 구성:

• 로컬 주소: http://127.0.0.1:8765/mcp

• LAN 주소: http://172.18.3.114:8765/mcp

• 상태 확인: http://172.18.3.114:8765/health

• MCP 엔드포인트는 Authorization: Bearer <MCP_API_KEY>를 반드시 포함해야 합니다;

• /health는 API Key를 요구하지 않으며 {"status":"ok"}만 반환합니다.

Windows 방화벽이 LAN 연결을 차단하는 경우 관리자 PowerShell에서 로컬 서브넷에 대해서만 포트를 열 수 있습니다:

New-NetFirewallRule -DisplayName 'WIND Index MCP 8765' `
  -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8765 `
  -RemoteAddress LocalSubnet

8765 포트를 공용 인터넷에 직접 매핑하지 마세요. 신뢰할 수 없는 네트워크를 통해 사용하는 경우 프런트엔드 프록시에서 HTTPS를 활성화하고 OAuth로 업그레이드해야 합니다.

Codex로 LAN 서비스에 연결

먼저 Codex를 실행하는 컴퓨터에 서버 측 .env의 MCP_API_KEY 값을 담은 환경 변수를 설정하세요:

$env:WIND_INDEX_MCP_API_KEY = '<从服务端安全复制 API Key>'

그런 다음 Codex config.toml에서 구성하세요:

[mcp_servers.wind_index_lan]
url = "http://172.18.3.114:8765/mcp"
bearer_token_env_var = "WIND_INDEX_MCP_API_KEY"
required = true
default_tools_approval_mode = "auto"

공식 구성 항목 bearer_token_env_var는 환경 변수에서 Bearer Token을 읽으므로 config.toml에 키를 직접 작성하지 않아도 됩니다. Streamable HTTP를 지원하는 다른 MCP 클라이언트도 동일한 URL을 사용하고 동일한 Authorization 요청 헤더를 설정하면 됩니다.

검증

자동화 테스트 실행:

.\.venv\Scripts\python.exe -m pytest

stdio 엔드투엔드 호출 검증:

.\.venv\Scripts\python.exe .\scripts\smoke_test.py stdio

HTTP 서비스가 시작된 후 다른 PowerShell 창에서 검증하세요:

.\.venv\Scripts\python.exe .\scripts\smoke_test.py http

구성 항목

DHCP로 인해 서버의 LAN IP가 변경되는 경우 .env의 MCP_ALLOWED_HOSTS와 클라이언트 URL을 함께 업데이트해야 합니다.

API Key 교체

새 Key 생성:

.\.venv\Scripts\python.exe -c "import secrets; print(secrets.token_urlsafe(48))"

출력을 서버 측 .env의 MCP_API_KEY에 작성하고 HTTP 서비스를 재시작한 다음 각 클라이언트의 환경 변수를 업데이트하세요. Key를 Git, 채팅 기록 또는 로그에 커밋하지 마세요.

다른 테이블 확장

새 테이블마다 또는 밀접하게 관련된 쿼리 그룹마다 독립적인 도메인 모듈을 만드세요:

src/index_mcp/domains/<domain>/
├─ models.py
├─ repository.py
├─ service.py
└─ tools.py

Repository는 고정되고 매개변수화된 읽기 전용 SQL만 저장할 수 있습니다. Service는 입력 정규화와 비즈니스 경계를 담당하고 Tools는 MCP 계약을 담당합니다. server.py에 새 도구를 등록하면 기존 연결 풀, 인증, 로깅 및 이중 전송 입력 지점을 재사용할 수 있습니다.

보안 참고 사항

• .env와 .venv는 Git에서 무시됩니다;

• stdio 로그는 stderr에만 기록되므로 MCP 프로토콜 스트림을 오염시키지 않습니다;

• HTTP는 Bearer API Key와 Host 화이트리스트를 사용합니다;

• CORS는 기본적으로 비활성화되어 있습니다;

• HTTP를 통한 API Key는 신뢰할 수 있는 LAN에서만 사용해야 하며, 네트워크 감청자가 평문 트래픽을 가로챌 수 있습니다;

• 데이터베이스 계정은 Oracle 측에서 최소 읽기 전용 권한을 유지해야 합니다.