npm package: @hlos/mcp-sdk
Description: Surface SDK for HLOS MCP servers — bootstrap, auth, and Kernel client
Author: Efficient Frontier Labs
Latest version: 0.2.0

# @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:

```ts
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:

```bash
pnpm -C packages/core generate:schemas
```

- CI guard (verify no diffs):

```bash
pnpm -C packages/core generate:schemas:check
```

## Downstream usage (example)

```ts
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:

```ts
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`:

```ts
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.