@cyanheads/openstates-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/get-event.tool.js

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview Fetch full event detail by OCD event ID (experimental).
+ * @module mcp-server/tools/definitions/get-event
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { getOpenStatesApiService } from '../../../services/openstates/openstates-service.js';
+const EventIncludeEnum = z.enum([
+    'links',
+    'sources',
+    'media',
+    'documents',
+    'participants',
+    'agenda',
+]);
+export const getEvent = tool('openstates_get_event', {
+    title: 'Get Event',
+    description: 'Fetch full event detail by OCD event ID. Returns agenda, participants, media links, and associated documents when requested via include. Experimental — event coverage is limited in Open States. Obtain the event_id from openstates_search_events.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        event_id: z.string().min(1).describe('OCD event ID (from openstates_search_events results).'),
+        include: z
+            .array(EventIncludeEnum)
+            .optional()
+            .describe('Related data to inline. "agenda" and "participants" are most useful.'),
+    }),
+    output: z.object({
+        id: z.string().describe('OCD event ID.'),
+        name: z.string().describe('Event name.'),
+        description: z.string().describe('Event description.'),
+        classification: z.string().describe('Event classification.'),
+        start_date: z.string().describe('Event start datetime.'),
+        end_date: z.string().optional().describe('Event end datetime. Absent when not recorded.'),
+        status: z.string().describe('Event status.'),
+        jurisdiction: z
+            .object({
+            id: z.string().describe('OCD jurisdiction ID.'),
+            name: z.string().describe('Jurisdiction name.'),
+        })
+            .describe('Hosting jurisdiction.'),
+        location: z
+            .object({
+            name: z.string().describe('Location name.'),
+            url: z.string().optional().describe('Location URL when available.'),
+        })
+            .optional()
+            .describe('Event location when available.'),
+        links: z
+            .array(z
+            .object({
+            url: z.string().describe('Link URL.'),
+            note: z.string().describe('Link description.'),
+        })
+            .describe('External link record.'))
+            .optional()
+            .describe('Event links when include=links is requested.'),
+        media: z
+            .array(z
+            .object({
+            url: z.string().describe('Media URL.'),
+            note: z.string().describe('Media description.'),
+        })
+            .describe('Media link record.'))
+            .optional()
+            .describe('Media links when include=media is requested.'),
+        documents: z
+            .array(z
+            .object({
+            url: z.string().describe('Document URL.'),
+            note: z.string().describe('Document description.'),
+        })
+            .describe('Document link record.'))
+            .optional()
+            .describe('Document links when include=documents is requested.'),
+        participants: z
+            .array(z
+            .object({
+            name: z.string().describe('Participant name.'),
+            entity_type: z.string().describe('Entity type.'),
+            role: z.string().describe('Participant role.'),
+        })
+            .describe('Participant record.'))
+            .optional()
+            .describe('Participants when include=participants is requested.'),
+        agenda: z
+            .array(z
+            .object({
+            description: z.string().describe('Agenda item description.'),
+            classification: z.array(z.string()).describe('Agenda item classifications.'),
+            subjects: z.array(z.string()).describe('Subject tags.'),
+            related_entities: z
+                .array(z
+                .object({
+                name: z.string().describe('Related entity name.'),
+                entity_type: z
+                    .string()
+                    .describe('Entity type (e.g., "bill", "person", "organization").'),
+            })
+                .describe('Related entity record.'))
+                .describe('Bills, people, or organizations referenced.'),
+        })
+            .describe('Agenda item record.'))
+            .optional()
+            .describe('Agenda items when include=agenda is requested.'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Event ID does not exist in Open States.',
+            recovery: 'Use openstates_search_events with a jurisdiction and date range to discover valid event IDs. Note that event data is experimental and coverage varies widely by state.',
+        },
+    ],
+    async handler(input, ctx) {
+        const svc = getOpenStatesApiService();
+        const event = await svc
+            .getEvent(input.event_id, input.include && input.include.length > 0 ? input.include : undefined, ctx)
+            .catch((err) => {
+            if (err instanceof McpError && err.code === JsonRpcErrorCode.NotFound) {
+                throw ctx.fail('not_found', `Event not found: ${input.event_id}`, {
+                    ...ctx.recoveryFor('not_found'),
+                });
+            }
+            throw err;
+        });
+        ctx.log.info('Fetched event', { id: event.id, name: event.name });
+        return {
+            id: event.id,
+            name: event.name,
+            description: event.description,
+            classification: event.classification,
+            start_date: event.start_date,
+            end_date: event.end_date,
+            status: event.status,
+            jurisdiction: event.jurisdiction,
+            ...(event.location
+                ? {
+                    location: {
+                        name: event.location.name,
+                        ...(event.location.url ? { url: event.location.url } : {}),
+                    },
+                }
+                : {}),
+            ...(event.links ? { links: event.links } : {}),
+            ...(event.media ? { media: event.media } : {}),
+            ...(event.documents ? { documents: event.documents } : {}),
+            ...(event.participants
+                ? {
+                    participants: event.participants.map((p) => ({
+                        name: p.name,
+                        entity_type: p.entity_type,
+                        role: p.role,
+                    })),
+                }
+                : {}),
+            ...(event.agenda
+                ? {
+                    agenda: event.agenda.map((item) => ({
+                        description: item.description,
+                        classification: item.classification,
+                        subjects: item.subjects,
+                        related_entities: item.related_entities.map((e) => ({
+                            name: e.name,
+                            entity_type: e.entity_type,
+                        })),
+                    })),
+                }
+                : {}),
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `# ${result.name}`,
+            `**ID:** ${result.id}`,
+            `**Classification:** ${result.classification} | **Status:** ${result.status}`,
+            result.end_date
+                ? `**Start:** ${result.start_date} | **End:** ${result.end_date}`
+                : `**Start:** ${result.start_date}`,
+            `**Jurisdiction:** ${result.jurisdiction.name} (${result.jurisdiction.id})`,
+        ];
+        if (result.description)
+            lines.push(result.description);
+        if (result.location) {
+            const locStr = result.location.url
+                ? `${result.location.name} — ${result.location.url}`
+                : result.location.name;
+            lines.push(`**Location:** ${locStr}`);
+        }
+        if (result.participants?.length) {
+            lines.push('');
+            lines.push('## Participants');
+            for (const p of result.participants) {
+                lines.push(`- ${p.name} (${p.role}) — ${p.entity_type}`);
+            }
+        }
+        if (result.agenda?.length) {
+            lines.push('');
+            lines.push('## Agenda');
+            for (const item of result.agenda) {
+                lines.push(`- ${item.description}`);
+                if (item.classification.length > 0)
+                    lines.push(`  Classification: ${item.classification.join(', ')}`);
+                if (item.subjects.length > 0)
+                    lines.push(`  Subjects: ${item.subjects.join(', ')}`);
+                if (item.related_entities.length > 0) {
+                    lines.push(`  Related: ${item.related_entities.map((e) => `${e.name} (${e.entity_type})`).join(', ')}`);
+                }
+            }
+        }
+        if (result.links?.length) {
+            lines.push('');
+            lines.push('## Links');
+            for (const l of result.links)
+                lines.push(`- ${l.note}: ${l.url}`);
+        }
+        if (result.media?.length) {
+            lines.push('');
+            lines.push('## Media');
+            for (const m of result.media)
+                lines.push(`- ${m.note}: ${m.url}`);
+        }
+        if (result.documents?.length) {
+            lines.push('');
+            lines.push('## Documents');
+            for (const d of result.documents)
+                lines.push(`- ${d.note}: ${d.url}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-event.tool.js.map

package/dist/mcp-server/tools/definitions/get-event.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-event.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-event.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/get-jurisdiction.tool.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Fetch full metadata for a specific Open States jurisdiction.
+ * @module mcp-server/tools/definitions/get-jurisdiction
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const getJurisdiction: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    jurisdiction_id: z.ZodString;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        legislative_sessions: "legislative_sessions";
+        organizations: "organizations";
+        latest_runs: "latest_runs";
+    }>>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    classification: z.ZodString;
+    url: z.ZodString;
+    latest_bill_update: z.ZodString;
+    latest_people_update: z.ZodString;
+    legislative_sessions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        identifier: z.ZodString;
+        name: z.ZodString;
+        classification: z.ZodString;
+        start_date: z.ZodString;
+        end_date: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Jurisdiction ID does not exist in Open States.";
+    readonly recovery: "Use openstates_list_jurisdictions to discover valid jurisdiction IDs. States use the pattern: ocd-jurisdiction/country:us/state:{2-letter-abbr}/government.";
+}]>;
+//# sourceMappingURL=get-jurisdiction.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-jurisdiction.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-jurisdiction.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-jurisdiction.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAK3E,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;GAyG1B,CAAC"}

package/dist/mcp-server/tools/definitions/get-jurisdiction.tool.js

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview Fetch full metadata for a specific Open States jurisdiction.
+ * @module mcp-server/tools/definitions/get-jurisdiction
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { getOpenStatesApiService } from '../../../services/openstates/openstates-service.js';
+const JurisdictionIncludeEnum = z.enum(['organizations', 'legislative_sessions', 'latest_runs']);
+export const getJurisdiction = tool('openstates_get_jurisdiction', {
+    title: 'Get Jurisdiction',
+    description: 'Fetch full metadata for a specific jurisdiction including all legislative sessions, their identifiers, and coverage dates. Use when you need to know the exact session identifier for a state before filtering bill searches — session formats vary widely (e.g., "2025", "2025rs", "2025s1"). Jurisdiction IDs follow OCD format: ocd-jurisdiction/country:us/state:{abbr}/government (e.g., ocd-jurisdiction/country:us/state:wa/government). State names (e.g., "Washington") and two-letter abbreviations (e.g., "wa") are also accepted.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        jurisdiction_id: z
+            .string()
+            .min(1)
+            .describe('OCD jurisdiction ID, state name (e.g., "Washington"), or two-letter abbreviation (e.g., "wa").'),
+        include: z
+            .array(JurisdictionIncludeEnum)
+            .optional()
+            .describe('Related data to inline. "legislative_sessions" returns all historical and current sessions with identifiers and date ranges. "latest_runs" shows last scraper run metadata.'),
+    }),
+    output: z.object({
+        id: z.string().describe('OCD jurisdiction ID.'),
+        name: z.string().describe('Jurisdiction name.'),
+        classification: z.string().describe('Jurisdiction type.'),
+        url: z.string().describe('Official legislature URL.'),
+        latest_bill_update: z.string().describe('ISO 8601 timestamp of most recent bill data update.'),
+        latest_people_update: z
+            .string()
+            .describe('ISO 8601 timestamp of most recent people data update.'),
+        legislative_sessions: z
+            .array(z
+            .object({
+            identifier: z
+                .string()
+                .describe('Session identifier — use as session= in bill searches.'),
+            name: z.string().describe('Human-readable session name.'),
+            classification: z
+                .string()
+                .describe('Session classification: "primary", "special", etc.'),
+            start_date: z.string().describe('Session start date.'),
+            end_date: z.string().describe('Session end date.'),
+        })
+            .describe('Legislative session record.'))
+            .optional()
+            .describe('All legislative sessions when include=legislative_sessions is requested.'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Jurisdiction ID does not exist in Open States.',
+            recovery: 'Use openstates_list_jurisdictions to discover valid jurisdiction IDs. States use the pattern: ocd-jurisdiction/country:us/state:{2-letter-abbr}/government.',
+        },
+    ],
+    async handler(input, ctx) {
+        const svc = getOpenStatesApiService();
+        const result = await svc
+            .getJurisdiction(input.jurisdiction_id, input.include && input.include.length > 0 ? input.include : undefined, ctx)
+            .catch((err) => {
+            if (err instanceof McpError && err.code === JsonRpcErrorCode.NotFound) {
+                throw ctx.fail('not_found', `Jurisdiction not found: ${input.jurisdiction_id}`, {
+                    ...ctx.recoveryFor('not_found'),
+                });
+            }
+            throw err;
+        });
+        ctx.log.info('Fetched jurisdiction', { id: result.id, name: result.name });
+        return {
+            id: result.id,
+            name: result.name,
+            classification: result.classification,
+            url: result.url,
+            latest_bill_update: result.latest_bill_update,
+            latest_people_update: result.latest_people_update,
+            ...(result.legislative_sessions ? { legislative_sessions: result.legislative_sessions } : {}),
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `# ${result.name}`,
+            `**ID:** ${result.id}`,
+            `**Classification:** ${result.classification}`,
+            `**URL:** ${result.url}`,
+            `**Latest bill update:** ${result.latest_bill_update}`,
+            `**Latest people update:** ${result.latest_people_update}`,
+        ];
+        if (result.legislative_sessions?.length) {
+            lines.push('');
+            lines.push('## Legislative Sessions');
+            for (const s of result.legislative_sessions) {
+                lines.push(`- \`${s.identifier}\` — ${s.name} (${s.classification}) ${s.start_date}–${s.end_date}`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-jurisdiction.tool.js.map

package/dist/mcp-server/tools/definitions/get-jurisdiction.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-jurisdiction.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-jurisdiction.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/get-legislators-by-location.tool.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Find legislators representing a geographic coordinate.
+ * @module mcp-server/tools/definitions/get-legislators-by-location
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const getLegislatorsByLocation: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    latitude: z.ZodNumber;
+    longitude: z.ZodNumber;
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        other_identifiers: "other_identifiers";
+        sources: "sources";
+        links: "links";
+        other_names: "other_names";
+        offices: "offices";
+    }>>>;
+}, z.core.$strip>, z.ZodObject<{
+    legislators: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        party: z.ZodString;
+        current_role: z.ZodNullable<z.ZodObject<{
+            title: z.ZodString;
+            org_classification: z.ZodString;
+            district: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        jurisdiction: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
+        email: z.ZodString;
+        openstates_url: z.ZodString;
+        offices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            classification: z.ZodString;
+            voice: z.ZodOptional<z.ZodString>;
+            fax: z.ZodOptional<z.ZodString>;
+            address: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        links: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            note: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    count: z.ZodNumber;
+    coverage_note: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "invalid_coordinate";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "Latitude or longitude is outside valid range.";
+    readonly recovery: "Latitude must be between -90 and 90, longitude between -180 and 180. For continental US: lat 24-50, lng -125 to -66. For Alaska: lat 51-72, lng -180 to -130.";
+}]>;
+//# sourceMappingURL=get-legislators-by-location.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-legislators-by-location.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-legislators-by-location.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-legislators-by-location.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAWjE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoKnC,CAAC"}

package/dist/mcp-server/tools/definitions/get-legislators-by-location.tool.js

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Find legislators representing a geographic coordinate.
+ * @module mcp-server/tools/definitions/get-legislators-by-location
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getOpenStatesApiService } from '../../../services/openstates/openstates-service.js';
+const PersonIncludeEnum = z.enum([
+    'other_names',
+    'other_identifiers',
+    'links',
+    'sources',
+    'offices',
+]);
+export const getLegislatorsByLocation = tool('openstates_get_legislators_by_location', {
+    title: 'Get Legislators by Location',
+    description: 'Find all state legislators representing a geographic coordinate. Pass latitude and longitude to get state senators and representatives (and potentially governor/executive officials) for that location. Useful for constituent-to-representative matching, address-based policy research, and electoral boundary analysis. This server does not geocode addresses — the caller must provide decimal-degree coordinates. Use include=offices to get contact information alongside the legislator list.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        latitude: z.number().describe('Latitude in decimal degrees (e.g., 47.6062 for Seattle, WA).'),
+        longitude: z
+            .number()
+            .describe('Longitude in decimal degrees (e.g., -122.3321 for Seattle, WA).'),
+        include: z
+            .array(PersonIncludeEnum)
+            .optional()
+            .describe('Related data to inline. "offices" includes phone, fax, and address.'),
+    }),
+    output: z.object({
+        legislators: z
+            .array(z
+            .object({
+            id: z.string().describe('OCD person ID.'),
+            name: z.string().describe('Full name.'),
+            party: z.string().describe('Primary party label. Empty string when unknown.'),
+            current_role: z
+                .object({
+                title: z.string().describe('Role title.'),
+                org_classification: z.string().describe('Chamber classification.'),
+                district: z.string().nullable().describe('District label or null.'),
+            })
+                .nullable()
+                .describe('Current role or null.'),
+            jurisdiction: z
+                .object({
+                id: z.string().describe('OCD jurisdiction ID.'),
+                name: z.string().describe('Jurisdiction name.'),
+            })
+                .describe('Home jurisdiction.'),
+            email: z.string().describe('Email address. Empty string when not available.'),
+            openstates_url: z.string().describe('Open States profile URL.'),
+            offices: z
+                .array(z
+                .object({
+                name: z.string().describe('Office name.'),
+                classification: z.string().describe('Office type.'),
+                voice: z.string().optional().describe('Phone number when available.'),
+                fax: z.string().optional().describe('Fax number when available.'),
+                address: z.string().optional().describe('Mailing address when available.'),
+            })
+                .describe('Contact office record.'))
+                .optional()
+                .describe('Contact offices when include=offices is requested.'),
+            links: z
+                .array(z
+                .object({
+                url: z.string().describe('Link URL.'),
+                note: z.string().describe('Link description.'),
+            })
+                .describe('External link record.'))
+                .optional()
+                .describe('Website and social links when include=links is requested.'),
+        })
+            .describe('Legislator record.'))
+            .describe('Legislators representing the given coordinate.'),
+        count: z.number().describe('Number of legislators returned.'),
+        coverage_note: z
+            .string()
+            .optional()
+            .describe('Present when no legislators were found — explains why (e.g., location outside US boundaries or unsupported territory).'),
+    }),
+    errors: [
+        {
+            reason: 'invalid_coordinate',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'Latitude or longitude is outside valid range.',
+            recovery: 'Latitude must be between -90 and 90, longitude between -180 and 180. For continental US: lat 24-50, lng -125 to -66. For Alaska: lat 51-72, lng -180 to -130.',
+        },
+    ],
+    async handler(input, ctx) {
+        if (input.latitude < -90 ||
+            input.latitude > 90 ||
+            input.longitude < -180 ||
+            input.longitude > 180) {
+            throw ctx.fail('invalid_coordinate', `Invalid coordinates: latitude=${input.latitude}, longitude=${input.longitude}`, {
+                ...ctx.recoveryFor('invalid_coordinate'),
+            });
+        }
+        const svc = getOpenStatesApiService();
+        const result = await svc.getPeopleByGeo(input.latitude, input.longitude, input.include && input.include.length > 0 ? input.include : undefined, ctx);
+        ctx.log.info('Fetched legislators by geo', {
+            latitude: input.latitude,
+            longitude: input.longitude,
+            count: result.results.length,
+        });
+        if (result.results.length === 0) {
+            return {
+                legislators: [],
+                count: 0,
+                coverage_note: `No legislators found for coordinates (${input.latitude}, ${input.longitude}). Verify the location is within a US state, DC, or Puerto Rico.`,
+            };
+        }
+        return { legislators: result.results, count: result.results.length };
+    },
+    format: (result) => {
+        const lines = [`**${result.count} legislators found**`];
+        if (result.coverage_note) {
+            lines.push('');
+            lines.push(`> ${result.coverage_note}`);
+        }
+        for (const person of result.legislators) {
+            lines.push('');
+            lines.push(`## ${person.name}`);
+            lines.push(`**ID:** ${person.id}`);
+            lines.push(`**Party:** ${person.party || 'Not available'}`);
+            lines.push(`**Jurisdiction:** ${person.jurisdiction.name} (${person.jurisdiction.id})`);
+            if (person.current_role) {
+                const district = person.current_role.district
+                    ? ` — District ${person.current_role.district}`
+                    : '';
+                lines.push(`**Role:** ${person.current_role.title} (${person.current_role.org_classification})${district}`);
+            }
+            if (person.email)
+                lines.push(`**Email:** ${person.email}`);
+            if (person.openstates_url)
+                lines.push(`**URL:** ${person.openstates_url}`);
+            if (person.offices?.length) {
+                for (const office of person.offices) {
+                    const parts = [`${office.name} [${office.classification}]`];
+                    if (office.voice)
+                        parts.push(`Phone: ${office.voice}`);
+                    if (office.fax)
+                        parts.push(`Fax: ${office.fax}`);
+                    if (office.address)
+                        parts.push(`Address: ${office.address}`);
+                    lines.push(`**Office:** ${parts.join(' | ')}`);
+                }
+            }
+            if (person.links?.length) {
+                lines.push(`**Links:** ${person.links.map((l) => `${l.note}: ${l.url}`).join(', ')}`);
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=get-legislators-by-location.tool.js.map

package/dist/mcp-server/tools/definitions/get-legislators-by-location.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-legislators-by-location.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-legislators-by-location.tool.ts"],"names":[],"mappings":"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"}