kispilot 0.1.0__tar.gz

kispilot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dong-Ju An
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kispilot-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: kispilot
+Version: 0.1.0
+Summary: 한국투자증권 Open API를 AI 에이전트(MCP)와 웹 콘솔에서 쓰기 위한 도구 모음 (비공식)
+Author: Dong-Ju An
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dongju923/kispilot
+Project-URL: Repository, https://github.com/dongju923/kispilot
+Project-URL: Issues, https://github.com/dongju923/kispilot/issues
+Project-URL: Changelog, https://github.com/dongju923/kispilot/releases
+Keywords: kis,korea-investment,한국투자증권,mcp,trading,backtest,claude,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: Korean
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: keyring>=25
+Requires-Dist: platformdirs>=4
+Requires-Dist: pandas>=2.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: yfinance>=0.2.40
+Requires-Dist: starlette>=0.37
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: websockets>=12
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: mcp<3,>=2.2
+Dynamic: license-file
+
+# KISPilot
+
+한국투자증권 Open API를 **AI 에이전트(MCP)** 와 **웹 콘솔**에서 쓰기 위한 도구 모음입니다.
+
+> **비공식 프로젝트입니다.** 한국투자증권과 관계가 없으며, 한국투자증권이 만들거나 검증하지 않았습니다.
+> 이 소프트웨어는 투자 조언이 아니며, 주문·백테스트 결과로 생긴 손실에 대해 책임지지 않습니다 (MIT 라이선스, 무보증).
+> 실전 계좌로 쓰기 전에 모의투자로 충분히 확인하세요.
+
+## 할 수 있는 것
+
+- **조회** — 시세·호가·체결, 투자자·수급, 재무, 순위, 업종·지수, ETF, 계좌 잔고·손익 (KIS API 80여 개)
+- **주문** — 현금·신용·예약 주문, 정정·취소 (에이전트는 모의투자가 기본, 실전은 2단계 확인)
+- **차트** — 1분~년봉, 이동평균·볼린저·일목균형표 등 지표, 보조 차트 30여 종
+- **백테스트** — 기본 전략 11종 + 지표 157개로 만드는 커스텀 전략, 벤치마크 비교, 거래 내역
+- **실시간** — KIS 웹소켓 체결·호가 (웹 콘솔)
+
+## 설치
+
+Python 3.11 이상이 필요합니다.
+
+**추천** — 도구 전용 환경에 설치되고 `kispilot` 명령이 PATH 에 자동으로 등록됩니다.
+
+```bash
+uv tool install kispilot      # 또는: pipx install kispilot
+```
+
+일반 `pip` 로도 설치할 수 있습니다. 가상환경·conda 를 켠 상태에서 설치하면 그 환경을 켰을 때만 `kispilot` 명령이 보입니다.
+
+```bash
+pip install kispilot
+```
+
+설치 없이 바로 실행 (`uv` 필요):
+
+```bash
+uvx kispilot ui
+```
+
+| 할 일 | uv | pipx | pip |
+|---|---|---|---|
+| 업데이트 | `uv tool upgrade kispilot` | `pipx upgrade kispilot` | `pip install -U kispilot` |
+| 특정 버전 | `uv tool install kispilot==0.1.0` | `pipx install kispilot==0.1.0` | `pip install kispilot==0.1.0` |
+| 삭제 | `uv tool uninstall kispilot` | `pipx uninstall kispilot` | `pip uninstall kispilot` |
+
+버전별 변경 내용은 [Releases](https://github.com/dongju923/kispilot/releases) 에 있습니다.
+
+소스에서 개발용으로 설치하려면:
+
+```bash
+git clone https://github.com/dongju923/kispilot
+cd kispilot
+pip install -e .
+```
+
+## 키 등록 (처음 한 번)
+
+[KIS Developers](https://apiportal.koreainvestment.com)에서 앱키·앱시크릿을 발급받은 뒤 터미널에서 실행합니다.
+
+```bash
+kispilot setup        # 실전 / 모의투자 / 둘 다 선택 → 앱키·시크릿·계좌 입력
+kispilot status       # 등록 상태 확인 (값은 가려서 표시)
+```
+
+- 앱키·시크릿은 **OS 키체인**(Windows 자격 증명 관리자, macOS 키체인, Linux Secret Service)에 저장됩니다. 파일에 평문으로 남지 않습니다.
+- 입력은 화면에 보이지 않고, 저장 전에 실제로 토큰을 발급해 키가 맞는지 확인합니다.
+- **키를 AI 채팅창에 붙여넣지 마세요.** 채팅 내용은 대화 기록과 AI 서비스 쪽에 남습니다.
+- 지우려면 `kispilot logout` (키체인 삭제 + 토큰 폐기).
+
+키체인을 쓸 수 없는 환경(서버 등)에서는 환경변수로 넣을 수 있습니다. 환경변수가 키체인보다 먼저 쓰입니다.
+변수 이름은 [.env.example](https://github.com/dongju923/kispilot/blob/main/.env.example)을 참고하여, .env 파일을 새로 생성하세요.
+
+## 웹 콘솔
+
+```bash
+kispilot ui           # http://127.0.0.1:8000
+```
+
+대시보드, 시장·업종, 순위, 종목 분석(차트·호가·수급·재무), ETF, 주문, 계좌, 백테스트 화면이 있습니다.
+같은 PC에서만 접속되도록 127.0.0.1에 열립니다.
+
+## AI 에이전트에서 쓰기 (MCP)
+
+명령 한 줄로 AI 클라이언트에 등록합니다. 설정 파일(JSON)은 이 명령이 대신 써 줍니다.
+
+```bash
+kispilot install claude-desktop   # Claude Desktop 앱
+kispilot install claude-code      # Claude Code (내 계정 전체, 어느 폴더에서나)
+```
+
+- 등록한 뒤 해당 앱을 다시 시작하면 연결됩니다. Claude Desktop 은 트레이 아이콘 → 종료 후 다시 켜세요.
+- 지금 설치된 `kispilot` 실행 파일의 전체 경로로 등록하므로 PATH 설정이 필요 없습니다.
+- Claude Desktop 설정 파일은 바꾸기 전에 `claude_desktop_config.json.bak-날짜` 로 백업하고, 다른 항목은 건드리지 않습니다.
+- 실전 주문은 꺼진 상태로 등록됩니다. 켜려면 `--allow-real-orders` 를 붙입니다 (아래 안전장치 참고).
+- 바뀔 내용만 보려면 `--dry-run`, 해제는 `kispilot uninstall claude-desktop` (또는 `claude-code`).
+- 동작 확인: `kispilot mcp --check`
+
+### MCP 도구 (95개)
+
+| 묶음 | 도구 |
+|---|---|
+| 시세·분석·순위·업종·재무·계좌 | KIS API 조회 도구 (`price_*`, `price_anal_*`, `ranking_anal_*`, `sector_*`, `info_*`, `account_*`, `order_inquire_*`) |
+| 주문 | `order_buy_cash` 등 (모의투자 기본), 실전 주문 확인 `order_confirm` · 취소 `order_discard`, 지금 장 구간·호가 유형 `market_session` |
+| 검색 | `search_stock_code`, `search_sector_code` |
+| 백테스트 | `backtest_options`, `backtest_indicator_catalog`, `backtest_run`, `backtest_strategy_validate` / `list` / `load` / `save` / `delete` |
+| 지표·차트 | `indicator_values` (RSI·MACD 등 최근 값), `chart_bars` (일·주·월·년봉), `yf_get_history` |
+
+예: "삼성전자 최근 5년 골든크로스(5/20) 백테스트, 손절 7% 익절 20%로 해줘", "SK하이닉스 RSI랑 20일선 지금 얼마야?"
+
+### MCP 프롬프트 (작업 템플릿)
+
+자주 하는 작업의 진행 순서를 담은 템플릿입니다. Claude Desktop 은 입력창의 `+` 메뉴, Claude Code 는 `/kispilot:<이름>` 으로 고릅니다.
+칸을 비워 두면 Claude 가 대화로 물어봅니다.
+
+| 프롬프트 | 하는 일 |
+|---|---|
+| 오늘 시장 브리핑 (`market_briefing`) | 지수 · 투자자 수급 · 강한/약한 업종 · 등락률/거래량 상위 · 주요 뉴스 |
+| 종목 종합 분석 (`stock_analysis`) | 시세 · 추세(이동평균·RSI·MACD·볼린저) · 수급 · 재무 · 긍정/위험 신호 |
+| 백테스트 마법사 (`backtest_wizard`) | 전략 선택 → 실행 → 지수 대비 해석 → 파라미터 비교 → 저장 |
+| 전략 만들기 (`strategy_builder`) | 말로 설명한 아이디어 → 커스텀 전략 JSON → 검증 → 백테스트 → 저장 |
+| 주문 도우미 (`order_assistant`) | 장 구간 확인 → 시세·주문 가능 수량 → 주문 내용 확인 → (실전) 2단계 승인 |
+| 보유 종목 점검 (`portfolio_review`) | 잔고 · 손익 · 종목별 추세/지표 · 쏠림 점검 (주문 안 함) |
+
+<details>
+<summary>직접 설정하려면</summary>
+
+등록되는 내용은 "MCP 서버를 `kispilot mcp` 명령으로 실행하라" 는 한 항목입니다.
+이 명령은 AI 클라이언트가 실행해서 표준 입출력으로 대화하므로, 터미널에서 직접 치면 아무것도 출력하지 않고 기다리는 것이 정상입니다.
+
+```json
+{
+  "mcpServers": {
+    "kispilot": {
+      "command": "<kispilot 실행 파일 전체 경로>",
+      "args": ["mcp"],
+      "env": { "KIS_ALLOW_REAL_ORDERS": "0" }
+    }
+  }
+}
+```
+
+- 실행 파일 경로: Windows `where kispilot`, macOS·Linux `which kispilot`
+- Claude Desktop: 설정 → 개발자 → 구성 편집 (`claude_desktop_config.json`)
+- Claude Code: 프로젝트 폴더의 `.mcp.json` (예시: [.mcp.json.example](https://github.com/dongju923/kispilot/blob/main/.mcp.json.example))
+- `uv` 사용자는 설치 없이 `"command": "uvx", "args": ["kispilot", "mcp"]`
+
+</details>
+
+### 주문 안전장치 (에이전트)
+
+AI 모델이 스스로 도구를 부르기 때문에 웹 콘솔보다 보수적으로 동작합니다.
+
+1. 주문 도구의 기본값은 **모의투자**입니다.
+2. 실전 주문은 MCP 서버 환경변수 `KIS_ALLOW_REAL_ORDERS=1` 을 사용자가 직접 넣어야 켜집니다.
+3. 켜져 있어도 바로 나가지 않습니다. 주문 내용과 확인 번호를 먼저 돌려주고, 사용자가 승인한 뒤 `order_confirm` 을 불러야 전송됩니다 (3분 안, 1회용).
+
+## 데이터 출처와 저장 위치
+
+- 과거 일봉·분봉: [yfinance](https://github.com/ranaroussi/yfinance) (Yahoo Finance, 개인적·연구 목적 이용 권장), 최근 거래일은 KIS API로 보강
+- 토큰 캐시·종목 마스터·커스텀 전략: 사용자 데이터 폴더 (`kispilot status` 에 표시, 환경변수 `KISPILOT_HOME` 으로 변경)
+- 차트: [TradingView Lightweight Charts](https://github.com/tradingview/lightweight-charts) (Apache-2.0)
+
+## 참고
+
+- [한국투자증권 Open API](https://apiportal.koreainvestment.com) — 모든 시세·계좌·주문 기능은 이 API 를 호출합니다.
+- [koreainvestment/open-trading-api](https://github.com/koreainvestment/open-trading-api) — 백테스트 기본 전략 구성(프리셋 종류)과 종목 마스터 파일 형식(필드 폭·열 이름)을 참고했습니다.
+
+## 라이선스
+
+[MIT](https://github.com/dongju923/kispilot/blob/main/LICENSE)

kispilot-0.1.0/README.md

@@ -0,0 +1,169 @@
+# KISPilot
+
+한국투자증권 Open API를 **AI 에이전트(MCP)** 와 **웹 콘솔**에서 쓰기 위한 도구 모음입니다.
+
+> **비공식 프로젝트입니다.** 한국투자증권과 관계가 없으며, 한국투자증권이 만들거나 검증하지 않았습니다.
+> 이 소프트웨어는 투자 조언이 아니며, 주문·백테스트 결과로 생긴 손실에 대해 책임지지 않습니다 (MIT 라이선스, 무보증).
+> 실전 계좌로 쓰기 전에 모의투자로 충분히 확인하세요.
+
+## 할 수 있는 것
+
+- **조회** — 시세·호가·체결, 투자자·수급, 재무, 순위, 업종·지수, ETF, 계좌 잔고·손익 (KIS API 80여 개)
+- **주문** — 현금·신용·예약 주문, 정정·취소 (에이전트는 모의투자가 기본, 실전은 2단계 확인)
+- **차트** — 1분~년봉, 이동평균·볼린저·일목균형표 등 지표, 보조 차트 30여 종
+- **백테스트** — 기본 전략 11종 + 지표 157개로 만드는 커스텀 전략, 벤치마크 비교, 거래 내역
+- **실시간** — KIS 웹소켓 체결·호가 (웹 콘솔)
+
+## 설치
+
+Python 3.11 이상이 필요합니다.
+
+**추천** — 도구 전용 환경에 설치되고 `kispilot` 명령이 PATH 에 자동으로 등록됩니다.
+
+```bash
+uv tool install kispilot      # 또는: pipx install kispilot
+```
+
+일반 `pip` 로도 설치할 수 있습니다. 가상환경·conda 를 켠 상태에서 설치하면 그 환경을 켰을 때만 `kispilot` 명령이 보입니다.
+
+```bash
+pip install kispilot
+```
+
+설치 없이 바로 실행 (`uv` 필요):
+
+```bash
+uvx kispilot ui
+```
+
+| 할 일 | uv | pipx | pip |
+|---|---|---|---|
+| 업데이트 | `uv tool upgrade kispilot` | `pipx upgrade kispilot` | `pip install -U kispilot` |
+| 특정 버전 | `uv tool install kispilot==0.1.0` | `pipx install kispilot==0.1.0` | `pip install kispilot==0.1.0` |
+| 삭제 | `uv tool uninstall kispilot` | `pipx uninstall kispilot` | `pip uninstall kispilot` |
+
+버전별 변경 내용은 [Releases](https://github.com/dongju923/kispilot/releases) 에 있습니다.
+
+소스에서 개발용으로 설치하려면:
+
+```bash
+git clone https://github.com/dongju923/kispilot
+cd kispilot
+pip install -e .
+```
+
+## 키 등록 (처음 한 번)
+
+[KIS Developers](https://apiportal.koreainvestment.com)에서 앱키·앱시크릿을 발급받은 뒤 터미널에서 실행합니다.
+
+```bash
+kispilot setup        # 실전 / 모의투자 / 둘 다 선택 → 앱키·시크릿·계좌 입력
+kispilot status       # 등록 상태 확인 (값은 가려서 표시)
+```
+
+- 앱키·시크릿은 **OS 키체인**(Windows 자격 증명 관리자, macOS 키체인, Linux Secret Service)에 저장됩니다. 파일에 평문으로 남지 않습니다.
+- 입력은 화면에 보이지 않고, 저장 전에 실제로 토큰을 발급해 키가 맞는지 확인합니다.
+- **키를 AI 채팅창에 붙여넣지 마세요.** 채팅 내용은 대화 기록과 AI 서비스 쪽에 남습니다.
+- 지우려면 `kispilot logout` (키체인 삭제 + 토큰 폐기).
+
+키체인을 쓸 수 없는 환경(서버 등)에서는 환경변수로 넣을 수 있습니다. 환경변수가 키체인보다 먼저 쓰입니다.
+변수 이름은 [.env.example](https://github.com/dongju923/kispilot/blob/main/.env.example)을 참고하여, .env 파일을 새로 생성하세요.
+
+## 웹 콘솔
+
+```bash
+kispilot ui           # http://127.0.0.1:8000
+```
+
+대시보드, 시장·업종, 순위, 종목 분석(차트·호가·수급·재무), ETF, 주문, 계좌, 백테스트 화면이 있습니다.
+같은 PC에서만 접속되도록 127.0.0.1에 열립니다.
+
+## AI 에이전트에서 쓰기 (MCP)
+
+명령 한 줄로 AI 클라이언트에 등록합니다. 설정 파일(JSON)은 이 명령이 대신 써 줍니다.
+
+```bash
+kispilot install claude-desktop   # Claude Desktop 앱
+kispilot install claude-code      # Claude Code (내 계정 전체, 어느 폴더에서나)
+```
+
+- 등록한 뒤 해당 앱을 다시 시작하면 연결됩니다. Claude Desktop 은 트레이 아이콘 → 종료 후 다시 켜세요.
+- 지금 설치된 `kispilot` 실행 파일의 전체 경로로 등록하므로 PATH 설정이 필요 없습니다.
+- Claude Desktop 설정 파일은 바꾸기 전에 `claude_desktop_config.json.bak-날짜` 로 백업하고, 다른 항목은 건드리지 않습니다.
+- 실전 주문은 꺼진 상태로 등록됩니다. 켜려면 `--allow-real-orders` 를 붙입니다 (아래 안전장치 참고).
+- 바뀔 내용만 보려면 `--dry-run`, 해제는 `kispilot uninstall claude-desktop` (또는 `claude-code`).
+- 동작 확인: `kispilot mcp --check`
+
+### MCP 도구 (95개)
+
+| 묶음 | 도구 |
+|---|---|
+| 시세·분석·순위·업종·재무·계좌 | KIS API 조회 도구 (`price_*`, `price_anal_*`, `ranking_anal_*`, `sector_*`, `info_*`, `account_*`, `order_inquire_*`) |
+| 주문 | `order_buy_cash` 등 (모의투자 기본), 실전 주문 확인 `order_confirm` · 취소 `order_discard`, 지금 장 구간·호가 유형 `market_session` |
+| 검색 | `search_stock_code`, `search_sector_code` |
+| 백테스트 | `backtest_options`, `backtest_indicator_catalog`, `backtest_run`, `backtest_strategy_validate` / `list` / `load` / `save` / `delete` |
+| 지표·차트 | `indicator_values` (RSI·MACD 등 최근 값), `chart_bars` (일·주·월·년봉), `yf_get_history` |
+
+예: "삼성전자 최근 5년 골든크로스(5/20) 백테스트, 손절 7% 익절 20%로 해줘", "SK하이닉스 RSI랑 20일선 지금 얼마야?"
+
+### MCP 프롬프트 (작업 템플릿)
+
+자주 하는 작업의 진행 순서를 담은 템플릿입니다. Claude Desktop 은 입력창의 `+` 메뉴, Claude Code 는 `/kispilot:<이름>` 으로 고릅니다.
+칸을 비워 두면 Claude 가 대화로 물어봅니다.
+
+| 프롬프트 | 하는 일 |
+|---|---|
+| 오늘 시장 브리핑 (`market_briefing`) | 지수 · 투자자 수급 · 강한/약한 업종 · 등락률/거래량 상위 · 주요 뉴스 |
+| 종목 종합 분석 (`stock_analysis`) | 시세 · 추세(이동평균·RSI·MACD·볼린저) · 수급 · 재무 · 긍정/위험 신호 |
+| 백테스트 마법사 (`backtest_wizard`) | 전략 선택 → 실행 → 지수 대비 해석 → 파라미터 비교 → 저장 |
+| 전략 만들기 (`strategy_builder`) | 말로 설명한 아이디어 → 커스텀 전략 JSON → 검증 → 백테스트 → 저장 |
+| 주문 도우미 (`order_assistant`) | 장 구간 확인 → 시세·주문 가능 수량 → 주문 내용 확인 → (실전) 2단계 승인 |
+| 보유 종목 점검 (`portfolio_review`) | 잔고 · 손익 · 종목별 추세/지표 · 쏠림 점검 (주문 안 함) |
+
+<details>
+<summary>직접 설정하려면</summary>
+
+등록되는 내용은 "MCP 서버를 `kispilot mcp` 명령으로 실행하라" 는 한 항목입니다.
+이 명령은 AI 클라이언트가 실행해서 표준 입출력으로 대화하므로, 터미널에서 직접 치면 아무것도 출력하지 않고 기다리는 것이 정상입니다.
+
+```json
+{
+  "mcpServers": {
+    "kispilot": {
+      "command": "<kispilot 실행 파일 전체 경로>",
+      "args": ["mcp"],
+      "env": { "KIS_ALLOW_REAL_ORDERS": "0" }
+    }
+  }
+}
+```
+
+- 실행 파일 경로: Windows `where kispilot`, macOS·Linux `which kispilot`
+- Claude Desktop: 설정 → 개발자 → 구성 편집 (`claude_desktop_config.json`)
+- Claude Code: 프로젝트 폴더의 `.mcp.json` (예시: [.mcp.json.example](https://github.com/dongju923/kispilot/blob/main/.mcp.json.example))
+- `uv` 사용자는 설치 없이 `"command": "uvx", "args": ["kispilot", "mcp"]`
+
+</details>
+
+### 주문 안전장치 (에이전트)
+
+AI 모델이 스스로 도구를 부르기 때문에 웹 콘솔보다 보수적으로 동작합니다.
+
+1. 주문 도구의 기본값은 **모의투자**입니다.
+2. 실전 주문은 MCP 서버 환경변수 `KIS_ALLOW_REAL_ORDERS=1` 을 사용자가 직접 넣어야 켜집니다.
+3. 켜져 있어도 바로 나가지 않습니다. 주문 내용과 확인 번호를 먼저 돌려주고, 사용자가 승인한 뒤 `order_confirm` 을 불러야 전송됩니다 (3분 안, 1회용).
+
+## 데이터 출처와 저장 위치
+
+- 과거 일봉·분봉: [yfinance](https://github.com/ranaroussi/yfinance) (Yahoo Finance, 개인적·연구 목적 이용 권장), 최근 거래일은 KIS API로 보강
+- 토큰 캐시·종목 마스터·커스텀 전략: 사용자 데이터 폴더 (`kispilot status` 에 표시, 환경변수 `KISPILOT_HOME` 으로 변경)
+- 차트: [TradingView Lightweight Charts](https://github.com/tradingview/lightweight-charts) (Apache-2.0)
+
+## 참고
+
+- [한국투자증권 Open API](https://apiportal.koreainvestment.com) — 모든 시세·계좌·주문 기능은 이 API 를 호출합니다.
+- [koreainvestment/open-trading-api](https://github.com/koreainvestment/open-trading-api) — 백테스트 기본 전략 구성(프리셋 종류)과 종목 마스터 파일 형식(필드 폭·열 이름)을 참고했습니다.
+
+## 라이선스
+
+[MIT](https://github.com/dongju923/kispilot/blob/main/LICENSE)

kispilot-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=77"]  # license = "MIT" 같은 SPDX 표기·license-files 는 77 부터
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kispilot"
+dynamic = ["version"]
+description = "한국투자증권 Open API를 AI 에이전트(MCP)와 웹 콘솔에서 쓰기 위한 도구 모음 (비공식)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Dong-Ju An" }]
+keywords = ["kis", "korea-investment", "한국투자증권", "mcp", "trading", "backtest", "claude", "agent"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Natural Language :: Korean",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "requests>=2.31",
+    "python-dotenv>=1.0",
+    "keyring>=25",
+    "platformdirs>=4",
+    "pandas>=2.2",
+    "numpy>=1.26",
+    "yfinance>=0.2.40",
+    "starlette>=0.37",
+    "uvicorn>=0.30",
+    "websockets>=12",
+    "aiohttp>=3.9",
+    "mcp>=2.2,<3",
+]
+
+[project.scripts]
+kispilot = "kispilot.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/dongju923/kispilot"
+Repository = "https://github.com/dongju923/kispilot"
+Issues = "https://github.com/dongju923/kispilot/issues"
+Changelog = "https://github.com/dongju923/kispilot/releases"
+
+[tool.setuptools.dynamic]
+version = { attr = "kispilot.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kispilot = ["app/ui/*.html", "app/ui/assets/*", "app/ui/assets/css/*", "app/ui/assets/js/*.js", "app/ui/assets/js/pages/*.js"]

kispilot-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kispilot-0.1.0/src/kispilot/__init__.py

@@ -0,0 +1,3 @@
+"""KISPilot — 한국투자증권 Open API 를 AI 에이전트(MCP)와 웹 콘솔에서 쓰기 위한 도구 모음 (비공식)."""
+
+__version__ = "0.1.0"

kispilot-0.1.0/src/kispilot/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from kispilot.cli import main
+
+sys.exit(main())

kispilot-0.1.0/src/kispilot/api/__init__.py

@@ -0,0 +1 @@
+

kispilot-0.1.0/src/kispilot/api/account/__init__.py

@@ -0,0 +1,24 @@
+"""계좌 단위(종목 개별이 아닌 계좌 전체) 조회 API 모음.
+
+    from kispilot.api.account import (
+        inquire_balance_rlz_pl, inquire_account_balance,
+        inquire_period_profit, inquire_period_trade_profit,
+        inquire_intgr_margin, inquire_period_rights,
+    )
+"""
+
+from .account_inquire_balance_rlz_pl import inquire_balance_rlz_pl
+from .account_asset_balance import inquire_account_balance
+from .account_inquire_period_profit import inquire_period_profit
+from .account_inquire_period_trade_profit import inquire_period_trade_profit
+from .account_intgr_margin import inquire_intgr_margin
+from .account_inquire_period_rights import inquire_period_rights
+
+__all__ = [
+    "inquire_balance_rlz_pl",
+    "inquire_account_balance",
+    "inquire_period_profit",
+    "inquire_period_trade_profit",
+    "inquire_intgr_margin",
+    "inquire_period_rights",
+]

kispilot-0.1.0/src/kispilot/api/account/account_asset_balance.py

@@ -0,0 +1,130 @@
+# 투자계좌자산현황조회[v1_국내주식-048]
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+from kispilot.api.config import DOMAIN, CANO, ACNT_PRDT_CD, REAL_APPKEY, REAL_APP_SECRET
+from kispilot.api.oauth.kis_token import load_token
+from kispilot.api.utils.http_session import get_session
+
+URL = "/uapi/domestic-stock/v1/trading/inquire-account-balance"
+# ※ 모의투자 미지원 (실전투자 전용).
+# ※ output1은 HTS(eFriend Plus) [0891] 계좌 자산비중(결제기준) 화면 아래 테이블과 동일.
+#   자산종류별로 고정된 순서(주식/펀드/채권/... /예수금/합계 등 최대 20개, 21번 계좌는 17개)로 내려온다.
+# ※ 응답 헤더에 tr_cont(F/M/D/E)가 있긴 하지만, 다음 페이지 요청에 필요한 CTX_AREA_FK100/NK100 같은
+#   연속조회 키 파라미터 자체가 Query Parameter에 없다. output1이 최대 20개로 고정된 목록이라
+#   실질적으로 연속조회가 필요 없는 것으로 보고, 페이지네이션 없이 1회 호출로 구현했다.
+# ※ INQR_DVSN_1, BSPR_BF_DT_APLY_YN은 문서상 "공란입력"이 고정값이라 파라미터로 노출하지 않는다.
+
+_TR_ID = "CTRP6548R"
+
+
+# ── DataClass 정의 ──────────────────────────────────────────
+
+@dataclass
+class ResponseBodyOutput1:
+    pchs_amt: Optional[str] = None          # 매입금액
+    evlu_amt: Optional[str] = None          # 평가금액
+    evlu_pfls_amt: Optional[str] = None     # 평가손익금액
+    crdt_lnd_amt: Optional[str] = None      # 신용대출금액
+    real_nass_amt: Optional[str] = None     # 실제순자산금액
+    whol_weit_rt: Optional[str] = None      # 전체비중율
+
+
+@dataclass
+class ResponseBodyOutput2:
+    pchs_amt_smtl: Optional[str] = None                     # 매입금액합계(유가매입금액)
+    nass_tot_amt: Optional[str] = None                       # 순자산총금액
+    loan_amt_smtl: Optional[str] = None                      # 대출금액합계
+    evlu_pfls_amt_smtl: Optional[str] = None                 # 평가손익금액합계
+    evlu_amt_smtl: Optional[str] = None                      # 평가금액합계(유가평가금액)
+    tot_asst_amt: Optional[str] = None                       # 총자산금액
+    tot_lnda_tot_ulst_lnda: Optional[str] = None              # 총대출금액총융자대출금액
+    cma_auto_loan_amt: Optional[str] = None                   # CMA자동대출금액
+    tot_mgln_amt: Optional[str] = None                        # 총담보대출금액
+    stln_evlu_amt: Optional[str] = None                       # 대주평가금액
+    crdt_fncg_amt: Optional[str] = None                       # 신용융자금액
+    ocl_apl_loan_amt: Optional[str] = None                    # OCL_APL대출금액
+    pldg_stup_amt: Optional[str] = None                       # 질권설정금액
+    frcr_evlu_tota: Optional[str] = None                      # 외화평가총액
+    tot_dncl_amt: Optional[str] = None                        # 총예수금액
+    cma_evlu_amt: Optional[str] = None                        # CMA평가금액
+    dncl_amt: Optional[str] = None                            # 예수금액
+    tot_sbst_amt: Optional[str] = None                        # 총대용금액
+    thdt_rcvb_amt: Optional[str] = None                       # 당일미수금액
+    ovrs_stck_evlu_amt1: Optional[str] = None                 # 해외주식평가금액1
+    ovrs_bond_evlu_amt: Optional[str] = None                  # 해외채권평가금액
+    mmf_cma_mgge_loan_amt: Optional[str] = None               # MMF·CMA담보대출금액
+    sbsc_dncl_amt: Optional[str] = None                       # 청약예수금액
+    pbst_sbsc_fnds_loan_use_amt: Optional[str] = None         # 공모주청약자금대출사용금액
+    etpr_crdt_grnt_loan_amt: Optional[str] = None             # 기업신용공여대출금액
+
+
+@dataclass
+class ResponseBody:
+    rt_cd: str                                                        # 성공 실패 여부
+    msg_cd: str                                                       # 응답코드
+    msg1: str                                                         # 응답메세지
+    output1: List[ResponseBodyOutput1] = field(default_factory=list)  # 자산종류별 현황(배열, 최대 20개)
+    output2: ResponseBodyOutput2 = field(default_factory=ResponseBodyOutput2)  # 계좌 자산 요약(단일)
+
+
+# ── 요청 함수 ───────────────────────────────────────────────
+
+def inquire_account_balance() -> ResponseBody:
+    """투자계좌 자산현황을 조회한다. (모의투자 미지원, 실전 계좌 전용)
+
+    HTS(eFriend Plus) [0891] 계좌 자산비중(결제기준) 화면과 동일한 데이터.
+    output1은 주식/펀드/채권/... /예수금/합계 등 자산종류별 현황이 고정된 순서로 최대 20개
+    (21번 계좌는 17개) 내려오고, output2는 계좌 전체의 자산/대출 요약이다.
+
+    Returns:
+        rt_cd/msg_cd/msg1과 자산종류별 현황(output1), 계좌 자산 요약(output2)을 담은 ResponseBody.
+    """
+    token = load_token("real")
+
+    headers = {
+        "content-type": "application/json; charset=utf-8",
+        "authorization": f"Bearer {token}",
+        "appkey": REAL_APPKEY,
+        "appsecret": REAL_APP_SECRET,
+        "tr_id": _TR_ID,
+        "custtype": "P",
+    }
+    params = {
+        "CANO": CANO,
+        "ACNT_PRDT_CD": ACNT_PRDT_CD,
+        "INQR_DVSN_1": "",
+        "BSPR_BF_DT_APLY_YN": "",
+    }
+    response = get_session().get(DOMAIN["real"] + URL, headers=headers, params=params, timeout=10)
+    raw = response.json()
+
+    # 에러 응답(rt_cd != "0")은 output1/output2 키가 없거나 null일 수 있어 안전 파싱.
+    # 문서 표기가 Output1/Output2(대문자)라 실제 JSON 키가 소문자일 가능성을 대비해 둘 다 확인한다.
+    fields1 = set(ResponseBodyOutput1.__dataclass_fields__)
+    raw_output1 = raw.get("output1") or raw.get("Output1") or []
+    output1 = [ResponseBodyOutput1(**{k: v for k, v in item.items() if k in fields1}) for item in raw_output1]
+
+    fields2 = set(ResponseBodyOutput2.__dataclass_fields__)
+    raw_output2 = raw.get("output2") or raw.get("Output2") or {}
+    output2 = ResponseBodyOutput2(**{k: v for k, v in raw_output2.items() if k in fields2})
+
+    return ResponseBody(
+        rt_cd=raw.get("rt_cd", ""),
+        msg_cd=raw.get("msg_cd", ""),
+        msg1=raw.get("msg1", ""),
+        output1=output1,
+        output2=output2,
+    )
+
+
+# ── 실행 ────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    result = inquire_account_balance()
+    if result.rt_cd != "0":
+        print(f"조회 실패: {result.msg_cd} - {result.msg1}")
+    else:
+        for row in result.output1:
+            print(row)
+        print(result.output2)