ts-mcp-template/src/capabilities/contracts.ts

import { AppError } from "../lib/errors.js";

export const EXAMPLE_ECHO_TOOL_NAME = "example.echo";
export const EXAMPLE_SUMMARY_PROMPT_NAME = "example.summary";

export type ExampleEchoToolInput = {
  message: string;
  uppercase?: boolean;
};

export type ExampleEchoToolResult = {
  output: string;
};

export type ExampleSummaryPromptInput = {
  topic: string;
  audience?: string;
};

type ObjectRecord = Record<string, unknown>;

function asRecord(value: unknown, context: string): ObjectRecord {
  if (value && typeof value === "object" && !Array.isArray(value)) {
    return value as ObjectRecord;
  }

  throw new AppError(`${context} must be an object`, "E_CONTRACT_INVALID_INPUT", {
    cause: value,
  });
}

function asNonEmptyString(value: unknown, field: string): string {
  if (typeof value !== "string") {
    throw new AppError(`${field} must be a string`, "E_CONTRACT_INVALID_INPUT", {
      cause: value,
    });
  }

  const normalized = value.trim();
  if (!normalized) {
    throw new AppError(`${field} must not be empty`, "E_CONTRACT_INVALID_INPUT", {
      cause: value,
    });
  }

  return normalized;
}

function asOptionalBoolean(value: unknown, field: string): boolean | undefined {
  if (value === undefined) {
    return undefined;
  }

  if (typeof value !== "boolean") {
    throw new AppError(`${field} must be a boolean when provided`, "E_CONTRACT_INVALID_INPUT", {
      cause: value,
    });
  }

  return value;
}

export function parseExampleEchoToolInput(input: unknown): ExampleEchoToolInput {
  const record = asRecord(input, EXAMPLE_ECHO_TOOL_NAME);

  return {
    message: asNonEmptyString(record.message, "message"),
    uppercase: asOptionalBoolean(record.uppercase, "uppercase"),
  };
}

export function runExampleEchoTool(input: unknown): ExampleEchoToolResult {
  const parsed = parseExampleEchoToolInput(input);
  return {
    output: parsed.uppercase ? parsed.message.toUpperCase() : parsed.message,
  };
}

export function parseExampleSummaryPromptInput(input: unknown): ExampleSummaryPromptInput {
  const record = asRecord(input, EXAMPLE_SUMMARY_PROMPT_NAME);

  return {
    topic: asNonEmptyString(record.topic, "topic"),
    audience:
      record.audience === undefined
        ? undefined
        : asNonEmptyString(record.audience, "audience"),
  };
}

export function renderExampleSummaryPrompt(input: unknown): string {
  const parsed = parseExampleSummaryPromptInput(input);
  const audienceLabel = parsed.audience ? ` for ${parsed.audience}` : "";
  return `Write a concise summary about ${parsed.topic}${audienceLabel}.`;
}