Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 | 4x 22x 22x 286x 286x 22x 22x 286x 286x 286x 22x 22x 1x 3x 14x 4x 24x 24x 2x 2x 2x 2x 2x 22x 22x 22x 22x 22x 4x | /**
* MCP Tool: get_server_health
*
* Returns server health status and per-feed availability diagnostics.
* Does NOT make upstream API calls — reports cached status from recent
* feed tool invocations.
*
* **Intelligence Perspective:** Operational awareness of data source
* availability is critical for reliable intelligence products.
*
* **Business Perspective:** Provides dashboard-ready health metrics
* and enables clients to adapt data collection strategies based on
* current feed availability.
*
* ISMS Policy: MO-001 (Monitoring and Alerting), PE-001 (Performance Standards)
*
* @module tools/getServerHealth
*/
import { z } from 'zod';
import { SERVER_VERSION } from '../config.js';
import { feedHealthTracker } from '../services/FeedHealthTracker.js';
import type { AvailabilityLevel, FeedStatus } from '../services/FeedHealthTracker.js';
import { buildToolResponse } from './shared/responseBuilder.js';
import { ToolError } from './shared/errors.js';
import type { ToolResult } from './shared/types.js';
/** Zod schema for the (empty) input of this tool. */
export const GetServerHealthSchema = z.object({});
/**
* Per-feed projection used in the `get_server_health` response.
*
* Preserves the existing `lastSuccess` / `lastError` / `lastAttempt`
* fields (backward compatible) and adds a `lastProbedAt` alias for
* `lastAttempt` so consumers can judge cache staleness
* (see issue #1, recommendation 3).
*/
export interface FeedProjection {
status: FeedStatus['status'];
lastAttempt?: string;
lastProbedAt?: string;
lastSuccess?: string;
lastError?: string;
}
/** Build the per-feed projection map from the tracker's raw statuses. */
function projectFeeds(feeds: Record<string, FeedStatus>): Record<string, FeedProjection> {
const projection: Record<string, FeedProjection> = {};
for (const [name, feed] of Object.entries(feeds)) {
const entry: FeedProjection = { status: feed.status };
if (feed.lastAttempt !== undefined) {
entry.lastAttempt = feed.lastAttempt;
entry.lastProbedAt = feed.lastAttempt;
}
if (feed.lastSuccess !== undefined) entry.lastSuccess = feed.lastSuccess;
if (feed.lastError !== undefined) entry.lastError = feed.lastError;
projection[name] = entry;
}
return projection;
}
/**
* Derive the overall server status from the feed availability level.
*
* The `Unknown` level maps to `'unknown'` — distinct from `'unhealthy'` —
* so consumers do not treat an empty health cache as a feeds outage.
* Cyclomatic complexity: 4
*/
function deriveServerStatus(
level: AvailabilityLevel,
): 'healthy' | 'degraded' | 'unhealthy' | 'unknown' {
switch (level) {
case 'Full':
return 'healthy';
case 'Unavailable':
return 'unhealthy';
case 'Unknown':
return 'unknown';
case 'Degraded':
case 'Sparse':
return 'degraded';
default: {
const exhaustiveCheck: never = level;
throw new Error(`Unhandled availability level: ${String(exhaustiveCheck)}`);
}
}
}
/**
* Handles the get_server_health MCP tool request.
*
* Returns a structured health snapshot including:
* - Server version, uptime, and overall status
* - Per-feed health status (ok / error / unknown)
* - Aggregate availability level (Full / Degraded / Sparse / Unavailable)
*
* @param args - Validated against empty-object schema (no parameters accepted)
* @returns MCP tool result with JSON health payload
*/
export async function handleGetServerHealth(args: unknown): Promise<ToolResult> {
try {
GetServerHealthSchema.parse(args ?? {});
} catch (error: unknown) {
Eif (error instanceof z.ZodError) {
const fieldErrors = error.issues
.map((e) => {
const path = e.path.join('.');
return path ? `${path}: ${e.message}` : e.message;
})
.join('; ');
throw new ToolError({
toolName: 'get_server_health',
operation: 'validateInput',
message: `Invalid parameters: ${fieldErrors}`,
isRetryable: false,
cause: error,
});
}
throw error;
}
const feeds = feedHealthTracker.getAllStatuses();
const availability = feedHealthTracker.getAvailability();
const feedsProjection = projectFeeds(feeds);
const result = {
server: {
version: SERVER_VERSION,
uptime_seconds: feedHealthTracker.getUptimeSeconds(),
status: deriveServerStatus(availability.level),
},
feeds: feedsProjection,
availability: {
operational_feeds: availability.operationalFeeds,
error_feeds: availability.errorFeeds,
unknown_feeds: availability.unknownFeeds,
total_feeds: availability.totalFeeds,
level: availability.level,
},
};
return await Promise.resolve(buildToolResponse(result));
}
/** Tool metadata for MCP registration. */
export const getServerHealthToolMetadata = {
name: 'get_server_health',
description:
'Check server health and feed availability status. Returns server version, uptime, ' +
'per-feed health status (ok/error/unknown) and overall availability level ' +
'(Full/Degraded/Sparse/Unavailable/Unknown). Per-feed `lastProbedAt` and ' +
'`lastAttempt` staleness timestamps are included only once a feed has been probed ' +
'(absent for never-probed feeds). `Unknown` is reported when no feeds have been ' +
'probed yet (cache empty) and must NOT be interpreted as an outage — consumers ' +
'should attempt at least one feed probe before treating the server as down. Does ' +
'not make upstream API calls — reports cached status from recent tool invocations. ' +
'Use this to check which feeds are healthy before making data requests and to ' +
'adapt data collection strategy.',
inputSchema: {
type: 'object' as const,
properties: {},
},
};
|