Claude Desktop (AI Client)
               │
               ▼  (Stdio Protocol)
       [ server.py ] (FastMCP Server Definition)
               │
               ▼
       [ scraper.py ] (Stateful 3-Way ASP.NET Handshake)
               │
               ▼
       [ parser.py ] ──► [ analyzer.py ]
    (HTML Extraction)      (Quality Metrics Engine)
    🛠️ Requirements

    Python 3.10+

    Claude Desktop Application

    Git

📦 Setup & Installation
1. Clone the Repository

Open your terminal or PowerShell and run the following commands to clone the repository to your local machine:
Bash

git clone https://github.com/abbdullahjan/comsats-timetable-mcp.git
cd comsats-timetable-mcp

2. Install Python Dependencies

Install the required packages for asynchronous network requests, HTML parsing, and the core MCP framework:
Bash

python -m pip install httpx beautifulsoup4 lxml mcp

3. Verify the Installation

Run the server entry point locally to verify everything initializes properly:
Bash

python -u server.py

    💡 Note: The terminal will appear to "hang" or pause silently. This is expected behavior! The server communicates exclusively via Standard Input/Output (stdio) channels. Press Ctrl + C to exit; Claude Desktop will spawn and manage this lifecycle automatically.

💻 Connecting to Claude Desktop
1. Install Claude Desktop

If you haven't installed the desktop environment yet:

    Download the app from claude.ai/download.

    Install the application and sign in with your account.

2. Open the Configuration File

Open Claude Desktop, click on your Profile icon in the bottom-left corner, go to Settings, and click the button to open or edit your configuration file (claude_desktop_config.json).

Alternatively, navigate directly to the system paths below:

    Windows: %APPDATA%\Claude\claude_desktop_config.json

    macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Inject the Server Configuration

Append the timetable-mcp configuration block inside your mcpServers section. Make sure to update the absolute path to your exact project directory location:
Windows Example (claude_desktop_config.json)
JSON

{
  "mcpServers": {
    "timetable-mcp": {
      "command": "python",
      "args": [
        "-u",
        "D:\\Field\\Projects\\Cyber\\McpProject\\timetable-mcp\\server.py"
      ]
    }
  }
}

macOS Example (claude_desktop_config.json)
JSON

{
  "mcpServers": {
    "timetable-mcp": {
      "command": "python3",
      "args": [
        "-u",
        "/Users/YourName/Projects/comsats-timetable-mcp/server.py"
      ]
    }
  }
}

    💡 Tip: On Windows, remember to use double backslashes (\\) within the path array items to properly escape JSON strings.

4. Relaunch Claude

Fully close Claude Desktop from your taskbar or system tray and reopen it. If configured successfully, a plug icon (🔌) will appear inside your text input box, indicating the timetable tools are live.
🎯 Usage Examples

Once connected, you don't need to write code or run scripts manually. Simply interact with Claude natively:

    📊 "Fetch the timetable layout for BCS 5A and show me the schedule."

    🔍 "What classes does BSE 4B have on Wednesday mornings?"

    ⚠️ "Analyze my schedule metrics for BCS 5A and highlight any early morning class distributions or heavy days."

📁 Project Structure
Plaintext

comsats-timetable-mcp/
│
├── server.py      # Core FastMCP Application — exposes tools to the LLM runtime
├── scraper.py     # Network Layer — executes multi-step POST handshakes to bypass ViewState guards
├── parser.py      # Dom Extraction — isolates and strips matrix nodes out of raw server responses
├── analyzer.py    # Analytics Layer — computes workload densities and flag parameters
└── README.md      # Documentation Asset

🔧 Troubleshooting

    Missing Plug Icon / "No Tools Available": Ensure Claude Desktop was completely restarted after updating the JSON config file. Check your Windows System Tray to verify it wasn't running silently in the background.

    JSON Syntax Validation Errors: Ensure your config file contains valid commas separating top-level elements. If you have multiple servers running concurrently, verify that keys are delimited by commas cleanly.

    ASP.NET Stateful Falling Back to BBA Timetable: Legacy servers rely heavily on session cookies and token lifecycles. If the dropdown verification step misses an evaluation tick, re-prompt Claude to fire the tool call again to synchronize the state engine.