@hlos/mcp-sdk

Core authentication and utilities for HLOS MCP server packages.

Wave 2: env validation + bootstrapServer

Downstream server packages should use bootstrapServer() to get consistent startup behavior:

• Validation: required env vars (from ServerMetadata.env) are validated before start() runs.
• Help text: formatEnvHelp(metadata) prints deterministic, sorted env var help.
• Redaction guarantee:
  • Env var names are safe to print.
  • Env var values are never printed by validation errors.
  • If a thrown error message accidentally contains a secret, bootstrapServer strips exact values for env vars marked sensitive: true in ServerMetadata.env (and also applies token-pattern redaction).

Minimal pattern:

import { bootstrapServer, formatEnvHelp, type ServerMetadata } from '@hlos/mcp-sdk';

export const SERVER_METADATA: ServerMetadata = {
  id: 'my-server',
  packageName: '@hlos/mcp-server-my-server',
  binName: 'mcp-server-my-server',
  description: '…',
  hostedEndpoint: 'https://mcp.hlos.ai/my-server',
  env: [{ name: 'HLOS_ACCESS_TOKEN', required: true, sensitive: true }],
  capabilities: [],
};

if (process.argv.includes('--help')) {
  console.log(formatEnvHelp(SERVER_METADATA));
  process.exit(0);
}

await bootstrapServer({
  metadata: SERVER_METADATA,
  start: async ({ env, logger }) => {
    logger.info(`Starting ${SERVER_METADATA.id}`);
    // Use env[...] and never log secrets.
  },
});

How to update schemas (generated contracts)

This package maintains canonical contracts (auth result shapes, hosted config shapes, shared metadata) and generates deterministic artifacts into src/generated/.

• Versioning: CONTRACTS_VERSION follows SemVer:

  • patch: docs / non-breaking clarifications (no schema shape changes)
  • minor: additive-only changes (new optional fields, new enum variants, etc.)
  • major: breaking changes (removals, renames, stricter validation)

• Update / add Zod schemas in scripts/schema.ts

• Regenerate committed artifacts:

pnpm -C packages/core generate:schemas

• CI guard (verify no diffs):

pnpm -C packages/core generate:schemas:check

Downstream usage (example)

import { CONTRACTS_SCHEMA, CONTRACTS_VERSION, assertContractsVersion } from '@hlos/mcp-sdk';

// Fail fast if you expect a compatible contracts major version:
assertContractsVersion('1.');

// CONTRACTS_SCHEMA is an embedded JSON Schema bundle you can feed into Ajv, etc.
console.log(CONTRACTS_VERSION, Object.keys((CONTRACTS_SCHEMA as any).schemas));

Attribution Metadata

MCP servers can forward optional attribution metadata for downstream billing and analytics:

import type { AttributionMetadata } from '@hlos/mcp-sdk';

const attribution: AttributionMetadata = {
  distributionSurface: 'discord',  // "discord", "slack", "cli", "api", "web", "unknown"
  clientType: 'claude_desktop',    // "claude_desktop", "claude_code", "chatgpt", "ide", "api", "unknown"
};

Server-Level Default

Set defaults via environment variables:

| Env Var | Field | Example | |---------|-------|---------| | HLOS_DISTRIBUTION_SURFACE | distributionSurface | "discord" | | HLOS_CLIENT_TYPE | clientType | "claude_desktop" |

These defaults are baked into ServerMetadata.attribution and passed to the BootstrapContext:

await bootstrapServer({
  metadata: SERVER_METADATA,
  start: async (ctx) => {
    // ctx.attribution?.distributionSurface
    // ctx.attribution?.clientType
  },
});

Request-Level Override (Future)

Server-level attribution is a default. Per-request attribution overrides (via headers or context) may be added in the future. Prefer per-request values when available.