MCP 服务器

MCP Server Template

A generic template for building remote MCP servers based on Streamable HTTP, with a demo ping tool and infrastructure for authentication, logging, testing, Docker, and CI/CD.

README

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.

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

Zmienna	Domyślnie	Opis
`PORT`	`3000`	Port HTTP
`LOG_LEVEL`	`info`	`debug`, `info`, `warn` albo `error`
`LOG_TO_FILE`	`true`	Zapis logów do `logs/`
`LOG_BODY_MAX_CHARS`	`2000`	Domyślny limit helpera `truncate()` do skracania logowanych treści
`TRUST_PROXY_HOPS`	`0`	Liczba zaufanych proxy
`OAUTH_ENABLED`	`false`	Włącza OAuth 2.1 obok legacy Bearer
`PUBLIC_BASE_URL`	—	Publiczny origin serwera; wymagany przy OAuth
`OAUTH_STORE_PATH`	`./data/oauth-store.json`	Szyfrowany magazyn OAuth
`OAUTH_STORE_KEY`	—	32 bajty base64; wymagane przy OAuth
`OAUTH_ALLOWED_REDIRECT_URIS`	callbacki Cursor	Dodatkowe dokładne callbacki DCR
`OAUTH_PENDING_TTL_MS`	`600000`	Ważność rozpoczętej autoryzacji
`OAUTH_CODE_TTL_MS`	`300000`	Ważność kodu autoryzacyjnego
`OAUTH_ACCESS_TTL_MS`	`0`	TTL access tokenu; `0` oznacza bezterminowy
`OAUTH_REFRESH_TTL_MS`	`0`	TTL refresh tokenu; `0` oznacza bezterminowy
`OAUTH_AUTHORIZATION_ATTEMPTS`	`10`	Maksymalna liczba prób formularza autoryzacji w jednym oknie
`OAUTH_AUTHORIZATION_ATTEMPT_WINDOW_MS`	`900000`	Długość okna limitu prób autoryzacji

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

Dodaj klienta upstream w osobnym katalogu domenowym w src/.
Zastąp ping w src/tools/register.ts narzędziami domenowymi.
Używaj tool() z src/tools/runner.ts do jednolitych logów i błędów.
Wywołuj countApiCall() przy każdym żądaniu do zewnętrznego API.
Zaimplementuj realną walidację w src/auth/validateApiToken.ts albo usuń OAuth, jeśli integracja nie ma poświadczeń użytkownika.
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:

Skopiuj docker-compose.example.yml do docker-compose.yml.
Ustaw GHCR_IMAGE, MCP_DOMAIN i TRAEFIK_CERTRESOLVER.
Utwórz data/; na natywnym Linuksie nadaj katalogowi UID/GID 1000.
Ustaw sekrety OAuth, jeśli ta funkcja ma być aktywna.
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.