server.ts

#!/usr/bin/env tsx
/**
 * Open Archieven MCP Server
 *
 * Exposes all 21 Open Archieven API endpoints (genealogy, statistics, related data,
 * and full-text page transcriptions of historical documents) as MCP tools via
 * multiple transports:
 *   POST /              — MCP JSON-RPC (canonical, Origin-validated)
 *   POST /mcp           — MCP JSON-RPC (legacy alias, Origin-validated)
 *   GET  /health        — Health check
 *   GET  /tools         — List tool names
 *   POST /tools/:name   — Direct HTTP tool call
 *   GET  /events/:name  — SSE streaming with auto-pagination
 *   POST /stream/:name  — Chunked HTTP streaming with auto-pagination
 *
 * Run: npx tsx server.ts
 * Requires: generated/tools.json (run generate.ts first)
 */

import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import express, { type Request, type Response, type NextFunction } from 'express';
import axios from 'axios';
import { Redis } from 'ioredis';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import {
  registerAppTool,
  registerAppResource,
  RESOURCE_MIME_TYPE,
} from '@modelcontextprotocol/ext-apps/server';
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
import { z } from 'zod';
import pino from 'pino';
import type { ToolDef, ParamDef } from './generate.js';
import {
  findUnmappedTools,
  resolveTtl,
  secondsUntilUtcMidnight,
} from './cache-ttl.js';
import { findUntitledTools, titleFor } from './tool-titles.js';

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// ─── Logger ───────────────────────────────────────────────────────────────────

const isDev = process.env['NODE_ENV'] !== 'production';

const log = pino({
  level: process.env['LOG_LEVEL'] ?? 'info',
  ...(isDev && {
    transport: {
      target: 'pino-pretty',
      options: { colorize: true, translateTime: 'SYS:HH:MM:ss', ignore: 'pid,hostname' },
    },
  }),
});

// ─── Config ───────────────────────────────────────────────────────────────────

const PORT = parseInt(process.env['PORT'] ?? '3001', 10);
const UPSTREAM_BASE = process.env['UPSTREAM_BASE'] ?? 'https://api.openarchieven.nl/1.1';
const RATE_LIMIT_RPS = parseInt(process.env['RATE_LIMIT_RPS'] ?? '4', 10);
const REDIS_URL = process.env['REDIS_URL'] ?? 'redis://localhost:6379/5';
const CACHE_TTL = parseInt(process.env['CACHE_TTL'] ?? '3600', 10);

const pkg = JSON.parse(
  fs.readFileSync(path.resolve(__dirname, 'package.json'), 'utf8'),
) as { name: string; version: string };
const UA_NAME = pkg.name.split('/').pop() ?? pkg.name;
const USER_AGENT = `${UA_NAME}/${pkg.version} (+https://github.com/coret/openarchieven-mcp-server)`;

// Origin allowlist for the remote MCP endpoint (DNS-rebinding defense).
// Hardcoded Claude origins are always allowed; ALLOWED_ORIGINS adds more.
const HARDCODED_ORIGINS = ['https://claude.ai', 'https://claude.com'];
const HARDCODED_ORIGIN_SUFFIXES = ['.claude.ai', '.claude.com'];
const EXTRA_ORIGINS = (process.env['ALLOWED_ORIGINS'] ?? '')
  .split(',')
  .map((s) => s.trim())
  .filter(Boolean);

// ─── Load tool definitions ────────────────────────────────────────────────────

const toolsPath = path.join(__dirname, 'generated', 'tools.json');
if (!fs.existsSync(toolsPath)) {
  log.fatal('generated/tools.json not found — run: npx tsx generate.ts');
  process.exit(1);
}
const TOOLS: ToolDef[] = JSON.parse(fs.readFileSync(toolsPath, 'utf8'));
const TOOL_MAP = new Map<string, ToolDef>(TOOLS.map((t) => [t.name, t]));

// Surface generator drift: any newly-introduced tool with no TTL entry will
// silently fall back to CACHE_TTL, which is rarely the right choice. Logging
// once at boot is enough to prompt a follow-up edit to cache-ttl.ts.
const unmappedTools = findUnmappedTools(TOOLS.map((t) => t.name));
if (unmappedTools.length > 0) {
  log.warn(
    { tools: unmappedTools, fallback_ttl_seconds: CACHE_TTL },
    'tool(s) have no entry in TOOL_TTL — falling back to CACHE_TTL; add them to cache-ttl.ts',
  );
}

// Same drift check for the human-readable titles shown in MCP host UIs.
const untitledTools = findUntitledTools(TOOLS.map((t) => t.name));
if (untitledTools.length > 0) {
  log.warn(
    { tools: untitledTools },
    'tool(s) have no curated title — falling back to Title Case; add them to tool-titles.ts',
  );
}

function resolveTool(name: string): ToolDef | undefined {
  return TOOL_MAP.get(name);
}

function isOriginAllowed(origin: string | undefined): boolean {
  if (!origin) return true; // curl, server-to-server, native MCP clients
  if (HARDCODED_ORIGINS.includes(origin)) return true;
  if (EXTRA_ORIGINS.includes(origin)) return true;
  try {
    const host = new URL(origin).hostname;
    if (HARDCODED_ORIGIN_SUFFIXES.some((s) => host.endsWith(s))) return true;
  } catch {
    return false;
  }
  return false;
}

// ─── Rate Limiter ─────────────────────────────────────────────────────────────

class RateLimiter {
  private queue: Array<() => void> = [];
  private processing = false;

  constructor(private rps: number) {}

  acquire(): Promise<void> {
    return new Promise((resolve) => {
      this.queue.push(resolve);
      if (!this.processing) this.processQueue();
    });
  }

  private processQueue() {
    if (this.queue.length === 0) {
      this.processing = false;
      return;
    }
    this.processing = true;
    const resolve = this.queue.shift()!;
    resolve();
    setTimeout(() => this.processQueue(), Math.ceil(1000 / this.rps));
  }
}

const rateLimiter = new RateLimiter(RATE_LIMIT_RPS);

// ─── Redis ────────────────────────────────────────────────────────────────────

let redis: Redis | null = null;
let redisAvailable = false;

function initRedis() {
  try {
    redis = new Redis(REDIS_URL, { lazyConnect: true, enableOfflineQueue: false });
    redis.on('ready', () => {
      redisAvailable = true;
      log.info({ redis: REDIS_URL }, 'Redis connected');
    });
    redis.on('error', (err: Error) => {
      const wasAvailable = redisAvailable;
      redisAvailable = false;
      if (wasAvailable) log.warn({ err: err.message }, 'Redis disconnected — running in degraded mode');
    });
    redis.connect().catch((err: Error) => {
      redisAvailable = false;
      log.warn({ err: err.message }, 'Redis unavailable — running in degraded mode');
    });
  } catch (err) {
    redisAvailable = false;
    log.warn({ err: err instanceof Error ? err.message : String(err) }, 'Redis init failed');
  }
}

function cacheKey(toolName: string, params: Record<string, unknown>): string {
  const sorted = Object.keys(params)
    .sort()
    .reduce<Record<string, unknown>>((acc, k) => { acc[k] = params[k]; return acc; }, {});
  return `mcp:${toolName}:${JSON.stringify(sorted)}`;
}

async function cacheGet(key: string): Promise<unknown | null> {
  if (!redisAvailable || !redis) return null;
  try {
    const val = await redis.get(key);
    return val ? JSON.parse(val) : null;
  } catch {
    return null;
  }
}

async function cacheSet(key: string, value: unknown, toolName: string): Promise<void> {
  if (!redisAvailable || !redis) return;
  try {
    const strategy = resolveTtl(toolName, CACHE_TTL);
    const json = JSON.stringify(value);
    if (strategy.kind === 'never') {
      await redis.set(key, json);
    } else if (strategy.kind === 'until_midnight') {
      await redis.set(key, json, 'EX', secondsUntilUtcMidnight());
    } else {
      await redis.set(key, json, 'EX', strategy.seconds);
    }
  } catch {
    // ignore
  }
}

// ─── Zod schema builder ───────────────────────────────────────────────────────

function buildZodShape(params: ParamDef[]): Record<string, z.ZodTypeAny> {
  const shape: Record<string, z.ZodTypeAny> = {};

  for (const p of params) {
    let base: z.ZodTypeAny;

    if (p.enum) {
      const vals = p.enum as [string | number, ...(string | number)[]];
      if (p.type === 'integer' || p.type === 'number') {
        const literals = vals.map((v) => z.literal(v as number));
        base = z.union(literals as [z.ZodLiteral<number>, z.ZodLiteral<number>, ...z.ZodLiteral<number>[]]);
      } else {
        const strVals = vals.map(String) as [string, ...string[]];
        base = z.enum(strVals);
      }
    } else if (p.type === 'integer') {
      let s = z.number().int();
      if (p.minimum !== undefined) s = s.min(p.minimum);
      if (p.maximum !== undefined) s = s.max(p.maximum);
      base = s;
    } else if (p.type === 'number') {
      let s = z.number();
      if (p.minimum !== undefined) s = s.min(p.minimum);
      if (p.maximum !== undefined) s = s.max(p.maximum);
      base = s;
    } else if (p.type === 'boolean') {
      base = z.boolean();
    } else {
      base = z.string();
    }

    shape[p.name] = p.required ? base : base.optional();
  }

  return shape;
}

// ─── Upstream API caller ──────────────────────────────────────────────────────

async function callUpstream(
  tool: ToolDef,
  params: Record<string, unknown>,
): Promise<unknown> {
  const key = cacheKey(tool.name, params);
  const cached = await cacheGet(key);
  if (cached !== null) {
    log.debug({ tool: tool.name, params }, 'cache hit');
    return cached;
  }

  await rateLimiter.acquire();

  const url = `${UPSTREAM_BASE}${tool.endpoint}`;
  log.debug({ tool: tool.name, url, params }, 'upstream request');

  const t0 = Date.now();
  const res = await axios.get(url, {
    params,
    headers: { Accept: 'application/json', 'User-Agent': USER_AGENT },
    timeout: 15_000,
  });
  log.info({ tool: tool.name, status: res.status, ms: Date.now() - t0 }, 'upstream ok');

  await cacheSet(key, res.data, tool.name);
  return res.data;
}

// ─── MCP App: interactive IIIF viewer ─────────────────────────────────────────
//
// `view_transcription` declares a `ui://` MCP App resource (an OpenSeadragon
// deep-zoom viewer + transcription panel) for hosts that support MCP Apps, and
// returns a text summary plus inline preview images as the fallback for hosts
// that don't. The viewer (dist/viewer.html) loads IIIF tiles directly.

const VIEWER_URI = 'ui://openarchieven/viewer.html';

const VIEWER_HTML: string = (() => {
  try {
    return fs.readFileSync(path.join(__dirname, 'dist', 'viewer.html'), 'utf8');
  } catch (err) {
    log.warn(
      { err: err instanceof Error ? err.message : String(err) },
      'dist/viewer.html missing — view_transcription UI disabled (run: npm run build:viewer)',
    );
    return '';
  }
})();

// IIIF / image hosts used across the transcription projects — the iframe CSP
// allowlist. Wildcards (supported by MCP Apps CSP) cover the whole host families:
//   *.transkribus.eu  → files.transkribus.eu (IIIF deep zoom)
//   *.archief.nl      → service.archief.nl   (iipsrv IIIF deep zoom)
//   *.archieven.nl    → preserve / preserve2 / preserve-nha / preserve-bhic … (flat thumbs)
//   *.memorix.nl      → images.memorix.nl
// All of these send `Access-Control-Allow-Origin: *`, so OpenSeadragon can render
// them to canvas. connectDomains = info.json XHR; resourceDomains = tiles/<img>.
const IIIF_HOSTS = [
  'https://*.transkribus.eu',
  'https://*.archief.nl',
  'https://*.archieven.nl',
  'https://*.memorix.nl',
  'https://*.razu.nl',
];
// Archive logos (`…/img/archives/<ISIL>.png`) are served from openarchieven.nl
// with `Access-Control-Allow-Origin: *`; allow them as <img> resources.
const VIEWER_CSP = {
  connectDomains: IIIF_HOSTS,
  resourceDomains: [...IIIF_HOSTS, 'https://www.openarchieven.nl'],
};

const SHOW_TX = TOOLS.find((t) => t.name === 'show_transcription');

/** Archival reference (the fonds `archive_number` or the `inventory_number`). */
interface SourceRef {
  nr?: string;
  title?: string;
  url?: string;
}

interface ViewerPage {
  id: string;
  page: string;
  /** IIIF info.json URL when derivable (enables deep zoom). */
  infoJson?: string;
  /** Plain image URL fallback (non-IIIF projects). */
  imageUrl?: string;
  thumbUrl?: string;
  transcript: string;
  sourceUrl?: string;
  /** Holding institution (source_archive). */
  archive?: string;
  archiveIsil?: string;
  archiveLogo?: string;
  /** archive_number — the fonds/collection the page belongs to. */
  archiveRef?: SourceRef;
  /** inventory_number within the fonds. */
  inventoryRef?: SourceRef;
}

/** Keep a reference only if it carries something; trim blanks. */
function cleanRef(r?: { nr?: unknown; title?: unknown; url?: unknown }): SourceRef | undefined {
  if (!r) return undefined;
  const nr = String(r.nr ?? '').trim() || undefined;
  const title = String(r.title ?? '').trim() || undefined;
  const url = String(r.url ?? '').trim() || undefined;
  return nr || title || url ? { nr, title, url } : undefined;
}

/**
 * IIIF `thumb_url` → info.json (deep zoom) when derivable, else a flat image URL.
 *
 * The IIIF Image API region segment `/full/` is the reliable marker: both
 * Transkribus (`…/iiif/2/{id}/full/512,/0/default.jpg`) and the archief.nl iipsrv
 * server (`…/iipsrv?IIIF=/…/{id}.jp2/full/256,/0/default.jpg`) embed it, and
 * stripping everything from `/full/` onward + `/info.json` yields a valid
 * descriptor for both. Non-IIIF thumbnail hosts (preserve*.archieven.nl, served as
 * `…​.jpg?format=thumb`) have no `/full/` and fall back to a flat image source.
 */
function deriveTileSource(thumbUrl?: string): Pick<ViewerPage, 'infoJson' | 'imageUrl'> {
  if (!thumbUrl) return {};
  if (thumbUrl.includes('/full/')) {
    return { infoJson: `${thumbUrl.split('/full/')[0]}/info.json` };
  }
  return { imageUrl: thumbUrl };
}

/** IIIF `thumb_url` → a larger sized derivative for the inline (Route A) fallback image. */
function iiifDerivative(thumbUrl: string, size = '1024,'): string {
  if (thumbUrl.includes('/full/')) {
    return `${thumbUrl.split('/full/')[0]}/full/${size}/0/default.jpg`;
  }
  return thumbUrl;
}

/** Fetch an image and base64-encode it (cached via Redis like upstream JSON). */
async function fetchImageDataUrl(
  url: string,
): Promise<{ data: string; mimeType: string } | null> {
  const key = `mcp:img:${url}`;
  const cached = (await cacheGet(key)) as { data: string; mimeType: string } | null;
  if (cached) return cached;
  try {
    await rateLimiter.acquire();
    const res = await axios.get<ArrayBuffer>(url, {
      responseType: 'arraybuffer',
      headers: { 'User-Agent': USER_AGENT },
      timeout: 15_000,
    });
    const mimeType = String(res.headers['content-type'] ?? 'image/jpeg').split(';')[0] ?? 'image/jpeg';
    const data = Buffer.from(res.data).toString('base64');
    const out = { data, mimeType };
    // Archival scans are stable — reuse the show_transcription TTL (1 day).
    await cacheSet(key, out, 'show_transcription');
    return out;
  } catch (err) {
    log.warn({ url, err: err instanceof Error ? err.message : String(err) }, 'image fetch failed');
    return null;
  }
}

async function fetchTranscriptionPage(id: string): Promise<ViewerPage> {
  if (!SHOW_TX) throw new Error('show_transcription tool not available');
  const data = (await callUpstream(SHOW_TX, { id, lang: 'nl' })) as {
    page?: unknown;
    transcript?: unknown;
    thumb_url?: string;
    source_url?: string;
    source_archive?: { isil?: string; name?: string };
    archive_number?: { nr?: string; title?: string; url?: string };
    inventory_number?: { nr?: string; title?: string; url?: string };
  };
  const thumbUrl = data?.thumb_url;
  const isil = data?.source_archive?.isil?.trim() || undefined;
  return {
    id,
    page: String(data?.page ?? ''),
    transcript: String(data?.transcript ?? ''),
    thumbUrl,
    sourceUrl: data?.source_url,
    archive: data?.source_archive?.name,
    archiveIsil: isil,
    archiveLogo: isil
      ? `https://www.openarchieven.nl/img/archives/${encodeURIComponent(isil)}.png`
      : undefined,
    archiveRef: cleanRef(data?.archive_number),
    inventoryRef: cleanRef(data?.inventory_number),
    ...deriveTileSource(thumbUrl),
  };
}

const MAX_INLINE_IMAGES = 3;

type ViewerContent =
  | { type: 'text'; text: string }
  | { type: 'image'; data: string; mimeType: string };

function registerViewer(server: McpServer): void {
  registerAppTool(
    server,
    'view_transcription',
    {
      title: titleFor('view_transcription'),
      description:
        'Open one or more transcribed document pages in an interactive deep-zoom viewer ' +
        'with the transcription text alongside. Pass page identifiers returned by ' +
        'search_transcriptions / browse_transcriptions (form <ISIL>_<archive>_<page>, ' +
        'e.g. NL-SdmGA_1504889_11). Optionally highlight a term in the transcript. Hosts ' +
        'without MCP Apps support receive a text summary plus inline preview images.',
      inputSchema: {
        ids: z
          .array(z.string())
          .min(1)
          .max(20)
          .describe('Transcription page identifiers, e.g. ["NL-SdmGA_1504889_11"].'),
        highlight_term: z
          .string()
          .optional()
          .describe('Optional term to highlight in the transcription text.'),
      },
      annotations: {
        title: titleFor('view_transcription'),
        readOnlyHint: true,
        destructiveHint: false,
        openWorldHint: true,
      },
      _meta: { ui: { resourceUri: VIEWER_URI } },
    },
    async ({ ids, highlight_term }) => {
      const settled = await Promise.allSettled(ids.map(fetchTranscriptionPage));
      const pages = settled
        .filter((r): r is PromiseFulfilledResult<ViewerPage> => r.status === 'fulfilled')
        .map((r) => r.value);
      const failed = ids.filter((_, i) => settled[i]?.status === 'rejected');

      if (pages.length === 0) {
        return {
          content: [{ type: 'text' as const, text: `Could not load any of: ${ids.join(', ')}` }],
          isError: true,
        };
      }

      // Text summary = what a non-Apps host shows the model/user (with IIIF URLs).
      const refLine = (r?: SourceRef) => [r?.nr, r?.title].filter(Boolean).join(' — ');
      const summaryLines = pages.map((p) =>
        [
          `• ${p.id} (page ${p.page})`,
          p.archive ? `  archive:   ${p.archive}${p.archiveIsil ? ` (${p.archiveIsil})` : ''}` : '',
          p.archiveRef ? `  fonds:     ${refLine(p.archiveRef)}` : '',
          p.inventoryRef ? `  inventory: ${refLine(p.inventoryRef)}` : '',
          p.sourceUrl ? `  source:    ${p.sourceUrl}` : '',
          p.thumbUrl ? `  image:     ${p.thumbUrl}` : '',
        ]
          .filter(Boolean)
          .join('\n'),
      );
      const summary =
        `Opened viewer with ${pages.length} page(s):\n${summaryLines.join('\n')}` +
        (failed.length ? `\n\nFailed to load: ${failed.join(', ')}` : '');

      const content: ViewerContent[] = [{ type: 'text', text: summary }];

      // Route A fallback: inline a few preview images so plain hosts show a picture.
      for (const p of pages.slice(0, MAX_INLINE_IMAGES)) {
        if (!p.thumbUrl) continue;
        const img = await fetchImageDataUrl(iiifDerivative(p.thumbUrl));
        if (img) content.push({ type: 'image', data: img.data, mimeType: img.mimeType });
      }

      return {
        content,
        structuredContent: { pages, highlightTerm: highlight_term ?? '' },
      };
    },
  );

  registerAppResource(
    server,
    'Open Archieven IIIF viewer',
    VIEWER_URI,
    {
      mimeType: RESOURCE_MIME_TYPE,
      description: 'Deep-zoom IIIF viewer with transcription overlay.',
    },
    async () => ({
      contents: [
        {
          uri: VIEWER_URI,
          mimeType: RESOURCE_MIME_TYPE,
          text: VIEWER_HTML,
          _meta: { ui: { csp: VIEWER_CSP } },
        },
      ],
    }),
  );
}

// ─── MCP Server factory ───────────────────────────────────────────────────────

function createMcpServer(): McpServer {
  const server = new McpServer({
    name: 'openarchieven',
    version: '1.1.1',
  });

  const registerTool = (name: string, tool: ToolDef) => {
    const shape = buildZodShape(tool.params);
    const title = titleFor(name);
    server.registerTool(
      name,
      {
        title,
        description: tool.description,
        inputSchema: shape,
        annotations: {
          title, // legacy ToolAnnotations.title, for hosts that read the label from annotations
          readOnlyHint: true,
          destructiveHint: false,
          openWorldHint: true,
        },
      },
      async (args) => {
        log.info({ tool: name, args }, 'mcp tool call');
        try {
          const result = await callUpstream(tool, args as Record<string, unknown>);
          return {
            content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
          };
        } catch (err) {
          const msg = err instanceof Error ? err.message : String(err);
          log.error({ tool: name, err: msg }, 'tool call failed');
          return {
            content: [{ type: 'text' as const, text: `Error: ${msg}` }],
            isError: true,
          };
        }
      },
    );
  };

  for (const tool of TOOLS) registerTool(tool.name, tool);

  registerViewer(server);

  return server;
}

// ─── Pagination helper ────────────────────────────────────────────────────────

interface Page {
  data: unknown;
  pageNum: number;
  done: boolean;
}

async function* paginate(
  tool: ToolDef,
  params: Record<string, unknown>,
): AsyncGenerator<Page> {
  const MAX_PAGES = 20;
  const numberShow = (params['number_show'] as number | undefined) ?? 10;

  if (!tool.pageable) {
    const data = await callUpstream(tool, params);
    yield { data, pageNum: 1, done: true };
    return;
  }

  let start = (params['start'] as number | undefined) ?? 0;

  for (let page = 1; page <= MAX_PAGES; page++) {
    const result = await callUpstream(tool, { ...params, start }) as Record<string, unknown>;
    const response = result['response'] as Record<string, unknown> | undefined;
    const docs = (response?.['docs'] as unknown[]) ?? [];
    const numberFound = (response?.['number_found'] as number | undefined) ?? 0;

    const done =
      docs.length === 0 ||
      start + numberShow >= numberFound ||
      page === MAX_PAGES;

    yield { data: result, pageNum: page, done };
    if (done) break;
    start += numberShow;
  }
}

// ─── Request logging middleware ───────────────────────────────────────────────

const app = express();
app.disable('x-powered-by');
app.use(express.json());

app.use((req: Request, res: Response, next: NextFunction) => {
  const t0 = Date.now();
  res.on('finish', () => {
    log.info({
      method: req.method,
      path: req.path,
      status: res.statusCode,
      ms: Date.now() - t0,
    }, 'request');
  });
  next();
});

// ── Discovery metadata (static, hand-editable JSON) ──────────────────────────
//   /.well-known/mcp/server-card.json  — SEP-1649 MCP Server Card
//   /.well-known/mcp.json              — SEP-1960 alias (same body)
//   /.well-known/agent-card.json       — A2A v0.3 Agent Card
//   /.well-known/agent.json            — older A2A path (same body)
const WELL_KNOWN_DIR = path.join(__dirname, 'well-known');

function serveWellKnown(filename: string) {
  return (_req: Request, res: Response) => {
    fs.readFile(path.join(WELL_KNOWN_DIR, filename), 'utf8', (err, body) => {
      if (err) {
        log.error({ file: filename, err: err.message }, 'well-known file missing');
        res.status(404).json({ error: 'Not found' });
        return;
      }
      res.setHeader('Content-Type', 'application/json; charset=utf-8');
      res.setHeader('Cache-Control', 'public, max-age=3600');
      res.send(body);
    });
  };
}

app.get('/.well-known/mcp/server-card.json', serveWellKnown('mcp-server-card.json'));
app.get('/.well-known/mcp.json',             serveWellKnown('mcp-server-card.json'));
app.get('/.well-known/agent-card.json',      serveWellKnown('agent-card.json'));
app.get('/.well-known/agent.json',           serveWellKnown('agent-card.json'));

// ── Health ────────────────────────────────────────────────────────────────────
app.get('/health', (_req, res) => {
  res.json({
    ok: true,
    tools: TOOLS.length,
    redis: redisAvailable,
    uptime: process.uptime(),
  });
});

// ── List tools ────────────────────────────────────────────────────────────────
app.get('/tools', (_req, res) => {
  res.json(TOOLS.map((t) => t.name));
});

// ── Direct HTTP tool call ─────────────────────────────────────────────────────
app.post('/tools/:name', async (req: Request, res: Response) => {
  const name = req.params['name'] as string;
  const tool = resolveTool(name);
  if (!tool) {
    log.warn({ tool: name }, 'unknown tool');
    res.status(404).json({ error: `Unknown tool: ${name}` });
    return;
  }

  try {
    const result = await callUpstream(tool, req.body as Record<string, unknown>);
    res.json(result);
  } catch (err) {
    const status = axios.isAxiosError(err) ? (err.response?.status ?? 500) : 500;
    const msg = err instanceof Error ? err.message : String(err);
    log.error({ tool: name, status, err: msg }, 'http tool call failed');
    res.status(status).json({ error: msg });
  }
});

// ── SSE streaming with auto-pagination ───────────────────────────────────────
app.get('/events/:name', async (req: Request, res: Response) => {
  const name = req.params['name'] as string;
  const tool = resolveTool(name);
  if (!tool) {
    res.status(404).json({ error: `Unknown tool: ${name}` });
    return;
  }

  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  res.flushHeaders();

  const heartbeat = setInterval(() => res.write(': heartbeat\n\n'), 10_000);
  req.on('close', () => clearInterval(heartbeat));

  try {
    const params = req.query as Record<string, unknown>;
    log.info({ tool: name, params }, 'sse stream start');
    let pages = 0;
    for await (const page of paginate(tool, params)) {
      res.write(`event: page\ndata: ${JSON.stringify(page.data)}\n\n`);
      pages++;
      if (page.done) break;
    }
    log.info({ tool: name, pages }, 'sse stream done');
    res.write('event: done\ndata: {}\n\n');
  } catch (err) {
    const msg = err instanceof Error ? err.message : String(err);
    log.error({ tool: name, err: msg }, 'sse stream error');
    res.write(`event: error\ndata: ${JSON.stringify({ error: msg })}\n\n`);
  } finally {
    clearInterval(heartbeat);
    res.end();
  }
});

// ── Chunked HTTP streaming with auto-pagination ───────────────────────────────
app.post('/stream/:name', async (req: Request, res: Response) => {
  const name = req.params['name'] as string;
  const tool = resolveTool(name);
  if (!tool) {
    res.status(404).json({ error: `Unknown tool: ${name}` });
    return;
  }

  res.setHeader('Content-Type', 'application/x-ndjson');
  res.setHeader('Transfer-Encoding', 'chunked');

  try {
    const params = req.body as Record<string, unknown>;
    log.info({ tool: name, params }, 'chunked stream start');
    let pages = 0;
    for await (const page of paginate(tool, params)) {
      res.write(JSON.stringify(page.data) + '\n');
      pages++;
      if (page.done) break;
    }
    log.info({ tool: name, pages }, 'chunked stream done');
  } catch (err) {
    const msg = err instanceof Error ? err.message : String(err);
    log.error({ tool: name, err: msg }, 'chunked stream error');
    res.write(JSON.stringify({ error: msg }) + '\n');
  } finally {
    res.end();
  }
});

// ── MCP endpoint — custom one-shot transport (no Accept-header requirement) ───
//
// StreamableHTTPServerTransport mandates Accept: application/json, text/event-stream.
// Instead we implement a minimal Transport that handles one JSON-RPC round-trip
// and returns the response directly as JSON — no special headers required.

class OneShotTransport implements Transport {
  onmessage?: (message: JSONRPCMessage) => void;
  onclose?: () => void;
  onerror?: (error: Error) => void;

  private _resolve?: (message: JSONRPCMessage) => void;

  async start(): Promise<void> {}
  async close(): Promise<void> { this.onclose?.(); }

  // Called by McpServer to send the response back to us
  async send(message: JSONRPCMessage): Promise<void> {
    // Only resolve on messages that carry an id (responses), not notifications
    if ('id' in message) this._resolve?.(message);
  }

  // Deliver the incoming request to the McpServer
  deliver(message: JSONRPCMessage): void {
    this.onmessage?.(message);
  }

  waitForResponse(timeoutMs = 30_000): Promise<JSONRPCMessage> {
    return new Promise((resolve, reject) => {
      const timer = setTimeout(() => reject(new Error('MCP response timeout')), timeoutMs);
      this._resolve = (msg) => { clearTimeout(timer); resolve(msg); };
    });
  }
}

function validateOrigin(req: Request, res: Response, next: NextFunction) {
  const origin = req.headers.origin as string | undefined;
  if (!isOriginAllowed(origin)) {
    log.warn({ origin, path: req.path }, 'rejected: Origin not allowed');
    res.status(403).json({ error: 'Origin not allowed' });
    return;
  }
  next();
}

async function handleMcp(req: Request, res: Response, next: NextFunction) {
  const body = req.body as JSONRPCMessage;
  const isNotification = !('id' in body);

  const server = createMcpServer();
  const transport = new OneShotTransport();

  try {
    await server.connect(transport);

    if (isNotification) {
      transport.deliver(body);
      res.status(202).end();
      return;
    }

    const responsePromise = transport.waitForResponse();
    transport.deliver(body);
    const response = await responsePromise;
    res.json(response);
  } catch (err) {
    next(err);
  } finally {
    server.close().catch(() => undefined);
  }
}

// Mounted on both / (canonical public URL) and /mcp (local/legacy).
// POST-only; Origin is validated to prevent DNS-rebinding from untrusted sites.
app.post('/', validateOrigin, handleMcp);
app.post('/mcp', validateOrigin, handleMcp);

// GET / — content-negotiated:
//   Accept: text/event-stream  → 405 (MCP spec: no server-initiated SSE here)
//   anything else (browsers)   → static landing page (index.html, hot-editable)
const INDEX_HTML_PATH = path.join(__dirname, 'index.html');

app.get('/', (req: Request, res: Response) => {
  const wants = req.accepts(['html', 'text/event-stream']);
  if (wants === 'text/event-stream') {
    res.setHeader('Allow', 'POST');
    res.status(405).json({ error: 'Method Not Allowed. Use POST for MCP JSON-RPC.' });
    return;
  }
  fs.readFile(INDEX_HTML_PATH, 'utf8', (err, body) => {
    if (err) {
      log.error({ err: err.message }, 'index.html missing');
      res.status(500).json({ error: 'Landing page unavailable' });
      return;
    }
    res.setHeader('Content-Type', 'text/html; charset=utf-8');
    res.setHeader('Cache-Control', 'public, max-age=300');
    res.send(body);
  });
});

// ─── Start ────────────────────────────────────────────────────────────────────

initRedis();

// Only bind a port when run directly (e.g. `tsx server.ts`).
// When imported (e.g. by api/index.ts on Vercel) we just export the app.
const isEntrypoint =
  import.meta.url === pathToFileURL(process.argv[1] ?? '').href;

if (isEntrypoint) {
  app.listen(PORT, '0.0.0.0', () => {
    log.info({
      port: PORT,
      tools: TOOLS.length,
      upstream: UPSTREAM_BASE,
      rateLimit: `${RATE_LIMIT_RPS} req/s`,
      redis: REDIS_URL,
      env: process.env['NODE_ENV'] ?? 'development',
    }, 'Open Archieven MCP server started');
  });
}

export default app;