Skip to main content
Glama

webear

npm version npm downloads License: MIT MCP Compatible

让你的 AI 拥有真实感官 — 聆听、观察并感知任何 Web 应用。

一个 MCP 服务器 + 浏览器 SDK,为 AI 编码助手提供对实时 Web 应用的直接感官访问。音频、视觉、性能、网络、安全和控制台 — 从浏览器捕获,实时分析,通过 MCP 交付。

“低音听起来很浑浊” → 你的 AI 捕获 3 秒音频,测得频谱质心为 580 Hz,且 45% 的能量低于 250 Hz,然后准确告诉你原因。


AI Web Perception Demo


它能做什么

工具

描述

capture_audio

录制一段当前 Web 应用正在输出的短音频(500ms–30s)

analyze_audio

信号分析:RMS、峰值 dB、削波、频谱质心、频段、BPM、时序抖动

describe_audio

通俗易懂的 AI 描述 — “低音很蓬松,80 Hz 附近有大量次低音堆积”

diff_audio

比较两次捕获并指出变化 — 响度、音色、时序、削波

Related MCP server: broca-machina

工作原理

Browser (Web Audio API)
    ↓ MediaRecorder taps the AudioContext output node
    ↓ Uploads WebM blob via HTTP POST
Express Middleware (your dev server)
    ↓ Stores captures in memory, dispatches commands via SSE
MCP Server (stdio — runs inside your IDE)
    ↓ Retrieves captures, sends to CodedSwitch analysis API
AI Coding Assistant
    → "Your bass band is 42% of the mix (high), spectral centroid
       is 580 Hz (muddy), and timing jitter is 23ms — the scheduler
       is drifting under load."

与其他所有音频 MCP 的关键区别:它直接接入 Web Audio 图,绕过了房间声学、麦克风硬件以及导出文件的需要。


快速开始

1. 安装

npm install webear

2. 将 Express 中间件添加到你的开发服务器

import express from 'express'
import { webearMiddleware } from 'webear/middleware'

const app = express()
app.use(express.json())

// Mount the audio debug bridge (automatically disabled in production)
app.use('/api/webear', webearMiddleware())

app.listen(5000)

3. 将客户端代码片段添加到你的 Web 应用

选项 A — 自动检测一切(Tone.js 或原始 Web Audio)

import WebEar from 'webear/client'
WebEar.init()

选项 B — 显式 AudioContext

const ctx = new AudioContext()
const masterGain = ctx.createGain()
masterGain.connect(ctx.destination)

WebEar.init({ audioContext: ctx, outputNode: masterGain })

选项 C — Tone.js 项目

import * as Tone from 'tone'
WebEar.init({ toneJs: true })

选项 D — Three.js WebGL 游戏

import * as THREE from 'three'
const listener = new THREE.AudioListener()
camera.add(listener)
WebEar.init({ tapNode: listener.getInput() })

选项 E — 普通 script 标签

<script src="node_modules/webear/client-snippet.js"></script>
<script>WebEar.init()</script>

4. 配置你的 IDE

Claude Code(项目根目录下的 .mcp.json):

{
  "mcpServers": {
    "webear": {
      "command": "npx",
      "args": ["webear"],
      "env": {
        "WEBEAR_BASE_URL": "http://localhost:5000",
        "CODEDSWITCH_API_KEY": "your-key-here"
      }
    }
  }
}

Cursor(.cursor/mcp.json):

{
  "mcpServers": {
    "webear": {
      "command": "npx",
      "args": ["webear"],
      "env": {
        "WEBEAR_BASE_URL": "http://localhost:5000",
        "CODEDSWITCH_API_KEY": "your-key-here"
      }
    }
  }
}

Windsurf(mcp_config.json):

{
  "webear": {
    "command": "npx",
    "args": ["webear"],
    "disabled": false,
    "env": {
      "WEBEAR_BASE_URL": "http://localhost:5000",
      "CODEDSWITCH_API_KEY": "your-key-here"
    }
  }
}

5. 获取 API 密钥 — 可选,且不是起步所必需

analyze_audio 无需密钥和账户即可使用。 如果 ffmpeg 在你的 PATH 中,它会在你的机器上解码并分析捕获内容,然后返回基本报告:时长、响度、峰值电平以及音频是否削波。不会上传任何内容。在注册任何服务之前,先试用该工具。

密钥可以解锁需要更多计算的部分:

无密钥

有密钥

capture_audio

✓

✓

analyze_audio

基础 — 时长、响度、峰值、削波(本地)

完整 — 频谱质心、频段能量、波峰因数、BPM、时序抖动

describe_audio — 它听起来像什么

—

✓

mix_coach — 测量 + 听感

—

✓

diff_audio — 前后对比

—

✓

获取方式:

  1. 在 codedswitch.com 创建一个免费账户。

  2. 前往 codedswitch.com/developer(也可在账户菜单中通过 Developer API 进入)。

  3. 点击 Generate API Key — 该值就是你的 CODEDSWITCH_API_KEY。密钥以 wbr_ 开头。

免费额度:每天 50 次分析。无需信用卡。

6. 启动你的开发服务器,打开应用,播放音频,然后向你的 AI 提问:

“捕获 3 秒音频,告诉我为什么低音听起来浑浊。”

“比较我上次提交前后的音频。”

“高频范围是否有任何削波?”


示例输出

analyze_audio

── Audio Analysis Report ──────────────────────────────
Duration:          3.02s

── Loudness ─────────────────────────────────────────
RMS:               -12.4 dBFS
Peak:              -1.2 dBFS
Dynamic range:     11.2 dB
Crest factor:      3.63
Clipping:          none

── Tone ──────────────────────────────────────────────
Spectral centroid: 2847 Hz
DC offset:         0.00012 (ok)

── Frequency Bands ───────────────────────────────────
Sub  (20-80 Hz):   8.2%
Bass (80-250 Hz):  22.1%
Mid  (250-2k Hz):  38.4%
Hi-mid (2-6k Hz):  21.8%
High (6k+ Hz):     9.5%

── Rhythm ────────────────────────────────────────────
Estimated BPM:     92
Onset count:       12
Timing jitter:     4.2 ms std dev

── Summary ───────────────────────────────────────────
Loudness: -12.4 dBFS RMS, peak -1.2 dBFS. Tone: balanced (centroid 2847 Hz).
Band mix — sub: 8% | bass: 22% | mid: 38% | hi-mid: 22% | high: 10%.
Rhythm: estimated 92 BPM, 12 onsets detected. Timing: very tight (< 5 ms jitter).

diff_audio

── Audio Diff: a1b2c3d4… → e5f6g7h8… ──

── Loudness ──────────────────────────────────────────
  RMS: -14.2 dBFS → -12.4 dBFS  (+1.8 dBFS)
⚠ Peak: -3.1 dBFS → -0.2 dBFS  (+2.9 dBFS)
⚠ CLIPPING INTRODUCED — gain staging regression

── Tone ──────────────────────────────────────────────
⚠ Spectral centroid: 2847.0 Hz → 1920.0 Hz  (-927.0 Hz)

── Interpretation ────────────────────────────────────
A gain bug was introduced that causes clipping.
Tonal character changed noticeably — EQ or filter behaviour may have shifted.

配置

环境变量

变量

默认值

描述

WEBEAR_BASE_URL

http://localhost:4000

你的开发服务器 URL(中间件挂载的位置)

CODEDSWITCH_API_KEY

—

来自 codedswitch.com 的 API 密钥 — analyze_audio 和 describe_audio 必需

MCP_API_URL

https://www.codedswitch.com

覆盖分析 API 基础地址(高级 / 自托管)

中间件选项

webearMiddleware({
  maxCaptures: 50,       // Max captures in memory (default: 50)
  maxAgeMins: 10,        // Auto-evict after N minutes (default: 10)
  maxUploadBytes: 50e6,  // Max upload size (default: 50MB)
  devOnly: true,         // Disable in production (default: true)
})

客户端选项

WebEar.init({
  audioContext: myCtx,             // Your AudioContext instance
  outputNode: myGainNode,          // The node to tap (defaults to destination)
  toneJs: true,                    // Auto-detect Tone.js context
  bridgeBase: '/api/webear',  // Override API path
  devOnly: true,                   // Only init outside of production (default: true)
})

要求

  • Node.js >= 18

  • 支持 MediaRecorder 的浏览器(Chrome、Firefox、Edge、Safari 14+)

  • 用于分析的 CODEDSWITCH_API_KEY(在 codedswitch.com 免费获取)


适合谁?

  • Web Audio / Tone.js 开发者 — 无需离开 IDE 即可调试节拍、合成器、效果和混音

  • 游戏音频开发者 — 实时验证音效、空间音频和混音

  • 音乐应用构建者 — 使用 diff_audio 捕获代码更改之间的回归

  • 播客 / 流媒体应用 — 验证音频质量、电平和编码

  • 任何制作发声应用的人 — 如果它有 Web Audio 图,你的 AI 现在就能听到它


为什么不直接使用麦克风?

麦克风 MCP 捕获的是房间声音 — 你的风扇噪音、椅子吱嘎声和房间混响都会进入录音。webear 在信号到达 DAC 之前接入 Web Audio API,从而获得没有房间伪影的干净数字信号。


Web Perception — 完整传感器套件

WebEar 最初仅支持音频。Web Perception 将其扩展到 6 种感官:

传感器

感知内容

WebEar

音频 — 混音质量、节奏、乐器、削波

WebEye

视觉 — 画布、UI 布局、动画、截图

WebSense

性能 — 帧率、内存、音频延迟

WebNerve

网络 — API 延迟、连接质量、存储

WebShield

安全 — Cookie、存储暴露、CSP、框架嵌入

WebLog

控制台 — 日志、警告、错误、未捕获异常

安装完整的浏览器 SDK

import { WebPerception } from 'webear/perception'

WebPerception.init({
  apiKey: 'wbr_YOUR_API_KEY',
  relayUrl: 'https://www.codedswitch.com',
  sensors: ['ear', 'eye', 'sense', 'nerve', 'shield', 'log'],
})

或使用单个传感器:

import { WebEar } from 'webear/perception'

WebEar.init({
  apiKey: 'wbr_YOUR_API_KEY',
  ear: { audioContext: myCtx, audioNode: masterGain },
})

通过 MCP 连接(托管中继 — 无需本地服务器)

{
  "mcpServers": {
    "webear": {
      "url": "https://www.codedswitch.com/api/webear/mcp/sse",
      "headers": {
        "Authorization": "Bearer wbr_YOUR_API_KEY"
      }
    }
  }
}

可用的 MCP 工具

传感器

工具

积分

描述

Ear

capture_audio

免费

录制当前标签页的实时音频

Ear

analyze_audio

1

BPM、响度、频段、削波、动态范围

Ear

describe_audio

2

AI 自然语言描述 — 乐器、风格、情绪、混音备注

Ear

diff_audio

1

比较两次捕获 — 响度、音色、时序差异

Ear

groove_score

2

网格对齐、摇摆因子、一致性(0–100%)

Ear

capture_and_analyze

1

一次调用完成捕获 + 分析

Ear

mix_coach

3

结构化混音反馈

Eye

capture_video

免费

录制标签页中的 canvas/video

Eye

describe_video

2

AI 视觉描述 — 布局、颜色、缺陷

Eye

diff_visuals

2

比较两次视觉捕获

Sense

capture_telemetry

免费

FPS、内存、布局偏移、音频延迟

Sense

analyze_telemetry

1

掉帧、内存压力、音频欠载

Nerve

capture_nerve

免费

API 计时、连接质量、存储大小

Nerve

analyze_nerve

1

慢 API、连接质量、存储膨胀

Shield

capture_shield

免费

Cookie、CSP、存储暴露、框架嵌入

Shield

analyze_shield

1

CORS 问题、非 HttpOnly Cookie、缺少 CSP

Log

capture_logs

免费

控制台输出 + 未捕获异常

Log

analyze_logs

1

错误模式、堆栈跟踪、重复警告

获取 API 密钥

  1. 在 codedswitch.com 创建一个免费账户。

  2. 打开 codedswitch.com/developer — 在账户菜单中也会作为 Developer API 链接到该页面。

  3. 点击 Generate API Key 并复制。密钥以 wbr_ 开头。

免费额度:每天 50 次分析,无需信用卡。


更新日志

2.0.1

  • 修复了 API 密钥的入门路径。 之前的说明(“设置 → WebEar”)是错误的 — “设置”下没有 WebEar 部分。密钥位于 codedswitch.com/developer(在账户菜单中作为 Developer API 链接)。快速开始和 Web Perception 部分现在都指向正确的位置。

  • SDK 的“缺少 API 密钥”控制台错误现在会直接链接到密钥页面。

贡献

参见 CONTRIBUTING.md。

许可证

MIT — 参见 LICENSE

作者

由 @asume21 构建 — CodedSwitch

Available Tools

4 tools
analyze_audioA

Run signal analysis on a captured audio clip. Returns RMS, peak dB, clipping, spectral centroid, frequency band energy, estimated BPM, and timing jitter.

ParametersJSON Schema
NameRequiredDescriptionDefault
capture_idYesThe capture ID returned by capture_audio

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description fully carries the burden of behavioral disclosure. It lists the analysis outputs and implies a non-destructive, read-only operation, which is appropriate for a signal analysis tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at one sentence, front-loaded with the action ('Run signal analysis'), and efficiently enumerates outputs without extraneous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only one parameter and no output schema, the description adequately lists the return values, providing enough context for an agent to understand what the tool produces.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter (capture_id), which already has a description. The tool description adds that the parameter should come from capture_audio, but this is marginal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb ('Run signal analysis'), resource ('captured audio clip'), and lists specific metrics returned (RMS, peak dB, clipping, etc.), distinguishing it from sibling tools like capture_audio or describe_audio.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool requires a prior captured audio clip (via capture_id), but does not explicitly state when to prefer this tool over alternatives like describe_audio or diff_audio, leaving room for ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

capture_audioA

Record a short clip of what the running web app is currently outputting. Returns a capture ID you can pass to analyze_audio or describe_audio.

ParametersJSON Schema
NameRequiredDescriptionDefault
duration_msNoHow many milliseconds to record (default 3000, max 30000)

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It states 'short clip' and mentions the duration parameter, but does not disclose what audio source is captured (e.g., system output, microphone), potential failure modes, or any destructive effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the verb and resource, no redundant information. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description fully covers the purpose, return value, and relationship to sibling tools. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (duration_ms fully documented). The main description provides no additional parameter semantics beyond what the schema already states (default 3000, max 30000). Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool records a short clip of the running web app's audio output and returns a capture ID. Distinguishes itself from sibling tools (analyze_audio, describe_audio, diff_audio) by specifying that the ID can be passed to them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use the capture ID with analyze_audio or describe_audio, implying a workflow. However, it does not provide explicit when-not-to-use scenarios or alternatives beyond the mentioned siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

describe_audioA

Send a captured audio clip to Gemini or GPT-4o to get a plain-English description of what it sounds like — useful when something sounds wrong but you cannot describe it.

ParametersJSON Schema
NameRequiredDescriptionDefault
capture_idYesThe capture ID returned by capture_audio to describe

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It mentions the AI models but omits side effects like cost, latency, or external dependencies. This is insufficient for a tool that sends audio to external APIs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that conveys purpose, usage context, and outcome without any wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description covers the essential information. Minor gaps exist regarding output format or latency, but overall it is complete enough for the complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the single parameter with 100% coverage. The description adds minimal value beyond restating the purpose, but no further semantic information is needed given the schema's completeness.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('send'), resource ('captured audio clip'), and outcome ('plain-English description'). It differentiates from sibling tools like analyze_audio, capture_audio, and diff_audio by focusing on description generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a usage context ('useful when something sounds wrong but you cannot describe it') but does not explicitly mention when not to use it or compare to alternatives like analyze_audio.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

diff_audioA

Compare two audio captures and flag what changed — loudness, tone, timing, clipping. Use this before and after a code change to verify the audio impact.

ParametersJSON Schema
NameRequiredDescriptionDefault
capture_id_aYesFirst capture ID (the "before")
capture_id_bYesSecond capture ID (the "after")

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool 'flags what changed,' implying a read-only operation, but does not explicitly disclose whether it is safe, destructive, or requires permissions. Given the simple nature of a diff tool, the lack of explicit behavioral disclosure is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: the first clearly states the purpose and what is flagged, the second gives a concise use case. No unnecessary words. Well-structured and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the purpose and usage but lacks information about return values or potential errors. Given the tool's simplicity and the absence of an output schema, a hint at the output format would improve completeness. Sibling tools are explained in their own descriptions, so differentiation is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter described as the 'before' and 'after' capture ID. The tool description adds context about comparing captures and the aspects examined, but does not significantly enhance the semantic meaning beyond the schema. With high schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool compares two audio captures and lists specific aspects (loudness, tone, timing, clipping). It distinguishes itself from siblings (capture_audio, analyze_audio, describe_audio) by focusing on comparative analysis and providing a concrete use case ('before and after a code change').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool: 'before and after a code change to verify the audio impact.' It provides clear context but does not explicitly state when not to use it or mention alternative tools, though the use case implies a comparison scenario.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv2.0.0
    • First observedanalyze_audio
    • First observedcapture_audio
    • First observeddescribe_audio
    • First observeddiff_audio

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: capture records audio, analyze does signal analysis, describe provides a language description, and diff compares two captures. No overlap.

Naming Consistency5/5

All tool names follow the consistent verb_noun pattern (capture_audio, analyze_audio, describe_audio, diff_audio), making them predictable and easy to understand.

Tool Count5/5

Four tools cover the essential operations for audio perception without being too few or too many, perfectly scoped for the server's purpose.

Completeness5/5

The tool set covers capture, analysis, description, and comparison, providing a complete workflow for assessing audio output. No obvious missing operations.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers