Study Assistant

로컬 Model Context Protocol (MCP) 서버로, 강의 계획서 문서를 검색 가능한 학습 지식 베이스로 변환합니다. 서버는 files/ementas에서 문서를 읽고 텍스트를 추출한 후, Genkit과 Ollama Cloud를 사용하여 요약 및 구조화된 세부 정보를 생성합니다.

아키텍처

이 저장소는 pnpm 모노레포입니다. mcp 패키지에는 Express 및 MCP 서버가 포함되어 있으며, files/ementas는 도구에 노출되는 유일한 문서 디렉터리입니다.

서버는 127.0.0.1에 바인딩되며 다음을 노출합니다:

• GET /health: 비밀번호나 공급자 정보 없이 프로세스 상태를 확인합니다.

• /mcp: 상태 비저장 MCP Streamable HTTP 엔드포인트.

• list_ementas: 지원되는 파일을 메타데이터 및 캐시된 요약과 함께 나열합니다.

• get_ementa: 추출된 텍스트와 구조화된 강의 계획서 세부 정보를 반환합니다.

지원되는 형식은 PDF, DOCX, Markdown 및 일반 텍스트입니다. 심볼릭 링크, 경로 및 지원되지 않는 확장자는 거부됩니다.

Related MCP server: Educational Tutor MCP Server

요구 사항

• Node.js 20 이상.

• pnpm 10 (Corepack이 고정 버전을 제공할 수 있음).

• Ollama Cloud API 키.

설정

저장소 루트에서 종속성을 설치합니다:

corepack pnpm install

mcp/.env.example을 저장소 루트의 .env 또는 mcp/.env로 복사한 후 API 키를 제공합니다:

OLLAMA_API_KEY=your-key

기본 모델은 gpt-oss:120b입니다. 선택적 설정은 다음과 같습니다:

OLLAMA_MODEL=gpt-oss:120b
OLLAMA_BASE_URL=https://ollama.com
OLLAMA_TIMEOUT_MS=60000
MCP_PORT=3000

환경 파일은 Git에서 무시됩니다. API 키를 커밋하지 마십시오.

애플리케이션은 pnpm이 패키지를 시작하는 디렉터리와 관계없이 두 위치를 모두 명시적으로 확인합니다. 기존 시스템 환경 변수가 우선합니다. 두 파일이 동일한 변수를 정의하는 경우 mcp/.env가 루트 .env보다 우선합니다.

강의 계획서 파일을 files/ementas 안에 직접 배치한 후 개발 서버를 시작합니다:

corepack pnpm dev

MCP 엔드포인트는 http://127.0.0.1:3000/mcp에서 사용할 수 있습니다.

Codex 연결

서버가 실행 중이면 로컬 Codex 클라이언트에 해당 URL을 등록합니다:

codex mcp add studyAssistant --url http://127.0.0.1:3000/mcp

동등한 Codex 구성:

[mcp_servers.studyAssistant]
url = "http://127.0.0.1:3000/mcp"

이 localhost 엔드포인트는 로컬 Codex 클라이언트용입니다. 원격 ChatGPT 클라이언트에는 노출되지 않습니다.

명령어

저장소 루트에서 다음 명령을 실행합니다:

corepack pnpm dev       # Watch and run the TypeScript server
corepack pnpm build     # Build the production JavaScript
corepack pnpm start     # Run the compiled server
corepack pnpm typecheck # Check strict TypeScript types
corepack pnpm lint      # Run ESLint
corepack pnpm test      # Run the Vitest suite

dev 및 build는 테스트 스위트를 실행하지 않습니다. 프로덕션 컴파일은 src/__tests__도 제외하므로 테스트 픽스처와 목(mock)은 서버에 로드되거나 dist에 포함될 수 없습니다.

생성된 분석은 .cache/ementas.json에 저장됩니다. 캐시 항목은 문서의 크기나 수정 시간이 변경되면 무효화됩니다. 유효한 캐시 결과는 Ollama Cloud가 일시적으로 사용 불가능한 경우에도 계속 사용할 수 있습니다.

보안 및 실패 동작

API 키는 환경에서 로드되며 Ollama 인증 헤더에만 전송됩니다. 상태 응답, MCP 응답 또는 애플리케이션 로그에는 포함되지 않습니다. 클라우드 요청은 타임아웃을 사용하며 일시적인 429, 500, 502 실패를 재시도합니다. 한 파일의 실패는 list_ementas에서 격리됩니다. get_ementa는 MCP 도구 오류를 보고합니다.