내 커스텀 MCP 서버를 테스트하기 위한 저장소입니다

COMP3900 프로젝트 설치 서버

comp3900_server.py는 https://github.com/arctic-cheetah/COMP3900-Project 프로젝트 전용 MCP 서버입니다. 이 서버는 다음을 수행할 수 있습니다:

• 고정된 저장소를 MCP 서버가 실행 중인 머신에 클론합니다;

• 프로젝트 README와 제한된 프로젝트 파일 읽기를 LLM에 노출합니다;

• Playwright의 Chromium 사용 가능 여부를 포함한 사전 요구 사항을 확인합니다;

• 백엔드, Playwright Chromium, 프론트엔드를 로컬에 설치합니다;

• 문서화된 Docker Compose 스택을 빌드/시작합니다; 또는

• 선택적으로 cloudflared 클라이언트를 설치합니다(아래 참조).

다운로드는 기본적으로 ./COMP3900-Project에 저장됩니다. 다른 위치를 사용하려면 COMP3900_PROJECT_DIR을 명시적인 프로젝트 디렉터리로 설정하세요.

먼저 이 MCP 서버의 의존성을 설치하세요:

python3 -m pip install -r requirements.txt

stdio로 실행하세요:

mcp run comp3900_server.py:mcp

또는 직접 실행하세요:

python3 comp3900_server.py

MCP 클라이언트에서 안내 워크플로를 위해 install_comp3900 프롬프트를 선택하거나 setup_project를 직접 호출하세요. 로컬 설치를 위한 예시 인수:

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

Docker의 경우 "method": "docker"를 사용하세요. 빌드 후 스택을 백그라운드에서 실행하려면 "start_services": true로 설정하세요.

Playwright

URL 감지기의 HTML 가져오기 엔진은 Playwright에서 실행되므로 실제 요구 사항입니다: backend/pyproject.toml에 playwright가 나열되어 있으며, backend/Dockerfile과 operational-install-manual.md 모두 playwright install --with-deps chromium을 실행합니다.

install_browser_system_dependencies는 이제 문서화된 단계와 일치하도록 기본값이 true입니다. 이 옵션은 Chromium의 공유 라이브러리를 위해 플랫폼 패키지 관리자를 호출하므로, 서버가 이미 root로 실행되고 있지 않은 호스트에서는 권한 상승을 요청할 수 있습니다. 해당 라이브러리를 직접 설치하려면 false로 설정하세요. check_prerequisites는 url_detector_ready를 보고하며, 이 값은 Playwright 모듈과 해당 Chromium 브라우저가 모두 확인될 때만 true입니다.

cloudflared

install_cloudflared는 공식 릴리스 바이너리를 <checkout>/.tools/cloudflared에 다운로드하고 해당 sha256을 보고합니다. install_project와 setup_project에서는 기본적으로 꺼져 있습니다. 포함하려면 "install_cloudflare_tunnel_client": true를 전달하세요.

알아두면 좋은 두 가지 주의 사항:

• Cloudflare는 COMP3900 프로젝트의 의존성이 아닙니다. README, 설치 매뉴얼 또는 어떤 매니페스트에도 나타나지 않습니다. 저장소에서 유일하게 나타나는 곳은 backend/ml/data/ 아래의 ML 학습 CSV 내부에 있는 cdnjs.cloudflare.com과 같은 도메인 문자열뿐입니다.

• 서버는 클라이언트만 설치합니다. Cloudflare에 인증하거나 터널을 시작하지 않습니다. 터널을 실행하면 로컬 서비스가 공개 인터넷에 노출되기 때문입니다. 이는 의도적인 사람의 수동 단계로 남아 있습니다.

체크아웃 디렉터리에 설치하면 권한 없는 작업이 유지됩니다: 시스템 패키지 관리자가 실행되지 않으며 프로젝트 디렉터리 밖에는 아무것도 기록되지 않습니다.

Related MCP server: homelab-mcp

지침

프로젝트 디렉터리에서 대화형 MCP Inspector를 실행하세요:

mcp dev server.py

이 명령은 로컬 Inspector URL을 출력합니다. URL을 열고 연결한 후 add 도구를 선택하고 다음을 제공하세요:

{
  "a": 1,
  "b": 2
}

결과는 3이어야 합니다.

MCP 클라이언트용 일반 stdio MCP 서버로 실행하려면:

mcp run server.py:mcp

현재 python server.py를 실행하면 파일이 서버만 정의하므로 즉시 종료됩니다. 해당 명령을 지원하려면 다음을 추가하세요:

if __name__ == "__main__":
    mcp.run()

그런 다음 실행하세요

python3 server.py

다른 머신에 MCP가 설치되어 있지 않은 경우:

python3 -m pip install "mcp[cli]"

그런 다음

mcp dev server.py

배포:

코드 블록 변경 사항에 대한 설명입니다: 기존 콘텐츠 뒤에 README.md에 연결 가이드(STDIO 및 HTTP 옵션)를 추가합니다.

제안된 코드 변경을 나타내는 코드 블록입니다:

ChatGPT Desktop에 연결하기

옵션 1: STDIO로 연결(권장)

서버가 현재 WSL 내에서 실행되므로 데스크톱 양식을 다음과 같이 작성하세요:

• 이름: MCP_test

• 유형: STDIO

• 실행 명령: wsl.exe

• 인수: 각 항목을 이 순서대로 개별적으로 추가하세요:

  --cd
  /home/khalifa/MCP-server
  --exec
  /home/khalifa/pythonPackages/bin/mcp
  run
  server.py:mcp

• 환경 변수: 비워 두세요

• 작업 디렉터리: 비워 두세요

잘못된 WSL 배포판이 선택된 경우 다음 인수를 먼저 삽입하세요:

--distribution
Ubuntu

Ubuntu를 다음 명령이 보고하는 이름으로 바꾸세요:

wsl.exe --list --verbose

따라서 실제로는 다음과 같습니다:

• 인수: 각 항목을 이 순서대로 개별적으로 추가하세요:

  --distribution
  kali-linux
  --cd
  /home/khalifa/MCP-server
  --exec
  /home/khalifa/pythonPackages/bin/mcp
  run
  server.py:mcp

서버를 저장하고 데스크톱 앱을 다시 시작하세요. 채팅에서 다음을 입력하세요:

/mcp

MCP_test와 해당 add 도구가 표시되어야 합니다. 다음을 시도하세요:

Use the MCP_test add tool to add 17 and 25.

공식 OpenAI 문서는 데스크톱 앱이 로컬 STDIO 프로세스와 Streamable HTTP 서버를 모두 지원한다고 확인합니다. 또한 구성 저장 후 다시 시작해야 합니다. OpenAI MCP 문서

옵션 2: HTTP로 서버 실행

mcp dev를 중지한 후 다음을 실행하세요:

cd /home/khalifa/MCP-server
mcp run server.py:mcp --transport streamable-http

기본 MCP 엔드포인트는 다음과 같습니다:

http://127.0.0.1:8000/mcp

데스크톱 양식에서:

• 이름: MCP_test_http

• 유형: Streamable HTTP

• URL: http://127.0.0.1:8000/mcp

이 모드에는 실행 명령이나 인수가 없습니다. HTTP 서버가 이미 실행 중이어야 합니다.

포트 8000이 사용 중인 경우 server.py에 다음을 추가하세요:

if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="127.0.0.1",
        port=8001,
    )

그런 다음 실행하세요:

python3 server.py

이 데스크톱 URL을 사용하세요:

http://127.0.0.1:8001/mcp

HTTP 요청으로 호출하기

MCP는 기존 REST API가 아닌 JSON-RPC입니다. 따라서 브라우저 주소 표시줄에서 /mcp를 열어도 add가 호출되지 않습니다. MCP 세션을 초기화한 다음 도구를 호출해야 합니다.

초기화:

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\"}}}"

Mcp-Session-Id 응답 헤더의 값을 복사하세요. 그런 다음 add를 호출하세요:

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}}}"

브라우저 기반 대화형 테스트의 경우 이미 보유한 Inspector가 JSON-RPC 세션을 수동으로 관리하는 것보다 쉽습니다. HTTP 엔드포인트는 주로 ChatGPT Desktop, Codex 또는 Inspector와 같은 MCP 클라이언트를 위한 것이며, 직접 브라우저 탐색을 위한 것이 아닙니다.