MCP Server Template

Generyczny szablon zdalnego serwera MCP opartego o Streamable HTTP. Zawiera Express, opcjonalny OAuth 2.1, szyfrowany magazyn poświadczeń, logi JSON, testy, Docker i konfigurowalny workflow CI/CD.

Szablon udostępnia wyłącznie narzędzie demonstracyjne ping. Nie zawiera logiki biznesowej ani klienta zewnętrznego API.

Stack

• Node.js 20+ i TypeScript ESM w trybie strict

• @modelcontextprotocol/sdk

• Express

• Zod

• Vitest

• Docker

Projekt nie używa bazy danych ani migracji. Opcjonalny OAuth zapisuje stan w zaszyfrowanym pliku data/oauth-store.json.

Related MCP server: MCP Server Template (Python)

Instalacja i uruchomienie

npm install
Copy-Item .env.example .env
npm run dev

Na Linuxie:

npm install
cp .env.example .env
npm run dev

Endpointy:

• MCP: POST http://localhost:3000/mcp

• health check: GET http://localhost:3000/health

Pozostałe polecenia:

npm test
npm run typecheck
npm run build
npm start

Konfiguracja

Uwierzytelnienie

Domyślnie serwer wymaga dowolnego niepustego nagłówka:

Authorization: Bearer <poswiadczenie-upstream>

Poświadczenie jest przekazywane do narzędzi tworzonych dla danego żądania. Podczas podpinania domeny należy zastąpić ten kontrakt rzeczywistą autoryzacją upstream.

OAuth jest domyślnie wyłączony. Kod zawiera DCR, PKCE S256, discovery, rotację refresh tokenów, revocation i szyfrowany store. Przed ustawieniem OAUTH_ENABLED=true trzeba zastąpić domyślną implementację w src/auth/validateApiToken.ts odczytową walidacją poświadczenia w docelowym API. Obecna implementacja sprawdza tylko, czy wartość nie jest pusta, i nie jest wystarczającym zabezpieczeniem produkcyjnym.

Klucz szyfrujący można wygenerować poleceniem:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

OAuth wymaga PUBLIC_BASE_URL wskazującego origin bez ścieżki. Produkcja wymaga HTTPS; HTTP jest akceptowane tylko dla localhost. Plikowy store zakłada jedną replikę aplikacji.

Dodawanie integracji

1. Dodaj klienta upstream w osobnym katalogu domenowym w src/.

2. Zastąp ping w src/tools/register.ts narzędziami domenowymi.

3. Używaj tool() z src/tools/runner.ts do jednolitych logów i błędów.

4. Wywołuj countApiCall() przy każdym żądaniu do zewnętrznego API.

5. Zaimplementuj realną walidację w src/auth/validateApiToken.ts albo usuń OAuth, jeśli integracja nie ma poświadczeń użytkownika.

6. Dodaj test narzędzia przed implementacją logiki.

Struktura

src/
  index.ts
  app.ts
  server.ts
  config.ts
  logger.ts
  callContext.ts
  auth/
    provider.ts
    runtime.ts
    store.ts
    resolveCredential.ts
    validateApiToken.ts
    ui.ts
  tools/
    register.ts
    runner.ts
test/
Dockerfile
docker-compose.dev.yml
docker-compose.example.yml

Docker

Development:

docker compose -f docker-compose.dev.yml up --build

Produkcja:

1. Skopiuj docker-compose.example.yml do docker-compose.yml.

2. Ustaw GHCR_IMAGE, MCP_DOMAIN i TRAEFIK_CERTRESOLVER.

3. Utwórz data/; na natywnym Linuksie nadaj katalogowi UID/GID 1000.

4. Ustaw sekrety OAuth, jeśli ta funkcja ma być aktywna.

5. Uruchom docker compose up -d.

Obraz produkcyjny działa jako użytkownik node i ma health check /health.

CI/CD

Workflow .github/workflows/ci-cd.yml:

• uruchamia testy, typecheck i build na Windows oraz Linux;

• buduje obraz runtime;

• publikuje go do GHCR;

• po publikacji wdraża go przez SSH.

Przed użyciem ustaw zmienne repozytorium:

• GHCR_IMAGE, np. ghcr.io/owner/repository;

• DEPLOY_PATH, np. /home/user/myapps/mcp-server.

Wymagane sekrety deployu: SSH_HOST, SSH_USERNAME, SSH_PRIVATE_KEY. Każdy push do main uruchamia cały workflow. Brak wymaganych zmiennych lub sekretów celowo zatrzymuje publikację albo wdrożenie.