Skip to content
Back to search

PUCIT_CGPA_Calculator_MCP_Server

FastMCP server providing PUCIT BS(CS) GPA, CGPA, credit hour, target planning, and report tools over Streamable HTTP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/muhammadhuzaifafarrukh--pucit-cgpa-calculator-mcp-server/badge.svg)](/listings/muhammadhuzaifafarrukh--pucit-cgpa-calculator-mcp-server)

HTML

<a href="/listings/muhammadhuzaifafarrukh--pucit-cgpa-calculator-mcp-server"><img src="/api/listings/muhammadhuzaifafarrukh--pucit-cgpa-calculator-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

From the repository root:

pip install -r requirements.txt

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 220 lines
  1. # PUCIT BS(CS) Academic Advisor Agent
  2. An interactive command-line academic advising assistant for **PUCIT BS(CS)** students, built with LangChain/LangGraph and connected to a FastMCP tool server. It helps with degree and course lookups, GPA/CGPA and credit-hour calculations, multi-semester GPA target planning, saving confirmed summary reports, and keeping persistent per-student conversation threads.
  3. **Hosted MCP server:**
  4. ```text
  5. https://pucit-cgpa-advisor.fastmcp.app/mcp
  6. ```
  7. ---
  8. ## Features
  9. - **Tool-backed calculations only:** All GPA, CGPA, credit-hour, and required-GPA calculations are delegated to MCP tools rather than done mentally, so every number comes directly from a tool response.
  10. - **PUCIT special course rules:**
  11. - Math Deficiency courses (`MD-001`, `MD-002`) are excluded from GPA calculations as non-credit pass/fail courses.
  12. - Quran Translation courses (`HQ-001` through `HQ-008`, `0.5` credit hours each) are included in all calculations.
  13. - **Automatic horizon widening for unreachable targets:** A required GPA above `4.0` in a single semester is treated as unreachable. The planner then widens the horizon across additional remaining semesters until a realistic required GPA (`<= 4.0`) is found.
  14. - **Confirmation-gated report saving:** The agent offers to save a summary report via `save_report` only after delivering a complete calculation or advising plan (never for quick lookups), and only after explicit student confirmation.
  15. - **Persistent SQLite memory (`AsyncSqliteSaver`):** Conversation checkpoints are stored per `thread_id` in `cgpa_memory.db`, so chat history survives CLI restarts and thread switches.
  16. - **Real-time streaming:** Tool progress and model output are streamed using `app.astream(..., stream_mode=["updates", "messages"], version="v2")`.
  17. - **Dangling tool call recovery:** Incomplete `tool_calls` in thread state are repaired with `repair_dangling_tool_calls` after interruptions or errors.
  18. ---
  19. ## Session Commands
  20. | Command | Description |
  21. |---|---|
  22. | `/switch` | Change the active `thread_id` |
  23. | `/history` | Inspect saved messages and tool calls |
  24. | `/forget` | Delete saved checkpoints for the active thread |
  25. | `exit` / `quit` | End the CLI session |
  26. ---
  27. ## Project Structure
  28. ```text
  29. ├── agent/
  30. │ ├── main.py # CLI entry point, streaming, SQLite checkpointer, commands, recovery
  31. │ ├── llm.py # LLM model configuration
  32. │ ├── requirements.txt # Agent Python dependencies
  33. │ └── .env.example # Example environment variables (add your own keys)
  34. ├── server.py # FastMCP server exposing academic advising tools
  35. ├── tools.py # GPA, CGPA, credit-hour, target-GPA, and report tools
  36. └── requirements.txt # Server Python dependencies
  37. ```
  38. ---
  39. ## How It Works
  40. The project has two parts:
  41. 1. **MCP server (`server.py` + `tools.py`):** exposes the GPA, CGPA, credit-hour, target-GPA, and report tools. It is hosted at the URL above, and you can also run it locally.
  42. 2. **Agent (`agent/`):** the CLI app that runs on your own machine. It connects to an MCP server over HTTP using `MCP_URL`.
  43. Your CLI and SQLite memory (`cgpa_memory.db`) always run on your computer. Only the tool execution happens on the MCP server, which is local or hosted depending on the method you choose.
  44. Choose one of the two methods below.
  45. | | Method A: Full project (local server) | Method B: Agent only (hosted server) |
  46. |---|---|---|
  47. | Files needed | Whole repo | `agent/` folder only |
  48. | Server runs | On your machine | On the hosted server |
  49. | `MCP_URL` | `http://127.0.0.1:8000/mcp` | `https://pucit-cgpa-advisor.fastmcp.app/mcp` |
  50. | `FASTMCP_KEY` | Not needed for the local server | Required (bearer token) |
  51. | Terminals | 2 | 1 |
  52. ---
  53. ## Prerequisites
  54. - Python 3.10+
  55. - A Groq API key (`GROQ_API_KEY`)
  56. ---
  57. ## Method A: Full Project Files (Local Server)
  58. Use this if you have the complete repository and want to run the MCP tools on your own machine.
  59. ### 1. Clone the repository
  60. ```bash
  61. git clone https://github.com/MuhammadHuzaifaFarrukh/PUCIT_CGPA_Calculator_MCP_Server.git
  62. cd PUCIT_CGPA_Calculator_MCP_Server
  63. ```
  64. ### 2. Install server dependencies
  65. From the repository root:
  66. ```bash
  67. pip install -r requirements.txt
  68. ```
  69. ### 3. Install agent dependencies
  70. ```bash
  71. cd agent
  72. pip install -r requirements.txt
  73. ```
  74. or install the packages directly:
  75. ```bash
  76. pip install python-dotenv fastmcp langchain langchain-core langchain-groq langgraph-checkpoint-sqlite
  77. ```
  78. ### 4. Configure environment variables
  79. Copy `.env.example` to `.env` inside the `agent/` directory and fill in your values:
  80. ```env
  81. GROQ_API_KEY="YOUR_KEY"
  82. MCP_URL=http://127.0.0.1:8000/mcp
  83. FASTMCP_KEY=
  84. ```
  85. ### 5. Start the MCP server
  86. Open a terminal in the repository root (where `server.py` is) and run:
  87. ```bash
  88. python server.py # or: py server.py
  89. ```
  90. Keep it running so it listens on `http://127.0.0.1:8000/mcp`.
  91. ### 6. Start the agent
  92. Open a **second** terminal in the `agent/` folder and run:
  93. ```bash
  94. python main.py # or: py main.py
  95. ```
  96. ---
  97. ## Method B: Agent Files Only (Hosted Server)
  98. Use this if you do **not** have the server files and do not want to run the server yourself. You only need the `agent/` folder. The tools run on the hosted server.
  99. ### 1. Get the agent files
  100. Clone the repository and use only the `agent/` folder:
  101. ```bash
  102. git clone https://github.com/MuhammadHuzaifaFarrukh/PUCIT_CGPA_Calculator_MCP_Server.git
  103. cd PUCIT_CGPA_Calculator_MCP_Server
  104. ```
  105. Or download just the `agent/` folder and open a terminal inside it.
  106. ### 2. Install dependencies
  107. ```bash
  108. pip install -r requirements.txt
  109. ```
  110. or install the packages directly:
  111. ```bash
  112. pip install python-dotenv fastmcp langchain langchain-core langchain-groq langgraph-checkpoint-sqlite
  113. ```
  114. ### 3. Configure environment variables
  115. Copy `.env.example` to `.env` inside the `agent/` directory and fill in your own keys:
  116. ```env
  117. GROQ_API_KEY="YOUR_GROQ_API_KEY"
  118. MCP_URL=https://pucit-cgpa-advisor.fastmcp.app/mcp
  119. FASTMCP_KEY="YOUR_FASTMCP_BEARER_TOKEN"
  120. ```
  121. | Variable | Description |
  122. |---|---|
  123. | `GROQ_API_KEY` | Your own Groq API key for the LLM |
  124. | `MCP_URL` | The hosted MCP endpoint shown above |
  125. | `FASTMCP_KEY` | A valid bearer token that authorizes access to the hosted server |
  126. ### 4. Run the agent
  127. ```bash
  128. python main.py # or: py main.py
  129. ```
  130. No local `server.py` is needed. Your CLI and `cgpa_memory.db` run on your computer, and tool calls are sent to the hosted server.
  131. ---
  132. ## Chatting with the Advisor
  133. Once `main.py` is running (with either method):
  134. 1. When prompted, enter a student name or `thread_id`. Existing saved threads are shown on startup.
  135. 2. Ask an advising, course, or GPA planning question and watch the streamed tool and advisor output.
  136. 3. Use `/history`, `/switch`, or `/forget` at any time, or type `exit` to quit.
  137. ---
  138. ## Error Handling & Recovery
  139. - **Before each turn and on any exception**, `repair_dangling_tool_calls` inspects the active thread's state for `AIMessage` tool calls that never received a matching `ToolMessage`. It patches them with a recovery `ToolMessage` so later turns stay intact.
  140. - **Connection drops and streaming errors** during a turn or MCP session are caught and surfaced cleanly in the CLI. You can retry, switch threads, or check the server without the program crashing.
  141. ---
  142. ## Troubleshooting
  143. | Problem | Fix |
  144. |---|---|
  145. | Connection refused / timeout | Check that `MCP_URL` is correct and ends in `/mcp`. For Method A, make sure `server.py` is still running |
  146. | `401` / unauthorized | Check that `FASTMCP_KEY` is a valid bearer token and is set in `agent/.env` (Method B) |
  147. | Tools not found | Make sure `MCP_URL` points to the right server and that it is running the latest `server.py` and `tools.py` |
  148. | Groq errors | Verify `GROQ_API_KEY` is valid and has not hit its rate limit |

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.