# This is the repo for testing my custom MCP-server

## COMP3900 project installer server

`comp3900_server.py` is a dedicated MCP server for the project at
<https://github.com/arctic-cheetah/COMP3900-Project>. It can:

- clone the fixed repository onto the machine running the MCP server;
- expose the project README and bounded project-file reads to the LLM;
- check prerequisites, including whether Playwright's Chromium is usable;
- install the backend, Playwright Chromium, and frontend locally;
- build/start the documented Docker Compose stack; or
- optionally install the `cloudflared` client (see below).

The download goes to `./COMP3900-Project` by default. To use another location,
set `COMP3900_PROJECT_DIR` to an explicit project directory.

Install this MCP server's dependency first:

```bash
python3 -m pip install -r requirements.txt
```

Run it over stdio:

```bash
mcp run comp3900_server.py:mcp
```

Or launch it directly:

```bash
python3 comp3900_server.py
```

In an MCP client, select the `install_comp3900` prompt for a guided workflow,
or call `setup_project` directly. Example arguments for a local installation:

```json
{
  "method": "local",
  "install_browser": true,
  "install_browser_system_dependencies": true,
  "start_services": false,
  "install_cloudflare_tunnel_client": false
}
```

For Docker, use `"method": "docker"`; set `"start_services": true` to run
the stack in the background after building it.

### Playwright

The URL detector's HTML fetch engine runs on Playwright, so it is a genuine
requirement: `backend/pyproject.toml` lists `playwright`, and both
`backend/Dockerfile` and `operational-install-manual.md` run
`playwright install --with-deps chromium`.

`install_browser_system_dependencies` now defaults to `true` to match that
documented step. It shells out to the platform package manager for Chromium's
shared libraries, so on a host where the server does not already run as root it
can prompt for elevation. Set it to `false` if you would rather install those
libraries yourself. `check_prerequisites` reports `url_detector_ready`, which is
true only when both the Playwright module and its Chromium browser resolve.

### cloudflared

`install_cloudflared` downloads the official release binary into
`<checkout>/.tools/cloudflared` and reports its sha256. It is off by default in
`install_project` and `setup_project`; pass
`"install_cloudflare_tunnel_client": true` to include it.

Two caveats worth knowing:

- Cloudflare is **not** a dependency of the COMP3900 project. It appears nowhere
  in the README, the install manual, or any manifest. The only occurrences in the
  repository are domain strings such as `cdnjs.cloudflare.com` inside the ML
  training CSVs under `backend/ml/data/`.
- The server installs the client only. It never authenticates to Cloudflare and
  never starts a tunnel, because running one publishes a local service on the
  public internet. That remains a deliberate human step.

Installing into the checkout keeps the operation unprivileged: no system package
manager runs and nothing is written outside the project directory.


## Instructions
From the project directory, launch the interactive MCP Inspector:

```python
mcp dev server.py
```

The command prints a local Inspector URL. Open it, connect, select the add tool, and provide:
```
{
  "a": 1,
  "b": 2
}
```

The result should be 3.


To run it as a normal stdio MCP server for an MCP client:
```
mcp run server.py:mcp
```

Running python `server.py` currently exits immediately because the file only defines the server. To support that command, append:
```
if __name__ == "__main__":
    mcp.run()
```

Then run
```
python3 server.py
```


If MCP is not installed on another machine:
```
python3 -m pip install "mcp[cli]"
```
Then
```
mcp dev server.py
```

## Deployments:
This is the description of what the code block changes:
<changeDescription>
Adding the connection guide (STDIO and HTTP options) to README.md after the existing content.
</changeDescription>

This is the code block that represents the suggested code change:
## Connecting to ChatGPT Desktop

### Option 1: Connect through STDIO (recommended)

Because the server currently runs inside WSL, fill the desktop form as follows:

- **Name:** `MCP_test`
- **Type:** STDIO
- **Command to launch:** `wsl.exe`
- **Arguments:** add each item separately, in this order:
  ```
  --cd
  /home/khalifa/MCP-server
  --exec
  /home/khalifa/pythonPackages/bin/mcp
  run
  server.py:mcp
  ```
- **Environment variables:** leave empty
- **Working directory:** leave empty

If the wrong WSL distribution is selected, insert these arguments first:
```
--distribution
Ubuntu
```

Replace `Ubuntu` with the name reported by:
```bash
wsl.exe --list --verbose
```

So effectively it looks like:

- **Arguments:** add each item separately, in this order:
  ```
  --distribution
  kali-linux
  --cd
  /home/khalifa/MCP-server
  --exec
  /home/khalifa/pythonPackages/bin/mcp
  run
  server.py:mcp
  ```

Save the server and restart the desktop app. In a chat, enter:
```
/mcp
```
You should see `MCP_test` and its `add` tool. Try:
```
Use the MCP_test add tool to add 17 and 25.
```

The official OpenAI documentation confirms that the desktop app supports both local STDIO processes and Streamable HTTP servers. It also requires restarting after saving the configuration. [OpenAI MCP documentation](https://openai.com/index/mcp-for-developers/)

### Option 2: Run the server over HTTP

Stop `mcp dev`, then run:
```bash
cd /home/khalifa/MCP-server
mcp run server.py:mcp --transport streamable-http
```

The default MCP endpoint is:
```
http://127.0.0.1:8000/mcp
```

In the desktop form:

- **Name:** `MCP_test_http`
- **Type:** Streamable HTTP
- **URL:** `http://127.0.0.1:8000/mcp`

There is no launch command or arguments for this mode. The HTTP server must already be running.

If port 8000 is occupied, add this to `server.py`:
```python
if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="127.0.0.1",
        port=8001,
    )
```

Then run:
```bash
python3 server.py
```

Use this desktop URL:
```
http://127.0.0.1:8001/mcp
```

### Calling it with an HTTP request

MCP is JSON-RPC, not a conventional REST API. Opening `/mcp` in the browser address bar will therefore not invoke `add`. You must initialize an MCP session and then call the tool.

**Initialize:**
```bash
curl.exe -i -N http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{},\"clientInfo\":{\"name\":\"curl\",\"version\":\"1.0\"}}}"
```

Copy the value of the `Mcp-Session-Id` response header. Then call `add`:
```bash
curl.exe -N http://127.0.0.1:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: PASTE_SESSION_ID_HERE" \
  --data "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"add\",\"arguments\":{\"a\":17,\"b\":25}}}"
```

For browser-based interactive testing, the Inspector you already have is easier than manually managing the JSON-RPC session. The HTTP endpoint is primarily intended for MCP clients such as ChatGPT Desktop, Codex, or the Inspector—not direct browser navigation.