@kieksme/mcp-http-kit 0.0.0-stage → 0.2.0

package/docs/migration.md

@@ -0,0 +1,125 @@
+# Migrating existing kieksme MCP servers to `@kieksme/mcp-http-kit`
+
+This guide covers moving servers off hand-rolled HTTP/auth helpers onto the shared kit.
+
+## SDK decision
+
+The kit targets **MCP TypeScript SDK v2**:
+
+- `@modelcontextprotocol/server`
+- `@modelcontextprotocol/node`
+
+v2 is the current stable release line (spec 2026-07-28). The monolithic
+`@modelcontextprotocol/sdk` (v1) is legacy. New and migrated kieksme servers
+should use v2; do not keep a v1 adapter in the kit.
+
+| Before | After |
+| --- | --- |
+| `mcp-enhancv`, `mcp-balena` | Already on v2 — swap local `http.ts` for the kit |
+| `mcp-contabo`, `mcp-listmonk`, `mcp-swetrix`, `mcp-hashnode` | On v1 `@modelcontextprotocol/sdk` — upgrade packages + imports, then adopt the kit |
+
+## Env var rename map
+
+| Legacy | Canonical |
+| --- | --- |
+| `MCP_HTTP_AUTH_TOKEN` / `MCP_SERVER_AUTH_TOKEN` | `MCP_AUTH_TOKEN` (comma list OK) |
+| `MCP_HTTP_PORT` (as primary) | `PORT` (fallback still reads `MCP_HTTP_PORT`) |
+| `MCP_HTTP_ALLOWED_HOSTS` | `MCP_ALLOWED_HOSTS` |
+| `MCP_HTTP_ALLOWED_ORIGINS` | `MCP_ALLOWED_ORIGINS` |
+| `MCP_HTTP_ENDPOINT` | `MCP_HTTP_PATH` (default `/mcp`) |
+| `HEALTH_ENDPOINT` | `MCP_HEALTH_PATH` (default `/health`) |
+
+Legacy names still work and emit a one-line warning.
+
+New knobs:
+
+- `MCP_AUTH_MODE=bearer|oauth|none`
+- `MCP_AUTH_ALLOW_NONE=true` (only for public read-only demos off localhost)
+- OAuth: `MCP_OAUTH_RESOURCE`, `MCP_OAUTH_AUTHORIZATION_SERVERS`, `MCP_OAUTH_AUDIENCES`, `MCP_OAUTH_JWKS_URL`, `MCP_OAUTH_REQUIRED_SCOPES`, `MCP_OAUTH_SCOPES_SUPPORTED`
+
+## Code shape
+
+**Before (enhancv-style):** local `parseHttpConfig` + `createHttpServer` + Host check before `/health`.
+
+**After:**
+
+```ts
+import { McpServer } from '@modelcontextprotocol/server';
+import { loadConfig, startMcpServer } from '@kieksme/mcp-http-kit';
+
+function createServer(ctx) {
+  const server = new McpServer({ name: 'my-mcp', version: '1.0.0' });
+  // register tools; ctx.auth.scopes available under oauth
+  return server;
+}
+
+await startMcpServer({ createServer, config: loadConfig(process.env, { realm: 'my-mcp' }) });
+```
+
+Important behavior change: **`/health` is served before Host/Origin checks** so Railway (and similar) healthchecks keep working when `MCP_ALLOWED_HOSTS` is tight.
+
+If you previously exposed `/healthz` (listmonk) or custom health JSON, use:
+
+```ts
+const config = loadConfig(process.env, {
+  realm: 'my-mcp',
+  healthPathAliases: ['/healthz'], // or MCP_HEALTH_ALIASES=/healthz
+});
+
+await startMcpServer({
+  createServer,
+  config,
+  getHealthInfo: () => ({ version: VERSION, tools: TOOL_COUNT }),
+});
+```
+
+## Per-request upstream credentials
+
+```ts
+import { resolveUpstreamCredential } from '@kieksme/mcp-http-kit';
+
+const cred = resolveUpstreamCredential(ctx.headers, {
+  mode: process.env.UPSTREAM_CREDENTIAL_MODE === 'header' ? 'header' : 'env',
+  envVar: 'CONTABO_API_KEY',
+  headerName: 'X-Contabo-Api-Key',
+  authMode: ctx.auth.mode,
+});
+```
+
+Header mode is rejected when `MCP_AUTH_MODE=none`.
+
+## Deploy templates
+
+Copy from this repo’s `templates/`:
+
+- `Dockerfile` — multi-stage, non-root, `HEALTHCHECK` on `/health`
+- `railway.json` — `healthcheckPath: /health`
+- `server.json` — npm + OCI + `remotes` streamable-http for the official registry
+- `smithery.yaml` — container runtime, HTTP start command
+
+## Contract tests
+
+```ts
+import { createMcpHttpApp } from '@kieksme/mcp-http-kit';
+import { createAppTestClient, createKitContractAssertions } from '@kieksme/mcp-http-kit/test';
+
+const config = loadConfig({ /* test env */ });
+const app = createMcpHttpApp({ createServer, config });
+const client = createAppTestClient(app, config);
+const assertions = createKitContractAssertions(client, config);
+
+await assertions.healthUnauthenticated();
+await assertions.unauthorizedWithoutToken();
+await assertions.forbiddenOnBadHost();
+await assertions.initializeAndListTools(token);
+```
+
+## Checklist
+
+1. Bump to `@modelcontextprotocol/server` + `@modelcontextprotocol/node` (drop v1 sdk).
+2. Add `@kieksme/mcp-http-kit` dependency.
+3. Replace local HTTP/auth modules with `loadConfig` + `startMcpServer`.
+4. Rename Railway/Docker env vars (or keep aliases temporarily).
+5. Ensure `/health` is what Railway probes (kit default).
+6. Copy deploy templates; publish `server.json` via `mcp-publisher` if applicable.
+7. Import kit contract assertions in CI.

package/package.json

@@ -1,6 +1,89 @@
 {
   "name": "@kieksme/mcp-http-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Shared Streamable HTTP transport, auth (bearer + OAuth 2.1 resource server), and deploy tooling for kieksme MCP servers",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./test": {
+      "types": "./dist/test/index.d.ts",
+      "import": "./dist/test/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kieksme/mcp-http-kit.git"
+  },
+  "homepage": "https://github.com/kieksme/mcp-http-kit#readme",
+  "bugs": {
+    "url": "https://github.com/kieksme/mcp-http-kit/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "streamable-http",
+    "oauth",
+    "railway",
+    "kieksme"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "prebuild": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "node scripts/prepare.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "pack:check": "node scripts/pack-check.mjs",
+    "example:echo": "tsx examples/echo-server/src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/node": "^2.1.0",
+    "@modelcontextprotocol/server": "^2.3.0",
+    "jose": "^6.2.13"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/node": "^2.1.0",
+    "@modelcontextprotocol/server": "^2.3.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@types/node": "^22.0.0",
+    "eslint": "^9.39.2",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^3.2.4",
+    "zod": "^4.6.7"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "packageManager": "pnpm@10.33.2"
+}

package/templates/Dockerfile

@@ -0,0 +1,46 @@
+# syntax=docker/dockerfile:1
+#
+# Template Dockerfile for a kieksme MCP server using @kieksme/mcp-http-kit.
+# Copy next to your server package.json and adjust COPY paths / labels.
+#
+# Runtime secrets (never bake into the image):
+#   MCP_AUTH_TOKEN   — bearer token(s), comma-separated for rotation
+#   <SERVICE>_API_KEY — upstream API credentials
+#
+# Railway / containers: PORT is honored by the kit (fallback MCP_HTTP_PORT).
+
+ARG NODE_VERSION=22-alpine
+ARG PNPM_VERSION=10.33.2
+
+# ---- build ----
+FROM node:${NODE_VERSION} AS build
+ARG PNPM_VERSION
+WORKDIR /app
+RUN npm install -g pnpm@${PNPM_VERSION}
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+COPY tsconfig.json tsconfig.build.json ./
+COPY src ./src
+RUN pnpm build && pnpm prune --prod
+
+# ---- runtime ----
+FROM node:${NODE_VERSION} AS runtime
+LABEL org.opencontainers.image.title="REPLACE_WITH_SERVER_NAME" \
+      org.opencontainers.image.description="MCP server (Streamable HTTP)" \
+      org.opencontainers.image.source="https://github.com/kieksme/REPLACE_WITH_REPO" \
+      org.opencontainers.image.licenses="MIT"
+ENV NODE_ENV=production \
+    MCP_TRANSPORT=http \
+    MCP_HTTP_HOST=0.0.0.0 \
+    PORT=3000 \
+    MCP_ALLOWED_HOSTS=localhost,127.0.0.1
+WORKDIR /app
+COPY --from=build --chown=node:node /app/package.json ./package.json
+COPY --chown=node:node LICENSE ./LICENSE
+COPY --from=build --chown=node:node /app/dist ./dist
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||process.env.MCP_HTTP_PORT||3000)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+CMD ["node", "dist/index.js"]

package/templates/railway.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "DOCKERFILE",
+    "dockerfilePath": "Dockerfile"
+  },
+  "deploy": {
+    "healthcheckPath": "/health",
+    "healthcheckTimeout": 30,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 3
+  }
+}

package/templates/server.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.kieksme/REPLACE_WITH_SERVER_NAME",
+  "title": "REPLACE_WITH_TITLE",
+  "description": "REPLACE_WITH_DESCRIPTION",
+  "repository": {
+    "url": "https://github.com/kieksme/REPLACE_WITH_REPO",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/kieksme/REPLACE_WITH_REPO#readme",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@kieksme/REPLACE_WITH_NPM_NAME",
+      "version": "0.1.0",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "REPLACE_WITH_UPSTREAM_API_KEY_ENV",
+          "description": "Upstream API key for the service this MCP server wraps.",
+          "isRequired": true,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    },
+    {
+      "registryType": "oci",
+      "identifier": "ghcr.io/kieksme/REPLACE_WITH_REPO",
+      "version": "0.1.0",
+      "transport": {
+        "type": "streamable-http",
+        "url": "http://localhost:3000/mcp"
+      },
+      "environmentVariables": [
+        {
+          "name": "MCP_AUTH_TOKEN",
+          "description": "Bearer token MCP clients must send (Authorization: Bearer …). Comma-separated list allowed for rotation.",
+          "isRequired": true,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "REPLACE_WITH_UPSTREAM_API_KEY_ENV",
+          "description": "Upstream API key for the service this MCP server wraps.",
+          "isRequired": true,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "MCP_ALLOWED_HOSTS",
+          "description": "Comma-separated Host allowlist (required when binding beyond localhost).",
+          "isRequired": true,
+          "isSecret": false,
+          "format": "string"
+        }
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://REPLACE_WITH_PUBLIC_HOST/mcp",
+      "headers": [
+        {
+          "name": "Authorization",
+          "description": "Bearer token (MCP_AUTH_TOKEN). Format: Bearer <token>",
+          "isRequired": true,
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}

package/templates/smithery.yaml

@@ -0,0 +1,31 @@
+# Smithery project config — https://smithery.ai/docs/build/project-config
+#
+# Container runtime: Smithery builds the Dockerfile and connects over
+# Streamable HTTP. The kit honors PORT (Smithery sets it) and serves MCP at
+# /mcp by default. Copy to the server repo root and fill configSchema.
+
+runtime: container
+
+build:
+  dockerfile: Dockerfile
+  dockerBuildPath: .
+
+startCommand:
+  type: http
+  configSchema:
+    type: object
+    properties:
+      mcpAuthToken:
+        type: string
+        title: MCP bearer token
+        description: Value for MCP_AUTH_TOKEN (clients send Authorization: Bearer …).
+      upstreamApiKey:
+        type: string
+        title: Upstream API key
+        description: Service API key mapped to your server's env var.
+    required:
+      - mcpAuthToken
+      - upstreamApiKey
+  exampleConfig:
+    mcpAuthToken: "replace-me"
+    upstreamApiKey: "replace-me"