AI导哈

AI问答助手服务

一个基于FastAPI的AI问答助手服务，通过Chrome扩展获取会话信息，利用Google Gemini处理自然语言问题并查询BIP数据。

  • by thanushri-10
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 thanushri-10/mcp-server

使用说明

BIP MCP服务器项目

该项目与BIT信息门户（BIP）集成，提供一个能够回答有关BIP数据的自然语言问题的人工智能助手。它由模型上下文协议（MCP）服务器、用于会话管理的Chrome浏览器扩展程序和web应用程序前端的占位符组成。

项目结构

该项目以单仓库的形式组织，主要由以下部分组成：

  • packages/mcp_server/：基于FastAPI的核心MCP服务器。此服务器与BIP API交互，并使用语言模型（LLM）来处理用户查询。
  • packages/bip-extension/：Chrome浏览器扩展程序，用于捕获活动的BIP会话Cookie并将其安全地传输到MCP服务器。
  • apps/web/：一个React/Vite前端应用程序（目前是一个占位符，用于用户与助手的交互）。
  • apps/api/：与此项目相关的潜在未来独立API的占位符。
  • memory_bank：用于存储长期项目背景、指导方针和架构决策的概念文件。

特性

1.MCP服务器(packages/mcp_server)

  • FastAPI框架：使用现代高性能FastAPI框架构建。
  • BIP集成：通过利用通过Chrome扩展程序获得的会话Cookie，安全地连接到实时BIP门户。
  • 人工智能助手(/assistant/ask 端点）:
    • 自然语言理解：接受用户以自然语言提出的问题。
    • API智能路由：使用LLM（Google Gemini）根据用户的问题确定要查询的最相关的BIP API端点。目前支持：
      • /nova-api/students （学生简介）
      • /nova-api/departments （部门列表）
      • /nova-api/academic-feedbacks （给用户的学术反馈）
      • /nova-api/student-activity-masters （大学活动一览表）
      • /nova-api/student-achievement-loggers （登录学生的个人成就/参与情况）
      • /nova-api/academic-course-faculty-mappings （教师对课程的分配）
    • 上下文查询参数化：使用LLM从用户的问题中提取实体（如学生姓名、事件名称、部门名称、地点、关键字）。这些用于构造具有的目标API调用 search 和 filters 参数。
    • 优化数据获取:
      • 对于特定的实体查询，获取最少的数据。
      • 对于更广泛的列表查询，使用分页(perPage=150)并根据需要获取多个页面（达到安全限制）。
    • 数据解析和规范化：将来自BIP API的复杂JSON响应解析为更统一的格式。
    • LLM生成的答案：使用LLM根据检索到的数据合成自然语言答案。
      • 组块：通过将大型数据集拆分为更小的块供LLM处理来处理，同时尊重令牌限制。
      • 提前退出：对于特定的实体查询，如果在早期块中找到答案，则停止进一步处理以提高效率。
      • 音调定制提示旨在为助手提供一种乐于助人、略带诙谐和人性化的语气。
    • 拼写错误容忍度：查询理解LLM对用户问题中的轻微拼写有一定的内置容忍度。
    • 用户上下文查询：可以通过首先获取登录学生的详细信息（部门、学期），然后使用该上下文查询相关课程-教师映射来处理“Faculties teaching me”等查询。
  • 会话管理:
    • 接收BIP会话Cookie(bip_session, XSRF-TOKEN, wiki_wiki_UserID, wiki_wiki_UserName)通过专用端点从Chrome扩展程序(/bip/session/bip).
    • 将这些Cookie安全地存储在服务器端会话中（使用 starlette.middleware.sessions).
    • 将这些存储的Cookie用于对BIP的所有后续身份验证请求。
  • 缓存：实现部门数据缓存，以减少冗余的API调用。
  • 配置：使用a .env 用于管理敏感信息的文件，如 GOOGLE_API_KEY.

2.BIP Chrome扩展程序(packages/bip-extension)

  • 目的：从用户浏览器中的活动BIP会话中安全地捕获必要的会话Cookie。
  • 功能:
    • 弹出式UI允许用户触发cookie捕获。
    • 后台脚本读取Cookie bip.bitsathy.ac.in 域。
    • 将捕获的Cookie发送到MCP服务器 /bip/session/bip 终点。

3.Web应用程序(apps/web)

  • 技术：使用React和Vite构建。
  • 目的：旨在作为与AI助手交互的主要用户界面。
  • 当前状态：基础Vite/React模板。与MCP服务器集成 /assistant/ask 端点是未来的任务。

设置和运行

先决条件

  • Python 3.10+
  • Node.js和npm（用于开发web应用程序）
  • 访问Google Gemini API（需要 GOOGLE_API_KEY)
  • BIP门户上的活动帐户和会话。

1.MCP服务器(packages/mcp_server)

  1. 导航到项目根目录（例如。， bip-mcp-server): 确保您的终端位于主项目目录中，而不是内部 packages/mcp_server.
  2. 创建并激活虚拟环境（最好在项目根目录中或 packages/mcp_server): 如果创建于 packages/mcp_server:
    cd packages/mcp_server
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
cd ../.. # Go back to project root
    如果在项目根目录中创建：
    python -m venv .venv 
source .venv/bin/activate # On Windows: .venv\Scripts\activate
  3. 安装Python依赖项（确保您的虚拟环境处于活动状态）：
    pip install -r packages/mcp_server/requirements.txt
  4. 配置环境变量： 创建一个 .env 文件在 packages/mcp_server 目录（即。， packages/mcp_server/.env)使用您的Google API密钥：
    GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY_HERE"
# Optional: Define a custom MCP_SERVER_SESSION_SECRET_KEY for Starlette sessions
# MCP_SERVER_SESSION_SECRET_KEY="your_strong_random_secret_key"
  5. 运行MCP服务器（从项目根目录）：
    uvicorn packages.mcp_server.main:app --reload --port 8000
    服务器将在以下时间可用 http://localhost:8000.API文档（Swagger UI）将在 http://localhost:8000/docs.

2.BIP Chrome扩展程序(packages/bip-extension)

  1. 打开谷歌Chrome浏览器并导航到 chrome://extensions.
  2. 启用“开发人员模式”（通常是右上角的切换）。
  3. 单击“加载解包”。
  4. 选择 packages/bip-extension 这个项目的目录。
  5. 扩展程序图标应出现在Chrome工具栏中。

3.使用系统

  1. 登录BIP门户(https://bip.bitsathy.ac.in)在您的Chrome浏览器中。

  2. 点击“BIP会话同步”Chrome扩展程序图标。

  3. 单击扩展弹出窗口中的“将BIP会话与MCP服务器同步”按钮。这将把您的BIP Cookie发送到在上运行的MCP服务器 http://localhost:8000.

  4. 现在，您可以将查询发送到MCP服务器 /assistant/ask 端点（例如，使用Postman、curl或最终使用web应用程序）。

    示例 curl 为了 /assistant/ask:

    curl -X POST http://localhost:8000/assistant/ask \
-H "Content-Type: application/json" \
-b "mcp_server_session=YOUR_MCP_SERVER_SESSION_COOKIE_FROM_BROWSER_DEVTOOLS_AFTER_SYNC" \
-d '{
    "user_question": "Who teaches Business Analytics and Intelligence?",
    "item_id": null
}'

    （注： mcp_server_session cookie由MCP服务器在初始同步后自行设置。通常，在与设置会话的服务器首次交互后，您会从浏览器的开发人员工具中获取此信息，或者依赖HTTP客户端来管理Cookie。)

4.Web应用程序(apps/web)（可选开发）

  1. 导航到web应用程序目录：
    cd apps/web
  2. 安装Node.js依赖项：
    npm install
  3. 运行开发服务器：
    npm run dev

关键技术

  • 后端（MCP服务器）：Python、FastAPI、Uvicorn、HTTPX、Pydantic
  • AI/LLM：Google Gemini API
  • 浏览器扩展：JavaScript、HTML、CSS（标准Chrome扩展技术）
  • 前端（Web应用程序）：React、Vite、TypeScript（目前为占位符）
  • Monorepo管理：隐式（手动目录结构）

未来的改进/工作领域

  • 精炼LLM提示：不断改进路径选择、查询理解和答案生成的提示，以提高准确性和语气。
  • 高级迭代推理：对需要顺序信息收集的查询实施更复杂的多步骤推理（例如，“本学期教授我特定选修课的学院”）。
  • 错误处理和稳健性：增强对API故障、意外数据结构和LLM问题的错误处理。
  • 过滤器结构：开发更复杂的逻辑来构建精确的 filters BIP API的参数基于提取的查询详细信息，而不是仅依赖于 search 某些情况下的参数。
  • Web应用程序开发：充分开发 apps/web 前端为助手提供用户友好的界面。
  • 安全：审查和增强安全方面，尤其是会话管理和API密钥处理方面。
  • 测试：添加全面的单元和集成测试。
  • 内存库集成：开发一个系统来利用 memory_bank 用于持久的项目上下文。
  • 配置管理：如果需要，可以将更多配置（例如，API路径、默认参数）移动到更结构化的配置系统。

相关 MCP