# All files / src/tools getCommitteeDocuments.ts

93.75% Statements 15/16
75% Branches 3/4
100% Functions 2/2
93.33% Lines 14/15

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

    18x
    18x

    5x
    5x
    5x

    13x
    13x
    3x
    2x

    10x

    10x

    9x

    2x

    4x

     /**
     * MCP Tool: get_committee_documents
     *
     * Retrieve European Parliament committee documents, with optional single document lookup.
     *
     * **Intelligence Perspective:** Committee documents reveal policy positions and
     * legislative drafting before plenary votes, enabling early detection of policy shifts.
     *
     * **Business Perspective:** Provides early access to legislative drafts for
     * regulatory intelligence and compliance preparation.
     *
     * **EP API Endpoints:**
     * - `GET /committee-documents` (list)
     * - `GET /committee-documents/{doc-id}` (single)
     *
     * ISMS Policy: SC-002 (Input Validation), AC-003 (Least Privilege)
     */

    import { GetCommitteeDocumentsSchema } from '../schemas/europeanParliament.js';
    import { epClient } from '../clients/europeanParliamentClient.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_committee_documents MCP tool request.
     *
     * Retrieves European Parliament committee documents, supporting single document
     * lookup by docId or a paginated list.
     *
     * Note: The EP API `/committee-documents` endpoint does **not** support `year` filtering.
     * Only pagination (limit/offset) is available.
     *
     * @param args - Raw tool arguments, validated against {@link GetCommitteeDocumentsSchema}
     * @returns MCP tool result containing either a single committee document or a paginated list of documents
     * @throws - If `args` fails schema validation (e.g., missing required fields or invalid format)
     * - If the European Parliament API is unreachable or returns an error response
     *
     * @example
     * ```typescript
     * // Single document lookup
     * const result = await handleGetCommitteeDocuments({ docId: 'A9-0001/2024' });
     * // Returns the full record for the specified committee document
     *
     * // List documents (no year filter available in the EP API)
     * const list = await handleGetCommitteeDocuments({ limit: 25 });
     * // Returns up to 25 committee documents
     * ```
     *
     * @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 getCommitteeDocumentsToolMetadata} for MCP schema registration
     * @see {@link handleGetCommitteeInfo} for retrieving committee membership and structure
     */
    export async function handleGetCommitteeDocuments(args: unknown): Promise<ToolResult> {
      let params: ReturnType<typeof GetCommitteeDocumentsSchema.parse>;
      try {
        params = GetCommitteeDocumentsSchema.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_committee_documents',
            operation: 'validateInput',
            message: `Invalid parameters: ${fieldErrors}`,
            isRetryable: false,
            cause: error,
          });
        }
        throw error;
      }

      try {
        if (params.docId !== undefined) {
          const result = await epClient.getCommitteeDocumentById(params.docId);
          return buildToolResponse(result);
        }

        const apiParams: Record<string, unknown> = {
          limit: params.limit,
          offset: params.offset,
        };

        const result = await epClient.getCommitteeDocuments(
          apiParams
        );

        return buildToolResponse(result);
      } catch (error: unknown) {
        throw new ToolError({
          toolName: 'get_committee_documents',
          operation: 'fetchData',
          message: 'Failed to retrieve committee documents',
          isRetryable: true,
          cause: error,
        });
      }
    }
    /** Tool metadata for get_committee_documents */
    export const getCommitteeDocumentsToolMetadata = {
      name: 'get_committee_documents',
      description:
        'Get European Parliament committee documents. Supports single document lookup by docId or paginated list. Note: The EP API /committee-documents endpoint does not support year filtering. Data source: European Parliament Open Data Portal.',
      inputSchema: {
        type: 'object' as const,
        properties: {
          docId: { type: 'string', description: 'Document ID for single document lookup' },
          limit: { type: 'number', description: 'Maximum results to return (1-100)', default: 50 },
          offset: { type: 'number', description: 'Pagination offset', default: 0 },
        },
      },
    };