kiwoom-mcp 0.1.0__tar.gz

kiwoom_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: kiwoom-mcp
+Version: 0.1.0
+Summary: MCP server for kiwoom-cli — 키움증권 REST API 236종을 AI 에이전트에 연결합니다
+Author: Yu Jin
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/gejyn14/kiwoom-plugin
+Project-URL: Repository, https://github.com/gejyn14/kiwoom-plugin
+Project-URL: Issues, https://github.com/gejyn14/kiwoom-plugin/issues
+Project-URL: kiwoom-cli, https://github.com/gejyn14/kiwoom-cli
+Keywords: mcp,model-context-protocol,kiwoom,trading,stock,korea
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: kiwoom-cli>=2.14.0
+Requires-Dist: mcp<2,>=1.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+
+# kiwoom-mcp (server)
+
+이 디렉터리는 [kiwoom-plugin](https://github.com/gejyn14/kiwoom-plugin)의 MCP 서버 본체입니다. 플러그인이 `uvx`로 이 디렉터리를 직접 실행하므로 별도 배포(PyPI/npm)가 없습니다.
+
+kiwoom-cli 236종 API를 MCP 도구로 노출합니다. 안전장치(주문 확인 게이트, dry-run, 멱등키, envelope)는 kiwoom-cli의 것을 그대로 통과시킵니다.
+
+## 단독 실행
+
+```bash
+uvx --from "git+https://github.com/gejyn14/kiwoom-plugin@v0.1.0#subdirectory=server" kiwoom-mcp
+uvx --from "git+https://github.com/gejyn14/kiwoom-plugin@v0.1.0#subdirectory=server" kiwoom-mcp --allow-orders
+```
+
+전송·인증·안전 모델은 상위 [README](../README.md)를 참고하세요.
+
+## 개발
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+ruff check kiwoom_mcp/
+```
+
+## 도구
+
+| 도구 | 설명 |
+|---|---|
+| `kiwoom_describe` | 명령 트리 조회 |
+| `kiwoom_find` | 키워드로 명령·API 검색 |
+| `kiwoom_run` | 임의의 kiwoom-cli 명령 실행 |
+| `kiwoom_stream_snapshot` | 실시간 스트림에서 N개 이벤트 |
+| `kiwoom_order_validate` | 주문 사전점검 (read-only) |
+| `kiwoom_order` | 주문 전송 — `--allow-orders` 시에만 등록 |
+
+## 라이선스
+
+Apache-2.0.

kiwoom_mcp-0.1.0/README.md

@@ -0,0 +1,37 @@
+# kiwoom-mcp (server)
+
+이 디렉터리는 [kiwoom-plugin](https://github.com/gejyn14/kiwoom-plugin)의 MCP 서버 본체입니다. 플러그인이 `uvx`로 이 디렉터리를 직접 실행하므로 별도 배포(PyPI/npm)가 없습니다.
+
+kiwoom-cli 236종 API를 MCP 도구로 노출합니다. 안전장치(주문 확인 게이트, dry-run, 멱등키, envelope)는 kiwoom-cli의 것을 그대로 통과시킵니다.
+
+## 단독 실행
+
+```bash
+uvx --from "git+https://github.com/gejyn14/kiwoom-plugin@v0.1.0#subdirectory=server" kiwoom-mcp
+uvx --from "git+https://github.com/gejyn14/kiwoom-plugin@v0.1.0#subdirectory=server" kiwoom-mcp --allow-orders
+```
+
+전송·인증·안전 모델은 상위 [README](../README.md)를 참고하세요.
+
+## 개발
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+ruff check kiwoom_mcp/
+```
+
+## 도구
+
+| 도구 | 설명 |
+|---|---|
+| `kiwoom_describe` | 명령 트리 조회 |
+| `kiwoom_find` | 키워드로 명령·API 검색 |
+| `kiwoom_run` | 임의의 kiwoom-cli 명령 실행 |
+| `kiwoom_stream_snapshot` | 실시간 스트림에서 N개 이벤트 |
+| `kiwoom_order_validate` | 주문 사전점검 (read-only) |
+| `kiwoom_order` | 주문 전송 — `--allow-orders` 시에만 등록 |
+
+## 라이선스
+
+Apache-2.0.

kiwoom_mcp-0.1.0/kiwoom_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for kiwoom-cli."""
+
+__version__ = "0.1.0"

kiwoom_mcp-0.1.0/kiwoom_mcp/cli.py

@@ -0,0 +1,180 @@
+"""`kiwoom-mcp` 실행 진입점."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+import sys
+from pathlib import Path
+
+from . import __version__
+from .runner import ServeSettings, credentials_available
+
+LOOPBACK_HOSTS = ("127.0.0.1", "::1", "localhost")
+
+
+def _env_or_file(name: str) -> str | None:
+    """NAME 또는 NAME_FILE. 컨테이너 시크릿은 파일로 마운트된다."""
+    direct = os.environ.get(name)
+    path = os.environ.get(f"{name}_FILE")
+    if direct and path:
+        _die(f"{name}와 {name}_FILE이 동시에 설정되었습니다. 하나만 쓰세요.")
+    if direct:
+        return direct.strip() or None
+    if path:
+        try:
+            return Path(path).read_text(encoding="utf-8").strip() or None
+        except OSError as exc:
+            _die(f"{name}_FILE을 읽을 수 없습니다 ({path}): {exc}")
+    return None
+
+
+def _die(message: str) -> None:
+    print(f"kiwoom-mcp: {message}", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def _env_flag(name: str) -> bool:
+    return os.environ.get(name, "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="kiwoom-mcp",
+        description="키움증권 kiwoom-cli를 MCP 서버로 노출합니다.",
+    )
+    parser.add_argument("--version", action="version", version=f"kiwoom-mcp {__version__}")
+    parser.add_argument("--transport", choices=("stdio", "http"), default="stdio",
+                        help="기본 stdio. http는 streamable HTTP.")
+    parser.add_argument("--host", default="127.0.0.1", help="http 바인드 주소 (기본 127.0.0.1)")
+    parser.add_argument("--port", type=int, default=8765, help="http 포트 (기본 8765)")
+    parser.add_argument("--profile", default=os.environ.get("KIWOOM_PROFILE") or None,
+                        help="kiwoom-cli 프로필. 모든 호출에 고정 적용됩니다.")
+    parser.add_argument("--allow-orders", action="store_true",
+                        default=_env_flag("KIWOOM_MCP_ALLOW_ORDERS"),
+                        help="주문 도구를 활성화합니다 (기본: 조회 전용).")
+    parser.add_argument("--allowed-host", action="append", default=[],
+                        help="http Host 헤더 허용 목록에 추가합니다.")
+    return parser
+
+
+def _resolve_http_auth(settings: ServeSettings) -> None:
+    """비루프백 바인드에는 토큰을 강제한다.
+
+    증권 계좌에 닿는 엔드포인트를 네트워크에 인증 없이 여는 모드는 두지 않는다.
+    조회 전용이어도 마찬가지다 — 잔고와 보유종목도 남에게 보일 것은 아니다.
+    """
+    token = _env_or_file("KIWOOM_MCP_AUTH_TOKEN")
+    settings.auth_token = token
+    is_loopback = settings.host in LOOPBACK_HOSTS
+    if not is_loopback and not token:
+        _die(
+            f"--host {settings.host}는 루프백이 아닙니다. KIWOOM_MCP_AUTH_TOKEN "
+            "(또는 _FILE)을 설정하세요. 컨테이너에서는 0.0.0.0 바인드가 정상이며, "
+            "호스트 노출은 -p 127.0.0.1:8765:8765로 제한하세요."
+        )
+    if is_loopback and not token:
+        print("kiwoom-mcp: [경고] 인증 토큰 없이 루프백에 바인드합니다 — "
+              "이 머신의 모든 로컬 프로세스가 호출할 수 있습니다.", file=sys.stderr)
+
+
+def _banner(settings: ServeSettings) -> None:
+    """기동 상태를 stderr로 알린다 (stdout은 stdio 전송이 쓴다)."""
+    from kiwoom_cli import config
+
+    try:
+        env = config.get_domain_key(settings.profile)
+    except Exception:
+        env = "unknown"
+    # 자격증명 출처는 보고하지 않는다: config.appkey_source()가 키체인을 읽고,
+    # 그 읽기가 macOS에서 GUI 승인 창을 띄워 서버를 멈추게 할 수 있다.
+    # env 자격증명 여부만 키체인 없이 확인한다.
+    creds = "환경변수" if credentials_available() else "환경변수 없음 (키체인 또는 KIWOOM_TOKEN 사용)"
+
+    lines = [
+        f"kiwoom-mcp {__version__} — transport={settings.transport}",
+        f"  도메인: {env}" + ("  [실거래]" if env == "prod" else ""),
+        f"  프로필: {settings.profile or '(기본)'}",
+        f"  자격증명: {creds}",
+        f"  주문: {'허용 (--allow-orders)' if settings.allow_orders else '차단 (조회 전용)'}",
+    ]
+    if settings.transport == "http":
+        lines.append(f"  바인드: {settings.host}:{settings.port}  "
+                     f"인증: {'bearer' if settings.auth_token else '없음'}")
+    print("\n".join(lines), file=sys.stderr)
+
+
+def _serve_http(mcp, settings: ServeSettings) -> None:
+    import uvicorn
+    from starlette.responses import JSONResponse
+
+    app = mcp.streamable_http_app()
+    expected = settings.auth_token
+
+    if expected:
+        async def auth_middleware(scope, receive, send):
+            if scope["type"] != "http":
+                await app(scope, receive, send)
+                return
+            headers = dict(scope.get("headers") or [])
+            presented = headers.get(b"authorization", b"").decode()
+            expected_header = f"Bearer {expected}"
+            if not secrets.compare_digest(presented, expected_header):
+                response = JSONResponse(
+                    {"error": "unauthorized"},
+                    status_code=401,
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+                await response(scope, receive, send)
+                return
+            await app(scope, receive, send)
+
+        served = auth_middleware
+    else:
+        served = app
+
+    uvicorn.run(served, host=settings.host, port=settings.port, log_level="info")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    settings = ServeSettings(
+        allow_orders=args.allow_orders,
+        profile=args.profile,
+        transport=args.transport,
+        host=args.host,
+        port=args.port,
+        allowed_hosts=tuple(args.allowed_host),
+    )
+
+    if settings.transport == "http":
+        _resolve_http_auth(settings)
+    elif _env_or_file("KIWOOM_MCP_AUTH_TOKEN"):
+        print("kiwoom-mcp: [알림] stdio 전송에는 인증 개념이 없어 "
+              "KIWOOM_MCP_AUTH_TOKEN을 무시합니다.", file=sys.stderr)
+
+    _banner(settings)
+
+    # 기동 시에는 토큰을 만지지 않는다. auth.load_token()이 키체인을 읽는데,
+    # macOS는 처음 보는 바이너리의 키체인 접근에 GUI 승인 창을 띄우고, 헤드리스
+    # MCP 서버에는 그 창에 답할 사람이 없다 — 서버가 initialize에 응답하지 못하고
+    # 클라이언트는 "Failed to connect"으로 끝난다.
+    #
+    # 토큰은 첫 호출에서 필요할 때 확보한다. runner가 exit 3(AUTH_REQUIRED/
+    # TOKEN_EXPIRED)을 보면 env 자격증명으로 발급을 시도한다. MCP 서버는 빨리
+    # 뜨고 일은 늦게 하는 편이 옳기도 하다.
+    from .server import build_server
+
+    mcp = build_server(settings)
+
+    if settings.transport == "http":
+        _serve_http(mcp, settings)
+    else:
+        mcp.run(transport="stdio")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

kiwoom_mcp-0.1.0/kiwoom_mcp/policy.py

@@ -0,0 +1,151 @@
+"""무엇을 MCP로 실행하게 둘지 분류한다.
+
+argv를 **Click의 파서로** 해석한다. 문자열을 직접 훑으면 `--opt=value`,
+옵션 사이에 끼인 인자, 축약 옵션에서 실제 실행 경로와 분류가 갈릴 수 있다.
+분류기가 "조회"라고 판단한 argv가 실제로는 주문을 보내는 상황을 원리적으로
+막으려면 실행과 같은 해석기를 써야 한다.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+import click
+from kiwoom_cli.api_spec import MUTATION_APIS
+from kiwoom_cli.main import cli
+
+Kind = Literal["ok", "denied", "local_admin", "mutation"]
+
+# 어떤 모드에서도 MCP로 실행하지 않는다.
+#   mcp*  — 서버가 자기 자신을 띄우는 재귀
+#   watch — Rich Live TUI. 터미널을 점유하고 끝나지 않는다
+DENIED_PREFIXES: tuple[tuple[str, ...], ...] = (
+    ("mcp",),
+    ("watch",),
+)
+
+# 로컬 상태를 바꾸는 명령. --allow-orders와 무관하게 차단한다: 서버의 자격증명
+# 수명주기는 서버가 소유한다. 모델이 config.toml을 다시 쓰거나, 토큰을 폐기하거나,
+# 멱등성 원장을 잘라내는 것은 어느 모드에서도 이득이 없다.
+# (config show/profiles, auth status 같은 조회는 통과시킨다.)
+LOCAL_ADMIN_PATHS: tuple[tuple[str, ...], ...] = (
+    ("config", "setup"),
+    ("config", "set"),
+    ("config", "use"),
+    ("config", "prune-ledger"),
+    ("auth", "login"),
+    ("auth", "logout"),
+)
+
+# --allow-orders가 있어야 실행되는 경로.
+MUTATION_PREFIXES: tuple[tuple[str, ...], ...] = (
+    ("order",),
+    ("account", "exchange", "apply"),
+)
+
+# order 하위지만 아무것도 전송하지 않는 read-only 사전점검.
+MUTATION_EXCEPTIONS: tuple[tuple[str, ...], ...] = (
+    ("order", "validate"),
+)
+
+
+@dataclass(frozen=True)
+class Classification:
+    path: tuple[str, ...]
+    kind: Kind
+    detail: str = ""
+
+
+def _starts_with(path: tuple[str, ...], prefix: tuple[str, ...]) -> bool:
+    return path[: len(prefix)] == prefix
+
+
+def _remaining_args(ctx: click.Context) -> list[str]:
+    """Group.parse_args 이후 남은 인자 전부.
+
+    Click의 Group.parse_args는 첫 번째 남은 토큰(= 하위 명령 이름)을 반환값이
+    아니라 protected_args에 넣는다. 반환값만 보면 하위 명령이 통째로 사라져
+    트리를 한 칸도 내려가지 못한다 — 실제로 이 실수로 주문 경로가 조회로
+    분류됐다. 속성 이름은 Click 8.2에서 _protected_args로 바뀌었으므로 둘 다 본다.
+    """
+    # _protected_args를 먼저 본다: Click 8.4의 공개 protected_args는 접근만 해도
+    # DeprecationWarning을 낸다. Click 9에서는 둘 다 없고 ctx.args가 전부 담으므로
+    # 이 함수는 그대로 옳다.
+    protected = getattr(ctx, "_protected_args", None)
+    if protected is None:
+        protected = getattr(ctx, "protected_args", [])
+    return [*protected, *ctx.args]
+
+
+def resolve_path(argv: list[str]) -> tuple[tuple[str, ...], list[str]]:
+    """argv를 Click 트리로 걸어 (명령 경로, 남은 인자)를 돌려준다.
+
+    resilient_parsing=True는 부작용 없이 옵션을 소비한다 — 필수 인자 누락으로
+    죽지 않고, 프롬프트도 뜨지 않는다. 해석할 수 없는 경로는 거기서 멈춘다
+    (그대로 실행하면 CLI 자신의 INVALID_INPUT으로 끝나므로 안전하다).
+    """
+    command: click.Command = cli
+    path: list[str] = []
+    args = list(argv)
+
+    while isinstance(command, click.Group):
+        ctx = click.Context(command, info_name=path[-1] if path else "kiwoom",
+                            resilient_parsing=True)
+        try:
+            command.parse_args(ctx, list(args))
+        except Exception:
+            return tuple(path), args
+        remaining = _remaining_args(ctx)
+        if not remaining:
+            return tuple(path), []
+        name = remaining[0]
+        try:
+            sub = command.get_command(ctx, name)
+        except Exception:
+            sub = None
+        if sub is None:
+            # 알 수 없는 하위 명령 — 여기까지가 경로다
+            return tuple(path), remaining
+        path.append(sub.name or name)
+        command = sub
+        args = remaining[1:]
+
+    return tuple(path), args
+
+
+def _mutation_api_id(path: tuple[str, ...], rest: list[str]) -> str | None:
+    """`kiwoom api <id>` 형태에서 주문성 api_id를 찾는다.
+
+    문자열을 훑지 않고 남은 인자의 첫 위치 인자만 본다. `api list`는 통과.
+    """
+    if path != ("api",):
+        return None
+    for token in rest:
+        if token.startswith("-"):
+            continue
+        return token if token in MUTATION_APIS else None
+    return None
+
+
+def classify_argv(argv: list[str]) -> Classification:
+    path, rest = resolve_path(argv)
+
+    for prefix in DENIED_PREFIXES:
+        if _starts_with(path, prefix):
+            return Classification(path, "denied", f"{'/'.join(prefix)}는 MCP로 실행하지 않습니다")
+
+    if path in LOCAL_ADMIN_PATHS:
+        return Classification(path, "local_admin", "로컬 설정·자격증명 변경은 MCP로 실행하지 않습니다")
+
+    api_id = _mutation_api_id(path, rest)
+    if api_id is not None:
+        return Classification(path, "mutation", f"주문성 API ({api_id})")
+
+    for prefix in MUTATION_PREFIXES:
+        if _starts_with(path, prefix):
+            if any(_starts_with(path, exc) for exc in MUTATION_EXCEPTIONS):
+                break
+            return Classification(path, "mutation", f"{' '.join(path)}는 주문을 전송할 수 있습니다")
+
+    return Classification(path, "ok")