@adsim/wordpress-mcp-server 4.6.0 → 5.1.0

package/src/tools/workflow.js

@@ -0,0 +1,409 @@
+// src/tools/workflow.js — workflow tools (9)
+// Definitions + handlers (v5.0.0 refactor Step B+C)
+
+import { json } from '../shared/utils.js';
+import { validateInput } from '../shared/governance.js';
+import { rt } from '../shared/context.js';
+
+// ── Named workflows ────────────────────────────────────────────
+const NAMED_WORKFLOWS = {
+  'seo_audit_and_stage': {
+    description: 'Full SEO audit then create staging draft',
+    required_context: ['post_id'],
+    steps: [
+      { tool: 'wp_audit_seo_score',      args: { post_id: '{{post_id}}' } },
+      { tool: 'wp_analyze_readability',   args: { post_id: '{{post_id}}' } },
+      { tool: 'wp_create_staging_draft',  args: { source_post_id: '{{post_id}}' } }
+    ]
+  },
+  'site_health_report': {
+    description: 'Complete site health and diagnostics',
+    required_context: [],
+    steps: [
+      { tool: 'wp_get_site_health_status', args: {} },
+      { tool: 'wp_list_site_health_issues', args: {} },
+      { tool: 'wp_get_site_health_info',    args: {} }
+    ]
+  },
+  'content_publish_safe': {
+    description: 'Validate blocks then publish post',
+    required_context: ['post_id', 'content'],
+    steps: [
+      { tool: 'wp_validate_block_structure', args: { content: '{{content}}' } },
+      { tool: 'wp_update_post',              args: { id: '{{post_id}}', status: 'publish' } }
+    ]
+  },
+  'wc_product_audit': {
+    description: 'WooCommerce product SEO and stock audit',
+    required_context: [],
+    steps: [
+      { tool: 'wc_audit_product_seo',  args: { limit: 50 } },
+      { tool: 'wc_audit_stock_alerts', args: { threshold: 5 } }
+    ]
+  }
+};
+
+// ── Template resolution ────────────────────────────────────────
+function resolveTemplates(obj, context) {
+  if (typeof obj === 'string') {
+    return obj.replace(/\{\{(\w+)\}\}/g, (_, key) => context[key] !== undefined ? context[key] : `{{${key}}}`);
+  }
+  if (Array.isArray(obj)) return obj.map(item => resolveTemplates(item, context));
+  if (obj && typeof obj === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) out[k] = resolveTemplates(v, context);
+    return out;
+  }
+  return obj;
+}
+
+export const definitions = [
+  { name: 'wp_submit_for_review', _category: 'workflow', description: 'Use to transition a draft post to pending status for editorial review. Write — blocked by WP_READ_ONLY.',
+        inputSchema: { type: 'object', properties: { id: { type: 'number' }, note: { type: 'string', description: 'Optional review note (stored as post meta _mcp_review_note)' } }, required: ['id'] }},
+  { name: 'wp_approve_post', _category: 'workflow', description: 'Use to transition a pending post to published (editor/admin action). Write — blocked by WP_READ_ONLY, WP_DRAFT_ONLY.',
+        inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] }},
+  { name: 'wp_reject_post', _category: 'workflow', description: 'Use to return a pending post to draft with a mandatory rejection reason. Write — blocked by WP_READ_ONLY.',
+        inputSchema: { type: 'object', properties: { id: { type: 'number' }, reason: { type: 'string', description: 'Reason for rejection (stored as post meta _mcp_rejection_reason)' } }, required: ['id', 'reason'] }},
+  { name: 'wp_create_staging_draft', _category: 'workflow', description: 'Use to clone a published post/page into a shadow draft for safe editing. The live page stays untouched. Write — blocked by WP_READ_ONLY.',
+        inputSchema: { type: 'object', properties: { source_id: { type: 'number', description: 'ID of the published post or page to clone' }, post_type: { type: 'string', enum: ['post', 'page'], default: 'page', description: 'Content type of the source' } }, required: ['source_id'] }},
+  { name: 'wp_list_staging_drafts', _category: 'workflow', description: 'Use to list all pending staging drafts, optionally filtered by source page. Read-only.',
+        inputSchema: { type: 'object', properties: { source_id: { type: 'number', description: 'Filter by original published page ID' }, per_page: { type: 'number', default: 20 }, page: { type: 'number', default: 1 } } }},
+  { name: 'wp_get_staging_preview_url', _category: 'workflow', description: 'Use to get the native WordPress preview URL for a staging draft. Read-only.',
+        inputSchema: { type: 'object', properties: { staging_id: { type: 'number', description: 'ID of the staging draft' } }, required: ['staging_id'] }},
+  { name: 'wp_merge_staging_to_live', _category: 'workflow', description: 'Use to push validated staging draft content to the live published page. Write — blocked by WP_READ_ONLY. Two-step: first call returns dry-run preview, pass confirm:true to execute.',
+        inputSchema: { type: 'object', properties: { staging_id: { type: 'number', description: 'ID of the staging draft' }, confirm: { type: 'boolean', default: false, description: 'false=dry-run preview, true=execute merge' } }, required: ['staging_id'] }},
+  { name: 'wp_discard_staging_draft', _category: 'workflow', description: 'Use to permanently delete a staging draft without touching the live page. Write — blocked by WP_READ_ONLY. Two-step: first call returns dry-run, pass confirm:true to execute.',
+        inputSchema: { type: 'object', properties: { staging_id: { type: 'number', description: 'ID of the staging draft to discard' }, confirm: { type: 'boolean', default: false, description: 'false=dry-run, true=execute deletion' } }, required: ['staging_id'] }},
+  { name: 'wp_run_workflow', _category: 'workflow', description: 'Execute a named workflow (sequence of tools) in a single call. Reduces latency and token usage vs sequential calls.',
+        inputSchema: { type: 'object', properties: { workflow: { type: 'string', description: 'Named workflow OR "custom"' }, steps: { type: 'array', description: 'Required if workflow="custom". Array of {tool, args}' }, context: { type: 'object', description: 'Shared variables available as {{key}} in step args' }, dry_run: { type: 'boolean', default: false, description: 'Return execution plan without running' }, stop_on_error: { type: 'boolean', default: true, description: 'Stop sequence on first failure' } }, required: ['workflow'] }}
+];
+
+export const handlers = {};
+
+handlers['wp_submit_for_review'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 } });
+  const { id, note } = args;
+  const p = await wpApiCall(`/posts/${id}`);
+  if (p.status !== 'draft' && p.status !== 'auto-draft') {
+    throw new Error(`Post ${id} is in "${p.status}" status. Only "draft" or "auto-draft" posts can be submitted for review.`);
+  }
+  const data = { status: 'pending' };
+  if (note) data.meta = { _mcp_review_note: note };
+  const up = await wpApiCall(`/posts/${id}`, { method: 'POST', body: JSON.stringify(data) });
+  result = json({ success: true, message: `Post ${id} submitted for review`, post: { id: up.id, title: up.title.rendered, status: up.status, link: up.link } });
+  auditLog({ tool: name, target: id, target_type: 'post', action: 'submit_for_review', status: 'success', latency_ms: Date.now() - t0, params: { id } });
+  return result;
+};
+handlers['wp_approve_post'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, getActiveControls, auditLog, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 } });
+  const { id } = args;
+  if (getActiveControls().draft_only) {
+    auditLog({ tool: name, target: id, target_type: 'post', action: 'approve', status: 'blocked', latency_ms: Date.now() - t0, params: { id }, error: 'Blocked: Server is in DRAFT-ONLY mode (WP_DRAFT_ONLY=true). Publishing is not allowed.' });
+    return { content: [{ type: 'text', text: 'Error: Blocked: Server is in DRAFT-ONLY mode (WP_DRAFT_ONLY=true). Publishing is not allowed.' }], isError: true };
+  }
+  const p = await wpApiCall(`/posts/${id}`);
+  if (p.status !== 'pending') {
+    throw new Error(`Post ${id} is in "${p.status}" status. Only "pending" posts can be approved.`);
+  }
+  const up = await wpApiCall(`/posts/${id}`, { method: 'POST', body: JSON.stringify({ status: 'publish' }) });
+  result = json({ success: true, message: `Post ${id} approved and published`, post: { id: up.id, title: up.title.rendered, status: up.status, link: up.link } });
+  auditLog({ tool: name, target: id, target_type: 'post', action: 'approve', status: 'success', latency_ms: Date.now() - t0, params: { id } });
+  return result;
+};
+handlers['wp_reject_post'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { id: { type: 'number', required: true, min: 1 }, reason: { type: 'string', required: true } });
+  const { id, reason } = args;
+  const p = await wpApiCall(`/posts/${id}`);
+  if (p.status !== 'pending') {
+    throw new Error(`Post ${id} is in "${p.status}" status. Only "pending" posts can be rejected.`);
+  }
+  const currentCount = parseInt(p.meta?._mcp_rejection_count || '0', 10);
+  const up = await wpApiCall(`/posts/${id}`, { method: 'POST', body: JSON.stringify({ status: 'draft', meta: { _mcp_rejection_reason: reason, _mcp_rejection_count: currentCount + 1 } }) });
+  result = json({ success: true, message: `Post ${id} rejected and moved to draft`, post: { id: up.id, title: up.title.rendered, status: up.status }, rejection: { reason, count: currentCount + 1 } });
+  auditLog({ tool: name, target: id, target_type: 'post', action: 'reject', status: 'success', latency_ms: Date.now() - t0, params: { id } });
+  return result;
+};
+handlers['wp_create_staging_draft'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { source_id: { type: 'number', required: true, min: 1 } });
+  const { source_id, post_type = 'page' } = args;
+  const endpoint = post_type === 'post' ? `/posts/${source_id}` : `/pages/${source_id}`;
+  const source = await wpApiCall(endpoint);
+  if (source.status !== 'publish') {
+    throw new Error(`Source ${post_type} ${source_id} is in "${source.status}" status. Only published content can be staged.`);
+  }
+  // Check if a staging draft already exists
+  const searchEndpoint = post_type === 'post' ? '/posts' : '/pages';
+  const existing = await wpApiCall(`${searchEndpoint}?status=draft&per_page=100&meta_key=_staging_source_id&meta_value=${source_id}`);
+  // WP REST API may not filter by meta — fallback: check returned posts
+  const existingDraft = Array.isArray(existing) ? existing.find(p => p.meta?._staging_source_id == source_id) : null;
+  if (existingDraft) {
+    result = json({ status: 'already_exists', staging_draft_id: existingDraft.id, source_id, message: `A staging draft already exists for ${post_type} ${source_id}` });
+    auditLog({ tool: name, target: source_id, target_type: post_type, action: 'create_staging', status: 'skipped', latency_ms: Date.now() - t0, params: { source_id } });
+    return result;
+  }
+  const sourceTitle = source.title?.rendered || '';
+  const draftData = {
+    title: `[STAGING] ${sourceTitle}`,
+    content: source.content?.rendered || '',
+    excerpt: source.excerpt?.rendered || '',
+    status: 'draft',
+    meta: { _staging_source_id: source_id }
+  };
+  if (post_type === 'page') {
+    draftData.parent = source.parent || 0;
+    draftData.template = source.template || '';
+  }
+  const createEndpoint = post_type === 'post' ? '/posts' : '/pages';
+  const draft = await wpApiCall(createEndpoint, { method: 'POST', body: JSON.stringify(draftData) });
+  result = json({ status: 'created', staging_draft_id: draft.id, source_id, source_title: sourceTitle, message: `Staging draft created. Edit draft ${draft.id}, then use wp_merge_staging_to_live to publish changes.` });
+  auditLog({ tool: name, target: draft.id, target_type: post_type, action: 'create_staging', status: 'success', latency_ms: Date.now() - t0, params: { source_id, staging_draft_id: draft.id } });
+  return result;
+};
+handlers['wp_list_staging_drafts'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  const { source_id, per_page = 20, page = 1 } = args;
+  // Search for drafts with [STAGING] prefix
+  const posts = await wpApiCall(`/posts?status=draft&per_page=${per_page}&page=${page}&search=${encodeURIComponent('[STAGING]')}`);
+  const pages = await wpApiCall(`/pages?status=draft&per_page=${per_page}&page=${page}&search=${encodeURIComponent('[STAGING]')}`);
+  let all = [
+    ...(Array.isArray(posts) ? posts : []).map(p => ({ ...p, _type: 'post' })),
+    ...(Array.isArray(pages) ? pages : []).map(p => ({ ...p, _type: 'page' }))
+  ].filter(p => p.meta?._staging_source_id);
+  if (source_id) {
+    all = all.filter(p => p.meta._staging_source_id == source_id);
+  }
+  result = json({
+    total: all.length,
+    staging_drafts: all.map(p => ({
+      staging_id: p.id,
+      source_id: p.meta._staging_source_id,
+      type: p._type,
+      title: p.title?.rendered || '',
+      modified: p.modified,
+      link: p.link
+    }))
+  });
+  auditLog({ tool: name, action: 'list_staging', status: 'success', latency_ms: Date.now() - t0, params: { source_id } });
+  return result;
+};
+handlers['wp_get_staging_preview_url'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, getActiveAuth, auditLog, name } = rt;
+  validateInput(args, { staging_id: { type: 'number', required: true, min: 1 } });
+  const { staging_id } = args;
+  // Try pages first, then posts
+  let draft, postType;
+  try {
+    draft = await wpApiCall(`/pages/${staging_id}`);
+    postType = 'page';
+  } catch (e) {
+    draft = await wpApiCall(`/posts/${staging_id}`);
+    postType = 'post';
+  }
+  if (!draft.meta?._staging_source_id) {
+    throw new Error(`${postType} ${staging_id} is not a staging draft (missing _staging_source_id meta).`);
+  }
+  const { url: siteUrl } = getActiveAuth();
+  const preview_url = `${siteUrl}/?p=${staging_id}&preview=true`;
+  result = json({ staging_id, source_id: draft.meta._staging_source_id, preview_url, status: draft.status, title: draft.title?.rendered || '' });
+  auditLog({ tool: name, target: staging_id, target_type: postType, action: 'preview_staging', status: 'success', latency_ms: Date.now() - t0 });
+  return result;
+};
+handlers['wp_merge_staging_to_live'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { staging_id: { type: 'number', required: true, min: 1 } });
+  const { staging_id, confirm = false } = args;
+  // Try pages first, then posts
+  let draft, postType, endpoint;
+  try {
+    draft = await wpApiCall(`/pages/${staging_id}`);
+    postType = 'page';
+    endpoint = '/pages';
+  } catch (e) {
+    draft = await wpApiCall(`/posts/${staging_id}`);
+    postType = 'post';
+    endpoint = '/posts';
+  }
+  if (!draft.meta?._staging_source_id) {
+    throw new Error(`${postType} ${staging_id} is not a staging draft (missing _staging_source_id meta).`);
+  }
+  const sourceId = draft.meta._staging_source_id;
+  const live = await wpApiCall(`${endpoint}/${sourceId}`);
+  if (!confirm) {
+    // Dry-run: show what would change
+    result = json({
+      status: 'dry_run',
+      staging_id,
+      source_id: sourceId,
+      changes_preview: {
+        title: { from: live.title?.rendered, to: draft.title?.rendered?.replace('[STAGING] ', '') },
+        content_length: { from: (live.content?.rendered || '').length, to: (draft.content?.rendered || '').length },
+        excerpt: { from: live.excerpt?.rendered, to: draft.excerpt?.rendered }
+      },
+      message: 'Call again with confirm=true to merge staging draft to live page.'
+    });
+    auditLog({ tool: name, target: staging_id, target_type: postType, action: 'merge_staging_preview', status: 'dry_run', latency_ms: Date.now() - t0, params: { staging_id, source_id: sourceId } });
+    return result;
+  }
+  // Execute merge
+  const mergeData = {
+    title: (draft.title?.rendered || '').replace('[STAGING] ', ''),
+    content: draft.content?.rendered || '',
+    excerpt: draft.excerpt?.rendered || ''
+  };
+  const updated = await wpApiCall(`${endpoint}/${sourceId}`, { method: 'POST', body: JSON.stringify(mergeData) });
+  // Delete the staging draft
+  await wpApiCall(`${endpoint}/${staging_id}?force=true`, { method: 'DELETE' });
+  result = json({
+    status: 'merged',
+    source_id: sourceId,
+    staging_id,
+    message: `Staging draft merged to live ${postType} ${sourceId}. Draft ${staging_id} deleted.`,
+    live: { id: updated.id, title: updated.title?.rendered, status: updated.status, link: updated.link, modified: updated.modified }
+  });
+  auditLog({ tool: name, target: sourceId, target_type: postType, action: 'merge_staging', status: 'success', latency_ms: Date.now() - t0, params: { staging_id, source_id: sourceId } });
+  return result;
+};
+handlers['wp_discard_staging_draft'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, name } = rt;
+  validateInput(args, { staging_id: { type: 'number', required: true, min: 1 } });
+  const { staging_id, confirm = false } = args;
+  // Try pages first, then posts
+  let draft, postType, endpoint;
+  try {
+    draft = await wpApiCall(`/pages/${staging_id}`);
+    postType = 'page';
+    endpoint = '/pages';
+  } catch (e) {
+    draft = await wpApiCall(`/posts/${staging_id}`);
+    postType = 'post';
+    endpoint = '/posts';
+  }
+  if (!draft.meta?._staging_source_id) {
+    throw new Error(`${postType} ${staging_id} is not a staging draft (missing _staging_source_id meta).`);
+  }
+  if (!confirm) {
+    result = json({
+      status: 'dry_run',
+      staging_id,
+      source_id: draft.meta._staging_source_id,
+      title: draft.title?.rendered || '',
+      message: 'Call again with confirm=true to permanently delete this staging draft. The live page will not be affected.'
+    });
+    auditLog({ tool: name, target: staging_id, target_type: postType, action: 'discard_staging_preview', status: 'dry_run', latency_ms: Date.now() - t0, params: { staging_id } });
+    return result;
+  }
+  const srcId = draft.meta._staging_source_id;
+  await wpApiCall(`${endpoint}/${staging_id}?force=true`, { method: 'DELETE' });
+  result = json({
+    status: 'discarded',
+    staging_id,
+    source_id: srcId,
+    message: `Staging draft ${staging_id} permanently deleted. Live ${postType} ${srcId} was not modified.`
+  });
+  auditLog({ tool: name, target: staging_id, target_type: postType, action: 'discard_staging', status: 'success', latency_ms: Date.now() - t0, params: { staging_id, source_id: srcId } });
+  return result;
+};
+
+/**
+ * Factory to create the wp_run_workflow handler.
+ * Called from src/tools/index.js after allHandlers is built, to avoid circular import.
+ */
+export function createWorkflowHandler(getHandlerFn) {
+  return async (args) => {
+    const { auditLog } = rt;
+    const { workflow, steps: customSteps, context: ctx = {}, dry_run = false, stop_on_error = true } = args;
+
+    // 1. Resolve workflow
+    let steps;
+    if (workflow === 'custom') {
+      if (!customSteps || !Array.isArray(customSteps) || customSteps.length === 0) {
+        throw new Error('workflow="custom" requires a non-empty "steps" array of {tool, args}.');
+      }
+      steps = customSteps;
+    } else {
+      const named = NAMED_WORKFLOWS[workflow];
+      if (!named) {
+        throw new Error(`Unknown workflow "${workflow}". Available: ${Object.keys(NAMED_WORKFLOWS).join(', ')}`);
+      }
+      // 2. Validate required context
+      const missing = named.required_context.filter(k => ctx[k] === undefined);
+      if (missing.length > 0) {
+        throw new Error(`Workflow "${workflow}" requires context keys: ${missing.join(', ')}`);
+      }
+      steps = named.steps;
+    }
+
+    // 3. Resolve templates
+    const resolvedSteps = steps.map(s => ({
+      tool: s.tool,
+      args: resolveTemplates(s.args || {}, ctx)
+    }));
+
+    // 4. Dry run
+    if (dry_run) {
+      return json({
+        mode: 'dry_run',
+        workflow,
+        steps_total: resolvedSteps.length,
+        execution_plan: resolvedSteps.map(s => ({ tool: s.tool, resolved_args: s.args })),
+        hint: 'Set dry_run=false to execute'
+      });
+    }
+
+    // 5. Execute
+    const t0 = Date.now();
+    const results = [];
+    for (const step of resolvedSteps) {
+      const stepT0 = Date.now();
+      try {
+        const handler = getHandlerFn(step.tool);
+        if (!handler) throw new Error(`Unknown tool: ${step.tool}`);
+        const stepResult = await handler(step.args);
+        const resultText = stepResult?.content?.[0]?.text || '';
+        let parsedResult;
+        try { parsedResult = JSON.parse(resultText); } catch { parsedResult = resultText; }
+        results.push({ tool: step.tool, status: 'success', duration_ms: Date.now() - stepT0, result: parsedResult });
+      } catch (e) {
+        results.push({ tool: step.tool, status: 'error', duration_ms: Date.now() - stepT0, error: e.message });
+        if (stop_on_error !== false) break;
+      }
+    }
+
+    const completed = results.filter(r => r.status === 'success').length;
+    auditLog({
+      tool: 'wp_run_workflow', action: workflow,
+      status: completed === resolvedSteps.length ? 'success' : 'partial',
+      latency_ms: Date.now() - t0,
+      params: { steps_total: resolvedSteps.length, steps_completed: completed }
+    });
+
+    return json({
+      workflow,
+      steps_total: resolvedSteps.length,
+      steps_completed: completed,
+      total_duration_ms: Date.now() - t0,
+      results,
+      summary: `${completed}/${resolvedSteps.length} steps completed`
+    });
+  };
+}

package/src/transport/http.js

@@ -12,10 +12,44 @@
  */
 
 import { createServer as createHttpServer } from 'node:http';
+import { createReadStream, existsSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { validateBearerToken } from '../auth/bearer.js';
 
+const STATIC_MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.txt': 'text/plain',
+};
+
+async function serveStatic(pathname, res, staticDir) {
+  let filePath = join(staticDir, pathname === '/' ? 'index.html' : pathname);
+  if (!existsSync(filePath) || statSync(filePath).isDirectory()) {
+    filePath = join(staticDir, 'index.html'); // SPA fallback
+  }
+  if (!existsSync(filePath)) {
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found');
+    return;
+  }
+  const contentType = STATIC_MIME[extname(filePath)] ?? 'application/octet-stream';
+  res.writeHead(200, { 'Content-Type': contentType });
+  createReadStream(filePath).pipe(res);
+}
+
 /**
  * @typedef {object} HttpConfig
  * @property {number}   [port=3000]
@@ -31,6 +65,7 @@ const DEFAULT_CONFIG = {
   authToken: null,
   allowedOrigins: [],
   sessionTimeoutMs: 30 * 60 * 1000,
+  staticDir: null, // optional: serve static files from this directory
 };
 
 export class HttpTransportManager {
@@ -81,6 +116,10 @@ export class HttpTransportManager {
 
       // ── Only /mcp from here ──
       if (pathname !== '/mcp') {
+        if (cfg.staticDir) {
+          await serveStatic(pathname, res, cfg.staticDir);
+          return;
+        }
         res.writeHead(404, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Not Found' }));
         return;

package/tests/unit/helpers/pagination.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest';
+import { buildPaginationMeta } from '../../../index.js';
+
+describe('buildPaginationMeta', () => {
+  it('computes total_pages, has_more, next_page for mid-range', () => {
+    const meta = buildPaginationMeta(47, 1, 10);
+    expect(meta.total).toBe(47);
+    expect(meta.total_pages).toBe(5);
+    expect(meta.has_more).toBe(true);
+    expect(meta.next_page).toBe(2);
+    expect(meta.page).toBe(1);
+    expect(meta.per_page).toBe(10);
+  });
+
+  it('returns has_more=false when total fits in one page', () => {
+    const meta = buildPaginationMeta(10, 1, 10);
+    expect(meta.has_more).toBe(false);
+    expect(meta.next_page).toBe(null);
+    expect(meta.total_pages).toBe(1);
+  });
+
+  it('handles zero total', () => {
+    const meta = buildPaginationMeta(0, 1, 10);
+    expect(meta.total).toBe(0);
+    expect(meta.total_pages).toBe(0);
+    expect(meta.has_more).toBe(false);
+    expect(meta.next_page).toBe(null);
+  });
+
+  it('returns has_more=false on the last page', () => {
+    const meta = buildPaginationMeta(25, 3, 10);
+    expect(meta.has_more).toBe(false);
+    expect(meta.next_page).toBe(null);
+    expect(meta.total_pages).toBe(3);
+  });
+
+  it('returns next_page=null on the last page', () => {
+    const meta = buildPaginationMeta(50, 5, 10);
+    expect(meta.has_more).toBe(false);
+    expect(meta.next_page).toBe(null);
+    expect(meta.page).toBe(5);
+  });
+});