AI 학생 개발자 어시스턴트 — MCP 서버

프로덕션 품질의 Model Context Protocol 서버로, AI 어시스턴트가 GitHub 이슈, 학업 마감일(LMS), 개인 작업 추적기에 통합 접근할 수 있게 해줍니다. 따라서 "오늘 무엇을 작업해야 할까?"와 같은 질문에 실제로 우선순위가 매겨진 답변을 할 수 있습니다.

Python 3.12+, 공식 MCP Python SDK(v2), FastAPI 스타일의 서비스 분리, SQLite, httpx로 구축되었습니다. 외부 API를 모킹하여 완전히 테스트되었으며, 스위트를 실행하는 데 실제 자격 증명이 필요하지 않습니다.

목차

• 프로젝트 개요

• 기능 — MCP 도구

• 아키텍처

• 기술 스택

• 설치

• 설정

• 서버 실행

• AI 클라이언트 연결

• 사용 예시

• API 통합

• 데이터베이스

• 테스트

• 보안

• 제한 사항

• 향후 개선 사항

• 프로젝트 아키텍처

• 데모 시나리오

• 면접 대화 포인트

프로젝트 개요

문제. 학생 개발자의 작업은 세 가지 분리된 공간에 존재합니다: GitHub의 코드 작업, 대학 LMS의 과제 및 시험, 노트에 흩어진 개인 할 일. 우선순위는 기억에 의해 결정되므로, 일이 누락됩니다.

해결책. 세 가지 소스를 모두 작고 잘 설명된 강력한 타입의 도구로 노출하는 하나의 MCP 서버입니다. AI 어시스턴트는 이 모든 것을 한 번에 읽고 추론합니다: 할당된 이슈, 이번 주 마감일, 보류 중인 작업을 가져오고, 기한이 지난 항목을 감지하며, 우선순위가 매겨진 요약을 작성할 수 있습니다. 또한 동일한 인터페이스로 시스템을 변경(이슈 생성/종료, 작업 생성, 마감일 일괄 가져오기)할 수 있습니다.

상태. 이는 개인 생산성 도구의 포트폴리오 수준 구현입니다. 모든 것이 종단 간 작동합니다. LMS 통합은 교체 가능한 인터페이스 뒤에 의도적으로 모킹되었습니다(제한 사항 참조).

기능 — MCP 도구

15개의 좁은 범위의 도구. 각각 명확한 이름, AI가 호출 시점을 결정하기 위해 읽는 설명, 검증된 입력, 예측 가능한 출력을 가지고 있습니다:

GitHub (4개 도구)

LMS / 학업 마감일 (3개 도구)

작업 추적기 (8개 도구)

모든 도구는 동일한 JSON 형태를 반환하므로 에이전트가 결과를 안정적으로 파싱할 수 있습니다:

{ "ok": true,  "data": { "...": "..." }, "error": null }
{ "ok": false, "data": null, "error": { "code": "not_found", "message": "..." } }

아키텍처

flowchart TB
    subgraph Host["AI Client (e.g. Claude Desktop)"]
        Agent["Assistant / Agent"]
    end
    subgraph MCP["MCP Protocol (stdio)"]
        S["MCPServer (mcp SDK v2)"]
    end
    subgraph App["app/"]
        Tools["tools/ · 15 thin tool functions"]
        Services["services/ · GitHub · LMS · Task"]
        Repo["TaskRepository"]
        DB[("SQLite")]
        Mock["MockLMSService"]
    end
    Ext["GitHub REST API v3"]
    Agent -->|tools/list · tools/call · server/discover| S
    S --> Tools
    Tools --> Services --> Repo --> DB
    Services --> Ext
    Services --> Mock

이 코드베이스의 황금률: MCP 계층은 오직 어댑터일 뿐입니다. 각 도구 함수는 타입 시그니처를 통해 입력을 검증하고, 서비스를 호출하며, 결과를 렌더링합니다. 비즈니스 로직은 도구 함수에 존재하지 않습니다.

기술 스택

설치

요구 사항: Python 3.12+ 및 git. (MCP SDK 자체는 ≥3.10이 필요합니다; 이 프로젝트는 3.12를 대상으로 합니다.)

Windows (PowerShell)

cd "C:\Users\ASUS\mcp project"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Activate.ps1이 실행 정책에 의해 차단된 경우:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

macOS / Linux

cd mcp-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

설정

플레이스홀더 파일을 복사하고 값을 입력하세요:

cp .env.example .env     # Windows:  copy .env.example .env

GitHub 토큰 생성 → GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token → 필요한 저장소만 선택 → Issues: Read and Write 권한만 부여.

⚠️ .env는 git에 무시됩니다. 절대 커밋하지 마세요. .env.example에는 플레이스홀더만 포함되어 있습니다.

서버 실행

1. 데이터베이스 초기화 및 데모 데이터 시드

python -m scripts.seed_demo

이 명령은 data/tasks.db를 생성하고 몇 가지 현실적인 데모 작업(하나는 의도적으로 기한 초과)을 삽입합니다.

2. MCP 서버 실행

python -m app.server

서버는 stdio를 통해 시작되며(데스크톱 MCP 클라이언트의 기본값), 중지될 때까지 실행됩니다.

개발 및 디버깅

SDK에는 CLI와 대화형 검사기가 포함되어 있습니다:

mcp dev app/server.py        # launch + open the MCP Inspector in a browser
mcp run app/server.py        # run the server (same behavior as python -m app.server)

AI 클라이언트 연결

로컬 MCP 서버는 stdio를 통해 실행됩니다: AI 클라이언트가 서버 프로세스를 시작하고 stdin/stdout을 통해 통신합니다. 구성 형식은 클라이언트의 mcpServers 블록입니다.

Claude Desktop (Windows)

%APPDATA%\Claude\claude_desktop_config.json 편집 (Settings → Developer → Edit Config를 통해 열기), 완전히 종료 후 다시 시작:

{
  "mcpServers": {
    "ai-student-assistant": {
      "command": "C:\\Users\\ASUS\\mcp project\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\ASUS\\mcp project\\app\\server.py"]
    }
  }
}

요구 사항:

• 절대 경로 — Claude Desktop은 셸 PATH나 작업 디렉터리를 상속하지 않습니다.

• where python / where git을 사용하여 정확한 인터프리터 경로를 확인하세요.

• 저장 후 Claude Desktop을 완전히 다시 시작한 다음, 커넥터/메시지 상자 메뉴에서 서버와 해당 도구를 확인하세요.

• 실패 시 로그: %APPDATA%\Claude\logs\mcp*.log.

대안

• MCP Inspector (구성 불필요): mcp dev app/server.py는 모든 도구를 수동으로 호출할 수 있는 GUI를 제공합니다 — 데모에 이상적입니다.

• Cursor — .cursor/mcp.json은 동일한 mcpServers 형태를 사용합니다.

• 서버는 전송에 구애받지 않습니다: 동일한 MCPServer를 나중에 Streamable HTTP를 통해 제공할 수 있습니다(향후 개선 사항 참조).

사용 예시

사용자: 현재 열려 있는 GitHub 이슈는 무엇인가요?

에이전트가 get_open_issues를 호출하고(저장소 없음 → 사용자에게 할당된 이슈), 요약합니다:

할당된 열린 이슈가 2개 있습니다: "Fix login bug" (#1, 버그) 및 "Add CI pipeline" (#2).

사용자: 앞으로 7일 이내에 마감인 과제는 무엇인가요?

에이전트가 오늘 날짜를 기준으로 start/end를 계산하여 get_upcoming_deadlines를 호출합니다:

이번 주 마감: Quiz 3 (수학, 8월 12일), Project Proposal Draft (ENG101, 8월 11일), Graph Traversal Assignment (CS101, 8월 13일).

사용자: 그 과제들에 대한 작업을 생성해 주세요.

에이전트가 create_tasks_from_deadlines를 호출합니다 (서버는 이미 source/source_id 중복 제거를 지원하므로 재실행해도 중복되지 않습니다):

3개의 작업이 생성되었습니다. 0개 건너뜀 (중복 없음).

사용자: 어떤 작업을 먼저 해야 하나요?

에이전트가 get_workload_summary와 get_overdue_tasks를 호출한 후 우선순위와 마감일을 고려하여 추론합니다:

첫 번째: "CI 파이프라인의 불안정한 테스트 수정" (기한 초과, 높음). 그 다음: 프로젝트 제안서 초안 (내일까지), 퀴즈 3 (2일 후까지)...

API 통합

GitHub

• 엔드포인트: GET /issues (할당된 항목), GET|POST /repos/{owner}/{repo}/issues, GET|PATCH /repos/{owner}/{repo}/issues/{number}.

• 인증: Authorization: Bearer <GITHUB_TOKEN>. 공개 저장소는 익명 접근이 허용되며, 401 발생 시 "인증 필요" 오류를 반환합니다.

• 속도 제한: x-ratelimit-remaining: 0이 포함된 403과 429는 rate_limited 오류로 매핑됩니다.

• 풀 리퀘스트: 이슈 엔드포인트는 PR도 반환하지만 pull_request 키를 통해 필터링됩니다.

• 모든 네트워크/시간 초과/오류 상태는 도메인 예외로 변환됩니다 (보안 참조).

LMS

이 프로젝트에서는 합법적이고 접근 가능한 대학 LMS API가 없다고 가정했으므로, LMS는 작은 인터페이스(LMSService) 뒤에 있으며 현실적인 모의 구현(MockLMSService)을 사용합니다:

• 오늘 날짜를 기준으로 마감일이 있는 강좌 카탈로그를 시드합니다.

• 강좌를 검증합니다 (알 수 없는 강좌 → not_found).

• 날짜와 범위를 검증합니다 (잘못된 입력 → invalid_input).

나중에 실제 제공자를 추가하려면 동일한 인터페이스를 구현하고 LMS_PROVIDER=real로 설정하면 됩니다. 보호된 페이지를 스크래핑하지 않으며, 인증을 우회하지 않습니다. 모의 서비스는 실제 서비스처럼 동작하므로 나머지 앱은 수정 없이 테스트됩니다.

데이터베이스

DATABASE_PATH(기본값 data/tasks.db)에 있는 SQLite 파일, MVP에서는 하나의 테이블:

CREATE TABLE tasks (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    title       TEXT    NOT NULL,
    description TEXT,
    status      TEXT    NOT NULL DEFAULT 'pending'
                    CHECK (status IN ('pending','completed')),
    priority    TEXT    NOT NULL DEFAULT 'medium'
                    CHECK (priority IN ('low','medium','high','urgent')),
    due_date    TEXT,                      -- ISO-8601 (date or timestamp)
    source      TEXT,                      -- 'github' | 'lms' | NULL
    source_id   TEXT,                      -- e.g. GitHub issue number
    source_url  TEXT,
    created_at  TEXT NOT NULL,
    updated_at  TEXT NOT NULL
);

CREATE INDEX idx_tasks_status    ON tasks(status);
CREATE INDEX idx_tasks_due_date  ON tasks(due_date);
CREATE INDEX idx_tasks_priority  ON tasks(priority, due_date);

CREATE UNIQUE INDEX uq_tasks_source ON tasks(source, source_id)
    WHERE source IS NOT NULL AND source_id IS NOT NULL;

각 결정이 중요한 이유:

• (source, source_id)에 대한 부분 고유 인덱스 — SQLite는 일반 UNIQUE에서 NULL을 구별된 값으로 처리하므로, 중복 가져오기가 허용될 뿐만 아니라 여러 "개인"(출처 없는) 작업을 금지합니다. WHERE source IS NOT NULL 부분 인덱스는 가져오기를 데이터베이스 계층에서 멱등성 있게 만듭니다. 이것이 create_task_from_issue / create_tasks_from_deadlines를 반복적으로 호출해도 안전한 이유입니다.

• status/priority를 TEXT + CHECK로 사용 — SQLite에는 열거형이 없습니다. CHECK는 무결성을 제공하고 Python enum.Enum은 값과 일치하여 타입 안전성을 보장합니다.

• 정렬 가능한 문자열로서의 ISO-8601 UTC 타임스탬프 — 사전식 순서 == 시간 순서, 시간대 모호성 없음, JSON 친화적.

• source + source_id + source_url 은 작업이 어떤 이슈나 과제에서 왔는지 항상 추적할 수 있도록 출처를 보존합니다.

테스트

pytest          # runs the whole suite: mocked GitHub, mock LMS, SQLite tasks, MCP client

범위 (tests/):

MCP 도구는 SDK의 인메모리 클라이언트(async with Client(server))를 사용하여 실제 프로토콜 연결에 대해 테스트됩니다. 이는 FastAPI의 TestClient와 동일한 패턴입니다. 하위 프로세스, 포트, 자격 증명이 필요하지 않습니다.

보안

• 비밀은 환경 변수에만 저장됩니다 (.env는 git에서 무시됨; .env.example에는 자리 표시자가 있음).

• 최소 권한: 특정 저장소의 이슈 읽기 및 쓰기로 제한된 세분화된 GitHub PAT — 전체 repo 범위는 절대 사용하지 않음.

• 비밀 로깅 없음: 리다이렉팅 필터가 로그에서 Authorization 값을 제거합니다. 서버는 stdout에 아무것도 출력하지 않으므로(logging은 stderr로 감), stdio 프로토콜 스트림이 깨끗하게 유지됩니다.

• 입력 검증: 도구 경계에서의 Pydantic + 서비스의 도메인 검증.

• SQLAlchemy를 통한 매개변수화된 SQL — 문자열로 작성된 쿼리 없음.

• 통제된 오류 노출: AI는 구조화된 오류(code, message)를 받습니다. 원시 스택 추적은 서버 로그에만 기록됩니다.

• 최소 클라이언트 노출: .env 토큰은 서버 프로세스에서 읽히며 클라이언트 구성을 통해 전달되지 않습니다.

인터뷰 포인트의 인터뷰 중심 논의도 참조하세요.

한계

의도적인 솔직한 한계:

• LMS는 모의입니다. LMS_PROVIDER=mock이 유일한 제공자입니다. 실제 API 어댑터, 내보낸 캘린더 또는 기타 승인된 데이터 소스를 추가하여 교체해야 합니다 (LMSService 인터페이스를 통해 상호 교환 가능).

• SQLite는 단일 사용자입니다. 동시성 보장, 네트워크 액세스, 백엔드 복제가 없습니다. 개인 비서용으로 의도적으로 설계되었습니다.

• 아직 OAuth / HTTP 전송이 없습니다. GitHub 토큰은 정적 비밀입니다. 서버는 stdio를 통해 실행됩니다. 로컬 개인 사용에는 적합하지만 원격/호스팅 사용에는 OAuth와 Streamable HTTP가 필요합니다.

• 이슈 생성은 할당이나 본문 마크다운을 명시적으로 지원하지 않습니다 (자유 텍스트 외에는) — 의도적으로 작게 유지되었습니다.

• 마감일의 단일 시간 단위 — 시간대 변환 없음. 날짜는 사용자가 제공한 ISO-8601 형식으로 비교됩니다.

• 가져오기는 변경 가능한 소스 항목을 스냅샷으로 설명합니다: GitHub 이슈가 나중에 편집되어도 이미 생성된 작업은 업데이트되지 않습니다 (설계된 동작이지 버그가 아닙니다).

향후 개선 사항

• 실제 LMSService 어댑터 (공식 API 또는 .ics 캘린더 내보내기)

• 마감일을 위한 Google 캘린더 통합

• 기한 초과 작업에 대한 Slack/Teams 알림

• PostgreSQL 백엔드 (저장소는 이미 이를 추상화함)

• GitHub OAuth + Streamable HTTP 전송 + Docker 배포

• 작업 기록/감사 테이블; 이슈 업데이트가 작업에 재동기화됨

• 더 풍부한 에이전트 워크플로우 (자동 분류, 주간 "스탠드업" 보고서 리소스)

프로젝트 아키텍처

의존성 순서의 계층:

app/tools       MCP adapters — type-hinted params, docstrings as descriptions, guard() → {ok, data, error}
app/services    GitHubService · LMSService (mock) · TaskService — business logic + cross-service workflows
app/database    Database (engine/session) · TaskRepository (all SQL)
app/models      SQLAlchemy ORM (Task) · Pydantic schemas (TaskCreate/Out, GitHubIssue, Deadline)
app/config.py   validated env config
app/exceptions  domain error hierarchy → AI-readable codes

의존성 주입: app/server.py는 구성 루트입니다 — config → database → services → MCPServer를 빌드하고 필요한 서비스와 함께 도구 함수를 등록합니다. 전역 변수는 없습니다. 테스트는 동일한 그래프를 가짜로 조립합니다.

오류 흐름: tool → service → repository/API가 StudentAssistantError를 발생시킴 → guard()가 {ok: false, error: {code, message}}를 렌더링합니다. 예상치 못한 예외는 기록되고(stderr) 일반 internal_error 메시지로 반환됩니다.

데모 시나리오

1. 세분화된 GitHub 토큰을 생성하고 .env에 GITHUB_TOKEN을 설정합니다.

2. 작업 데이터베이스를 시드합니다: python -m scripts.seed_demo (몇 가지 작업을 생성하며, 하나는 기한 초과).

3. 서버를 시작합니다: python -m app.server (또는 mcp dev app/server.py로 Inspector 실행).

4. Claude Desktop / Inspector를 서버에 연결합니다.

5. 질문: "이번 주에 무엇을 작업해야 하나요?" → 에이전트가 get_workload_summary를 호출하고, 열린 GitHub 이슈 + 다가오는 마감일 + 보류 중/기한 초과 작업을 결합하여 우선순위가 있는 답변을 제공합니다.

6. 질문: "이번 주 마감인 모든 과제에 대한 작업을 생성해 줘." → 에이전트가 create_tasks_from_deadlines를 호출합니다.

7. 데이터베이스에서 확인:

   sqlite3 data/tasks.db "SELECT title, due_date, source FROM tasks ORDER BY due_date;"

   → source = 'lms'인 새 행이 마감일당 하나씩 나타납니다. 동일한 질문을 다시 실행하면 도구가 중복 대신 skipped를 보고합니다.

인터뷰 포인트

다음 결정을 방어할 준비를 하세요:

1. 왜 MCP인가? 표준화된 프로토콜이므로 하나의 서버가 모든 AI 클라이언트와 작동합니다. 도구는 발견되고(tools/list), 호출되며(tools/call), 모델에 설명됩니다 — 이름 지정과 설명은 LLM을 위한 UX 계약입니다.

2. 왜 현재 MCP SDK v2인가? SDK는 FastMCP → MCPServer로 이름을 변경했으며 이제 하나의 프로세스에서 2025 및 2026-07-28 프로토콜 개정판을 모두 제공합니다. pip install mcp는 v2를 설치합니다. 유지 관리되는 라인(v1 유지 관리 아님)을 기반으로 구축하는 것이 방어 가능한 선택입니다.

3. 얇은 MCP 계층 / 서비스 계층. 도구 함수는 어댑터입니다. 로직은 인터페이스 뒤의 서비스에 있습니다. 이것이 GitHub, LMS 및 작업을 네트워크 없이 플러그 가능하고 테스트 가능하게 만드는 이유입니다.

4. 멱등성을 위한 부분 고유 인덱스. SQLite가 (source, source_id)에 부분 인덱스가 필요한 이유와 이것이 create_task_from_issue/create_tasks_from_deadlines를 SQL 깊이에 대한 작고 합리적인 데모로 안전하게 만드는 방법을 설명하세요.

5. GitHub 403 모호성. 금지됨과 속도 제한은 x-ratelimit-remaining 응답 헤더를 통해 구분됩니다 — 실제 API 통합의 미묘함이지, 전설이 아닙니다.

6. 최소 권한 토큰. Issues: Read & Write만 있는 세분화된 PAT와 기존 repo 범위 토큰. "이유"를 완벽히 알아두세요.

7. 오류 분류. 안정적인 AI 읽기 가능 코드에 매핑된 하나의 예외 계층 구조, 스택 추적은 로그에만 기록됩니다. 신뢰성은 사후 고려 사항이 아닌 설계 목표입니다.

8. 프로토콜 계층 테스트. 인메모리 Client(server)는 MCP 배선이 클라이언트가 사용하는 것과 정확히 동일하게 테스트됨을 의미합니다.

9. 솔직한 범위. LMS는 명시적으로 모의되었습니다. SQLite는 단일 사용자입니다 — "개인 생산성 도구"이지 엔터프라이즈 다중 사용자 제품을 주장하는 것이 아닙니다.

라이선스

MIT — LICENSE 참조. Copyright (c) 2026 Mahendra Vattikuti.