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 | 16x 16x 4x 4x 4x 12x 12x 3x 1x 9x 9x 7x 4x 2x 2x 4x | /**
* MCP Tool: get_procedures
*
* Retrieve European Parliament legislative procedures.
* Supports single procedure lookup by processId or paginated list.
* Note: The EP API /procedures endpoint does not support year filtering.
*
* **Intelligence Perspective:** Procedure data enables end-to-end legislative tracking,
* outcome prediction, and timeline analysis—core for policy monitoring intelligence.
*
* **Business Perspective:** Procedure tracking powers legislative intelligence products,
* regulatory risk assessments, and compliance early-warning systems.
*
* **EP API Endpoints:**
* - `GET /procedures` (list)
* - `GET /procedures/{process-id}` (single)
*
* ISMS Policy: SC-002 (Input Validation), AC-003 (Least Privilege)
*/
import { GetProceduresSchema } from '../schemas/europeanParliament.js';
import { epClient } from '../clients/europeanParliamentClient.js';
import { APIError } from '../clients/ep/baseClient.js';
import { buildToolResponse } from './shared/responseBuilder.js';
import { ToolError } from './shared/errors.js';
import { z } from 'zod';
import type { ToolResult } from './shared/types.js';
/**
* Handles the get_procedures MCP tool request.
*
* Retrieves European Parliament legislative procedures enabling end-to-end legislative
* tracking, outcome prediction, and timeline analysis. Supports both a single-procedure
* lookup by `processId` and a paginated list.
*
* Note: The EP API `/procedures` endpoint does **not** support `year` filtering.
* Only `process-type` is available. Callers needing year-specific counts
* must filter client-side.
*
* @param args - Raw tool arguments, validated against {@link GetProceduresSchema}
* @returns MCP tool result containing procedure data (single procedure or paginated list)
* @throws - If `args` fails schema validation (e.g., invalid field types or formats)
* - If the European Parliament API is unreachable or returns an error response
*
* @example
* ```typescript
* // Single procedure lookup
* const single = await handleGetProcedures({ processId: '2023/0132(COD)' });
* // Returns the legislative procedure for the Artificial Intelligence Act
*
* // List procedures (no year filter available in the EP API)
* const list = await handleGetProcedures({ limit: 50, offset: 0 });
* // Returns up to 50 legislative procedures
* ```
*
* @security - Input is validated with Zod before any API call.
* - Personal data in responses is minimised per GDPR Article 5(1)(c).
* - All requests are rate-limited and audit-logged per ISMS Policy AU-002.
* @since 0.8.0
* @see {@link getProceduresToolMetadata} for MCP schema registration
* @see {@link handleGetProcedureEvents} for retrieving events linked to a specific procedure
*/
export async function handleGetProcedures(args: unknown): Promise<ToolResult> {
// Validate input — ZodErrors here are client mistakes (non-retryable)
let params: ReturnType<typeof GetProceduresSchema.parse>;
try {
params = GetProceduresSchema.parse(args);
} catch (error: unknown) {
Eif (error instanceof z.ZodError) {
const fieldErrors = error.issues.map((e) => `${e.path.join('.')}: ${e.message}`).join('; ');
throw new ToolError({
toolName: 'get_procedures',
operation: 'validateInput',
message: `Invalid parameters: ${fieldErrors}`,
isRetryable: false,
cause: error,
});
}
throw error;
}
try {
if (params.processId !== undefined) {
const result = await epClient.getProcedureById(params.processId);
return buildToolResponse(result);
}
const apiParams = {
limit: params.limit,
offset: params.offset,
};
const result = await epClient.getProcedures(
apiParams
);
return buildToolResponse(result);
} catch (error: unknown) {
// Surface upstream 404s as a non-retryable UPSTREAM_404 ToolError only for
// single-procedure lookups, where 404 semantically means the requested
// procedure does not exist. List retrievals fall through to the generic
// retryable failure path because a 404 there likely indicates
// misconfiguration or transient upstream routing issues.
if (
params.processId !== undefined &&
error instanceof APIError &&
error.statusCode === 404
) {
throw new ToolError({
toolName: 'get_procedures',
operation: 'fetchData',
message: `Procedure not found: ${params.processId} (EP API returned 404)`,
isRetryable: false,
errorCode: 'UPSTREAM_404',
httpStatus: 404,
cause: error,
});
}
throw new ToolError({
toolName: 'get_procedures',
operation: 'fetchData',
message: 'Failed to retrieve procedures',
isRetryable: true,
cause: error,
});
}
}
/** Tool metadata for get_procedures */
export const getProceduresToolMetadata = {
name: 'get_procedures',
description:
'Get European Parliament legislative procedures. Supports single procedure lookup by processId or paginated list. Note: The EP API /procedures endpoint does not support year filtering. Data source: European Parliament Open Data Portal.',
inputSchema: {
type: 'object' as const,
properties: {
processId: { type: 'string', description: 'Process ID for single procedure lookup' },
limit: { type: 'number', description: 'Maximum results to return (1-100)', default: 50 },
offset: { type: 'number', description: 'Pagination offset', default: 0 },
},
},
};
|