Add Service

Context

Services use the init/accessor pattern: initialized once in createApp's setup() callback, then accessed at request time via a lazy getter. Each service lives in src/services/[domain]/ with an init function and accessor.

Service methods receive Context for correlated logging (ctx.log) and tenant-scoped storage (ctx.state). Convention: ctx.requestInput should only be called from tool, resource, and prompt handlers, not from services — a service can call it, but the never return means TypeScript cannot narrow across it at the handler's call site.

For the full service pattern, CoreServices, and Context interface, read the framework's CLAUDE.md/AGENTS.md (loaded at session start).

Steps

1. Gather the service domain name and what it integrates with from the user's request — ask only if genuinely absent
2. Create the directory at src/services/{{domain}}/
3. Create the service file at src/services/{{domain}}/{{domain}}-service.ts
4. Create types at src/services/{{domain}}/types.ts if needed
5. Register in setup() in the server's entry point (src/index.ts, or src/worker.ts for Worker-only servers)
6. Run bun run devcheck to verify

Template

Service file

/**
 * @fileoverview {{SERVICE_DESCRIPTION}}
 * @module services/{{domain}}/{{domain}}-service
 */

import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
import type { Context } from '@cyanheads/mcp-ts-core';

export class {{ServiceName}} {
  constructor(
    private readonly config: AppConfig,
    private readonly storage: StorageService,
  ) {}

  async doWork(input: string, ctx: Context): Promise<string> {
    ctx.log.debug('Processing', { input });
    // Domain logic here
    return `result: ${input}`;
  }
}

// --- Init/accessor pattern ---

let _service: {{ServiceName}} | undefined;

export function init{{ServiceName}}(config: AppConfig, storage: StorageService): void {
  _service = new {{ServiceName}}(config, storage);
}

export function get{{ServiceName}}(): {{ServiceName}} {
  if (!_service) {
    throw new Error('{{ServiceName}} not initialized — call init{{ServiceName}}() in setup()');
  }
  return _service;
}

Entry point registration

Add the setup() callback and import to the existing createApp() call — preserve the existing tool/resource/prompt arrays:

// In src/index.ts (or src/worker.ts for Worker-only servers)
import { init{{ServiceName}} } from './services/{{domain}}/{{domain}}-service.js';

// Add setup() alongside existing options:
setup(core) {
  init{{ServiceName}}(core.config, core.storage);
},

Usage in tool handlers

import { get{{ServiceName}} } from '@/services/{{domain}}/{{domain}}-service.js';

handler: async (input, ctx) => {
  return get{{ServiceName}}().doWork(input.query, ctx);
},

Resilience (External API Services)

When a service wraps an external API, apply these patterns. For the framework retry contract, see framework-skills/api-utils/SKILL.md.

Retry wraps the full pipeline

Place retry at the service method level — covering both HTTP fetch and response parsing/validation. The HTTP client should be single-attempt; the service owns retry. Use withRetry from @cyanheads/mcp-ts-core/utils:

import { withRetry, fetchWithTimeout } from '@cyanheads/mcp-ts-core/utils';
import type { Context } from '@cyanheads/mcp-ts-core';

async fetchItem(id: string, ctx: Context): Promise<Item> {
  return withRetry(
    async () => {
      const response = await fetchWithTimeout(
        `${this.baseUrl}/items/${id}`,
        10_000,
        ctx,
        { signal: ctx.signal },
      );
      const text = await response.text();
      return this.parseResponse<Item>(text);
    },
    {
      operation: 'fetchItem',
      context: ctx,
      baseDelayMs: 1000,    // calibrate to upstream recovery time
      signal: ctx.signal,
    },
  );
}

Key principles

1. Calibrate backoff to the upstream. 200–500ms for ephemeral failures, 1–2s for rate-limited APIs, 2–5s for service degradation. The default baseDelayMs: 1000 suits most APIs.
2. Check HTTP status before parsing. fetchWithTimeout already throws on non-OK responses with granular status mapping (401→Unauthorized, 403→Forbidden, 404→NotFound, 408/425→Timeout, 422→ValidationError, 429→RateLimited, 5xx→ServiceUnavailable/InternalError) — this prevents feeding HTML error pages into XML/JSON parsers.
3. Classify parse failures by content. If the upstream returns HTTP 200 with an HTML error page, detect it and throw ServiceUnavailable (transient) instead of SerializationError (non-transient). Exception — deterministic HTTP 200 errors fail fast, not transient. Some upstreams return HTTP 200 with a structured error body for failures that will never succeed regardless of how many times you retry: a query too expensive for the server's budget, an oversized result set, or a malformed request the server rejects. Retrying these wastes upstream capacity and delays the client. Declare them in the contract with retryable: false (or pass { retryable: false } in data at the throw site) — withRetry's default predicate reads error.data.retryable === false and fails immediately, even for Timeout/ServiceUnavailable codes. ctx.fail auto-populates data.retryable from the contract entry, so declaring it once in errors[] is enough.
4. Exhausted retries say so. withRetry automatically enriches the final error with attempt count — callers know retries were already attempted.

When you need finer-grained HTTP error classification

fetchWithTimeout already maps status codes to appropriate error codes (see key principle 2 above). Use httpErrorFromResponse instead when you need Retry-After header capture, request body passthrough in error data, or custom service/data fields on the thrown error:

import { httpErrorFromResponse, withRetry } from '@cyanheads/mcp-ts-core/utils';

async fetchItem(id: string, ctx: Context): Promise<Item> {
  return withRetry(
    async () => {
      const response = await fetch(`${this.baseUrl}/items/${id}`, { signal: ctx.signal });
      if (!response.ok) {
        throw await httpErrorFromResponse(response, {
          service: 'MyAPI',
          data: { itemId: id },
        });
      }
      return this.parseResponse<Item>(await response.text());
    },
    { operation: 'fetchItem', context: ctx, signal: ctx.signal },
  );
}

httpErrorFromResponse maps the full status table (401/403/408/422/429/5xx) to the appropriate JsonRpcErrorCode, captures the response body (truncated), and forwards Retry-After headers into error.data.retryAfter. The codes it produces line up with withRetry's transient-code set, so retryable HTTP failures (429, 503, 504) are retried automatically and non-retryable ones (401, 404, 422) fail immediately.

Response handler pattern

import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';

parseResponse<T>(text: string): T {
  // Detect HTML error pages masquerading as successful responses
  if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
    throw serviceUnavailable('API returned HTML instead of expected format — likely rate-limited.');
  }
  // Parse and validate...
}

Sparse upstream payloads

Third-party APIs often omit fields entirely instead of returning null. If your raw response types, normalized domain types, or tool output schemas are stricter than the real upstream payloads, you'll either fail validation or silently invent facts.

Guidance:

1. Raw upstream types default to optional unless presence is guaranteed. Trust the docs only after you've verified real payloads.
2. Preserve absence when it means "unknown". Missing data is different from false, 0, '', or an empty array.
3. Don't fabricate defaults during normalization unless the upstream contract or your own tool semantics explicitly define them.
4. With exactOptionalPropertyTypes, omit absent fields instead of returning undefined. Conditional spreads keep the normalized object honest.

type RawRepo = {
  id: string;
  name: string;
  archived?: boolean;
  star_count?: number;
  description?: string | null;
};

type Repo = {
  id: string;
  name: string;
  archived?: boolean;
  starCount?: number;
  description?: string;
};

function normalizeRepo(raw: RawRepo): Repo {
  const description = raw.description?.trim();
  return {
    id: raw.id,
    name: raw.name,
    ...(typeof raw.archived === 'boolean' && { archived: raw.archived }),
    ...(typeof raw.star_count === 'number' && { starCount: raw.star_count }),
    ...(description ? { description } : {}),
  };
}