swagger-parser-mcp-server 2.0.4 → 2.3.0

package/dist/web/dashboard.js

@@ -0,0 +1,540 @@
+const API_BASE = '/api/snapshots';
+const HISTORY_LIMIT = 50;
+
+const elements = {
+  alert: document.getElementById('status-alert'),
+  sourceCaption: document.getElementById('source-caption'),
+  refreshButton: document.getElementById('refresh-snapshots-button'),
+  captureButton: document.getElementById('capture-button'),
+  compareForm: document.getElementById('compare-form'),
+  baselineSelect: document.getElementById('baseline-select'),
+  targetSelect: document.getElementById('target-select'),
+  snapshotList: document.getElementById('snapshot-list'),
+  metricTotal: document.getElementById('metric-total'),
+  metricBreaking: document.getElementById('metric-breaking'),
+  metricNonBreaking: document.getElementById('metric-non-breaking'),
+  metricInfo: document.getElementById('metric-info'),
+  diffSummaryLine: document.getElementById('diff-summary-line'),
+  changeTableBody: document.getElementById('change-table-body'),
+  historyCaption: document.getElementById('history-caption'),
+  historyFilterForm: document.getElementById('history-filter-form'),
+  historyPathInput: document.getElementById('history-path-input'),
+  historyMethodSelect: document.getElementById('history-method-select'),
+  historyClearButton: document.getElementById('history-clear-button'),
+  historyList: document.getElementById('history-list'),
+  detailHeading: document.getElementById('detail-heading'),
+  detailEvents: document.getElementById('detail-events'),
+  detailBefore: document.getElementById('detail-before'),
+  detailAfter: document.getElementById('detail-after'),
+};
+
+if (
+  !elements.alert ||
+  !elements.sourceCaption ||
+  !elements.refreshButton ||
+  !elements.captureButton ||
+  !elements.compareForm ||
+  !elements.baselineSelect ||
+  !elements.targetSelect ||
+  !elements.snapshotList ||
+  !elements.metricTotal ||
+  !elements.metricBreaking ||
+  !elements.metricNonBreaking ||
+  !elements.metricInfo ||
+  !elements.diffSummaryLine ||
+  !elements.changeTableBody ||
+  !elements.historyCaption ||
+  !elements.historyFilterForm ||
+  !elements.historyPathInput ||
+  !elements.historyMethodSelect ||
+  !elements.historyClearButton ||
+  !elements.historyList ||
+  !elements.detailHeading ||
+  !elements.detailEvents ||
+  !elements.detailBefore ||
+  !elements.detailAfter
+) {
+  throw new Error('Dashboard markup is missing required elements.');
+}
+
+const state = {
+  projectKey: '',
+  sourceUrl: '',
+  snapshots: [],
+  diffResult: null,
+  historyEvents: [],
+  historyFilter: {
+    path: null,
+    method: null,
+  },
+};
+
+function formatTimestamp(isoDate) {
+  const parsed = new Date(isoDate);
+  return Number.isNaN(parsed.getTime()) ? isoDate : parsed.toLocaleString();
+}
+
+function setAlert(message, kind = 'info') {
+  if (!message) {
+    elements.alert.hidden = true;
+    elements.alert.textContent = '';
+    elements.alert.classList.remove('error');
+    return;
+  }
+
+  elements.alert.hidden = false;
+  elements.alert.textContent = message;
+  elements.alert.classList.toggle('error', kind === 'error');
+}
+
+async function requestJson(path, options) {
+  const response = await fetch(path, options);
+  let payload = null;
+  try {
+    payload = await response.json();
+  } catch {
+    payload = null;
+  }
+
+  if (!response.ok) {
+    const errorMessage =
+      payload && typeof payload.error === 'string' ? payload.error : `Request failed: ${response.status}`;
+    throw new Error(errorMessage);
+  }
+
+  return payload;
+}
+
+function renderSnapshotSelects() {
+  const previousBaseline = elements.baselineSelect.value;
+  const previousTarget = elements.targetSelect.value;
+  const options = state.snapshots
+    .map(snapshot => `<option value="${snapshot.id}">${formatTimestamp(snapshot.capturedAt)} · ${snapshot.id}</option>`)
+    .join('');
+
+  elements.baselineSelect.innerHTML = options;
+  elements.targetSelect.innerHTML = options;
+
+  const hasPreviousBaseline = state.snapshots.some(snapshot => snapshot.id === previousBaseline);
+  const hasPreviousTarget = state.snapshots.some(snapshot => snapshot.id === previousTarget);
+
+  if (hasPreviousBaseline) {
+    elements.baselineSelect.value = previousBaseline;
+  }
+  if (hasPreviousTarget) {
+    elements.targetSelect.value = previousTarget;
+  }
+
+  if (!elements.baselineSelect.value && state.snapshots.length >= 2) {
+    elements.baselineSelect.value = state.snapshots[1].id;
+  }
+
+  if (!elements.targetSelect.value && state.snapshots.length >= 1) {
+    elements.targetSelect.value = state.snapshots[0].id;
+  }
+
+  if (elements.baselineSelect.value === elements.targetSelect.value && state.snapshots.length >= 2) {
+    elements.baselineSelect.value = state.snapshots[1].id;
+    elements.targetSelect.value = state.snapshots[0].id;
+  }
+}
+
+function renderSnapshotList() {
+  if (state.snapshots.length === 0) {
+    elements.snapshotList.innerHTML = '<p class="caption">No snapshots captured yet.</p>';
+    return;
+  }
+
+  const list = document.createElement('div');
+  list.className = 'snapshot-list';
+
+  for (const snapshot of state.snapshots) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'snapshot-item';
+    button.innerHTML = `
+      <time datetime="${snapshot.capturedAt}">${formatTimestamp(snapshot.capturedAt)}</time>
+      <strong>${snapshot.id}</strong>
+    `;
+    button.addEventListener('click', () => {
+      elements.targetSelect.value = snapshot.id;
+      if (elements.baselineSelect.value === snapshot.id && state.snapshots.length > 1) {
+        const fallback = state.snapshots.find(item => item.id !== snapshot.id);
+        if (fallback) {
+          elements.baselineSelect.value = fallback.id;
+        }
+      }
+      setAlert(`Target snapshot selected: ${snapshot.id}`);
+    });
+    list.appendChild(button);
+  }
+
+  elements.snapshotList.innerHTML = '';
+  elements.snapshotList.appendChild(list);
+}
+
+function renderChangeHistory() {
+  elements.historyPathInput.value = state.historyFilter.path ?? '';
+  elements.historyMethodSelect.value = state.historyFilter.method ?? '';
+
+  if (state.historyFilter.path && state.historyFilter.method) {
+    elements.historyCaption.textContent = `Timeline for ${state.historyFilter.method.toUpperCase()} ${state.historyFilter.path}`;
+  } else {
+    elements.historyCaption.textContent = 'Latest endpoint changes.';
+  }
+
+  if (state.historyEvents.length === 0) {
+    elements.historyList.innerHTML = '<p class="caption">No change history events.</p>';
+    return;
+  }
+
+  const list = document.createElement('div');
+  list.className = 'history-list';
+
+  for (const event of state.historyEvents) {
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'history-item';
+    button.innerHTML = `
+      <div class="history-item-top">
+        <strong>${event.method.toUpperCase()} ${event.path}</strong>
+        <span class="${classificationClassName(event.classification)}">${event.classification}</span>
+      </div>
+      <div class="history-item-meta">
+        <span>${event.changeReason}</span>
+        <time datetime="${event.changedAt}">${formatTimestamp(event.changedAt)}</time>
+      </div>
+      <div class="caption">${event.baselineSnapshotId} -> ${event.targetSnapshotId}</div>
+    `;
+    button.addEventListener('click', () => {
+      setLoading(true);
+      void fetchSnapshots()
+        .then(() => {
+          elements.baselineSelect.value = event.baselineSnapshotId;
+          elements.targetSelect.value = event.targetSnapshotId;
+          return compareSnapshots();
+        })
+        .then(() => loadEndpointDetail(event.path, event.method))
+        .then(() => {
+          setAlert(`History event loaded: ${event.method.toUpperCase()} ${event.path}`);
+        })
+        .catch(error => {
+          const message = error instanceof Error ? error.message : String(error);
+          setAlert(message, 'error');
+        })
+        .finally(() => {
+          setLoading(false);
+        });
+    });
+    list.appendChild(button);
+  }
+
+  elements.historyList.innerHTML = '';
+  elements.historyList.appendChild(list);
+}
+
+function classificationClassName(value) {
+  if (value === 'breaking') {
+    return 'classification breaking';
+  }
+  if (value === 'non-breaking') {
+    return 'classification non-breaking';
+  }
+  return 'classification info';
+}
+
+function resetDetail() {
+  elements.detailHeading.textContent = 'Pick one endpoint from the diff table.';
+  elements.detailEvents.innerHTML = '';
+  elements.detailBefore.textContent = 'No selection';
+  elements.detailAfter.textContent = 'No selection';
+}
+
+function renderDiffSummary() {
+  if (!state.diffResult) {
+    elements.metricTotal.textContent = '-';
+    elements.metricBreaking.textContent = '-';
+    elements.metricNonBreaking.textContent = '-';
+    elements.metricInfo.textContent = '-';
+    elements.diffSummaryLine.textContent = 'No diff selected.';
+    elements.changeTableBody.innerHTML = '<tr><td colspan="3" class="caption">No change rows.</td></tr>';
+    resetDetail();
+    return;
+  }
+
+  const { summary, counts, changes, warnings } = state.diffResult;
+  elements.metricTotal.textContent = String(counts.total);
+  elements.metricBreaking.textContent = String(counts.breaking);
+  elements.metricNonBreaking.textContent = String(counts.nonBreaking);
+  elements.metricInfo.textContent = String(counts.info);
+  elements.diffSummaryLine.textContent = `Compared ${summary.baselineSnapshotId} -> ${summary.targetSnapshotId} at ${formatTimestamp(
+    summary.comparedAt
+  )}`;
+
+  if (warnings.length > 0) {
+    setAlert(warnings.map(warning => warning.message).join(' | '));
+  }
+
+  if (changes.length === 0) {
+    elements.changeTableBody.innerHTML = '<tr><td colspan="3" class="caption">No endpoint changes.</td></tr>';
+    return;
+  }
+
+  elements.changeTableBody.innerHTML = '';
+  for (const change of changes) {
+    const row = document.createElement('tr');
+    const endpointCell = document.createElement('td');
+    const endpointButton = document.createElement('button');
+    endpointButton.type = 'button';
+    endpointButton.className = 'button secondary';
+    endpointButton.textContent = `${change.method.toUpperCase()} ${change.url}`;
+    endpointButton.addEventListener('click', () => {
+      void loadEndpointDetail(change.url, change.method);
+    });
+    endpointCell.appendChild(endpointButton);
+
+    const classificationCell = document.createElement('td');
+    classificationCell.className = classificationClassName(change.classification);
+    classificationCell.textContent = change.classification;
+
+    const reasonCell = document.createElement('td');
+    reasonCell.textContent = change.changeReason;
+
+    row.appendChild(endpointCell);
+    row.appendChild(classificationCell);
+    row.appendChild(reasonCell);
+    elements.changeTableBody.appendChild(row);
+  }
+}
+
+function renderEndpointDetail(detail) {
+  elements.detailHeading.textContent = `${detail.method.toUpperCase()} ${detail.path} · ${detail.changeReason ?? 'no_change'}`;
+  elements.detailEvents.innerHTML = '';
+
+  if (detail.details.length === 0) {
+    const empty = document.createElement('p');
+    empty.className = 'caption';
+    empty.textContent = 'No detail events.';
+    elements.detailEvents.appendChild(empty);
+  } else {
+    for (const event of detail.details) {
+      const item = document.createElement('div');
+      item.className = 'event-row';
+      item.innerHTML = `
+        <strong class="${classificationClassName(event.classification)}">${event.classification}</strong>
+        <div>${event.message}</div>
+      `;
+      elements.detailEvents.appendChild(item);
+    }
+  }
+
+  elements.detailBefore.textContent = JSON.stringify(detail.before, null, 2) ?? 'null';
+  elements.detailAfter.textContent = JSON.stringify(detail.after, null, 2) ?? 'null';
+}
+
+async function fetchSnapshots() {
+  const result = await requestJson(`${API_BASE}?limit=200`);
+  state.projectKey = result.projectKey;
+  state.sourceUrl = result.sourceUrl;
+  state.snapshots = result.snapshots;
+  elements.sourceCaption.textContent = `${result.projectKey} · ${result.sourceUrl}`;
+  renderSnapshotSelects();
+  renderSnapshotList();
+}
+
+function normalizeHistoryFilter(filter = {}) {
+  const path = typeof filter.path === 'string' && filter.path.trim().length > 0 ? filter.path.trim() : undefined;
+  const method =
+    typeof filter.method === 'string' && filter.method.trim().length > 0
+      ? filter.method.trim().toLowerCase()
+      : undefined;
+
+  if (!path && !method) {
+    return {};
+  }
+
+  return {
+    path,
+    method,
+  };
+}
+
+function readHistoryFilterInputs() {
+  return normalizeHistoryFilter({
+    path: elements.historyPathInput.value,
+    method: elements.historyMethodSelect.value,
+  });
+}
+
+async function loadChangeHistory(filter = {}) {
+  const normalizedFilter = normalizeHistoryFilter(filter);
+  const params = new URLSearchParams({
+    limit: String(HISTORY_LIMIT),
+  });
+
+  if (normalizedFilter.path) {
+    params.set('path', normalizedFilter.path);
+  }
+  if (normalizedFilter.method) {
+    params.set('method', normalizedFilter.method);
+  }
+
+  const result = await requestJson(`${API_BASE}/change-history?${params.toString()}`);
+  state.historyEvents = result.events;
+  state.historyFilter = result.filter;
+  renderChangeHistory();
+}
+
+async function compareSnapshots() {
+  const baselineSnapshotId = elements.baselineSelect.value;
+  const targetSnapshotId = elements.targetSelect.value;
+
+  if (!baselineSnapshotId || !targetSnapshotId) {
+    setAlert('Choose baseline and target snapshot first.', 'error');
+    return;
+  }
+
+  if (baselineSnapshotId === targetSnapshotId) {
+    setAlert('Baseline and target must be different.', 'error');
+    return;
+  }
+
+  const diffResult = await requestJson(
+    `${API_BASE}/diff?baselineSnapshotId=${encodeURIComponent(baselineSnapshotId)}&targetSnapshotId=${encodeURIComponent(
+      targetSnapshotId
+    )}`
+  );
+
+  state.diffResult = diffResult;
+  renderDiffSummary();
+}
+
+async function loadEndpointDetail(endpointPath, endpointMethod) {
+  const baselineSnapshotId = elements.baselineSelect.value;
+  const targetSnapshotId = elements.targetSelect.value;
+  const detail = await requestJson(
+    `${API_BASE}/endpoint-detail?baselineSnapshotId=${encodeURIComponent(
+      baselineSnapshotId
+    )}&targetSnapshotId=${encodeURIComponent(targetSnapshotId)}&path=${encodeURIComponent(
+      endpointPath
+    )}&method=${encodeURIComponent(endpointMethod)}`
+  );
+  await loadChangeHistory({
+    path: endpointPath,
+    method: endpointMethod,
+  });
+  renderEndpointDetail(detail);
+}
+
+async function captureSnapshot() {
+  const capturedDiff = await requestJson(`${API_BASE}/capture`, { method: 'POST' });
+  state.diffResult = capturedDiff;
+  await fetchSnapshots();
+  await loadChangeHistory({
+    path: state.historyFilter.path ?? undefined,
+    method: state.historyFilter.method ?? undefined,
+  });
+  if (capturedDiff.summary?.baselineSnapshotId) {
+    elements.baselineSelect.value = capturedDiff.summary.baselineSnapshotId;
+  }
+  if (capturedDiff.summary?.targetSnapshotId) {
+    elements.targetSelect.value = capturedDiff.summary.targetSnapshotId;
+  }
+  renderDiffSummary();
+}
+
+function setLoading(isLoading) {
+  elements.refreshButton.disabled = isLoading;
+  elements.captureButton.disabled = isLoading;
+}
+
+async function loadInitialData() {
+  setLoading(true);
+  try {
+    await fetchSnapshots();
+    await loadChangeHistory();
+    if (state.snapshots.length >= 2) {
+      await compareSnapshots();
+    } else {
+      renderDiffSummary();
+    }
+    setAlert('Dashboard loaded.');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    setAlert(message, 'error');
+    renderDiffSummary();
+  } finally {
+    setLoading(false);
+  }
+}
+
+elements.refreshButton.addEventListener('click', () => {
+  void loadInitialData();
+});
+
+elements.captureButton.addEventListener('click', () => {
+  setLoading(true);
+  void captureSnapshot()
+    .then(() => {
+      setAlert('Snapshot captured successfully.');
+    })
+    .catch(error => {
+      const message = error instanceof Error ? error.message : String(error);
+      setAlert(message, 'error');
+    })
+    .finally(() => {
+      setLoading(false);
+    });
+});
+
+elements.compareForm.addEventListener('submit', event => {
+  event.preventDefault();
+  setLoading(true);
+  void compareSnapshots()
+    .then(() => {
+      setAlert('Diff updated.');
+      resetDetail();
+    })
+    .catch(error => {
+      const message = error instanceof Error ? error.message : String(error);
+      setAlert(message, 'error');
+    })
+    .finally(() => {
+      setLoading(false);
+    });
+});
+
+elements.historyFilterForm.addEventListener('submit', event => {
+  event.preventDefault();
+  setLoading(true);
+  void loadChangeHistory(readHistoryFilterInputs())
+    .then(() => {
+      setAlert('Change history updated.');
+    })
+    .catch(error => {
+      const message = error instanceof Error ? error.message : String(error);
+      setAlert(message, 'error');
+    })
+    .finally(() => {
+      setLoading(false);
+    });
+});
+
+elements.historyClearButton.addEventListener('click', () => {
+  elements.historyPathInput.value = '';
+  elements.historyMethodSelect.value = '';
+  setLoading(true);
+  void loadChangeHistory()
+    .then(() => {
+      setAlert('Change history filter cleared.');
+    })
+    .catch(error => {
+      const message = error instanceof Error ? error.message : String(error);
+      setAlert(message, 'error');
+    })
+    .finally(() => {
+      setLoading(false);
+    });
+});
+
+void loadInitialData();

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "swagger-parser-mcp-server",
-  "version": "2.0.4",
+  "version": "2.3.0",
   "description": "MCP server for parsing Swagger/OpenAPI JSON files",
+  "packageManager": "pnpm@9.0.0",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
@@ -15,6 +16,27 @@
     "README.md",
     "package.json"
   ],
+  "scripts": {
+    "build": "tsc && node scripts/copy-postgres-migrations.mjs && node scripts/copy-web-assets.mjs",
+    "dev": "tsx src/index.ts",
+    "dev:http": "tsx src/http.ts",
+    "migrate": "tsx src/infrastructure/postgres/runMigrations.ts",
+    "start": "node dist/index.js",
+    "start:http": "node dist/http.js",
+    "test": "jest",
+    "test:db:mem": "jest --runInBand --cache=false src/tests/postgresMigrationSmoke.test.ts src/tests/snapshotCapturePipeline.test.ts",
+    "test:db:real": "node -e \"if(!process.env.TEST_DATABASE_URL){console.error('TEST_DATABASE_URL is required for test:db:real');process.exit(1)}\" && jest --runInBand --cache=false src/tests/snapshotPersistence.real.test.ts",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "check-all": "pnpm run typecheck && pnpm run lint && pnpm run format:check",
+    "prepublishOnly": "pnpm run check-all && pnpm run build",
+    "preinstall": "npx only-allow pnpm"
+  },
   "keywords": [
     "mcp",
     "swagger",
@@ -34,6 +56,7 @@
     "@modelcontextprotocol/sdk": "^1.17.4",
     "axios": "^1.6.0",
     "openapi-types": "^12.1.3",
+    "pg": "^8.20.0",
     "swagger-schema-official": "2.0.0-bab6bed",
     "zod": "^3.22.0",
     "zod-to-json-schema": "^3.24.6"
@@ -45,32 +68,19 @@
     "@semantic-release/gitlab": "^13.2.8",
     "@types/jest": "^29.5.0",
     "@types/node": "^20.0.0",
+    "@types/pg": "^8.18.0",
     "@types/swagger-schema-official": "^2.0.25",
     "eslint": "^9.32.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.3",
     "globals": "^16.3.0",
     "jest": "^29.7.0",
+    "pg-mem": "^3.0.14",
     "prettier": "^3.6.2",
     "semantic-release": "^24.2.7",
     "ts-jest": "^29.1.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",
     "typescript-eslint": "^8.38.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts",
-    "start": "node dist/index.js",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "typecheck": "tsc --noEmit",
-    "check-all": "pnpm run typecheck && pnpm run lint && pnpm run format:check",
-    "preinstall": "npx only-allow pnpm"
   }
-}
+}