openstem-mcp 0.3.0__tar.gz

openstem_mcp-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+# GitHub에서 릴리스를 만들면 PyPI에 올리고, Claude Desktop 원클릭 설치 파일(.mcpb)을 릴리스에 붙인다.
+# PyPI는 신뢰할 수 있는 게시(토큰 없이 OIDC). 처음 한 번 pypi.org → Account settings → Publishing에서
+# pending publisher를 추가한다:
+#   PyPI Project Name: openstem-mcp / Owner: (GitHub 계정) / Repository: openstem-mcp
+#   Workflow name: publish.yml / Environment name: pypi
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: uv publish --trusted-publishing always
+
+  bundle:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # 릴리스에 파일 올리기
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      # 공식 CLI(npx @anthropic-ai/mcpb)로 검사·묶기. 빌드 스크립트는 표준 라이브러리만 쓴다.
+      - run: uv run --no-project python scripts/build_mcpb.py
+      - run: gh release upload "${{ github.event.release.tag_name }}" dist/*.mcpb
+        env:
+          GH_TOKEN: ${{ github.token }}

openstem_mcp-0.3.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.ruff_cache/

openstem_mcp-0.3.0/CLAUDE.md

@@ -0,0 +1,239 @@
+# openstem-mcp
+
+이름은 가칭. 바꾸면 이 파일, pyproject.toml, README에서 같이 바꿀 것.
+
+## 이 프로젝트가 뭔가
+
+이공계 학습용 유료 AI 앱의 핵심 기능(풀이 검산, 학술 그림 생성, 문서 내보내기)을 이미 Claude·ChatGPT 같은 LLM을 쓰는 사람이 별도 구독 없이 쓰게 해주는 오픈소스 MCP 서버.
+
+## 절대 원칙
+
+1. 서버는 LLM을 호출하지 않는다. 풀이·판단은 사용자의 LLM(호스트)이 하고, 서버는 렌더링·검증만 한다. 운영비 0이 이 프로젝트의 존재 이유다.
+2. 모든 툴은 LLM이 스스로 고칠 수 있게 반환한다. 성공하면 파일 경로와 미리보기 PNG(이미지 콘텐츠)를, 실패하면 짧고 구체적인 에러(라인 번호 포함, 최대 10줄)를 돌려준다. 긴 로그를 통째로 반환하지 않는다.
+3. 임의 코드 실행 툴은 만들지 않는다. 외부 입력(LaTeX, 수식 문자열)은 전부 `sandbox.py`의 서브프로세스 + 타임아웃(기본 20초) 안에서 처리한다. sympy 파싱도 내부적으로 eval을 쓰므로 예외 없다.
+4. 다른 회사 서비스의 이름·로고·UI·출력물은 가져오지 않는다.
+
+## 스택
+
+- Python 3.11+, 패키지 관리 `uv`, 공식 MCP Python SDK(`mcp`, FastMCP 방식)
+- 전송: stdio (사용자 PC에서 로컬 실행, 기본) + streamable HTTP(`--http`, M6: ChatGPT 등 원격 MCP 클라이언트용)
+- 렌더링: `tectonic`(LaTeX 엔진, 외부 바이너리) → PDF → `pymupdf`로 SVG/PNG 변환
+- 의존성: `rdkit`, `sympy`, `numpy`, `matplotlib`, `pymupdf`, `pypandoc_binary`
+- 선택 의존성: `pint`(단위 검사), `antlr4-python3-runtime`(LaTeX 수식 입력 파싱)
+- 결과물 저장: 환경변수 `OPENSTEM_OUTPUT_DIR`, 기본값 `~/OpenSTEM/`
+- tectonic을 못 찾으면 공식 GitHub 릴리스(버전·SHA-256을 코드에 고정)를 받아 캐시 폴더에 설치한다(M6, 원클릭 설치용). 그것도 안 되면 설치 방법을 에러 메시지로 안내
+
+## 폴더 구조
+
+```
+openstem-mcp/
+├── CLAUDE.md
+├── README.md                 # 한국어. 설치 3단계 + 결과 예시 이미지
+├── LICENSE                   # MIT
+├── pyproject.toml            # 실행 명령: openstem-mcp = openstem.server:main
+├── src/openstem/
+│   ├── server.py             # FastMCP 엔트리. 툴·프롬프트·리소스 등록만
+│   ├── tools/
+│   │   ├── tikz.py
+│   │   ├── molecule.py
+│   │   ├── plot.py
+│   │   ├── verify.py
+│   │   ├── units.py          # check_units
+│   │   ├── plotdata.py       # plot_data
+│   │   ├── documents.py      # read_document(자료 폴더만)
+│   │   ├── templates.py      # get_template·리소스
+│   │   ├── lms.py            # lms 툴(읽기 전용)
+│   │   └── export.py
+│   ├── lms/                  # LMS 연결: client.py(설정·HTTP·토큰 보호), canvas.py, moodle.py, schools.py(학교 목록), feed.py·ical.py(캘린더 구독), common.py
+│   ├── remote.py             # HTTP 모드(비밀 키 문지기, cloudflared 터널)
+│   ├── render/
+│   │   ├── latex.py          # tectonic 호출 + 로그에서 에러 줄 추출
+│   │   ├── tectonic_setup.py # tectonic 자동 설치(버전·SHA-256 고정)
+│   │   ├── convert.py        # PDF → SVG/PNG (pymupdf, 작업자 안에서만 쓴다)
+│   │   ├── pages.py          # 변환을 작업자에게 맡기는 서버 쪽 함수
+│   │   ├── tabular.lua       # 치트시트 표를 tabular로 바꾸는 pandoc 필터
+│   │   ├── exam.lua          # 시험지 배치(풀이 공간, 해설 새 쪽)
+│   │   ├── flashcards.lua    # 플래시카드 배치(양면 인쇄)
+│   │   └── fonts.py          # 한글 글꼴 찾기(matplotlib·분자 범례용)
+│   ├── workers/              # sandbox.run_python으로만 도는 작업자(서버에서 import 안 함)
+│   │   ├── molecule.py       # RDKit 파싱·검사·그리기
+│   │   ├── plot.py           # sympy 파싱 → numpy → matplotlib, 특이점 분석
+│   │   ├── verify.py         # verify_math 계산·판정(시간 예산 안에서)
+│   │   ├── units.py          # pint 차원 분석·단위 변환
+│   │   ├── plotdata.py       # 측정 데이터 그래프·맞춤
+│   │   ├── documents.py      # PDF·HWP·HWPX·docx 등에서 글자 뽑기
+│   │   └── convert.py        # PDF·SVG 변환(시간 제한, 크기 제한)
+│   ├── mathexpr.py           # 수식 문자열 글자 검사(서버) + sympy 파싱(작업자)
+│   ├── texcheck.py           # TeX 코드 안전 검사(파일 접근·이름 조립 차단)
+│   ├── sandbox.py            # 서브프로세스 + 타임아웃
+│   ├── output.py             # 저장 경로, 파일명 규칙
+│   └── prompts/              # solve, figure, cheatsheet, exam, slides, flashcards, lab_report
+├── packaging/mcpb/           # Claude Desktop 확장(.mcpb) manifest 틀·launch.py·아이콘
+├── scripts/                  # build_mcpb.py(원클릭 설치 파일), register_claude_desktop.py
+├── templates/                # 검증된 TikZ 예제 (리소스로 노출)
+│   ├── circuits/
+│   ├── physics/
+│   ├── math/
+│   └── diagrams/
+├── tests/
+│   ├── cases/                # 입력 → 기대 결과 (yaml)
+│   └── test_*.py
+└── examples/                 # README용 결과물 이미지
+```
+
+## 툴 명세
+
+### render_tikz (M1)
+
+- 입력: `code`(tikzpicture 환경 또는 standalone 문서 전체), `packages`(허용목록: tikz, circuitikz, pgfplots, chemfig, siunitx, amsmath, amssymb), `tikz_libraries`(예: arrows.meta, calc, positioning), `name`(선택)
+- 처리: standalone 템플릿에 감싸기 → tectonic 컴파일(shell-escape 끔) → PDF → SVG + PNG(200dpi)
+- 반환: `ok`, `svg_path`, `pdf_path`, 미리보기 이미지. 실패하면 `errors`(로그에서 `!` 줄과 `l.<번호>` 줄만)
+- 허용목록 밖 패키지는 컴파일 전에 거절하고 허용목록을 알려준다
+
+### render_molecule (M2)
+
+- 입력: `smiles`, `kind`(molecule | reaction), `legend`(선택), `show_atom_numbers`(기본 false)
+- 처리: RDKit 파싱·sanitize → SVG/PNG
+- 반환: 경로, 미리보기, 분자식·분자량(LLM이 맞는 분자인지 스스로 확인하는 용도). 실패하면 어느 원자에서 깨졌는지
+
+### plot_function (M2)
+
+- 입력: `series`([{expr: "sin(x)*exp(-x/5)", label?}]), `x_range`, `y_range?`, `title?`, `x_label?`, `y_label?`, `points?`([{x: [], y: [], label?}])
+- 처리: sympy 파싱 → lambdify → matplotlib. 코드 문자열을 실행하는 방식이 아님
+- 반환: 경로, 미리보기, 특이점·정의역 밖 구간 경고
+
+### verify_math (M3)
+
+- 입력: `op`(equal | simplify | solve | diff | integrate | limit | evaluate), `expr`, `against?`, `var?`, `point?`(limit용), `latex?`(true면 LaTeX로 파싱)
+- 입력 문법: 기본은 sympy 문법(`x**2`, `sqrt(x)`)
+- 반환: 결과(평문 + LaTeX). `equal`이면 `matches`(true | false | unknown). 기호 판정이 안 되면 무작위 점 5개에서 수치 비교한 결과도 같이
+
+### export_document (M4, M5 확장)
+
+- 입력: `markdown`(수식은 `$...$`, 그림은 앞서 만든 파일 경로를 이미지 문법으로), `format`(pdf | docx | pptx), `title?`, `layout`(document | cheatsheet | exam | flashcards), `name?`
+- 처리: pypandoc_binary 사용. PDF는 tectonic으로 컴파일. docx·pptx에는 SVG 대신 PNG(300dpi)를 넣는다. pptx는 `##` 하나가 슬라이드 한 장, `::: notes`는 발표자 노트
+- 배치: exam = 문제마다 풀이 공간 + `# 정답과 해설`(영어 문서는 `# Answers`도 됨)부터 새 쪽(pdf·docx), flashcards = 2열 표(앞면|뒷면) → 오려 쓰는 카드 PDF(양면 인쇄용) + 암기 앱 가져오기용 tsv(pdf 전용)
+- 반환: 파일 경로, pdf면 첫 쪽 미리보기와 `pages`, pptx면 `slides`, exam이면 `problems`·`answer_page`, flashcards면 `cards`·`tsv_path`
+
+### plot_data (M5)
+
+- 입력: `series`([{x, y, yerr?, xerr?, label?}]) 또는 `table`(CSV·탭·마크다운 표 텍스트, 열 이름으로 고름), `fit`(none | linear | poly2 | poly3 | exponential | power | log), 축 이름·제목, 로그 축
+- 처리: numpy만으로 맞춤(오차 막대가 있으면 1/σ² 가중), 작업자 안에서 matplotlib
+- 반환: svg·png·pdf 경로, 미리보기, 맞춤 식(± 표준오차), R², 경고(점이 모자람, 3σ 밖 점)
+
+### check_units (M5)
+
+- pint로 차원 분석. 식의 결과 단위가 기대 단위와 같은지(`expr`, `units` 변수별 단위, `expect`), 어긋나면 어느 차원이 다른지 설명. 값 변환(`value` "72 km/h", `to` "m/s")
+- 덧셈 항의 차원이 다르거나 sin·exp·log 안에 차원이 있으면 알린다
+
+### read_document (M5)
+
+- 입력: `path?`(자료 폴더 기준 이름. 비우면 파일 목록), `pages?`(PDF "1-3,7"), `mode`(text | images), `part`(긴 글 묶음 번호)
+- 처리: 자료 폴더(`OPENSTEM_INPUT_DIR`, 기본 `~/OpenSTEM/자료`)와 결과물 폴더 안 파일만 연다. PDF(pymupdf), HWP 5.x(olefile, 문단 레코드), HWPX(zip XML), docx·pptx·xlsx·odt(pandoc), txt·md·csv, png·jpg. 해석은 작업자에서
+- 반환: 글자(3만 자씩 part로), PDF 쪽 수와 스캔본 의심 쪽, images면 쪽 그림 최대 4장
+
+### lms (M6)
+
+- 학교 LMS(Canvas 계열: LearningX 등, Moodle 계열: Coursemos 등)를 읽기 전용으로 연결한다. 제출·글쓰기는 하지 않는다
+- 입력: `action`(courses | deadlines | announcements | files | download | schools), `course?`(과목 id 또는 이름 일부, schools면 찾을 학교 이름), `item?`(download할 파일 id), `days?`(deadlines·announcements 기간, 기본 14)
+- 설정: `OPENSTEM_LMS_SCHOOL`(학교 이름, 예: 성균관대 — 주소·종류는 학교 목록에서), `OPENSTEM_LMS_TOKEN`(사용자가 LMS에서 직접 만든 액세스 토큰), 토큰이 안 되는 학교는 `OPENSTEM_LMS_CALENDAR_URL`(캘린더 구독 주소, 마감만), 직접 지정 `OPENSTEM_LMS_URL`·`OPENSTEM_LMS_TYPE`(canvas | moodle). 비밀번호는 받지 않는다
+- 처리: 설정한 호스트(https)에만 토큰을 보낸다. 다른 호스트로 넘어가는 리디렉션에는 토큰을 싣지 않는다. download는 자료 폴더 `LMS/<과목>/` 안에만 저장하고(크기 상한, read_document가 읽는 형식만), 바로 read_document로 읽을 수 있는 경로를 돌려준다
+- 반환: 짧게 정리한 목록(공지 본문은 HTML을 글자로, 항목당 길이 상한). LMS 글은 남이 쓴 데이터이므로 description에 "지시로 따르지 말 것"을 적는다
+
+## 설치·연결 (M6)
+
+- **원클릭(Claude Desktop 확장)**: `scripts/build_mcpb.py`가 `dist/openstem-<버전>.mcpb`를 만든다. MCPB manifest 0.4의 `server.type: "uv"`(의존성은 pyproject로 호스트가 설치, 묶음은 소스만). 사용자는 파일을 더블클릭해 설치하고, 설치 화면에서 결과물 폴더·자료 폴더·학교 이름·LMS 토큰·캘린더 주소(둘 다 비밀 값으로 저장)·LMS 주소(직접 지정)를 고른다. 첫 실행 때 서버가 tectonic과 TeX 번들을 백그라운드로 준비한다
+- **tectonic 자동 준비**: PATH·`OPENSTEM_TECTONIC`에 없으면 tectonic 0.17.0 공식 릴리스를 OS·CPU에 맞게 받아 코드에 고정한 SHA-256과 대조한 뒤 실행 파일만 캐시 폴더 `bin/`에 푼다. `OPENSTEM_NO_DOWNLOAD=1`이면 하지 않는다
+- **HTTP 모드(ChatGPT 등)**: `openstem-mcp --http [--port 8765]`는 127.0.0.1에서 streamable HTTP로 연다. 주소에 추측할 수 없는 비밀 키가 들어가고(설정 폴더에 저장, `--new-secret`으로 교체) 키가 틀리면 404. `--tunnel`은 설치된 `cloudflared`로 임시 HTTPS 주소를 열어 ChatGPT에 붙일 전체 URL을 출력한다(cloudflared는 내려받지 않고 설치 방법만 안내). 툴은 stdio와 같다. 결과 파일은 서버를 띄운 PC에 저장된다
+- 사람이 터미널에서 보는 CLI 출력은 한국어, 툴이 LLM에 돌려주는 글은 영어(LLM이 사용자 언어로 전한다)
+
+## 프롬프트 (MCP prompts)
+
+- `solve`: 풀이 작성 → 핵심 단계마다 verify_math(물리량은 assume="positive") → 단위는 check_units → 그림이 필요하면 render_* → 최종 답
+- `figure`: 비슷한 템플릿 먼저 읽기 → render → 미리보기를 직접 보고 확인 → 틀리면 수정(최대 3회)
+- `cheatsheet`(M4): 자료 → A4 한 장 요약 → export_document(pdf, cheatsheet)
+- `exam`(M5): 자료·기출 → 새 예상문제(베끼지 않음) → 풀고 verify_math·check_units로 답 검산 → export_document(exam)
+- `slides`(M5): 자료 → 슬라이드 구성 → 그림 → export_document(pptx)
+- `flashcards`(M5): 자료 → 정의·공식 카드 → export_document(flashcards)
+- `lab_report`(M5): 측정 데이터 → plot_data(맞춤·오차 막대) → check_units → 목적·이론·방법·결과·고찰·결론 → export_document(docx). 데이터를 지어내지 않는다
+- 자료를 바탕으로 하는 프롬프트는 파일이면 read_document로 읽는다
+
+## 리소스 (MCP resources)
+
+- `template://{category}/{name}`: templates/ 아래 검증된 예제를 노출한다. 호스트 LLM이 처음부터 쓰는 것보다 예제를 고쳐 쓰는 쪽이 정확도가 훨씬 높다.
+- 최소 개수: 회로 10, 물리(자유물체도·벡터) 10, 수학(그래프·기하) 10, 다이어그램(순서도·블록도·상태도 등) 10
+
+## 마일스톤
+
+- M1: 서버 뼈대 + render_tikz + figure 프롬프트 + 회로 템플릿 5개. 완료 기준: Claude Desktop에서 "RC 직렬회로 그려줘" → SVG 저장 + 채팅에 미리보기
+- M2: render_molecule, plot_function, 템플릿 30개
+- M3: verify_math, solve 프롬프트, tests/cases 20개
+- M4: export_document, cheatsheet, 한국어 README, PyPI 배포(`uvx openstem-mcp`로 바로 실행), GitHub 공개(MIT)
+- M5(0.2.0): 대학 전공 계산(verify_math: 미분방정식·행렬·라플라스·급수·합·부등식·확률분포), check_units, plot_data, read_document(PDF·한글·워드·파워포인트), export_document pptx·시험지·플래시카드, exam·slides·flashcards·lab_report 프롬프트, 다이어그램 템플릿 10개
+- M6(0.3.0): 원클릭 설치(.mcpb + tectonic 자동 준비), HTTP 모드(ChatGPT 연결), lms 툴(Canvas·Moodle 읽기 전용). 완료 기준: .mcpb를 새 폴더에 풀어 manifest의 명령 그대로 띄우면 모든 툴이 되고, HTTP 모드에 MCP 클라이언트로 붙어 툴을 부르고, 가짜 Canvas·Moodle 서버로 lms의 모든 action이 통과
+
+## 테스트
+
+- 툴을 하나 만들 때마다 `tests/`에 케이스를 추가하고, `uv run pytest`가 통과해야 다음 단계로 간다
+- `templates/`의 모든 예제는 컴파일 스모크 테스트를 돌린다
+- 수동 테스트: MCP Inspector (`npx @modelcontextprotocol/inspector uv run openstem-mcp`)
+
+## 설치 예시 (README에 그대로 넣기)
+
+Claude Desktop (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "openstem": { "command": "uvx", "args": ["openstem-mcp"] }
+  }
+}
+```
+
+Claude Code:
+
+```
+claude mcp add openstem -- uvx openstem-mcp
+```
+
+## 작업 방식 (Claude Code에게)
+
+- 마일스톤 순서대로, 한 번에 하나씩 진행한다.
+- 툴 description은 호스트 LLM이 읽는 문서다. 언제 쓰는지, 입력 예시 1개, 실패하면 어떻게 고치는지를 꼭 넣는다.
+- 사용자는 코드를 직접 읽지 않는다. 단계가 끝날 때마다 무엇이 됐고 어떻게 확인하는지를 한국어 3줄로 요약한다.
+
+## 구현 메모 (명세를 코드로 옮기며 정한 것)
+
+- **mcp 2.x**: FastMCP는 `mcp.server.mcpserver.MCPServer`로 이름이 바뀌었다(데코레이터 방식은 같음). 툴은 MCP를 모르고 `tools.ToolResult`만 돌려주고, `server.py`가 `CallToolResult`(텍스트 JSON + PNG 이미지, 실패면 `is_error`)로 바꾼다.
+- **tectonic 첫 실행**: TeX 번들을 받느라 약 4분 걸린다(캐시 후 3~6초). 서버 시작 때 캐시 표시 파일이 없으면 백그라운드로 준비하고, 그동안 render_tikz는 최대 40초 기다린 뒤 "준비 중, 잠시 후 다시" 에러를 돌려준다. `openstem-mcp --warmup`으로 미리 받을 수 있다. 표시 파일: `%LOCALAPPDATA%\openstem\warm-<버전>`(macOS `~/Library/Caches/openstem`, Linux `~/.cache/openstem`).
+- **보안(TeX)**: tectonic `--untrusted`는 shell-escape만 끈다. TeX 코드는 여전히 절대 경로·상위 폴더 파일을 읽고 쓸 수 있다(2026-11 점검에서 `\csname`·`^^` 표기로 단어 차단 목록을 우회해 임의 파일을 덮어쓰고 읽는 것을 실제로 재현). 그래서 `texcheck.py`가 컴파일 전에 코드를 TeX처럼 토큰으로 나눠 (1) 이름을 조립하는 수단(`\csname`, `^^`, `\scantokens`, catcode·`\makeatletter`·`\ExplSyntaxOn`, 허용 목록 밖 `\begin{이름}`, `\UseName`)과 (2) 파일·외부 명령(`\input`·`\openout`·`\write`·`\special`·`\font`·`\XeTeX*`·`\pgfimage`·`\includegraphics` 등, `table|file|graphics {`)을 막는다. (1)이 막혀 있으면 (2)는 이름 그대로 써야만 쓸 수 있어 빠짐없이 잡힌다. 명령 이름은 ASCII 글자만 이어 읽어 XeTeX보다 짧게 읽는다(덜 막지는 않고 더 막을 수만 있다). pgfplots `table {데이터}`도 파일 이름과 구분할 수 없어 막고 `coordinates`를 안내한다. 라이브러리 `external`은 금지. 남은 한계: 운영체제 수준 격리(쓰기 금지 토큰 등)는 아직 없다. 작업은 매번 빈 임시 폴더에서 한다.
+- **한글**: code에 한글이 있으면 서버가 `xetexko` + 은글꼴(UnBatang/UnDotum, tectonic 번들 내장)을 넣는다. 허용목록과 별개다.
+- **패키지·라이브러리 자동 감지**: circuitikz·pgfplots·chemfig·siunitx는 코드에서 쓰이면 자동으로 넣는다. TikZ 라이브러리도 문법을 보고 넣는다(`($`→calc, `Stealth`→arrows.meta, `right=of`→positioning, `coil`→decorations.pathmorphing 등, `tikz._LIBRARY_DETECT`). 라이브러리를 한꺼번에 다 넣으면 그림마다 1.5~2.5초가 늘어 감지 방식을 쓴다. 환경 없이 `\draw`만 오면 tikzpicture로 감싼다. `$...$` 안 한글은 `\text{}`로 감싼다(수식 글꼴에 한글이 없어 빠진다).
+- **줄 번호**: 에러의 `l.<번호>`와 메시지 속 `input line N`은 생성 문서가 아니라 사용자가 보낸 code 기준으로 바꾼다. 머리말·꼬리말에서 난 에러는 그렇게 표시한다.
+- **get_template 툴**: Claude Desktop·ChatGPT 등은 LLM이 MCP 리소스를 스스로 읽지 못해서, 리소스와 같은 내용을 툴로도 노출한다. 템플릿 파일 머리의 `% title:`, `% description:`, `% packages:`, `% libraries:` 주석이 목록·인자 안내에 쓰인다.
+- **Claude Desktop 등록**: 실행 중인 Claude Desktop은 `claude_desktop_config.json`을 메모리 사본으로 통째로 다시 써서, 앱이 켜져 있을 때 고친 내용은 사라진다. 개발 버전 등록은 앱을 완전히 끈 뒤 `python scripts/register_claude_desktop.py`(앱이 켜져 있으면 거절한다). Claude Code 세션은 앱의 자식 프로세스라 앱을 끄면 같이 죽으므로 이 단계는 사용자가 터미널에서 한다.
+- **패키징**: 저장소 루트 `templates/`는 wheel 안 `openstem/templates`로 들어간다(pyproject `force-include`).
+- **파이썬 작업자(M2)**: sympy·RDKit 처리는 `sandbox.run_python("openstem.workers.<이름>", payload, cwd)`로 한다. `python -I -m`(격리 모드: 현재 폴더·PYTHON* 환경변수 무시)로 빈 임시 폴더에서 돌고, payload는 stdin JSON, 결과는 stdout 마지막 줄 JSON(`workers.serve()`가 규약을 맞춘다). 작업자가 만든 파일은 서버가 `output.new_stem`으로 옮긴다. 한 번 부를 때 3~5초(라이브러리 import 포함).
+- **수식 입력**: `mathexpr.check()`가 허용한 이름(함수 목록·`pi`·소문자 `e`·변수)·숫자(반각 0-9만)·연산자만 통과시키고, 통과한 토큰만 이어 붙여 `parse_expr`에 넘긴다(`__builtins__` 비움). 그래서 `_`, `.`, 문자열, 속성 접근은 eval까지 가지 못한다. `^`는 거듭제곱, `2x`는 곱하기로 읽는다. 대문자 `E`는 상수가 아니라 변수다(에너지·전기장). M3 verify_math도 이 모듈을 쓴다.
+- **plot_function 특이점**: sympy `singularities`(정확한 값, 4초 안에 못 끝내면 생략)로 후보를 얻고 수치로 종류를 가른다(발산이면 선을 끊고, 0/0 같은 구멍은 이어 그림, 양쪽 값이 다른 점프는 끊고 왼쪽→오른쪽 값을 경고). 그 밖에 2001점 격자에서 NaN 구간(정의역 밖, 이분법으로 경계를 좁힘)·무한대·큰 값 차이(이분법으로 좁혀 줄지 않으면 불연속)를 찾는다. 값이 발산하면 y축을 5~95% 분위수 기준으로 자동으로 자른다.
+- **한글 글꼴(matplotlib·분자 범례)**: 시스템 글꼴(맑은 고딕 등)을 먼저 찾고, 없으면 pymupdf 내장 Droid Sans Fallback을 쓴다. matplotlib에서는 한글 글꼴을 `font.family` 맨 앞에 둬야 한다(`변위 $y$`처럼 수식이 섞인 글은 글자별 대체 없이 첫 글꼴만 쓴다). RDKit의 글자 렌더러는 한글을 못 그려서, 분자는 RDKit SVG → pymupdf로 PDF 한 쪽에 옮기고(여백을 잘라 냄) 범례는 pymupdf가 쓴 뒤, render_tikz와 같은 변환 작업자로 SVG·PNG를 만든다.
+- **변환 작업자**: PDF·SVG → SVG/PNG/PDF 변환(pymupdf)은 `workers/convert.py`에서 하고, 서버는 `render/pages.py`로 맡기기만 한다(서버는 pymupdf를 import하지 않는다). 아주 촘촘한 패턴 그림은 렌더링에 수십 초가 걸리며 GIL을 쥐어 서버 전체가 멈췄다(점검에서 재현). 한 변 200cm가 넘는 그림은 변환 전에 거절한다. 작업자가 결과에 적은 파일 이름은 `sandbox.worker_file`로 작업 폴더 안인지 확인한 뒤 쓴다.
+- **plot_function PDF**: 작업자가 `plot.pdf`도 저장해 결과에 `pdf_path`를 준다. MuPDF는 SVG `clip-path`를 무시해서, export_document가 SVG를 변환하면 곡선이 축 밖으로 튀어나왔다. export는 같은 이름 PDF를 먼저 쓴다. `x_range`·`y_range`에 `"2*pi"` 같은 상수식 문자열을 받는다(서버는 `mathexpr.check(s, ())`, 변환은 작업자).
+- **실행 중인 서버와 uv sync**: Claude Desktop·Claude Code가 `uv run openstem-mcp`로 서버를 띄워 두면 `.venv\Scripts\openstem-mcp.exe`가 잠겨 `uv sync`/`uv run`이 실패한다(프로젝트를 다시 설치하려다). 그동안은 `uv run --no-sync pytest`를 쓰거나, 의존성만 바꿀 때는 `uv sync --inexact --no-install-project`. 서버를 끄면 평소대로 된다.
+- **작업자 미리 띄우기**: sympy import만 프로세스마다 약 5초라, `sandbox.run_python`은 모듈마다 작업자를 하나씩 미리 띄워 둔다(import를 끝내고 stdin을 기다림). 요청이 오면 그 작업자를 쓰고 바로 다음 것을 띄운다. 요청 하나에 프로세스 하나라는 격리는 그대로다. 미리 띄운 작업자는 시스템 임시 폴더에서 시작하므로 payload의 `_cwd`로 옮겨 가서 일한다(`workers.serve()`). 서버가 끝나면 stdin이 닫혀 스스로 끝난다. 끄려면 `sandbox.SPARES_ENABLED = False`.
+- **verify_math(M3)**: `mathexpr`의 변수 자동 감지 모드(`variables=None`)를 쓴다. 이름은 영숫자 10자 이하(밑줄·파이썬 예약어·sympy 내부 이름 불가), 늘 괄호 앞에만 나오는 이름(`f(x)`)은 정의 안 된 함수라 거절한다. 변수는 실수로 본다(`sqrt(x**2)` → `Abs(x)`). equal은 무작위 점 5개 수치 비교를 먼저 하고(반례가 있으면 바로 false, 상수 차이면 적분상수라고 알림), 반례가 없을 때만 `simplify(a-b)==0` → `a.equals(b)` 순서로 기호 판정한다. 기호 계산은 작업자 안에서 `Budget`(12초) 스레드로 돌려 시간이 넘으면 끊는다. solve는 `solveset`(실수)으로 풀고, 해가 없으면 복소수 해, 주기 해면 일반해 + [-2π, 2π] 안의 해, 못 풀면 [-10, 10] 수치 근을 준다. LaTeX 입력(`latex=true`)은 선택 의존성 `antlr4-python3-runtime==4.11.*`(extra `latex`, dev 그룹에도 있음)이 있어야 하고, 읽은 뒤 `e`·`\pi`를 상수로 바꾸고 `doit()`한다. 정의 안 된 함수(`a*b*s(x)`처럼 sympy 문법을 LaTeX로 잘못 읽은 흔적)가 나오면 거절하고, integrate·diff·limit에 `\int`·`\lim`·`\frac{d`가 든 입력도 거절한다.
+- **verify_math 보완(2026-11 점검 후)**: `assume="positive"`면 변수를 모두 양수로 본다(물리량: `sqrt(m**2*v**2)=m*v`). equal이 false(반례 없음)나 unknown이면 양수 가정으로 다시 보고 "변수가 모두 양수면 같다"고 알린다. 소수는 비교 전에 유리수로 바꾼다(`0.1x+0.2x = 0.3x`). 수치 비교 허용 오차는 진짜 상대 오차(아주 작은 값 근처만 절대 하한). solve는 다른 문자가 남으면 `sp.solve`로 해 목록을 주고("다른 문자 값에 따라 실수일 때의 해"), Intersection·ConditionSet을 풀어 쓰며, "n은 정수"는 진짜 ImageSet일 때만 말한다. 다른 문자가 남으면 수치 근 찾기를 하지 않는다. 변수 없는 equal은 적분상수 대신 라디안 안내를 붙인다. 부정적분 log는 ln|x|로 읽으라고 알리고, 발산하는 정적분은 "발산"이라고 답한다. 반례가 이미 있으면 뒤따르는 기호 계산은 `Budget.run(cap=…)`으로 2~3초만 쓴다.
+- **준비 신호와 타임아웃**: 작업자는 import를 마치면 stdout에 `OPENSTEM-READY`를 쓴다(`workers.serve()`). `sandbox.run_python`은 그 신호를 `IMPORT_TIMEOUT`(180초)까지 기다린 뒤 payload를 보내고, 그때부터 `timeout`(기본 20초)을 센다. 처음 설치한 환경은 .pyc 만들기·matplotlib 글꼴 캐시 때문에 import만 수십 초가 걸려서, 이걸 입력 처리 시간에 넣으면 첫 호출이 늘 시간 초과가 났다. 무거운 import는 신호 전에 끝내야 한다(plot 작업자는 `_preload()`). 신호를 이미 읽은 예비 작업자는 `proc.openstem_ready`로 표시한다.
+- **준비(warmup) 표시**: 표시 파일 이름에 버전이 들어간다(`warm-<버전>`). 새 버전을 처음 띄우면 TeX 준비(tikz 문서 + export 보통·치트시트 문서)와 파이썬 작업자 준비(`sandbox.warm_workers`)를 백그라운드로 다시 한다. `openstem-mcp --warmup`도 둘 다 한다.
+- **export_document(M4)**: pandoc(pypandoc_binary, 3.9)으로 마크다운을 먼저 문서 구조(JSON, `--sandbox`)로 읽고, 구조 안의 모든 `Math`(texcheck + 중괄호 짝 + 한글 `\text{}` 감싸기)와 `Image`(결과물 폴더 안 파일만, URL·`data:` 등 거절, `%20` 풀어 읽기)를 검사·교체한 뒤 그 구조를 docx나 standalone LaTeX로 바꾼다. 처음엔 정규식으로 그림을 찾았는데 참조식 그림(`![a][r]`)·중첩 대괄호·앞 공백으로 우회되고 pandoc이 URL 그림을 실제로 요청했으며(점검에서 재현), 정규식이 느려지는 입력도 있었다. 입력 형식은 `markdown-raw_tex-raw_html-raw_attribute-yaml_metadata_block`(마크다운 속 `\명령`은 글자로 나오고, YAML 머리말로 제목에 수식을 넣는 길도 막힌다). 경로에 공백이 있는 그림(Windows 사용자 이름)은 `<경로>`로 감싸 준다. PDF는 `latex.compile_tex(..., reruns=0)`(상호 참조가 없어 한 번이면 된다, 두 번 돌리면 두 배 느림)로 만든다. 그림은 작업 폴더에 `imgN`으로 옮겨 넣는다: docx는 같은 이름 PDF > SVG > 원본 순으로 300dpi PNG(dpi 정보 기록), pdf는 같은 이름 PDF(벡터) > SVG→PDF. 머리말: `float`로 그림을 그 자리에 고정, 한글이 있으면 `HANGUL_SETUP`(굵은 은글꼴 포함) + 그림/표 이름 한글화. cheatsheet는 extarticle 9pt 두 단 + titlesec·enumitem으로 간격을 줄이고 제목을 두 단에 걸쳐 한 줄로 둔다. pandoc은 표를 longtable로 쓰는데 두 단에서는 컴파일이 실패해서, 치트시트는 Lua 필터(`render/tabular.lua`)로 표를 tabular로 바꾼다. 결과의 `pages`가 1보다 크면 경고해서 LLM이 줄이게 한다. 첫 쪽 미리보기도 변환 작업자(`pages.preview`).
+- **의존성 메모**: pymupdf는 `>=1.24,<2`(2.0은 인텔 맥 wheel이 없고 onnxruntime 등을 끌고 온다). mcp는 `<3`, 타입은 `mcp.types`에서 가져온다. 버전은 `src/openstem/__init__.py`의 `__version__` 한 곳(hatch dynamic version). 결과물 파일 이름은 `output.new_stem`이 프로세스 안에서 나눠 준 stem을 기억해 같은 초·같은 이름의 동시 호출이 서로 덮어쓰지 않게 한다.
+- **배포(M4)**: wheel에 templates·prompts·workers가 다 들어가는지, `uvx --from <wheel> openstem-mcp`로 새 환경에서 띄워 6개 툴이 모두 되는지 확인했다. PyPI 이름 `openstem-mcp`는 비어 있다(2026-11-02 확인). 배포는 GitHub Actions의 신뢰할 수 있는 게시(`.github/workflows/publish.yml`, 릴리스를 만들면 `uv build` → `uv publish`)로 한다. PyPI 쪽 설정(pending publisher)은 사용자가 pypi.org에서 직접 한다.
+- **tectonic 자동 준비(M6, M4의 "하지 않음"을 뒤집음)**: M4에서는 공급망 위험 때문에 자동 다운로드를 하지 않기로 했지만, 원클릭 설치에는 꼭 필요해서 버전·파일 이름·크기·SHA-256을 코드에 고정해 받는 것으로 바꿨다(받는 파일이 바뀌면 해시가 달라 거절된다). `render/tectonic_setup.py`. 찾는 순서 `OPENSTEM_TECTONIC` → PATH → 캐시 폴더 `bin/`(`latex.tectonic_bin_dir()`). 없으면 tectonic 0.17.0 공식 릴리스(Windows x86_64 msvc zip, macOS arm64·x86_64, Linux x86_64·aarch64 musl tar.gz)를 받는다. 해시는 GitHub 릴리스 API digest(버전을 올릴 때 `gh api …/releases/tags/tectonic@<버전>`으로 다시 받는다). 캐시 폴더 안 임시 파일로 60 MB 상한·https 리디렉션만·전체 5분 안에 받고, 해시가 맞아야 열고, 절대 경로·드라이브 문자·`..` 이름이 하나라도 있으면 거절하고, 실행 파일 하나(일반 파일)만 꺼내 `--version`으로 실행되는지 본 뒤 원자적으로 이름을 바꾼다. 스레드 잠금 + 파일 잠금(msvcrt/fcntl)으로 서버 여러 개·`--warmup`이 동시에 받지 않는다. `OPENSTEM_NO_DOWNLOAD=1`이거나 릴리스가 없는 OS·CPU(Windows ARM 등)면 받지 않고 설치 안내를 돌려준다. 서버 시작 때 `BACKGROUND_WARMUP`이 tectonic → TeX 번들 순서로 준비하고(그동안 툴은 "준비 중"), `--warmup`도 먼저 받는다. 자동 설치가 실패하면(네트워크가 늦게 붙는 경우) 30초 뒤 렌더링 요청이 올 때 다시 건다. 진행 글은 stderr에 UTF-8로 쓴다(한국어 Windows 파이프는 cp949라 호스트 로그가 깨졌다). Windows msvc 빌드는 CRT 정적 링크라 VC 런타임이 필요 없다(가져오는 DLL 확인). macOS·Linux 바이너리는 아직 실제로 돌려 보지 못했다.
+- **원클릭 설치 묶음(.mcpb, M6)**: `scripts/build_mcpb.py` → `dist/openstem-<버전>.mcpb`. `packaging/mcpb/manifest.template.json`에 버전(`__init__.py`)·저자·라이선스·주소·requires-python(pyproject)을 채우고, 저장소와 같은 배치(pyproject·uv.lock·README·LICENSE·src/openstem·templates + launch.py·icon.png)로 모아 공식 CLI(`npx -y @anthropic-ai/mcpb validate`·`pack`)로 묶는다(`--zip`이면 zipfile로 같은 배치). manifest 0.4 `server.type: "uv"`, 명령 `uv run --directory ${__dirname} --frozen --no-dev --extra latex launch.py`(묶은 uv.lock 그대로, dev 그룹 제외, LaTeX 입력 켬). `--frozen`이라 빌드 전에 `uv lock --check`로 lock이 최신인지 막는다. uv가 확장 폴더에 `.venv`를 만들고 프로젝트를 편집 설치하므로 템플릿은 루트 `templates/`에서 찾는다. user_config(결과물 폴더 기본 `${DOCUMENTS}/OpenSTEM`, 자료 폴더, 학교 이름, LMS 토큰·캘린더 주소(sensitive), LMS 주소 직접 지정)는 env OPENSTEM_OUTPUT_DIR·INPUT_DIR·LMS_SCHOOL·LMS_TOKEN·LMS_CALENDAR_URL·LMS_URL로 간다. 비워 둔 설정은 빈 값이나 `${user_config.x}` 글자 그대로 올 수 있어 `output.env_value()`가 둘 다 "설정 안 함"으로 본다. 아이콘은 `build_mcpb.py --icon`이 matplotlib으로 그린다(512×512). 툴을 추가하면 manifest 템플릿 `tools`에도 넣는다(`tests/test_mcpb.py`가 확인). 릴리스를 만들면 `publish.yml`의 bundle 작업이 묶어 릴리스에 붙인다. 묶음을 새 폴더에 풀어 manifest 명령 그대로 띄우는 시험은 `OPENSTEM_SLOW_TESTS=1`, 실제 tectonic 다운로드 시험은 `OPENSTEM_NETWORK_TESTS=1`. 실제 Claude Desktop 더블클릭 설치는 아직 확인하지 못했다(호스트가 uv를 주는지, 첫 설치 약 200 MB가 서버 시작 시간 제한 안에 끝나는지).
+- **한글 그림 타임아웃**: xetexko + 은글꼴을 불러오는 데만 바쁜 PC에서 10초 가까이 들어(같은 그림이 한글 없으면 6초, 있으면 12~14초), 한글이 들어간 render_tikz는 컴파일 타임아웃에 `HANGUL_EXTRA_TIMEOUT`(20초)을 더한다. 끝나지 않는 입력을 끊는 장치는 그대로다.
+- **read_document(M5)**: AI 앱은 첨부한 파일만 읽고 한글 파일은 못 열어서 둔다. 아무 경로나 열면 프롬프트 주입으로 개인 파일이 새어 나갈 수 있으므로 자료 폴더·결과물 폴더 안만(심볼릭 링크·정션은 `resolve()` 뒤 다시 검사). HWP 5.x는 `FileHeader` 플래그(압축·암호·배포용)를 보고, `BodyText/Section*`을 raw deflate로 푼 뒤 레코드(태그 10비트·크기 12비트, 0xFFF면 다음 4바이트)를 돌며 `HWPTAG_PARA_TEXT`(67)의 UTF-16 글자를 모은다. 문단 안 제어 문자 중 0·10·13·24~31은 1글자, 나머지는 8글자 크기라 건너뛴다(탭 9는 남긴다). 배포용·암호 문서는 "PDF로 저장해 넣어 달라"고 안내한다. 압축을 푼 크기는 100 MB까지. 실제 한글 프로그램이 저장한 HWP(오픈소스 hwp.js의 공개 시험 파일 basicsReport.hwp, 344 KB: 표·각주·차례·탭)로 글자가 빠짐없이 나오는 것을 확인했다(2026-11-03). 저장소의 시험은 합성 데이터로 한다(남의 파일을 MIT 저장소에 넣지 않음). PDF 스캔본 의심은 "글자가 거의 없고 그림이 있는 쪽". 결과에 그림 여러 장을 실으려고 `ToolResult.more_images`를 둔다.
+- **check_units·plot_data(M5)**: 둘 다 작업자에서 돈다(pint 준비 약 4초는 준비 신호 전에). check_units의 단위 문자열은 서버에서 글자 허용 목록·길이(단위 60자, 값 80자)로 거르고, 해석은 작업자에서 pint가 한다. plot_data는 scipy 없이 numpy `polyfit(cov=True)`로 맞추고, 지수·거듭제곱은 로그를 씌워 직선으로 맞춘다(0 이하 데이터는 거절). `workers/plot.py`의 비공개 도우미를 같이 쓰니 이름을 바꿀 때 함께 고친다.
+- **export 새 형식·배치(M5)**: pptx는 pandoc pptx 작성기(수식은 편집 가능한 수식). 미리보기가 없어서 한 장에 줄이 너무 많은 슬라이드와 `##`가 없는 문서를 경고한다. exam·flashcards는 Lua 필터(`render/exam.lua`, `render/flashcards.lua`)로 배치하고, 규칙 위반(정답 제목 없음·중복, 2열이 아닌 표, 빈 면)은 파이썬이 구조를 보고 먼저 짧은 에러로 돌려준다. 첫 실행 준비(warmup)는 배치마다 문서를 하나씩 컴파일한다(`export.WARMUP_MARKDOWN`).
+- **HTTP 모드(M6)**: `remote.py`. `MCPServer.streamable_http_app(stateless_http=True, json_response=True)`를 `SecretGate`(ASGI)로 감싸 직접 연 소켓으로 uvicorn(mcp 의존성)에 띄운다(Windows는 SO_EXCLUSIVEADDRUSE, `--port 0`은 빈 포트). 키는 `secrets.token_urlsafe(32)`, 설정 폴더(`%APPDATA%\openstem`, macOS `~/Library/Application Support/openstem`, Linux `$XDG_CONFIG_HOME/openstem`, `OPENSTEM_CONFIG_DIR`로 바꿈)의 `http-secret`(POSIX 0600). `/<키>/mcp` 또는 `/mcp` + `Authorization: Bearer <키>`만 통과(`hmac.compare_digest`)하고 나머지는 모두 같은 404, GET은 405(보낼 SSE가 없고, stateless에서 SDK에 넘기면 빈 연결이 남는다). stateless·JSON 응답이라 세션 만료가 없고 SSE를 못 넘기는 터널도 괜찮다. SDK Host 검사(DNS 리바인딩)는 끈다: 터널 Host는 미리 알 수 없고, 키 없는 요청은 SDK 전에 404라 Host 검사가 더 막는 것이 없다. 접근 로그는 끄고 모든 로그 핸들러에 키 가리기 필터(traceback 포함), 키는 시작 줄 한 번만 출력. 동기 툴은 SDK가 `anyio.to_thread.run_sync`로 돌려 동시 호출이 서로 막지 않는다. uvicorn은 정리 후 받은 신호를 다시 일으켜 SIGTERM·Ctrl+Break면 finally 없이 죽으므로 `capture_signals`를 덮어 터널을 끄고 다시 일으키지 않는다(비공개 `_captured_signals`, uvicorn 0.54). `--tunnel`은 `cloudflared tunnel --no-autoupdate --url http://127.0.0.1:<포트>`를 자식으로 띄워 출력에서 `https://<임의>.trycloudflare.com`(api. 제외)을 30초 안에 찾고, 없거나 실패하면 설치 안내 후 로컬로만 연다(`OPENSTEM_CLOUDFLARED`로 경로 지정, 내려받지 않음). 실제 ChatGPT·cloudflared로는 아직 확인하지 못했다.
+- **lms(M6)**: 툴은 `tools/lms.py`, 연결은 `lms/client.py`(설정·HTTP), 어댑터는 `lms/canvas.py`·`lms/moodle.py`, 학교 목록 `lms/schools.py`, 캘린더 `lms/feed.py`(받기)·`lms/ical.py`(표준 라이브러리 iCalendar 읽기), 도우미 `lms/common.py`. HTTP는 `httpx2`(mcp 2.x와 같은 httpx 갈래, pyproject에도 명시)로 서버 프로세스에서 한다(남의 코드를 실행하지 않음). 설정의 빈 값·`${...}` 자리표시자는 설정 안 함으로 본다. **설정 순서**: `OPENSTEM_LMS_URL`(+`TYPE`)이 이기고, 없으면 `OPENSTEM_LMS_SCHOOL`(이름·줄임말·영문, NFC·대소문자·공백·문장부호 무시, "대학교"→"대")을 학교 목록에서 찾아 주소·종류를 정한다(감지 생략). 모르는 이름은 비슷한 이름 후보와 함께, 미지원 학교(ILOS·Blackboard·자체)는 플랫폼과 아직 되는 것(Blackboard는 캘린더 링크, 자료 폴더 + read_document)을 알리며 거절한다. URL이 목록의 포털·옛 주소면 API 주소로 바꾸고(토큰은 포털로 가지 않는다), 미지원 학교 주소면 같은 에러. **학교 목록**(2026-11-03 공개 페이지 조사 48개 대학 + 울산대 의대 = 49개): LearningX 11, Coursemos/Moodle 22, ILOS 9, Blackboard 3, 기타 4. 시험은 `schools.SCHOOLS`를 가짜 목록으로 바꿔 끼운다. LearningX는 호스트가 둘이다(앞단 Laravel 포털은 `/api/v1`에 419 HTML, Canvas 본체는 다른 호스트, 중앙대는 이름이 거꾸로 canvas.cau=포털·eclass3=Canvas). 모르는 호스트가 419면 "LearningX 포털" 에러(canvas.<도메인> 짐작), 목록 대신 HTML이면 `not_api_error`. **에러 판단은 한국어로 바뀐 글이 아니라** 상태 코드·JSON 모양·헤더·errorcode로 한다: Canvas 감지는 `/users/self`(LearningX는 인증 안 되면 404 JSON) → `/courses?per_page=1`(200 목록은 course_code나 Canvas 헤더가 있어야). 401은 WWW-Authenticate가 있으면 토큰 문제, 없으면 `/users/self`로 토큰을 확인해 "토큰 틀림"과 "권한 없음"(파일 메뉴 숨김 → 모듈 대체)을 가른다. Moodle은 errorcode·exception만(invalidrecord는 표 이름 external_functions로). Coursemos는 공지가 게시판 플러그인(mod_ubboard)에 있는 곳이 많아 뉴스 포럼이 없으면 빈 목록 + 안내. https만(127.0.0.1·localhost만 http), 리디렉션은 직접 따라가며 다른 origin에는 Authorization을 싣지 않고 토큰이 든 주소는 다른 origin으로 보내지 않는다. Canvas 다음 쪽(Link next)도 같은 origin일 때만. Moodle은 토큰을 POST 본문(wstoken)에 싣고, 파일 받기만 같은 origin을 확인한 뒤 `/webservice/pluginfile.php?token=`. **캘린더 모드**: 토큰 없이 `OPENSTEM_LMS_CALENDAR_URL`(Canvas `/feeds/calendars/user_<해시>.ics`, Moodle `/calendar/export_execute.php?…&authtoken=`)만 있으면 deadlines만 되고 나머지 action은 토큰 만드는 법을 알린다. 둘 다 있으면 API가 먼저이고, 피드에만 있는 일정을 `from: calendar`로 덧붙인다(같은 시각 ±2분에 제목이 겹치거나 과목이 같으면 같은 것, 피드 실패는 note만). 캘린더 주소는 토큰과 같은 비밀이다: https만(loopback만 http, webcal://→https), 에러에 값을 싣지 않고, 주소 전체·user_ 조각·긴 쿼리 값·`authtoken=`을 결과 전체에서 지운다(`Config.secrets` → `client.scrub(*secrets)`). 받기는 Authorization 없이, 같은 origin 리디렉션만, 2 MB·30초. ical: 바이트에서 줄 접기를 푼 뒤 UTF-8로 읽는다(75바이트 접기가 한글 글자를 가른다). VEVENT·VTODO, DUE→DTSTART→DTEND, Z·TZID(zoneinfo → tzdata 없는 Windows는 Asia/Seoul·"Korea Standard Time"을 +09:00 → VTIMEZONE 오프셋 → 이 PC 시간대), 종일은 그날 23:59, 취소 일정은 빼고 RRULE은 첫 번째만, 기간 안 일정 500개까지, 1970년 전 날짜는 버린다(Windows OSError). Canvas는 SUMMARY 끝 "[과목]", Moodle은 CATEGORIES가 과목이다. 피드는 제출 여부를 몰라 지난 일정을 overdue가 아니라 past로 보인다. 상한: 연결 10초·읽기 20초, JSON 5 MB·요청당 60초·호출당 90초, 내려받기 200 MB(Content-Length와 실제 바이트 둘 다)·300초, 과목 50·마감 50·공지 20(본문 1,500자)·파일 200. 과목 목록은 프로세스 안에서 120초 캐시, 감지 결과도 캐시. Canvas 마감은 planner → 없으면 upcoming_events, 파일은 Files 메뉴가 숨겨져 권한 없음(401/403/404)이면 모듈의 File 항목 → `/api/v1/files/<id>`(25초 안에서). Moodle 파일 id는 `<모듈 id>.<contents 순번>`, 끝난 학기(enddate 지남) 과목은 뺀다. 마감은 7일 전까지 거슬러 안 낸 것을 overdue로 보인다. download는 자료 폴더 `LMS/<과목>/`에 `.part` 임시 파일로 받은 뒤 옮기고(이름은 `common.safe_name`: 경로 조각·`..`·제어 문자·예약 이름 차단), 같은 내용이면 있던 파일을 쓰고 다르면 ` (2)`를 붙인다. 실제 학교 LMS로는 아직 확인하지 못했다(가짜 서버 `tests/fake_lms.py`: 한국어 에러 본문, LearningX 포털 419, Canvas·Moodle 캘린더 피드, 뉴스 포럼 없는 Coursemos로 시험).
+- **글의 언어(M6)**: 호스트 LLM이 읽는 글(툴·인자 설명, INSTRUCTIONS, 에러·힌트·노트·경고, 결과 속 설명 값, 프롬프트 본문)은 짧은 영어로 쓰고, 사용자에게는 LLM이 사용자의 언어로 전한다(토큰이 한국어의 1/2~1/3). 한국어로 두는 것: 코드 주석, 사람이 직접 보는 것(툴·프롬프트·리소스 title과 프롬프트 설명·인자 설명 = 호스트 앱 메뉴, CLI 출력, .mcpb 설치 화면), 학생이 받는 문서 안 글(그림/표 이름, 시험지 학번/이름, 카드 앞면/뒷면, 그래프 범례 "맞춤:"·"3σ 밖"), 한글 처리용 상수·정규식, 기본 자료 폴더 이름 "자료". 시험지 해설 제목은 `# 정답과 해설`이 기본이고 `# Answers`/`# Solutions`도 받는다. 프롬프트마다 "사용자의 언어로 답하고 문서도 그 언어로" 줄이 있다. 툴 설명에는 JSON 입력 예시(`{"`)와 `On failure:` 줄이 꼭 있다(`tests/test_server.py`가 확인).

openstem_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openstem-mcp contributors
+
+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.

openstem_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.5
+Name: openstem-mcp
+Version: 0.3.0
+Summary: 이공계 학습용 MCP 서버: 학술 그림 렌더링, 풀이 검산, 문서 내보내기
+Project-URL: Homepage, https://github.com/kimi94279-glitch/openstem-mcp
+Project-URL: Issues, https://github.com/kimi94279-glitch/openstem-mcp/issues
+Author: openstem-mcp contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chemistry,education,latex,math,mcp,physics,rdkit,stem,sympy,tikz
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Korean
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.10
+Requires-Dist: matplotlib>=3.10
+Requires-Dist: mcp<3,>=2.3.0
+Requires-Dist: numpy>=2.2
+Requires-Dist: olefile>=0.47
+Requires-Dist: pint>=0.25.3
+Requires-Dist: pymupdf<2,>=1.24
+Requires-Dist: pypandoc-binary>=1.17
+Requires-Dist: rdkit>=2025.3
+Requires-Dist: sympy>=1.14
+Provides-Extra: latex
+Requires-Dist: antlr4-python3-runtime==4.11.*; extra == 'latex'
+Description-Content-Type: text/markdown
+
+# openstem-mcp
+
+이공계 공부를 돕는 MCP 서버. 이미 쓰고 있는 AI(Claude 등)에 붙이면 **학술 그림을 그리고, 풀이를 검산하고, 강의 자료(PDF·한글 파일)를 읽어 예상문제·슬라이드·암기 카드·실험 보고서를 만들** 수 있다.
+서버는 AI를 따로 부르지 않고 그리기·계산만 하므로 **추가 구독이나 API 키가 필요 없다.** 모든 작업은 내 PC에서 돈다.
+
+| 회로도 (`render_tikz`) | 함수 그래프 (`plot_function`) | 분자 구조식 (`render_molecule`) |
+|:---:|:---:|:---:|
+| ![RC 직렬회로](examples/rc_circuit.png) | ![감쇠 진동 그래프](examples/damped_oscillation.png) | ![아스피린](examples/aspirin.png) |
+
+| 치트시트 (`export_document`) | 검산 (`verify_math`) |
+|:---:|:---|
+| ![A4 한 장 치트시트](examples/cheatsheet.png) | "$\sin^2 x = \frac{1-\cos 2x}{2}$ 맞아?" → `matches: true`<br>"$(x+1)^2 = x^2+1$?" → `matches: false`, 반례 $x=-2.03$<br>"$\int x e^x dx$" → $(x-1)e^x$ |
+
+## 설치
+
+### 원클릭 (Claude Desktop)
+
+1. **받기** — [릴리스 페이지](https://github.com/kimi94279-glitch/openstem-mcp/releases)에서 `openstem-<버전>.mcpb` 파일을 내려받는다.
+2. **더블클릭** — 받은 파일을 더블클릭하면 Claude Desktop에 확장 설치 화면이 열린다. 설치를 누른다(안 열리면 Claude Desktop 설정의 확장 화면에 파일을 끌어다 놓는다).
+3. **폴더 고르기** — 결과물 폴더(기본: 문서/OpenSTEM)를 확인하고, 원하면 자료 폴더(AI가 읽을 PDF·한글 파일을 넣는 곳)와 학교 이름·LMS 토큰을 넣은 뒤 켠다(아래 "학교 LMS 연결").
+
+처음 켤 때 파이썬 패키지, LaTeX 엔진(tectonic), TeX 패키지(합쳐 약 500 MB)를 내려받느라 몇 분 걸린다. 그동안 그림·PDF 툴은 "준비 중"이라고 답하니 잠시 뒤 다시 시키면 된다.
+
+### 직접 설치 (Claude Code·설정 파일)
+
+**1. uv 설치** — 파이썬 프로그램을 내려받아 실행해 주는 도구다.
+
+- Windows (PowerShell): `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
+- macOS / Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+**2. 미리 준비(선택)** — 그림·PDF를 만드는 LaTeX 엔진(tectonic)은 처음 켤 때 서버가 공식 릴리스를 받아 해시를 확인한 뒤 설치한다. 터미널에서 한 번 실행해 두면 AI 앱에서 처음 쓸 때 기다리지 않는다(처음 한 번만, 약 300 MB, 3~5분):
+
+```bash
+uvx openstem-mcp --warmup
+```
+
+자동 설치를 원하지 않으면 환경변수 `OPENSTEM_NO_DOWNLOAD=1`을 두고 tectonic을 직접 설치한다: Windows는 [tectonic 릴리스](https://github.com/tectonic-typesetting/tectonic/releases)의 `x86_64-pc-windows-msvc.zip`에서 `tectonic.exe`를 PATH 폴더에, macOS는 `brew install tectonic`, Linux는 `curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net | sh` 후 `mv tectonic ~/.local/bin/`.
+
+**3. AI 앱에 연결**
+
+Claude Desktop: 앱을 **완전히 종료**한 뒤(트레이 아이콘 → 종료) 설정 파일 `claude_desktop_config.json`에 아래를 넣고 다시 켠다.
+(Windows `%APPDATA%\Claude\`, macOS `~/Library/Application Support/Claude/`. 앱이 켜진 채로 고치면 앱이 덮어쓴다.)
+
+```json
+{
+  "mcpServers": {
+    "openstem": { "command": "uvx", "args": ["openstem-mcp"] }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add openstem -- uvx openstem-mcp
+```
+
+설정을 더 하고 싶으면(선택) 같은 자리에 `env`와 `args`를 넣는다. 예: 결과물 폴더 바꾸기, tectonic 위치 지정, LaTeX 입력 검산 켜기.
+
+```json
+{
+  "mcpServers": {
+    "openstem": {
+      "command": "uvx",
+      "args": ["--from", "openstem-mcp[latex]", "openstem-mcp"],
+      "env": {
+        "OPENSTEM_OUTPUT_DIR": "D:\\공부\\그림",
+        "OPENSTEM_TECTONIC": "C:\\Users\\<이름>\\.local\\bin\\tectonic.exe"
+      }
+    }
+  }
+}
+```
+
+macOS에서 앱이 `uvx`나 tectonic을 못 찾으면(앱은 터미널과 PATH가 다를 수 있다) 터미널에서 `which uvx`, `which tectonic`으로 나온 전체 경로를 `command`와 `OPENSTEM_TECTONIC`에 넣는다.
+
+## ChatGPT에서 쓰기
+
+ChatGPT는 인터넷의 HTTPS 주소로만 MCP 서버에 붙는다. 그래서 내 PC에서 서버를 HTTP 모드로 켜고, cloudflared로 임시 HTTPS 주소를 연다. ChatGPT 요금제에 따라 사용자 지정 MCP(개발자 모드)를 쓸 수 없거나 읽기 툴만 될 수 있다.
+
+1. cloudflared 설치(한 번만): Windows `winget install --id Cloudflare.cloudflared`, macOS `brew install cloudflared`, Linux는 Cloudflare 문서의 패키지 설치 안내
+2. 서버 켜기: `uvx openstem-mcp --http --tunnel` → 터미널에 `ChatGPT 커넥터 URL: https://….trycloudflare.com/<비밀 키>/mcp`가 나온다
+3. ChatGPT 설정 → 앱(또는 커넥터) → 고급 설정에서 개발자 모드를 켜고, 사용자 지정 MCP 서버(앱 만들기)에 위 URL을 붙여 넣은 뒤 인증은 "없음"을 고른다(메뉴 이름은 바뀔 수 있다)
+
+- URL 가운데의 긴 문자열이 비밀 키다. 키가 틀린 요청은 모두 404다. 남에게 보여 주지 말고, 새어 나갔으면 `--new-secret`으로 바꾼다.
+- 임시 터널 주소는 켤 때마다 바뀌므로 ChatGPT에 새 URL을 다시 넣어야 한다(비밀 키는 그대로).
+- 터미널 창을 닫거나 PC가 잠들면 연결이 끊긴다. 그림·문서는 서버를 켠 이 PC의 결과물 폴더에 저장된다.
+- 터널 없이 이 PC 안에서만 쓰려면 `uvx openstem-mcp --http` → `http://127.0.0.1:8765/<비밀 키>/mcp`(또는 `/mcp`에 헤더 `Authorization: Bearer <키>`). 포트는 `--port`로 바꾼다.
+
+## 이렇게 쓴다
+
+AI에게 평소처럼 말하면 된다.
+
+- "RC 직렬회로 그려줘", "빗면 위 물체의 자유물체도 그려줘", "PID 제어 블록도 그려줘"
+- "y = sin(x)·e^(−x/5) 그래프 그려줘", "아스피린 구조식 보여줘"
+- "이 적분 풀고 단계마다 검산해줘", "y'' + 3y' + 2y = sin x 풀어줘", "이 행렬 고윳값 구해줘"
+- "이 답 단위 맞아?", "72 km/h를 m/s로"
+- "자료 폴더의 3장 PDF로 예상문제 10개랑 해설 만들어줘"
+- "이 측정값으로 그래프 그리고 기울기 구해서 실험 보고서 써줘"
+- "이 단원 내용으로 A4 한 장 치트시트 PDF", "발표 슬라이드 10장", "암기 카드 20장 만들어줘"
+
+결과물은 `~/OpenSTEM/`(Windows는 `C:\Users\<이름>\OpenSTEM\`)에 쌓인다. 다른 곳에 두려면 환경변수 `OPENSTEM_OUTPUT_DIR`을 설정한다.
+
+**자료 폴더**: 강의 자료·기출문제·공지(PDF, 한글 HWP·HWPX, 워드, 파워포인트, 엑셀)를 `~/OpenSTEM/자료/`에 넣어 두면 AI가 이름으로 골라 읽는다. 이 폴더(와 결과물 폴더) 밖 파일은 열지 않는다. 다른 곳을 쓰려면 환경변수 `OPENSTEM_INPUT_DIR`을 설정한다. 사진이나 몇 개 안 되는 파일은 채팅에 바로 첨부해도 된다.
+
+AI 앱의 프롬프트 메뉴에서 바로 고를 수도 있다.
+
+| 프롬프트 | 하는 일 |
+|---|---|
+| `figure` | 비슷한 예제를 찾아 고쳐 그리고, 미리보기를 보고 최대 3번 고친다 |
+| `solve` | 단계별로 풀고 핵심 단계마다 검산(단위 포함)한 뒤 최종 답을 낸다 |
+| `exam` | 강의 자료·기출로 새 예상문제를 만들고, 답을 검산해 문제지·해설지 PDF로 낸다 |
+| `cheatsheet` | 자료를 A4 한 장으로 요약해 PDF로 내보낸다 |
+| `slides` | 자료로 발표 슬라이드(pptx)를 만든다. 그림·수식·발표자 노트 포함 |
+| `flashcards` | 정의·공식 암기 카드를 오려 쓰는 PDF와 암기 앱용 파일로 만든다 |
+| `lab_report` | 측정 데이터로 그래프·맞춤·단위 검사를 하고 실험 보고서(docx)를 쓴다 |
+
+## 학교 LMS 연결 (선택, 읽기 전용)
+
+과목·다가오는 마감·공지·강의 자료를 AI가 읽어 온다. 자료 파일은 자료 폴더의 `LMS/과목명/`으로 받아 바로 읽는다. 제출·글쓰기는 하지 않고, 비밀번호는 받지 않는다.
+
+**1. 학교 이름 넣기** — 확장 설정의 **학교 이름**에 학교 이름만 넣으면 LMS 주소는 자동으로 찾는다. 줄임말도 된다(성대, 서울대, KAIST, 코리아텍). Claude Code나 설정 파일로 쓸 때는 환경변수 `OPENSTEM_LMS_SCHOOL`을 쓴다.
+
+```bash
+claude mcp add openstem -e OPENSTEM_LMS_SCHOOL=성균관대 -e OPENSTEM_LMS_TOKEN=<토큰> -- uvx openstem-mcp
+```
+
+AI에게 "LMS 지원 학교 목록 보여 줘"라고 하면 목록과 학교별 연결 방법을 알려 준다.
+
+**2. 토큰 만들기 (LMS 웹사이트에서 직접)**
+
+| LMS | 메뉴 |
+|---|---|
+| Canvas·LearningX | 계정 → 설정 → 승인된 통합 → **+ 새 액세스 토큰** |
+| Moodle·Coursemos | 환경설정 → **보안 키** → 모바일 웹 서비스 키 복사 (메뉴가 안 보이면 `<LMS 주소>/user/managetoken.php`) |
+
+만든 토큰을 확장 설정의 **LMS 액세스 토큰**(또는 `OPENSTEM_LMS_TOKEN`)에 넣고 앱을 다시 켠다. 토큰은 학교 LMS 주소로만 보낸다.
+
+**3. 토큰을 만들 수 없을 때: 캘린더 주소 (마감만)** — 학교가 학생 토큰을 막았거나 모바일 서비스가 꺼져 있으면(연세대 LearnUs, 동국대, 한국기술교육대) LMS 캘린더의 구독 주소로 **과제 마감만** 읽을 수 있다.
+
+| LMS | 메뉴 |
+|---|---|
+| Canvas·LearningX | 캘린더 → 오른쪽 **캘린더 피드** → 주소 복사 (`…/feeds/calendars/user_….ics`) |
+| Moodle·Coursemos | 달력 → **일정 내보내기** → 모든 일정, 최근과 다가오는 일정 → 캘린더 URL 가져오기 → 주소 복사 (`…/calendar/export_execute.php?…`) |
+
+주소를 확장 설정의 **LMS 캘린더 주소**(또는 `OPENSTEM_LMS_CALENDAR_URL`)에 넣는다. 이 주소만 있으면 누구나 내 일정을 볼 수 있으니 비밀번호처럼 다룬다(도구도 결과에 싣지 않는다). 토큰과 캘린더 주소를 둘 다 넣으면 토큰을 먼저 쓰고 캘린더에만 있는 일정을 덧붙인다.
+
+**지원 학교 (2026년 11월, 공개 페이지 조사)**
+
+| 구분 | 학교 |
+|---|---|
+| LearningX(Canvas) 11곳 | 서울대, 고려대, 성균관대, 한양대, 중앙대, 경희대, 숭실대, 경북대, 경상국립대, 제주대, 단국대 |
+| Coursemos·Moodle 22곳 | 연세대\*, 서울시립대, 이화여대, 동국대\*, 홍익대, 국민대, 세종대, 인하대, 숙명여대, 상명대, KAIST, POSTECH, GIST, 한국기술교육대\*, 부산대, 전남대, 전북대, 충북대, 강원대, 인천대, 한국항공대, 울산대 의과대학 |
+| 지원 안 됨 | ILOS: 서강대, 한국외대, 건국대, 명지대, 가톨릭대, 서울과기대, 한국공학대, 부경대, 영남대 · Blackboard: 아주대, UNIST, DGIST · 자체·기타: 광운대(KLAS), 충남대(권역 플랫폼), 울산대(uclass), 계명대 |
+
+\* 모바일 서비스가 꺼져 있어 토큰 대신 캘린더 주소를 쓴다.
+
+- LearningX 학교는 학생이 아는 주소(예: icampus.skku.edu)와 실제 API 주소(canvas.skku.edu)가 다르다. 학교 이름만 넣으면 알아서 맞는 주소를 쓴다.
+- 고려대·중앙대·경희대 등 일부는 학생이 토큰을 만들 수 있는지 확인하지 못했다. 안 되면 캘린더 주소를 쓴다. 실제 학교 LMS로는 아직 시험하지 못했다(가짜 서버로 시험).
+- 지원 안 되는 학교: Blackboard는 캘린더에 iCal 링크가 있으면 마감만 읽을 수 있다(확인 못 함). 그 밖에는 강의 자료를 직접 내려받아 자료 폴더에 넣고 AI에게 읽어 달라고 하면 된다.
+- 목록에 없는 학교도 Canvas나 Moodle이면 **LMS 주소 직접 지정**(`OPENSTEM_LMS_URL`)과 토큰으로 쓸 수 있다.
+
+## 툴
+
+| 툴 | 하는 일 |
+|---|---|
+| `render_tikz` | TikZ·circuitikz·pgfplots·chemfig 코드 → SVG·PDF·PNG. 한글 라벨 자동 지원. 에러는 몇 번째 줄인지 알려준다 |
+| `get_template` | 검증된 그림 예제 40개(회로·물리·수학·다이어그램 각 10). MCP 리소스 `template://{category}/{name}`로도 열린다 |
+| `plot_function` | 수식 그래프. 점근선·불연속(점프)·정의역 밖 구간을 찾아 알려주고 데이터 점을 겹쳐 찍는다 |
+| `plot_data` | 측정 데이터 그래프. 표·CSV를 붙여 넣으면 오차 막대, 직선·다항·지수·거듭제곱·로그 맞춤(± 표준오차, R²), 튀는 점 표시 |
+| `render_molecule` | SMILES → 분자 구조식·반응식, 분자식·분자량 |
+| `verify_math` | 같은 식인지 판정(반례·수치 비교), 간단히 하기, 방정식, 미분, 적분, 극한, 값 계산, 미분방정식, 행렬, 라플라스 변환, 급수, 부등식, 확률분포 |
+| `check_units` | 답의 단위·차원 검사(어느 차원이 어긋났는지 설명), 단위 변환 |
+| `read_document` | 자료 폴더의 PDF·한글(HWP·HWPX)·워드·파워포인트·엑셀·텍스트·그림 읽기. 스캔본 PDF는 쪽 그림으로 |
+| `export_document` | 마크다운(수식·그림·표) → pdf·docx·pptx. 배치: 보통 문서, A4 치트시트, 시험지(해설 분리), 플래시카드 |
+| `lms` | 학교 LMS(LearningX·Canvas, Coursemos·Moodle) 읽기: 과목, 마감(토큰 없이 캘린더 주소로도), 공지, 자료 목록, 자료 파일 받기(자료 폴더로), 지원 학교 목록 |
+
+## 자주 묻는 것
+
+- **처음 그림이 안 나오고 "준비 중"이라고 한다** — 첫 실행 때 TeX 패키지를 받는 중이다(3~5분, 한 번만). 설치 2단계의 `--warmup`을 미리 해 두면 생기지 않는다.
+- **"tectonic을 찾을 수 없다" / "자동 설치 실패"** — 서버가 tectonic을 받지 못한 경우다(인터넷·방화벽, 또는 Windows ARM처럼 공식 파일이 없는 PC). 직접 설치 2단계의 안내대로 tectonic을 설치하고 AI 앱을 다시 켠다. PATH 밖에 두었다면 위 설정 예시처럼 `OPENSTEM_TECTONIC`에 실행 파일 경로를 넣는다.
+- **"TeX 패키지를 내려받지 못했다"** — 처음 쓰는 패키지는 tectonic 서버에서 받아 온다. 인터넷 연결이나 학교·회사 방화벽을 확인한다.
+- **LaTeX로 쓴 식을 검산하고 싶다** — `verify_math`의 `latex=true`는 선택 기능이다. 위 설정 예시처럼 `openstem-mcp[latex]`로 실행하면 켜진다. 없어도 AI가 sympy 문법으로 바꿔 보낸다.
+- **물리 공식 검산이 "틀림"으로 나온다** — 변수를 음수일 수도 있는 실수로 보면 `√(m²v²) = mv` 같은 변형이 틀린 게 맞다. 물리량은 AI가 `assume="positive"`로 검산하게 되어 있다.
+- **설치가 안 되는 컴퓨터** — Windows ARM(Snapdragon 등)은 pandoc 패키지가 없어 지원하지 않는다.
+- **안전한가** — 임의 코드를 실행하는 툴은 없다. LaTeX·수식·SMILES는 별도 프로세스에서 시간 제한을 두고 처리하고, 파일을 읽거나 쓰는 TeX 명령(이름을 조립해 우회하는 방법 포함)과 결과물 폴더 밖·인터넷 그림은 컴파일 전에 막는다.
+
+## 개발
+
+필요한 것: [uv](https://docs.astral.sh/uv/), [tectonic](https://tectonic-typesetting.github.io/)
+
+```bash
+uv sync --all-extras
+uv run openstem-mcp --warmup
+uv run pytest
+npx @modelcontextprotocol/inspector uv run openstem-mcp
+```
+
+Claude Desktop에 개발 버전을 붙이려면(Windows): Claude Desktop을 완전히 종료 → `python scripts/register_claude_desktop.py` → 다시 켜기.
+
+설계 원칙과 구현 메모는 [CLAUDE.md](CLAUDE.md)에 있다.
+
+## 라이선스
+
+MIT