AI 学生开发者助手 — MCP 服务器

一个生产级的 Model Context Protocol 服务器，为 AI 助手提供对您的 GitHub Issues、学术截止日期（LMS）以及 个人任务追踪器 的统一访问——从而使其能够回答诸如“我今天该做什么？”这样的问题，并给出一个真实且经过优先级排序的答案。

基于 Python 3.12+、官方 MCP Python SDK（v2）、FastAPI 风格的服务分离、SQLite 和 httpx 构建。已通过模拟外部 API 完成全面测试——运行测试套件无需真实凭据。

目录

• 项目概述

• 功能特性——MCP 工具

• 架构

• 技术栈

• 安装

• 配置

• 运行服务器

• 连接 AI 客户端

• 使用示例

• API 集成

• 数据库

• 测试

• 安全性

• 局限性

• 未来改进

• 项目架构

• 演示场景

• 面试谈论要点

项目概述

问题所在。 学生开发者的工作分散在三个互不关联的地方：GitHub 上的代码任务、大学 LMS 中的作业和考试，以及散落在笔记中的个人待办事项。优先级靠记忆决定，因此事情容易被遗漏。

解决方案。 一个 MCP 服务器，将这三个来源暴露为小型、描述清晰、强类型的 工具。AI 助手可以同时读取并推理所有这些数据：它可以拉取分配给您的 Issues、本周的截止日期、待办任务，检测逾期项，构建一个按优先级排序的摘要——并且通过相同的接口 修改 系统（创建/关闭 Issues、创建任务、批量导入截止日期）。

状态。 这是一个达到作品集质量的 个人生产力工具 实现。所有功能端到端均可工作；LMS 集成故意通过可替换接口进行模拟（参见局限性）。

功能特性——MCP 工具

十五个范围狭窄的工具。每个都有清晰的名称、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 → 设置 → 开发者设置 → 个人访问令牌 → 细粒度令牌 → 生成新令牌 → 仅选择您需要的仓库 → 仅授予 Issues：读取和写入。

⚠️ .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（通过 设置 → 开发者 → 编辑配置 打开），完全退出并重新启动：

{
  "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 不会继承您的 shell PATH 或工作目录。

• 使用 where python / where git 确认确切解释器路径。

• 保存后，完全重启 Claude Desktop，然后查看连接器/消息框菜单以找到服务器及其工具。

• 失败时的日志：%APPDATA%\Claude\logs\mcp*.log。

替代方案

• MCP 检查器（无需配置）：mcp dev app/server.py 为您提供一个图形界面，可以手动调用每个工具——非常适合演示。

• Cursor——.cursor/mcp.json 使用相同的 mcpServers 格式。

• 服务器与传输方式无关：同一个 MCPServer 稍后可以通过 Streamable HTTP 提供服务（参见未来改进）。

使用示例

用户： 目前有哪些开放的 GitHub Issues？

代理调用 get_open_issues（不指定仓库 → 分配给您的 Issues），然后总结：

您有 2 个开放的 Issues 分配给您：“修复登录错误”（#1，bug）和“添加 CI 流水线”（#2）。

用户： 未来 7 天有哪些作业截止？

代理调用 get_upcoming_deadlines，根据今天计算 start/end：

本周截止：小测验 3（数学，8月12日），项目提案草稿（ENG101，8月11日），图遍历作业（CS101，8月13日）。

用户： 为这些作业创建任务。

The agent calls create_tasks_from_deadlines (the server already honors source/source_id dedup, so re-running never duplicates):

已创建 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 错误。

• 拉取请求： issues 端点也会返回 PR；它们通过 pull_request 键被过滤掉。

• 所有网络/超时/错误状态都会被转换为领域异常（参见 安全）。

LMS

本项目的假设是没有合法/可访问的大学 LMS API，因此 LMS 位于一个微型接口（LMSService）之后，并带有一个逼真的模拟实现（MockLMSService），该实现：

• 使用相对于今天的截止日期填充课程目录，

• 验证课程（未知课程 → not_found），

• 验证日期和范围（错误输入 → invalid_input）。

以后添加真实提供程序 = 实现相同的接口 + 设置 LMS_PROVIDER=real。没有抓取受保护的页面；没有任何内容绕过身份验证。 该模拟的行为与真实服务一致，因此应用的其余部分无需修改即可进行测试。

数据库

SQLite 文件位于 DATABASE_PATH（默认 data/tasks.db），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，仅限于特定仓库上的 Issues 读写 — 绝不使用完整的 repo 范围。

• 不记录机密： 一个脱敏过滤器会从日志中清除 Authorization 值；而且由于服务器不会在 stdout 上打印任何内容（日志输出到 stderr），stdio 协议流保持干净。

• 输入验证： 在工具边界使用 Pydantic + 在服务中进行领域验证。

• 参数化 SQL 通过 SQLAlchemy — 没有字符串拼接的查询。

• 受控的错误暴露： AI 获得结构化错误（code、message）；原始堆栈跟踪仅进入服务器日志。

• 最小的客户端暴露： .env 令牌由服务器进程读取，而不是通过客户端配置传递。

另请参阅 面试要点 中以面试为重点的讨论。

局限性

有意的坦诚说明：

• LMS 是模拟的。 LMS_PROVIDER=mock 是唯一的提供程序。必须添加真实的 API 适配器、导出的日历或其他授权数据源才能替换它（可通过 LMSService 接口互换）。

• SQLite 是单用户的。 没有并发保证，没有网络访问，没有后端复制。这是为个人助理特意设计的。

• 尚无 OAuth / HTTP 传输。 GitHub 令牌是静态机密；服务器通过 stdio 运行。适用于本地个人使用；远程/托管使用将需要 OAuth 和 Streamable HTTP。

• 创建 issue 除了自由文本外，不支持显式的分配或正文 Markdown — 故意保持功能精简。

• 截止日期只有小时级粒度 — 没有时区转换；日期按用户提供的 ISO-8601 格式进行比较。

• 导入将可变源项描述为快照：如果某个 GitHub issue 之后被编辑，已创建的任务不会更新（这是设计行为，不是缺陷）。

未来改进

• 真实的 LMSService 适配器（官方 API 或 .ics 日历导出）

• 将 Google Calendar 集成用于截止日期

• 针对逾期任务的 Slack/Teams 通知

• PostgreSQL 后端（仓库层已对此进行抽象）

• 针对 GitHub 的 OAuth + Streamable HTTP 传输 + Docker 部署

• 任务历史/审计表；issue 更新重新同步到任务

• 更丰富的代理工作流（自动分诊、每周“站会”报告资源）

项目架构

按依赖顺序排列的层：

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 是组合根 — 它构建配置 → 数据库 → 服务 → MCPServer，并将工具函数注册到它们所需的服务。没有任何全局变量；测试使用替身组装相同的图。

错误流： 工具 → 服务 → 仓库/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 issue + 即将到来的截止日期 + 待处理/逾期的任务，并给出按优先级排序的回答。

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。版权所有（c）2026 Mahendra Vattikuti。