# @h-ear/mcp-server

MCP server for the [H-ear World](https://h-ear.world) audio classification API. Connect Claude, ChatGPT, Copilot, and other AI agents to 521+ sound classes.

## Quick Start

```bash
npx @h-ear/mcp-server --key ncm_sk_your_key
```

## Authentication

Three ways to authenticate, from easiest to most manual:

| Method | Setup | Best For |
|--------|-------|----------|
| **claude.ai Connector** | Click "Add" in claude.ai Connectors Directory | claude.ai web/mobile (OAuth automatic) |
| **API Key (stdio)** | Set `HEAR_API_KEY` in config | Claude Desktop, Claude Code |
| **OAuth 2.1 + PKCE (Streamable HTTP)** | Connect to `https://api.h-ear.world/mcp` | Claude Code remote, custom MCP clients |

Two tools (`healthCheck`, `listClasses`) work without any authentication.

### claude.ai (easiest — zero config)

Search for "H-ear" in **Settings > Connectors** on claude.ai. OAuth login is automatic.

### Claude Desktop (API key)

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "h-ear": {
      "command": "npx",
      "args": ["-y", "@h-ear/mcp-server"],
      "env": { "HEAR_API_KEY": "ncm_sk_your_key", "HEAR_ENV": "prod" }
    }
  }
}
```

> **Windows MSIX users:** The config file is at `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`, NOT at `%APPDATA%\Claude\`. The "Edit Config" button opens the wrong path.

### Claude Code (API key)

Add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "h-ear": {
      "command": "npx",
      "args": ["-y", "@h-ear/mcp-server"],
      "env": { "HEAR_API_KEY": "ncm_sk_your_key", "HEAR_ENV": "prod" }
    }
  }
}
```

### Claude Code (OAuth — remote)

```bash
claude mcp add --transport http h-ear https://api.h-ear.world/mcp
```

OAuth 2.1 + PKCE discovery is automatic via [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) Protected Resource Metadata. Run `/mcp` in Claude Code to authenticate via browser — no API key needed.

## Tools

14 tools across classification, account, and webhook management:

| Tool | Description | Auth |
|------|-------------|------|
| `classifyAudio` | Classify a single audio file or URL (MP3, WAV, FLAC, OGG, M4A). Supports optional GPS coordinates (`latitude`/`longitude`) for location tagging. No file size limit — large local files are uploaded via byte-slice chunking (no ffmpeg required); URL mode is fetched server-side with no client upload. | API Key |
| `classifyBatch` | Batch classify up to 50 audio files or URLs. Supports optional GPS (`latitude`/`longitude`) applied to all files. | API Key |
| `listClasses` | List 521+ supported audio classes across 3 taxonomies (AudioSet/YAMNet, AudioSet/PANNs, Species). | None |
| `healthCheck` | API liveness check — status, version, deployment timestamp. | None |
| `usage` | API quota: minutes used, calls today, remaining balance. | API Key |
| `listJobs` | Paginated classification job history with status and filename. | API Key |
| `getJob` | Detailed job result with all detected sound events and timestamps. | API Key |
| `createWebhook` | Create enterprise webhook with event/taxonomy/tier filters. Returns signing secret once. | Bearer (enterprise) |
| `listWebhooks` | List all enterprise webhook registrations. | Bearer (enterprise) |
| `getWebhook` | Get webhook details including filter config and delivery stats. | Bearer (enterprise) |
| `updateWebhook` | Update webhook URL, events, status (active/paused), or filters. | Bearer (enterprise) |
| `deleteWebhook` | Permanently delete a webhook registration. | Bearer (enterprise) |
| `pingWebhook` | Send a test.ping event to verify connectivity and signing. | Bearer (enterprise) |
| `listWebhookDeliveries` | Delivery audit trail with response status and timing. | Bearer (enterprise) |

> **Web/Connector note:** `classifyAudio(filePath)` and `classifyBatch(filePaths)` require local filesystem access — unavailable via the claude.ai Connector (Streamable HTTP). Use `url` parameters instead, or switch to stdio transport.

## Resources

| URI | Description |
|-----|-------------|
| `h-ear://status` | Live API status with health, version, available taxonomies, and class counts. |

## Prompts

| Name | Description |
|------|-------------|
| `classify-audio` | Pre-built classification workflow prompt with configurable detail level. |

## Options

```
--key <key>        API key (or set HEAR_API_KEY env var)
--env <env>        Environment: dev, staging, prod (default: prod)
--base-url <url>   Override API base URL
--help, -h         Show help
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `HEAR_API_KEY` | H-ear Enterprise API key | (required for classify tools) |
| `HEAR_ENV` | Target environment | `prod` |
| `HEAR_BASE_URL` | Override base URL | Environment default |

## Large File Support

Files larger than 25 MB are automatically uploaded via byte-slice chunking. Raw 25 MB slices of the original file are uploaded sequentially to the server, which reassembles them via Azure AppendBlob. No ffmpeg required. Original file quality preserved.

- **No dependencies** — no ffmpeg, no temp files, no re-encoding
- **Memory efficient** — one 25 MB buffer at a time
- **Resumable** — per-chunk retry with exponential backoff

### Claude Desktop timeout

Claude Desktop has a hardcoded 60-second MCP timeout. Large file uploads can exceed this. Workarounds:
- **Claude Code:** Set `MCP_TIMEOUT=300000` (5 min) environment variable
- **Claude Desktop:** Use URL mode (`url` parameter) instead of `filePath` for large files — the API fetches the file server-side with no timeout concern

## GPS / Location

Pass `latitude` and `longitude` to `classifyAudio` or `classifyBatch` to tag recordings with GPS coordinates. Both must be provided together (decimal degrees: lat -90..90, lng -180..180).

The server applies a priority cascade: file-embedded GPS > client-provided GPS > IP geolocation. Location data is returned in the job result via `getJob` when available.

## Supported Formats

MP3, WAV, FLAC, OGG, M4A

## Requirements

- Node.js >= 18

## Get an API Key

Visit [h-ear.world](https://h-ear.world) to create an account and generate an API key.

## License

MIT