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

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@kieksme/mcp-http-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+    "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": {
+    "jose": "^6.2.13"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/node": "^2.1.0",
+    "@modelcontextprotocol/server": "^2.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/node": {
+      "optional": false
+    },
+    "@modelcontextprotocol/server": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/node": "^2.1.1",
+    "@modelcontextprotocol/server": "^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"