Jak z ChatGPT zrobić semi-agenta. Własny MCP z folderem, Pythonem, PowerShellem i ngrok

Jeżeli chcesz, żeby ChatGPT naprawdę pomagał przy technicznej robocie, nie potrzebujesz od razu pełnej autonomii. Potrzebujesz modelu, który może dokładnie to, na co mu pozwolisz.

U nas najlepiej sprawdził się wariant pośredni: semi-agent do pracy na jednym repo. Taki układ nie steruje całym systemem. Widzi jeden katalog roboczy, umie czytać i zapisywać pliki tekstowe, potrafi uruchamiać przygotowane skrypty w Pythonie i PowerShellu. I na tym koniec.

To już wystarcza do zaskakująco dużej liczby zadań: poprawy konfiguracji, generowania plików pomocniczych, uruchamiania walidacji, analizy wyników i ponawiania prób. Nadal nie jest to pełny agent. I bardzo dobrze.

Zamiast wielkiego kombajnu postawiliśmy connector minimum. Operacyjnie korzystamy tylko z zestawu narzędzi, który naprawdę ma sens dla codziennej pracy technicznej.

get_root
list_dir
read_file_text
write_file_text
append_file_text
stat_path
search_text
run_python_file
run_powershell

To jest punkt, w którym ChatGPT staje się użyteczny, ale jeszcze nie zamienia się w cyfrowego stażystę z kluczem do serwerowni. Sam serwer może wystawiać więcej funkcji, ale do scenariusza semi-agenta używamy tylko wybranego minimum tooli.

Najważniejszy element bezpieczeństwa nie siedzi w promptach. Siedzi w granicach serwera. Kluczowa zasada była prosta: semi-agent działa tylko w obrębie repo.

Mniej elastyczności, więcej przewidywalności. W praktyce to bardzo dobry interes, bo model nie ma fizycznej możliwości wędrówki poza ustaloną strefę.

Poprzednia wersja tekstu miała istotną lukę. Opisywała uruchomienie i tunelowanie, ale nie prowadziła czytelnika od zera przez instalację FastMCP i instalację ngrok.

To ważne także dlatego, że w naszym repo kod importuje FastMCP, ale obecny requirements.txt nie zawiera jeszcze jawnie pakietu fastmcp. Czyli ktoś, kto postawi środowisko wyłącznie z tego pliku, może skończyć z klasycznym błędem o brakującym module.

Jeżeli startujesz od zera, najpierw przygotuj środowisko:

cd C:\jagoda-memory-api
python -m venv .venv
.\.venv\Scripts\Activate.ps1

Jeżeli PowerShell blokuje aktywację:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

Potem instalujesz zależności z repo:

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

A następnie doinstalowujesz FastMCP:

.\.venv\Scripts\python.exe -m pip install fastmcp

Jeżeli chcesz od razu naprawić projekt, a nie tylko środowisko lokalne, dopisz fastmcp do requirements.txt, żeby kolejna osoba nie musiała zgadywać, czego brakuje.

Na końcu sprawdź, czy FastMCP faktycznie siedzi w środowisku:

fastmcp version

ngrok nie jest częścią repo Python i nie powinien udawać, że nią jest. To osobny składnik infrastrukturalny, instalowany systemowo obok projektu.

Najprostsza ścieżka jest taka: instalujesz ngrok Agent CLI systemowo, logujesz go do swojego konta przez authtoken, sprawdzasz konfigurację i dopiero potem wystawiasz lokalny port.

Po instalacji sprawdzasz, czy narzędzie działa:

ngrok version

Następnie podłączasz konto:

ngrok config add-authtoken <TWOJ_TOKEN>

Potem weryfikujesz konfigurację:

ngrok config check

A jeśli wszystko jest poprawnie, uruchamiasz tunel na lokalny serwer:

ngrok http 8015

Projekt działał lokalnie w katalogu C:\\jagoda-memory-api. Serwer startowaliśmy zwyczajnie:

python server.py

Po poprawnym uruchomieniu aktywny był lokalny endpoint:

http://127.0.0.1:8015/mcp/

Przed startem środowiska warto też sprawdzić bazę, aktywować virtualenv i odświeżyć zależności.

python --version
pip --version
powershell -v

.\.venv\Scripts\Activate.ps1

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Bardzo łatwo po starcie serwera pójść w złą stronę i od razu testować zapis albo wykonywanie skryptów. To jest błąd. U nas najrozsądniej działała taka kolejność:

1. get_root()
2. list_dir('.')
3. read_file_text('README.md')
4. stat_path('README.md')

Ten prosty smoke test odpowiada na cztery najważniejsze pytania: czy serwer stoi na właściwym katalogu, czy umie listować strukturę, czy odczyt plików działa i czy metadane plików są widoczne. Dopiero później warto przechodzić do zapisu, Pythona i PowerShella.

To detal, który potrafi zmarnować pół dnia. W naszym wdrożeniu endpoint /mcp/ odpowiadał, a przy bezpośrednim wejściu mógł zwracać status 406. I to nie oznaczało, że serwer jest zepsuty.

Wręcz przeciwnie. To był sygnał, że endpoint żyje, ale oczekuje poprawnego żądania MCP. Zanim zaczniesz rozkręcać debugging na poziomie kodu, sprawdź warstwę klienta, nagłówki i sposób wołania protokołu.

W technicznym semi-agencie najłatwiej przesadzić właśnie tu. Skrót myślowy „skoro już działa, to dajmy pełny shell” prowadzi prosto do kłopotów.

run_python_file powinien uruchamiać tylko lokalny plik .py z obrębu repo. Model nie wykonuje dowolnego kodu przekazanego jako tekst, tylko wybrany plik istniejący w kontrolowanym katalogu.

print("Hello from MAPI connector minimum")

run_powershell powinien przyjmować niepusty skrypt, mieć limit czasu i pilnować, żeby workdir siedział w repo. Na start najlepiej używać komend nudnych, ale bezpiecznych:

Get-Location
Get-ChildItem
Test-Path .

Sam lokalny serwer to za mało, jeśli ChatGPT ma go zobaczyć spoza Twojej maszyny. I właśnie tu wchodzi ngrok. U nas nie był częścią repo ani zależnością z requirements.txt, tylko osobną warstwą infrastrukturalną.

Najpierw sprawdzasz, czy ngrok w ogóle jest zainstalowany i czy konfiguracja przechodzi walidację:

ngrok version
ngrok config check

U nas problem dotyczył konfiguracji związanej z update_channel. Pomogła taka poprawka:

version: "3"
agent.update_channel: stable
agent.update_check: false

Tunel musi wskazywać na lokalny serwer działający pod http://localhost:8015. Nie tunelujesz „jakiegoś procesu”. Tunelujesz wybrany port, na którym już działa serwer MCP.

Dopiero kiedy lokalny serwer wstaje, port odpowiada, endpoint /mcp/ jest aktywny, a ngrok ma poprawną konfigurację, całość zaczyna mieć sens jako zewnętrznie widoczny connector.

Największy błąd przy takich integracjach polega na tym, że ludzie patrzą na cały stos jak na jedną rzecz. A to nie jest jedna rzecz. To kilka warstw, które trzeba rozdzielać.

Kiedy connector jest już widoczny od strony klienta, nie zaczynaj od zadań złożonych. Najpierw każ modelowi zrobić rzeczy kontrolne.

Użyj mojego MCP i wywołaj get_root.

Użyj mojego MCP i pokaż zawartość katalogu głównego przez list_dir('.').

Użyj mojego MCP i odczytaj README.md przez read_file_text.

Znajdź w repo wystąpienia run_powershell przez search_text.

Utwórz plik raport.md, zapisz krótkie podsumowanie i dopisz do niego wynik kolejnego kroku.

Uruchom testowy plik Python z katalogu scripts.

Uruchom bezpieczną komendę PowerShell w katalogu projektu.

Bo jest przewidywalny. ChatGPT w tym układzie nie ma magicznych zdolności. Ma kilka narzędzi, jasno ograniczony obszar pracy i prosty zakres odpowiedzialności. Dzięki temu łatwiej go testować, debugować, zabezpieczyć i wdrożyć.

Semi-agent nie jest uboższą wersją agenta. W wielu scenariuszach jest często lepszą wersją narzędzia do pracy.

Jeżeli chcesz zrobić z ChatGPT coś na kształt technicznego operatora, nie zaczynaj od pełnej autonomii. Zacznij od dobrze ograniczonego MCP. Daj mu jeden katalog zamiast całego dysku, pliki, Pythona i PowerShella, ale tylko w obrębie repo.

Najpierw sprawdź odczyt. Potem zapis. Na końcu wykonanie procesów. A jeśli chcesz wystawić lokalny serwer na zewnątrz, zrób to świadomie przez ngrok jako osobną warstwę infrastruktury.

U nas właśnie taki układ okazał się najrozsądniejszy: lokalny serwer pod 127.0.0.1:8015/mcp/, smoke test przed cięższymi akcjami, ograniczony zestaw tooli, ręczne dopięcie fastmcp tam, gdzierequirements.txt jeszcze go nie obejmował, i tunel do świata zewnętrznego dopięty dopiero wtedy, gdy lokalne fundamenty były już sprawdzone.

I to jest chyba najlepsza definicja semi-agenta: nie robi wszystkiego, tylko robi to, co trzeba, w granicach, które da się zrozumieć i utrzymać.