@h-ear/mcp-server 1.0.10 → 1.1.0-dev.202604171007

package/dist/schemas/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Single source of truth for H-ear MCP tool inputSchemas and descriptions.
+ *
+ * Why this file exists: stdio and https transports must advertise identical
+ * tool contracts to clients. Stdio uses the Zod shapes directly in
+ * `server.tool(name, desc, shape, ...)`. The APIM REST-as-MCP passthrough
+ * (api-version 2025-03-01-preview) auto-generates tool schemas from APIM
+ * operations but DROPS query/header parameters, so filters like
+ * `listClasses(category: "Animal")` silently vanish on the https transport
+ * unless we patch explicit inputSchemas into `mcpTools[]`.
+ *
+ * Flow: Zod SHAPE → zod-to-json-schema → toolSchemas / toolDescriptions →
+ *       consumed by stdio tool files AND by scripts/userMcp.root-status.mjs
+ *       when PATCHing APIM.
+ */
+import { z, type ZodRawShape } from 'zod';
+export declare const HEALTH_CHECK_SHAPE: {};
+export declare const USAGE_SHAPE: {};
+export declare const LIST_WEBHOOKS_SHAPE: {};
+export declare const LIST_CLASSES_SHAPE: {
+    taxonomy: z.ZodOptional<z.ZodEnum<["audioset-yamnet-521", "audioset-panns-527", "species"]>>;
+    category: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+};
+export declare const LIST_JOBS_SHAPE: {
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodEnum<["processing", "completed", "failed"]>>;
+    batchId: z.ZodOptional<z.ZodString>;
+    startDate: z.ZodOptional<z.ZodString>;
+    endDate: z.ZodOptional<z.ZodString>;
+};
+export declare const GET_JOB_SHAPE: {
+    jobId: z.ZodString;
+};
+export declare const GET_JOB_EVENTS_SHAPE: {
+    jobId: z.ZodString;
+    taxonomy: z.ZodOptional<z.ZodString>;
+    minConfidence: z.ZodOptional<z.ZodNumber>;
+    category: z.ZodOptional<z.ZodString>;
+    tier2: z.ZodOptional<z.ZodString>;
+    tier3: z.ZodOptional<z.ZodString>;
+    startTime: z.ZodOptional<z.ZodNumber>;
+    endTime: z.ZodOptional<z.ZodNumber>;
+    sourceId: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+};
+export declare const GET_JOB_AUDIO_SHAPE: {
+    jobId: z.ZodString;
+};
+export declare const GET_JOB_WAVEFORM_SHAPE: {
+    jobId: z.ZodString;
+    zoom: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<256>, z.ZodLiteral<1024>, z.ZodLiteral<4096>]>>;
+};
+export declare const GET_UPLOAD_STATUS_SHAPE: {
+    uploadSessionId: z.ZodString;
+};
+export declare const CLASSIFY_AUDIO_SHAPE: {
+    filePath: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    threshold: z.ZodDefault<z.ZodNumber>;
+    filterMinDurationSeconds: z.ZodOptional<z.ZodNumber>;
+    waitForResult: z.ZodDefault<z.ZodAny>;
+    callbackUrl: z.ZodOptional<z.ZodString>;
+    callbackSecret: z.ZodOptional<z.ZodString>;
+    latitude: z.ZodOptional<z.ZodNumber>;
+    longitude: z.ZodOptional<z.ZodNumber>;
+};
+export declare const CLASSIFY_BATCH_SHAPE: {
+    filePaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        id?: string | undefined;
+    }, {
+        url: string;
+        id?: string | undefined;
+    }>, "many">>;
+    callbackUrl: z.ZodOptional<z.ZodString>;
+    callbackSecret: z.ZodOptional<z.ZodString>;
+    threshold: z.ZodDefault<z.ZodNumber>;
+    filterMinDurationSeconds: z.ZodOptional<z.ZodNumber>;
+    latitude: z.ZodOptional<z.ZodNumber>;
+    longitude: z.ZodOptional<z.ZodNumber>;
+};
+export declare const CREATE_WEBHOOK_SHAPE: {
+    url: z.ZodString;
+    events: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    description: z.ZodOptional<z.ZodString>;
+    taxonomyFilter: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    notificationTierDepth: z.ZodOptional<z.ZodNumber>;
+    notificationTierValues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+};
+export declare const UPDATE_WEBHOOK_SHAPE: {
+    webhookId: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+    events: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    status: z.ZodOptional<z.ZodEnum<["active", "paused"]>>;
+    description: z.ZodOptional<z.ZodString>;
+    taxonomyFilter: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    notificationTierDepth: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    notificationTierValues: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+};
+export declare const GET_WEBHOOK_SHAPE: {
+    webhookId: z.ZodString;
+};
+export declare const DELETE_WEBHOOK_SHAPE: {
+    webhookId: z.ZodString;
+};
+export declare const PING_WEBHOOK_SHAPE: {
+    webhookId: z.ZodString;
+};
+export declare const LIST_WEBHOOK_DELIVERIES_SHAPE: {
+    webhookId: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+};
+export declare const GET_JOB_REPORT_SHAPE: {
+    jobId: z.ZodString;
+};
+export declare const toolDescriptions: Record<string, string>;
+export declare const toolShapes: Readonly<Record<string, ZodRawShape>>;
+export declare const toolSchemas: Readonly<Record<string, unknown>>;
+export declare const toolNames: readonly string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAM1C,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,eAAO,MAAM,WAAW,IAAI,CAAC;AAE7B,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,eAAO,MAAM,kBAAkB;;;;;CAS9B,CAAC;AAEF,eAAO,MAAM,eAAe;;;;;;;CAa3B,CAAC;AAEF,eAAO,MAAM,aAAa;;CAGzB,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;CAyBhC,CAAC;AAEF,eAAO,MAAM,mBAAmB;;CAG/B,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;CAKlC,CAAC;AAEF,eAAO,MAAM,uBAAuB;;CAGnC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;CAmBhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;CAoBhC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;CAahC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;;;;;;;;CAiBhC,CAAC;AAEF,eAAO,MAAM,iBAAiB;;CAG7B,CAAC;AAEF,eAAO,MAAM,oBAAoB;;CAGhC,CAAC;AAEF,eAAO,MAAM,kBAAkB;;CAG9B,CAAC;AAEF,eAAO,MAAM,6BAA6B;;;CAKzC,CAAC;AAEF,eAAO,MAAM,oBAAoB;;CAGhC,CAAC;AAOF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA+CnD,CAAC;AA0BF,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAyB,CAAC;AAcvF,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzD,CAAC;AAIF,eAAO,MAAM,SAAS,EAAE,SAAS,MAAM,EAAuC,CAAC"}

package/dist/schemas/index.js

@@ -0,0 +1,269 @@
+/**
+ * Single source of truth for H-ear MCP tool inputSchemas and descriptions.
+ *
+ * Why this file exists: stdio and https transports must advertise identical
+ * tool contracts to clients. Stdio uses the Zod shapes directly in
+ * `server.tool(name, desc, shape, ...)`. The APIM REST-as-MCP passthrough
+ * (api-version 2025-03-01-preview) auto-generates tool schemas from APIM
+ * operations but DROPS query/header parameters, so filters like
+ * `listClasses(category: "Animal")` silently vanish on the https transport
+ * unless we patch explicit inputSchemas into `mcpTools[]`.
+ *
+ * Flow: Zod SHAPE → zod-to-json-schema → toolSchemas / toolDescriptions →
+ *       consumed by stdio tool files AND by scripts/userMcp.root-status.mjs
+ *       when PATCHing APIM.
+ */
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { HEAR_API } from '@h-ear/core';
+// ─── Shapes (authoritative) ──────────────────────────────────────────────────
+export const HEALTH_CHECK_SHAPE = {};
+export const USAGE_SHAPE = {};
+export const LIST_WEBHOOKS_SHAPE = {};
+export const LIST_CLASSES_SHAPE = {
+    taxonomy: z.enum(['audioset-yamnet-521', 'audioset-panns-527', 'species']).optional()
+        .describe('Taxonomy to query. Defaults to audioset-yamnet-521.'),
+    category: z.string().optional()
+        .describe('Filter by category name (case-insensitive partial match). E.g. "Animal", "Human sounds", "Music".'),
+    limit: z.number().int().positive().optional()
+        .describe('Max classes to return (pagination).'),
+    offset: z.number().int().min(0).optional()
+        .describe('Number of classes to skip (pagination).'),
+};
+export const LIST_JOBS_SHAPE = {
+    limit: z.number().int().positive().max(100).default(10)
+        .describe('Max jobs to return (1-100, default 10).'),
+    offset: z.number().int().min(0).default(0)
+        .describe('Number of jobs to skip (pagination).'),
+    status: z.enum(['processing', 'completed', 'failed']).optional()
+        .describe('Filter by job status.'),
+    batchId: z.string().optional()
+        .describe('Filter by batch ID (from classifyBatch).'),
+    startDate: z.string().optional()
+        .describe('ISO8601 date range start — jobs created on or after this date (e.g. "2026-01-01T00:00:00Z").'),
+    endDate: z.string().optional()
+        .describe('ISO8601 date range end — jobs created on or before this date (e.g. "2026-04-04T23:59:59Z").'),
+};
+export const GET_JOB_SHAPE = {
+    jobId: z.string().min(1)
+        .describe('The job ID returned from classifyAudio or classifyBatch.'),
+};
+export const GET_JOB_EVENTS_SHAPE = {
+    jobId: z.string().min(1)
+        .describe('Job ID from classifyAudio, classifyBatch, or listJobs.'),
+    taxonomy: z.string().optional()
+        .describe('Filter by taxonomy: audioset-yamnet-521, audioset-panns-527, or species.'),
+    minConfidence: z.number().min(0).max(1).optional()
+        .describe('Minimum confidence threshold (0.0–1.0). e.g. 0.7 returns only events ≥70% confidence.'),
+    category: z.string().optional()
+        .describe('Filter by tier1 category (e.g. "Animal", "Music", "Vehicle", "Nature").'),
+    tier2: z.string().optional()
+        .describe('Filter by tier2 subcategory (e.g. "Domestic animals, pets", "Wild animals"). Narrows within a tier1 category.'),
+    tier3: z.string().optional()
+        .describe('Filter by tier3 class (e.g. "Dog", "Cat", "Bird"). Finest supported filter depth — tiers 4-5 exist in the taxonomy but are not filterable.'),
+    startTime: z.number().min(0).optional()
+        .describe('Only return events starting at or after this time in seconds.'),
+    endTime: z.number().min(0).optional()
+        .describe('Only return events ending at or before this time in seconds.'),
+    sourceId: z.string().optional()
+        .describe('Filter by noise source cluster ID.'),
+    sort: z.string().optional()
+        .describe('Sort field:direction — e.g. "startTime:asc", "confidence:desc", "decibelLevel:desc".'),
+    limit: z.number().int().positive().max(5000).default(50)
+        .describe('Max events per page (1–5000, default 50). Start small — a 12h recording can have 10,000+ events. Use filters to narrow before increasing.'),
+    offset: z.number().int().min(0).default(0)
+        .describe('Pagination offset.'),
+};
+export const GET_JOB_AUDIO_SHAPE = {
+    jobId: z.string().min(1)
+        .describe('Job ID from classifyAudio, classifyBatch, or listJobs.'),
+};
+export const GET_JOB_WAVEFORM_SHAPE = {
+    jobId: z.string().min(1)
+        .describe('Job ID from classifyAudio, classifyBatch, or listJobs.'),
+    zoom: z.union([z.literal(256), z.literal(1024), z.literal(4096)]).default(1024)
+        .describe('Waveform resolution in samples-per-pixel: 256 (high detail), 1024 (default), 4096 (overview).'),
+};
+export const GET_UPLOAD_STATUS_SHAPE = {
+    uploadSessionId: z.string().min(1)
+        .describe('The uploadSessionId returned by classifyAudio for large files.'),
+};
+export const CLASSIFY_AUDIO_SHAPE = {
+    filePath: z.string().optional()
+        .describe('Path to a local audio file (Desktop/CLI only — requires local filesystem access). The server reads and encodes it automatically. Large files are split into chunks. Use url for web/mobile clients.'),
+    url: z.string().url().optional()
+        .describe('Public URL to audio file.'),
+    threshold: z.number().min(0).max(1).default(0.3)
+        .describe('Confidence threshold (0.0-1.0). Only classes above this score are returned.'),
+    filterMinDurationSeconds: z.number().min(0.1).max(595).optional()
+        .describe('Minimum event duration filter in seconds.'),
+    waitForResult: z.any().default(false)
+        .describe('If true, polls until classification completes (up to 5 min). Default false — returns immediately with job ID for later retrieval via getJob.'),
+    callbackUrl: z.string().url().optional()
+        .describe('Webhook URL (HTTPS) for async result delivery. When provided, the server POSTs classification results to this URL on completion — no polling needed. Use getJob to check status manually.'),
+    callbackSecret: z.string().optional()
+        .describe('HMAC-SHA256 secret for webhook signature verification. Only used with callbackUrl.'),
+    latitude: z.number().min(-90).max(90).optional()
+        .describe('GPS latitude (decimal degrees, -90 to 90). Tag the recording location. Must be paired with longitude.'),
+    longitude: z.number().min(-180).max(180).optional()
+        .describe('GPS longitude (decimal degrees, -180 to 180). Tag the recording location. Must be paired with latitude.'),
+};
+export const CLASSIFY_BATCH_SHAPE = {
+    filePaths: z.array(z.string()).min(1).max(HEAR_API.MAX_BATCH_FILES).optional()
+        .describe('Array of local audio file paths to classify (Desktop/CLI only — requires local filesystem access). Use files with URLs for web/mobile clients.'),
+    files: z.array(z.object({
+        url: z.string().url().describe('Public URL to audio file.'),
+        id: z.string().optional().describe('Client-provided tracking ID.'),
+    })).min(1).max(HEAR_API.MAX_BATCH_FILES).optional()
+        .describe('Array of public audio URLs (alternative to filePaths). Requires callbackUrl.'),
+    callbackUrl: z.string().url().optional()
+        .describe('Webhook URL (HTTPS) for async result delivery. Required for URL-based files. Optional for local files — when provided, skips polling and delivers results via webhook instead.'),
+    callbackSecret: z.string().optional()
+        .describe('HMAC-SHA256 secret for webhook signature verification.'),
+    threshold: z.number().min(0).max(1).default(0.3)
+        .describe('Confidence threshold for all files.'),
+    filterMinDurationSeconds: z.number().min(0.1).max(595).optional()
+        .describe('Minimum event duration filter in seconds.'),
+    latitude: z.number().min(-90).max(90).optional()
+        .describe('GPS latitude (decimal degrees, -90 to 90). Applied to all files in the batch. Must be paired with longitude.'),
+    longitude: z.number().min(-180).max(180).optional()
+        .describe('GPS longitude (decimal degrees, -180 to 180). Applied to all files in the batch. Must be paired with latitude.'),
+};
+export const CREATE_WEBHOOK_SHAPE = {
+    url: z.string().url()
+        .describe('HTTPS webhook URL where events will be POSTed.'),
+    events: z.array(z.string()).optional()
+        .describe('Event types to subscribe to (e.g. job.completed, job.failed). Defaults to all events if omitted.'),
+    description: z.string().max(200).optional()
+        .describe('Human-readable description for this webhook.'),
+    taxonomyFilter: z.array(z.string()).optional()
+        .describe('Scope notifications to specific taxonomies (e.g. audioset-yamnet-521, species).'),
+    notificationTierDepth: z.number().int().min(1).max(3).optional()
+        .describe('AudioSet tier depth for filtering: 1=coarse (Animal), 2=mid (Domestic animals, pets), 3=fine (Dog). Max depth is 3 — the taxonomy has tiers 4-5 but webhook filtering does not extend beyond tier 3. Must pair with notificationTierValues.'),
+    notificationTierValues: z.array(z.string()).optional()
+        .describe('Tier labels to match at the specified depth (e.g. ["Animal", "Music"]). Must pair with notificationTierDepth.'),
+};
+export const UPDATE_WEBHOOK_SHAPE = {
+    webhookId: z.string().min(1)
+        .describe('The webhook ID to update.'),
+    url: z.string().url().optional()
+        .describe('New HTTPS webhook URL.'),
+    events: z.array(z.string()).optional()
+        .describe('New event types to subscribe to.'),
+    status: z.enum(['active', 'paused']).optional()
+        .describe('Set to "paused" to disable or "active" to re-enable.'),
+    description: z.string().max(200).optional()
+        .describe('Updated description.'),
+    taxonomyFilter: z.array(z.string()).nullable().optional()
+        .describe('Scope to taxonomies. Pass null to clear filter.'),
+    notificationTierDepth: z.number().int().min(1).max(3).nullable().optional()
+        .describe('AudioSet tier depth (1=coarse, 2=mid, 3=fine). Max depth is 3 — tiers 4-5 exist in the taxonomy but are not supported for webhook filtering. Pass null to clear. Must pair with notificationTierValues.'),
+    notificationTierValues: z.array(z.string()).nullable().optional()
+        .describe('Tier labels to match. Pass null to clear. Must pair with notificationTierDepth.'),
+};
+export const GET_WEBHOOK_SHAPE = {
+    webhookId: z.string().min(1)
+        .describe('The webhook ID to retrieve.'),
+};
+export const DELETE_WEBHOOK_SHAPE = {
+    webhookId: z.string().min(1)
+        .describe('The webhook ID to delete.'),
+};
+export const PING_WEBHOOK_SHAPE = {
+    webhookId: z.string().min(1)
+        .describe('The webhook ID to ping.'),
+};
+export const LIST_WEBHOOK_DELIVERIES_SHAPE = {
+    webhookId: z.string().min(1)
+        .describe('The webhook ID to get deliveries for.'),
+    limit: z.number().int().positive().max(100).default(20)
+        .describe('Max deliveries to return (1-100, default 20).'),
+};
+export const GET_JOB_REPORT_SHAPE = {
+    jobId: z.string().min(1)
+        .describe('Job ID from classifyAudio, classifyBatch, or listJobs.'),
+};
+// ─── Descriptions (authoritative) ────────────────────────────────────────────
+const formats = HEAR_API.SUPPORTED_FORMATS.join(', ');
+const maxMB = HEAR_API.MAX_FILE_SIZE_BYTES / (1024 * 1024);
+export const toolDescriptions = {
+    healthCheck: 'Check H-ear API health and liveness. No authentication required. Returns API status/version, deployment timestamp, and the loaded @h-ear/mcp-server package version (mcpServerVersion) for --pull verification.',
+    usage: 'Get H-ear API usage statistics: minutes used, calls today, quota remaining, active keys. Requires API key (HEAR_API_KEY).',
+    listClasses: 'List supported audio classification classes. Default taxonomy: audioset-yamnet-521 (521 classes across 7 categories). Also available: audioset-panns-527 (527 classes), species (6522 bird species). ' +
+        'Each class has a tierDepth (1–5) indicating its position in the AudioSet hierarchy, but filtering in getJobEvents and webhook notifications is supported up to tier 3 only. ' +
+        'Response fields: total and totalFiltered both reflect the post-filter count; totalAvailable is the unfiltered class count for the entire taxonomy. ' +
+        'Some AudioSet indices are retired and absent (e.g. 79, 83, 87) — this is normal, do not treat index gaps as errors. ' +
+        'No authentication required.',
+    listJobs: 'List recent classification jobs with status, file name, event count, and timestamps. Supports pagination. Requires API key (HEAR_API_KEY).',
+    getJob: 'Get detailed results for a specific classification job, including all detected sound events and classifications. Requires API key (HEAR_API_KEY).',
+    getJobEvents: 'Get paginated and filtered noise events for a completed classification job. ' +
+        'Use minConfidence to filter by confidence threshold (e.g. 0.7 for ≥70%). ' +
+        'Use category/tier2/tier3 to filter by sound class hierarchy up to 3 tiers deep (e.g. "Animal" > "Domestic animals, pets" > "Dog"). ' +
+        'Use startTime/endTime to get events within a time window in seconds. ' +
+        'Returns startTime, endTime, tier1 class, confidence, decibelLevel, and realTimeStart for each event. ' +
+        'IMPORTANT: Long recordings can produce thousands of events. Always start with a small limit (10–50) and use filters (category, minConfidence, startTime/endTime) to narrow results before increasing. ' +
+        'For bulk export use getJobAudio to download the source file instead. ' +
+        'Requires API key.',
+    getJobAudio: 'Get a time-limited SAS URL for streaming the source audio of a classification job. ' +
+        'Returns a 1-hour URL for direct audio playback via HTML5 <audio> element or fetch. ' +
+        'The URL supports HTTP Range requests — browsers can seek without downloading the full file. ' +
+        'For event-specific playback, append a Media Fragment time range to the URL: audioUrl + "#t=1.92,5.76". ' +
+        'Only available for jobs submitted via file upload (not URL-submitted jobs). ' +
+        'Requires API key.',
+    getJobWaveform: 'Get pre-computed waveform data and audio URL for a completed classification job. ' +
+        'Returns waveformUrl (peaks.js-compatible .dat binary) and audioUrl for synchronized playback. ' +
+        'Initialize peaks.js with: Peaks.init({ dataUri: { arraybuffer: waveformUrl }, mediaElement: audioEl }). ' +
+        'If waveformUrl is null, use wavesurfer.js with audioUrl instead (decodes via Web Audio API). ' +
+        'Zoom controls resolution: 256=high detail, 1024=standard (default), 4096=overview. ' +
+        'Both URLs expire in 1 hour. ' +
+        'For event navigation, combine with getJobEvents to get startTime values for seeking. ' +
+        'Requires API key.',
+    getUploadStatus: 'Check the status of an in-flight byte-slice upload started by classifyAudio in fire-and-return mode. Returns slice progress, and once status is "complete", a requestId you can pass to getJob. State lives in the MCP server process — if the process restarted since the upload started, the session will not be found.',
+    getJobReport: 'Get a 7-day SAS URL to download the Excel analysis report for a completed classification job. Returns `{ jobId, reportUrl, expiresIn }`. Returns 409 if the job is still processing, 404 if the report blob is missing. Requires API key.',
+    classifyAudio: `Classify a local audio file or public URL for noise/sound detection. Provide filePath (recommended) or url. Returns detected sound classes with confidence scores. Formats: ${formats}. Files over ${maxMB}MB are automatically uploaded via byte-slice chunking (no ffmpeg required). Requires API key (HEAR_API_KEY). For large files, may take several minutes to upload. Returns job ID for later retrieval via getJob.`,
+    classifyBatch: `Classify multiple audio files. Provide filePaths for local files (recommended) or files with URLs. Local files: submits all then polls each sequentially (may take several minutes), or provide callbackUrl to skip polling and receive results via webhook. URL files: returns immediately with batch ID (results via webhook). Max ${HEAR_API.MAX_BATCH_FILES} files. Requires API key (HEAR_API_KEY).`,
+    createWebhook: 'Create an enterprise webhook registration for async event delivery (job.completed, job.failed, etc.). Returns webhook details and a signing secret shown ONCE — save it immediately. Supports taxonomy and tier-based notification filtering. Requires Bearer token (enterprise subscription).',
+    updateWebhook: 'Update an enterprise webhook registration. Change events, URL, status (active/paused), or notification filters. Set status to "paused" to temporarily disable without deleting. Requires Bearer token (enterprise subscription).',
+    listWebhooks: 'List all enterprise webhook registrations. Shows URL, subscribed events, status, failure count, and notification filter config. Requires Bearer token (enterprise subscription).',
+    getWebhook: 'Get detailed information about a specific enterprise webhook, including delivery stats, notification filters, and status. Requires Bearer token (enterprise subscription).',
+    deleteWebhook: 'Permanently delete an enterprise webhook registration. This action cannot be undone. Requires Bearer token (enterprise subscription).',
+    pingWebhook: 'Send a test ping event to an enterprise webhook to verify connectivity. Returns delivery result with response status and timing. Requires Bearer token (enterprise subscription).',
+    listWebhookDeliveries: 'List recent delivery attempts for an enterprise webhook. Shows event type, HTTP response status, success/failure, timing, and attempt count for audit trail. Requires Bearer token (enterprise subscription).',
+};
+// ─── Shape map ───────────────────────────────────────────────────────────────
+const shapes = {
+    healthCheck: HEALTH_CHECK_SHAPE,
+    usage: USAGE_SHAPE,
+    listClasses: LIST_CLASSES_SHAPE,
+    listJobs: LIST_JOBS_SHAPE,
+    getJob: GET_JOB_SHAPE,
+    getJobEvents: GET_JOB_EVENTS_SHAPE,
+    getJobAudio: GET_JOB_AUDIO_SHAPE,
+    getJobWaveform: GET_JOB_WAVEFORM_SHAPE,
+    getJobReport: GET_JOB_REPORT_SHAPE,
+    getUploadStatus: GET_UPLOAD_STATUS_SHAPE,
+    classifyAudio: CLASSIFY_AUDIO_SHAPE,
+    classifyBatch: CLASSIFY_BATCH_SHAPE,
+    createWebhook: CREATE_WEBHOOK_SHAPE,
+    updateWebhook: UPDATE_WEBHOOK_SHAPE,
+    listWebhooks: LIST_WEBHOOKS_SHAPE,
+    getWebhook: GET_WEBHOOK_SHAPE,
+    deleteWebhook: DELETE_WEBHOOK_SHAPE,
+    pingWebhook: PING_WEBHOOK_SHAPE,
+    listWebhookDeliveries: LIST_WEBHOOK_DELIVERIES_SHAPE,
+};
+export const toolShapes = Object.freeze(shapes);
+// ─── JSON Schemas (derived from shapes) ──────────────────────────────────────
+function shapeToJsonSchema(shape) {
+    // zod-to-json-schema expects a ZodObject; wrap the raw shape.
+    const obj = z.object(shape);
+    const full = zodToJsonSchema(obj, { $refStrategy: 'none' });
+    // Strip the top-level $schema keyword for a compact inputSchema payload; APIM
+    // accepts JSON Schema draft-07 style without it.
+    delete full.$schema;
+    return full;
+}
+export const toolSchemas = Object.freeze(Object.fromEntries(Object.entries(shapes).map(([name, shape]) => [name, shapeToJsonSchema(shape)])));
+// ─── Tool name catalogue ─────────────────────────────────────────────────────
+export const toolNames = Object.freeze(Object.keys(shapes));
+//# sourceMappingURL=index.js.map

package/dist/schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAqB/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAkC/F"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAuB/D,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAoC/F"}

package/dist/server.js

@@ -17,6 +17,7 @@ import { registerGetJob } from './tools/get-job.js';
 import { registerGetJobEvents } from './tools/get-job-events.js';
 import { registerGetJobAudio } from './tools/get-job-audio.js';
 import { registerGetJobWaveform } from './tools/get-job-waveform.js';
+import { registerGetJobReport } from './tools/get-job-report.js';
 import { registerCreateWebhook } from './tools/create-webhook.js';
 import { registerListWebhooks } from './tools/list-webhooks.js';
 import { registerGetWebhook } from './tools/get-webhook.js';
@@ -24,6 +25,7 @@ import { registerUpdateWebhook } from './tools/update-webhook.js';
 import { registerDeleteWebhook } from './tools/delete-webhook.js';
 import { registerPingWebhook } from './tools/ping-webhook.js';
 import { registerListWebhookDeliveries } from './tools/list-webhook-deliveries.js';
+import { registerGetUploadStatus } from './tools/get-upload-status.js';
 import { registerApiStatus } from './resources/api-status.js';
 import { registerClassifyAudioPrompt } from './prompts/classify-audio.js';
 export function createServer(config) {
@@ -40,6 +42,7 @@ export function createServer(config) {
     registerGetJobEvents(server, client);
     registerGetJobAudio(server, client);
     registerGetJobWaveform(server, client);
+    registerGetJobReport(server, client);
     registerCreateWebhook(server, client);
     registerListWebhooks(server, client);
     registerGetWebhook(server, client);
@@ -47,6 +50,7 @@ export function createServer(config) {
     registerDeleteWebhook(server, client);
     registerPingWebhook(server, client);
     registerListWebhookDeliveries(server, client);
+    registerGetUploadStatus(server);
     // Resources
     registerApiStatus(server, client, config);
     // Prompts

package/dist/server.js.map

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

package/dist/tools/classify-audio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"classify-audio.d.ts","sourceRoot":"","sources":["../../src/tools/classify-audio.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EACH,KAAK,aAAa,EAErB,MAAM,aAAa,CAAC;AAyCrB,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CA0JpF"}
+{"version":3,"file":"classify-audio.d.ts","sourceRoot":"","sources":["../../src/tools/classify-audio.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EACH,KAAK,aAAa,EAErB,MAAM,aAAa,CAAC;AA0CrB,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAmMpF"}

package/dist/tools/classify-audio.js

@@ -1,10 +1,11 @@
-import { z } from 'zod';
 import { createReadStream, readFileSync, existsSync, statSync } from 'fs';
 import { basename, extname } from 'path';
 import { createHash } from 'crypto';
 import { pipeline } from 'stream/promises';
 import { HearApiError, HEAR_API, getAudioDuration, } from '@h-ear/core';
 import { createProgressReporter } from '../progress.js';
+import { trackerStart, trackerUpdate } from '../upload-tracker.js';
+import { CLASSIFY_AUDIO_SHAPE, toolDescriptions } from '../schemas/index.js';
 async function hashFile(filePath) {
     const hash = createHash('sha256');
     await pipeline(createReadStream(filePath, { highWaterMark: 1024 * 1024 }), hash);
@@ -40,28 +41,8 @@ async function buildClientMetadata(filePath, fileStat) {
     return out;
 }
 const formats = HEAR_API.SUPPORTED_FORMATS.join(', ');
-const maxMB = HEAR_API.MAX_FILE_SIZE_BYTES / (1024 * 1024);
 export function registerClassifyAudio(server, client) {
-    server.tool('classifyAudio', `Classify a local audio file or public URL for noise/sound detection. Provide filePath (recommended) or url. Returns detected sound classes with confidence scores. Formats: ${formats}. Files over ${maxMB}MB are automatically uploaded via byte-slice chunking (no ffmpeg required). Requires API key (HEAR_API_KEY). For large files, may take several minutes to upload. Returns job ID for later retrieval via getJob.`, {
-        filePath: z.string().optional()
-            .describe('Path to a local audio file (Desktop/CLI only — requires local filesystem access). The server reads and encodes it automatically. Large files are split into chunks. Use url for web/mobile clients.'),
-        url: z.string().url().optional()
-            .describe('Public URL to audio file.'),
-        threshold: z.number().min(0).max(1).default(0.3)
-            .describe('Confidence threshold (0.0-1.0). Only classes above this score are returned.'),
-        filterMinDurationSeconds: z.number().min(0.1).max(595).optional()
-            .describe('Minimum event duration filter in seconds.'),
-        waitForResult: z.any().default(false)
-            .describe('If true, polls until classification completes (up to 5 min). Default false — returns immediately with job ID for later retrieval via getJob.'),
-        callbackUrl: z.string().url().optional()
-            .describe('Webhook URL (HTTPS) for async result delivery. When provided, the server POSTs classification results to this URL on completion — no polling needed. Use getJob to check status manually.'),
-        callbackSecret: z.string().optional()
-            .describe('HMAC-SHA256 secret for webhook signature verification. Only used with callbackUrl.'),
-        latitude: z.number().min(-90).max(90).optional()
-            .describe('GPS latitude (decimal degrees, -90 to 90). Tag the recording location. Must be paired with longitude.'),
-        longitude: z.number().min(-180).max(180).optional()
-            .describe('GPS longitude (decimal degrees, -180 to 180). Tag the recording location. Must be paired with latitude.'),
-    }, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async (params, extra) => {
+    server.tool('classifyAudio', toolDescriptions.classifyAudio, CLASSIFY_AUDIO_SHAPE, { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, async (params, extra) => {
         try {
             const { onProgress } = createProgressReporter(extra);
             // Desktop sends booleans as strings — coerce here to keep schema simple
@@ -126,18 +107,20 @@ export function registerClassifyAudio(server, client) {
                 const result = await client.pollJob(accepted.requestId, onProgress);
                 return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
-            // Large file: byte-slice upload. Server AppendBlob concatenates raw bytes into one ML job.
+            // Large file: byte-slice upload. Head returns fast; tail runs in background to fit
+            // the MCP client tool-call wall budget. AI agent polls getUploadStatus(uploadSessionId)
+            // until status='complete', then uses the returned requestId with getJob.
             const fileSize = stat.size;
-            const chunkSize = HEAR_API.MAX_FILE_SIZE_BYTES;
-            const totalChunks = Math.ceil(fileSize / chunkSize);
-            onProgress(`Large file (${fileSizeMB.toFixed(1)}MB) — uploading in ${totalChunks} chunks`);
+            const sliceSize = HEAR_API.MAX_FILE_SIZE_BYTES;
+            const totalSlices = Math.ceil(fileSize / sliceSize);
+            onProgress(`Large file (${fileSizeMB.toFixed(1)}MB) — uploading in ${totalSlices} byte slices`);
             const chunks = [];
-            for (let i = 0; i < totalChunks; i++) {
-                const offset = i * chunkSize;
-                const length = Math.min(chunkSize, fileSize - offset);
+            for (let i = 0; i < totalSlices; i++) {
+                const offset = i * sliceSize;
+                const length = Math.min(sliceSize, fileSize - offset);
                 chunks.push({ filePath: params.filePath, offset, length, index: i });
             }
-            const accepted = await client.submitClassifyChunked(chunks, basename(params.filePath), {
+            const sliceOptions = {
                 threshold: params.threshold,
                 filterMinDurationSeconds: params.filterMinDurationSeconds,
                 callbackUrl: params.callbackUrl,
@@ -145,13 +128,60 @@ export function registerClassifyAudio(server, client) {
                 latitude: params.latitude,
                 longitude: params.longitude,
                 ...clientMetadata,
-            }, onProgress);
-            if (params.callbackUrl || !waitForResult) {
-                return { content: [{ type: 'text', text: JSON.stringify(accepted, null, 2) }] };
+            };
+            // Wait-for-result: caller explicitly opts into the long blocking call (rare on stdio).
+            if (waitForResult) {
+                const accepted = await client.submitClassifyChunked(chunks, basename(params.filePath), sliceOptions, onProgress);
+                onProgress(`Polling job ${accepted.requestId}`);
+                const result = await client.pollJob(accepted.requestId, onProgress);
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
+            // Fire-and-return: head sync (one HTTP RTT), tail in background.
+            const head = await client.submitChunkUploadHead(chunks[0], basename(params.filePath), sliceOptions, 
+            /*isFinal*/ totalSlices === 1, totalSlices, onProgress);
+            // Single-slice case: head was also final, requestId already returned.
+            if (totalSlices === 1) {
+                return { content: [{ type: 'text', text: JSON.stringify(head, null, 2) }] };
             }
-            onProgress(`Polling job ${accepted.requestId}`);
-            const result = await client.pollJob(accepted.requestId, onProgress);
-            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            const headResult = head;
+            const startedAt = new Date().toISOString();
+            trackerStart({
+                uploadSessionId: headResult.uploadSessionId,
+                fileName: basename(params.filePath),
+                totalSlices,
+                slicesUploaded: headResult.chunksReceived,
+                totalBytes: headResult.totalBytes,
+                startedAt,
+                status: 'uploading',
+            });
+            // Background: upload remaining slices. Process stays alive between MCP tool calls.
+            void client.submitChunkUploadTail(headResult.uploadSessionId, chunks.slice(1), basename(params.filePath), headResult.chunksReceived, totalSlices, (msg) => {
+                // Best-effort: bump slicesUploaded each time the tail logs a slice ack.
+                const m = /server confirmed (\d+) slices/.exec(msg);
+                if (m) {
+                    trackerUpdate(headResult.uploadSessionId, { slicesUploaded: parseInt(m[1], 10) });
+                }
+                process.stderr.write(`[h-ear-mcp] ${msg}\n`);
+            }).then((accepted) => {
+                trackerUpdate(headResult.uploadSessionId, {
+                    status: 'complete',
+                    slicesUploaded: totalSlices,
+                    requestId: accepted.requestId,
+                });
+            }).catch((err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                trackerUpdate(headResult.uploadSessionId, { status: 'failed', error: msg });
+                process.stderr.write(`[h-ear-mcp] background upload failed for session ${headResult.uploadSessionId}: ${msg}\n`);
+            });
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            status: 'uploading',
+                            uploadSessionId: headResult.uploadSessionId,
+                            totalSlices,
+                            slicesUploaded: headResult.chunksReceived,
+                            totalBytes: headResult.totalBytes,
+                            fileName: basename(params.filePath),
+                            message: `Upload started in background. Poll getUploadStatus('${headResult.uploadSessionId}') until status='complete', then use the returned requestId with getJob.`,
+                        }, null, 2) }] };
         }
         catch (error) {
             // POLL_TIMEOUT: job is still processing server-side (large file / chunk-by-requeue).