{
"canonical_name": "quietnotion/barevalue-mcp",
"compilation_id": "pack_75fae03fc0aa4518ab5e18d6f05fac08",
"created_at": "2026-05-24T16:54:23.888394+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx barevalue-mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx barevalue-mcp",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_5971a828f9214ccfbdcc13daf567601b"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_24e22860359d6625d46e2b152c2bc862",
"canonical_name": "quietnotion/barevalue-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/quietnotion/barevalue-mcp",
"slug": "barevalue-mcp",
"source_packet_id": "phit_2a1021b5a5b949278c6e7a8770e81cb9",
"source_validation_id": "dval_323ab2998e1149cbb8c3c0d5054c9da2"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": null,
"github_stars": null,
"one_liner_en": "Submit podcast orders, check status, and manage webhooks via Barevalue editing API.",
"one_liner_zh": "Submit podcast orders, check status, and manage webhooks via Barevalue editing API.",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, api, notion"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "barevalue-mcp",
"title_zh": "barevalue-mcp 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_2a1021b5a5b949278c6e7a8770e81cb9",
"page_model": {
"artifacts": {
"artifact_slug": "barevalue-mcp",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx barevalue-mcp",
"label": "Node.js / npx · 官方安装入口",
"source": "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Submit podcast orders, check status, and manage webhooks via Barevalue editing API."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。",
"category": "运行坑",
"evidence": [
"packet_text.keyword_scan | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | matched external service / cloud / webhook / database keyword"
],
"severity": "medium",
"suggested_check": "确认是否有离线 demo、mock 数据或可替代服务。",
"title": "运行可能依赖外部服务",
"user_impact": "本地安装成功不等于能力可用，外部服务不可用会阻断体验。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": null,
"forks": null,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": null
},
"source_url": "https://github.com/quietnotion/barevalue-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Submit podcast orders, check status, and manage webhooks via Barevalue editing API.",
"title": "barevalue-mcp 能力包",
"trial_prompt": "# barevalue-mcp - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for quietnotion/barevalue-mcp.\n\nProject:\n- Name: barevalue-mcp\n- Repository: https://github.com/quietnotion/barevalue-mcp\n- Summary: Submit podcast orders, check status, and manage webhooks via Barevalue editing API.\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Submit podcast orders, check status, and manage webhooks via Barevalue editing API.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Submit podcast orders, check status, and manage webhooks via Barevalue editing API.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Project Overview. Produce one small intermediate artifact and wait for confirmation.\n2. configuration: Configuration Reference. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. account-tools: Account and Billing Tools. Produce one small intermediate artifact and wait for confirmation.\n5. order-workflow: Order Workflow Tools. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3\n- README.md\n- package.json\n- server.json\n- src/index.ts\n- src/api-client.ts\n- src/types.ts\n- test-mcp.js\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
"items": [],
"status": "待发现 Agent 补证",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Submit podcast orders, check status, and manage webhooks via Barevalue editing API.",
"effort": "安装已验证",
"forks": null,
"icon": "link",
"name": "barevalue-mcp 能力包",
"risk": "需复核",
"slug": "barevalue-mcp",
"stars": null,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/quietnotion/barevalue-mcp Project Manual\n\nGenerated on: 2026-05-24 16:52:56 UTC\n\n## Table of Contents\n\n- [Project Overview](#overview)\n- [Installation Guide](#installation)\n- [Configuration Reference](#configuration)\n- [System Architecture](#system-architecture)\n- [Data Flow](#data-flow)\n- [Account and Billing Tools](#account-tools)\n- [Order Workflow Tools](#order-workflow)\n- [Webhook Management](#webhook-management)\n- [Error Handling and Rate Limits](#error-handling)\n- [Security](#security)\n\n\n\n## Project Overview\n\n### Related Pages\n\nRelated topics: [Installation Guide](#installation), [System Architecture](#system-architecture)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n \n\n# Project Overview\n\n## Introduction\n\n**barevalue-mcp** is a Model Context Protocol (MCP) server that integrates the Barevalue AI podcast editing API into AI assistants like Claude Code. It enables programmatic submission of podcast episodes for AI-powered editing, along with order management, status tracking, and webhook configuration.\n\nThe project is implemented in TypeScript, built with the `@modelcontextprotocol/sdk`, and distributed as an npm package (`barevalue-mcp`). Source: [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Purpose and Scope\n\nThis MCP server serves as a bridge between AI assistants and the Barevalue podcast editing service, providing:\n\n- **Audio Upload**: Upload local audio files via presigned S3 URLs\n- **Order Submission**: Submit podcast episodes for AI editing with customizable options\n- **Status Tracking**: Monitor order progress through various processing stages\n- **Account Management**: Query subscription minutes, credit balances, and pricing\n- **Webhook Integration**: Configure webhooks for order completion notifications\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Architecture\n\nThe project follows a modular architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n A[Claude Code / AI Assistant] -->|MCP Protocol| B[src/index.ts
MCP Server]\n B --> C[src/api-client.ts
API Client]\n C -->|HTTPS| D[Barevalue API
barevalue.com/api/v1]\n C -->|S3 Upload| E[AWS S3]\n \n F[src/types.ts
Type Definitions] --> B\n F --> C\n \n G[package.json] -->|npm dependencies| B\n G -->|@modelcontextprotocol/sdk| C\n```\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|-----------------|\n| MCP Server | `src/index.ts` | Handles MCP protocol communication, tool definitions, and request routing |\n| API Client | `src/api-client.ts` | Encapsulates all Barevalue API calls including file uploads and webhooks |\n| Type Definitions | `src/types.ts` | TypeScript interfaces for inputs, outputs, and API responses |\n\nSource: [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts), [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts), [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Available Tools\n\nThe MCP server exposes the following tools organized by functional area:\n\n### Account & Billing\n\n| Tool | Description |\n|------|-------------|\n| `barevalue_account` | Get account information including credit balance, AI subscription status, and pricing |\n| `barevalue_estimate` | Calculate the cost of an order before submission based on duration |\n\n### Order Workflow\n\n| Tool | Description |\n|------|-------------|\n| `barevalue_upload` | Upload a local audio file; returns `order_id` and `s3_key` for submission |\n| `barevalue_validate` | Pre-check a file from a public URL before submission (external URLs only) |\n| `barevalue_submit` | Submit an uploaded file for AI editing; charges credits |\n| `barevalue_submit_url` | Submit using a public URL instead of uploading |\n| `barevalue_status` | Check order status and retrieve download URLs when complete |\n| `barevalue_list_orders` | List recent orders with pagination support |\n\n### Webhook Management\n\n| Tool | Description |\n|------|-------------|\n| `barevalue_list_webhooks` | List all configured webhooks |\n| `barevalue_create_webhook` | Create a new webhook endpoint |\n| `barevalue_get_webhook` | Get details of a specific webhook |\n| `barevalue_update_webhook` | Update webhook URL, events, or active status |\n| `barevalue_delete_webhook` | Delete a webhook |\n| `barevalue_webhook_rotate_secret` | Rotate webhook secret for security |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Complete Workflow\n\n### Local File Upload Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as barevalue-mcp\n participant BV as Barevalue API\n participant S3 as AWS S3\n \n User->>MCP: barevalue_upload(file_path)\n MCP->>BV: getUploadUrl(filename, contentType)\n BV-->>MCP: presigned S3 URL + s3_key\n MCP->>S3: PUT file to presigned URL\n S3-->>MCP: upload confirmation\n MCP-->>User: order_id, s3_key\n \n User->>MCP: barevalue_submit(order_id, s3_key, ...)\n MCP->>BV: POST /orders/submit\n BV-->>MCP: order confirmation\n MCP-->>User: order submitted\n \n User->>MCP: barevalue_status(order_id)\n loop Until completed\n MCP->>BV: GET /orders/{id}\n BV-->>MCP: status update\n MCP-->>User: current status\n end\n```\n\n### External URL Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as barevalue-mcp\n participant BV as Barevalue API\n \n User->>MCP: barevalue_validate(file_url)\n MCP->>BV: validate file URL\n BV-->>MCP: validation result\n MCP-->>User: speech percentage, music detection\n \n User->>MCP: barevalue_submit_url(file_url, ...)\n MCP->>BV: POST /orders/submit-url\n BV-->>MCP: order confirmation\n MCP-->>User: order submitted\n```\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Supported File Formats\n\nThe system supports the following audio formats for upload:\n\n| Format | MIME Type | Extension |\n|--------|-----------|-----------|\n| MP3 | audio/mpeg | .mp3 |\n| WAV | audio/wav | .wav |\n| M4A | audio/mp4 | .m4a |\n| FLAC | audio/flac | .flac |\n| AAC | audio/aac | .aac |\n| OGG | audio/ogg | .ogg |\n| WMA | audio/x-ms-wma | .wma |\n| AIFF | audio/aiff | .aiff, .aif |\n\n**Maximum file size:** 750MB\n**Minimum speech content:** 10% of audio must contain speech\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts), [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | — | API key starting with `bv_sk_` |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\n### Claude Code Setup\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\nOr for global installation:\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"barevalue-mcp\",\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Order Status Lifecycle\n\nOrders progress through the following states:\n\n```mermaid\nstateDiagram-v2\n [*] --> pending: Submit order\n pending --> downloading: Start processing\n downloading --> transcribing: Download complete\n transcribing --> editing: Transcription done\n editing --> completed: Processing done\n editing --> failed: Error occurred\n completed --> [*]\n failed --> refunded: Refund issued\n refunded --> [*]\n```\n\n### Status Values\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Order received, waiting to start |\n| `downloading` | Fetching audio file |\n| `processing` | General processing |\n| `transcribing` | Converting speech to text |\n| `editing` | AI editing audio |\n| `completed` | Ready for download |\n| `failed` | Processing error |\n| `refunded` | Credits refunded |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Processing Options\n\nWhen submitting an order, the following processing styles are available:\n\n| Style | Description |\n|-------|-------------|\n| `standard` | Default editing level |\n| `minimal` | Light editing, preserves more original content |\n| `aggressive` | Heavy editing, removes more filler |\n\nAdditional options include:\n- `host_names`: Array of host names for transcript speaker labels (max 5)\n- `guest_names`: Array of guest names for transcript speaker labels (max 10)\n- `special_instructions`: Custom editing instructions (max 2000 characters)\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Security\n\nThe implementation includes several security measures:\n\n| Feature | Implementation |\n|---------|----------------|\n| API Key Validation | Keys must start with `bv_sk_` |\n| HTTPS Enforcement | Warns when using non-HTTPS for non-localhost URLs |\n| Error Message Sanitization | Raw API/S3 response data not exposed in errors |\n| Environment Variable Storage | API key never hardcoded in source |\n\n```typescript\n// API key format validation\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Rate Limits\n\n| Limit | Value |\n|-------|-------|\n| Requests per minute | 10 per API key |\n| File upload timeout | 5 minutes |\n| Order processing time | 10-30 minutes typical |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Error Handling\n\nThe API returns structured errors:\n\n```json\n{\n \"error\": \"error_code\",\n \"message\": \"Human readable message\",\n \"statusCode\": 400\n}\n```\n\n### Common Error Codes\n\n| Error Code | Meaning |\n|------------|---------|\n| `invalid_api_key` | API key missing, invalid, or revoked |\n| `insufficient_credits` | Not enough credits or subscription minutes |\n| `validation_failed` | File failed pre-checks |\n| `file_too_large` | File exceeds 750MB limit |\n| `rate_limited` | Too many requests (10/minute) |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Development\n\n### Prerequisites\n\n- Node.js >= 18.0.0\n- npm\n\n### Build Commands\n\n| Command | Action |\n|---------|--------|\n| `npm install` | Install dependencies |\n| `npm run build` | Compile TypeScript to JavaScript |\n| `npm run dev` | Watch mode compilation |\n| `npm start` | Run production server |\n\n### Project Structure\n\n```\nbarevalue-mcp/\n├── src/\n│ ├── index.ts # MCP server implementation\n│ ├── api-client.ts # Barevalue API client\n│ └── types.ts # TypeScript type definitions\n├── package.json # Project metadata and dependencies\n├── server.json # MCP server configuration for registries\n├── README.md # Documentation\n└── dist/ # Compiled output (generated)\n```\n\nSource: [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json), [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Deliverables\n\nEvery completed order includes:\n\n| Deliverable | Description |\n|-------------|-------------|\n| Edited Audio | Audio with filler words, long pauses, and false starts removed |\n| Transcript PDF | Formatted transcript document |\n| Transcript DOCX | Editable Word document transcript |\n| Show Notes | Timestamped show notes |\n| Social Clips | AI-selected highlight clips |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n---\n\n\n\n## Installation Guide\n\n### Related Pages\n\nRelated topics: [Configuration Reference](#configuration), [Project Overview](#overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n \n\n# Installation Guide\n\nThis guide covers all methods for installing and configuring the **barevalue-mcp** server, which provides a Model Context Protocol (MCP) interface for the Barevalue AI podcast editing API.\n\n## Overview\n\nThe barevalue-mcp package is an MCP server that enables AI assistants like Claude Code to interact with the Barevalue podcast editing service. It exposes tools for uploading audio files, submitting editing orders, checking order status, and managing webhooks.\n\nThe server communicates with the Barevalue API over HTTPS, transmits the API key via environment variable, and uses stdio for MCP protocol communication with the host application.\n\n**Source:** [README.md:1-5](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Prerequisites\n\nBefore installation, ensure your environment meets the following requirements:\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Node.js | >= 18.0.0 | Required runtime |\n| npm | Latest stable | For package management |\n| Claude Code | Compatible version | MCP host application |\n| Barevalue Account | Active | With API key access |\n\n**Source:** [package.json:19](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Obtaining an API Key\n\nAn API key is required to authenticate with the Barevalue API. Follow these steps to obtain one:\n\n1. Log in to your [Barevalue account](https://barevalue.com/login)\n2. Navigate to **Settings** → **API Keys**\n3. Click **Create API Key**\n4. Copy the key (starts with `bv_sk_`) — it is only shown once\n\nThe API key format must start with `bv_sk_`. The API client validates this format on initialization and throws an error if the format is incorrect.\n\n**Source:** [README.md:47-55](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n```typescript\n// API key validation in api-client.ts\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\n**Source:** [src/api-client.ts:34-38](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Installation Methods\n\n### Method 1: NPX (Recommended for Most Users)\n\nThe npx method downloads and executes the package without requiring a global installation. This is the simplest approach for most users.\n\nAdd the following configuration to your Claude Code settings file (`~/.claude/settings.json`):\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:1-15](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Method 2: Global Install\n\nFor environments where npx execution is not preferred, install the package globally:\n\n```bash\nnpm install -g barevalue-mcp\n```\n\nThen configure Claude Code with the global command:\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"barevalue-mcp\",\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:20-35](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Configuration\n\n### Claude Code Settings File\n\nThe MCP server configuration is stored in your Claude Code settings file. The default location is:\n\n```\n~/.claude/settings.json\n```\n\n### Configuration Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `command` | string | Yes | Executable command (`npx` or `barevalue-mcp`) |\n| `args` | array | No (npx only) | Arguments for the command (`[\"-y\", \"barevalue-mcp\"]`) |\n| `env` | object | Yes | Environment variables |\n| `env.BAREVALUE_API_KEY` | string | Yes | Your Barevalue API key |\n\n**Source:** [README.md:8-14](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | — | API key starting with `bv_sk_` |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\n**Source:** [README.md:59-62](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\nThe API client reads these environment variables on initialization:\n\n```typescript\nthis.apiKey = process.env.BAREVALUE_API_KEY || '';\nthis.baseUrl = process.env.BAREVALUE_API_URL || 'https://barevalue.com/api/v1';\n```\n\n**Source:** [src/api-client.ts:28-32](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Security Configuration\n\n### HTTPS Enforcement\n\nThe API client enforces HTTPS for non-localhost connections. If the configured base URL uses HTTP, a warning is logged:\n\n```typescript\nconst url = new URL(this.baseUrl);\nconst isHttps = url.protocol === 'https:';\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\n**Source:** [src/api-client.ts:39-45](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### API Key Transmission\n\nAPI keys are transmitted exclusively via the `Authorization` header using Bearer token authentication:\n\n```typescript\nheaders: {\n 'Authorization': `Bearer ${this.apiKey}`,\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'User-Agent': 'barevalue-mcp/1.0.0',\n}\n```\n\n**Source:** [src/api-client.ts:59-65](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Development Installation\n\nFor contributors or those who want to run from source, follow these steps:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the TypeScript project\nnpm run build\n\n# Run in watch mode during development\nnpm run dev\n\n# Start the production server\nnpm start\n```\n\n**Source:** [README.md:142-151](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Build Scripts\n\nThe following npm scripts are defined in package.json:\n\n| Script | Command | Purpose |\n|--------|---------|---------|\n| `build` | `tsc` | Compile TypeScript to JavaScript |\n| `dev` | `tsc --watch` | Watch mode for development |\n| `start` | `node dist/index.js` | Run production server |\n| `prepublishOnly` | `npm run build` | Build before publishing |\n\n**Source:** [package.json:9-14](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n### Dependencies\n\nThe project has the following runtime dependencies:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.0.0 | MCP protocol implementation |\n\n**Source:** [package.json:22-26](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Server Initialization\n\nThe MCP server starts by initializing the SDK with the server name and version:\n\n```typescript\nconst server = new Server(\n {\n name: 'barevalue-mcp',\n version: '1.0.0',\n },\n {\n capabilities: {\n tools: {},\n },\n }\n);\n```\n\n**Source:** [src/index.ts:120-130](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\nThe server registers two request handlers:\n\n1. **ListToolsRequestSchema** — Returns all available MCP tools\n2. **CallToolRequestSchema** — Executes tool calls by name\n\n```typescript\nserver.setRequestHandler(ListToolsRequestSchema, async () => {\n return { tools: TOOLS };\n});\n\nserver.setRequestHandler(CallToolRequestSchema, async (request) => {\n const { name, arguments: args } = request.params;\n return handleToolCall(name, args as Record);\n});\n```\n\n**Source:** [src/index.ts:132-142](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## MCP Server Metadata\n\nThe server.json file defines MCP registry metadata:\n\n```json\n{\n \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n \"name\": \"io.github.quietnotion/barevalue\",\n \"title\": \"Barevalue\",\n \"description\": \"Submit podcast orders, check status, and manage webhooks via Barevalue editing API.\",\n \"version\": \"1.0.3\"\n}\n```\n\n**Source:** [server.json:1-7](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n### NPM Package Metadata\n\n| Field | Value |\n|-------|-------|\n| Package Name | `barevalue-mcp` |\n| Version | `1.0.3` |\n| MCP Name | `io.github.quietnotion/barevalue` |\n| Main Entry | `dist/index.js` |\n| License | MIT |\n\n**Source:** [package.json:1-6](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Installation Flow\n\nThe following diagram illustrates the complete installation and configuration flow:\n\n```mermaid\ngraph TD\n A[Start Installation] --> B{Have Node.js >= 18?}\n B -->|No| C[Install Node.js]\n C --> D\n B -->|Yes| D{Have Barevalue API Key?}\n D -->|No| E[Create API Key at barevalue.com]\n E --> F\n D -->|Yes| F{Choose Installation Method}\n F -->|npx| G[Add MCP Config to settings.json]\n F -->|global| H[Run npm install -g barevalue-mcp]\n H --> I[Add MCP Config to settings.json]\n G --> J[Restart Claude Code]\n I --> J\n J --> K[Server Ready]\n K --> L[Check with barevalue_account tool]\n```\n\n## Available Tools After Installation\n\nOnce installed and configured, the following MCP tools become available:\n\n| Tool | Purpose |\n|------|---------|\n| `barevalue_account` | Get account information and credit balance |\n| `barevalue_estimate` | Calculate order cost before submission |\n| `barevalue_upload` | Upload local audio file |\n| `barevalue_validate` | Validate external URL before submission |\n| `barevalue_submit` | Submit uploaded file for editing |\n| `barevalue_submit_url` | Submit external URL for editing |\n| `barevalue_status` | Check order status |\n| `barevalue_list_orders` | List recent orders |\n| `barevalue_webhook_*` | Webhook management tools |\n\n**Source:** [src/index.ts:54-112](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Verifying Installation\n\nAfter installation, verify the setup by checking your account balance:\n\n```\nUser: Check my Barevalue account balance\n\nClaude: [calls barevalue_account]\n\nYour account information:\n- Balance: X credits\n- Subscription: [plan name]\n- AI Minutes: [available minutes]\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `invalid_api_key` error | Ensure API key starts with `bv_sk_` |\n| Connection timeout | Check network/firewall settings |\n| Server won't start | Verify Node.js >= 18.0.0 |\n| Tools not appearing | Restart Claude Code after config changes |\n\n**Source:** [README.md:114-121](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Support\n\n- **Documentation:** https://barevalue.com/docs/api-v1\n- **Email:** support@barevalue.com\n\n**Source:** [README.md:155-156](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n---\n\n\n\n## Configuration Reference\n\n### Related Pages\n\nRelated topics: [Installation Guide](#installation), [Security](#security)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n \n\n# Configuration Reference\n\nThis page documents all configuration options available for the barevalue-mcp server, including environment variables, Claude Code integration, and runtime settings.\n\n## Overview\n\nThe barevalue-mcp server is a Model Context Protocol (MCP) server that integrates with the Barevalue AI podcast editing API. Configuration is primarily driven through environment variables and JSON configuration files for Claude Code integration.\n\n**Source:** [server.json:1-20](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n## Environment Variables\n\nThe server supports the following environment variables for configuration:\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | - | Your Barevalue API key (must start with `bv_sk_`) |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\n**Source:** [README.md:1-50](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Obtaining an API Key\n\n1. Log in to your [Barevalue account](https://barevalue.com/login)\n2. Navigate to **Settings** → **API Keys**\n3. Click **Create API Key**\n4. Copy the key (starts with `bv_sk_`)\n\n**Important:** The API key is only shown once during creation. Store it securely.\n\n**Source:** [README.md:45-60](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Claude Code Integration\n\n### Configuration File Location\n\nAdd the barevalue-mcp server to your Claude Code settings file at `~/.claude/settings.json`.\n\n**Source:** [README.md:35-45](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Option 1: NPX (Recommended)\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:1-15](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Option 2: Global Install\n\n```bash\nnpm install -g barevalue-mcp\n```\n\nThen configure with the installed command:\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"barevalue-mcp\",\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:20-35](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Server Metadata\n\nThe MCP server announces the following metadata to Claude Code:\n\n| Property | Value |\n|----------|-------|\n| Server Name | `io.github.quietnotion/barevalue` |\n| Display Name | `Barevalue` |\n| Version | `1.0.3` |\n| Transport | `stdio` |\n| Package | `barevalue-mcp` |\n\n**Source:** [server.json:1-25](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n## Available Tools Configuration\n\nThe server exposes the following tools, each with specific input requirements:\n\n**Source:** [src/index.ts:50-150](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n### Tool Input Schemas\n\n#### barevalue_account\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"required\": []\n}\n```\n\n**Source:** [src/index.ts:55-65](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n#### barevalue_estimate\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"duration_minutes\": {\n \"type\": \"number\",\n \"description\": \"Audio duration in minutes (1-300)\"\n }\n },\n \"required\": [\"duration_minutes\"]\n}\n```\n\n**Source:** [src/index.ts:70-85](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n#### barevalue_upload\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"file_path\": {\n \"type\": \"string\",\n \"description\": \"Path to the audio file on your local machine\"\n }\n },\n \"required\": [\"file_path\"]\n}\n```\n\n**Source:** [src/index.ts:90-105](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n#### barevalue_submit\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"order_id\": { \"type\": \"number\" },\n \"s3_key\": { \"type\": \"string\" },\n \"podcast_name\": { \"type\": \"string\" },\n \"episode_name\": { \"type\": \"string\" },\n \"episode_number\": { \"type\": \"string\" },\n \"special_instructions\": { \"type\": \"string\", \"maxLength\": 2000 },\n \"processing_style\": {\n \"type\": \"string\",\n \"enum\": [\"standard\", \"minimal\", \"aggressive\"]\n },\n \"host_names\": { \"type\": \"array\", \"items\": { \"type\": \"string\" }, \"maxItems\": 5 },\n \"guest_names\": { \"type\": \"array\", \"items\": { \"type\": \"string\" }, \"maxItems\": 10 }\n },\n \"required\": [\"order_id\", \"s3_key\", \"podcast_name\", \"episode_name\"]\n}\n```\n\n**Source:** [src/types.ts:1-30](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Security Configuration\n\n### API Key Validation\n\nThe server validates API key format on initialization:\n\n```typescript\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\n**Source:** [src/api-client.ts:20-30](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### HTTPS Enforcement\n\nNon-HTTPS connections are blocked for non-localhost URLs with a warning:\n\n```typescript\nconst isHttps = url.protocol === 'https:';\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\n**Source:** [src/api-client.ts:25-35](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Sensitive Directory Protection\n\nFile uploads are blocked from sensitive system directories:\n\n```typescript\nconst sensitivePatterns = [\n /^\\/etc\\//,\n /^\\/var\\//,\n /^\\/usr\\//,\n /^\\/root\\//,\n /[/\\\\]\\.ssh[/\\\\]/,\n /[/\\\\]\\.aws[/\\\\]/,\n /[/\\\\]\\.gnupg[/\\\\]/,\n /[/\\\\]\\.config[/\\\\]/,\n /[/\\\\]\\.env$/,\n /[/\\\\]\\.env\\./,\n];\n```\n\n**Source:** [src/api-client.ts:150-165](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## File Upload Configuration\n\n### Supported Formats\n\n| Extension | MIME Type |\n|-----------|-----------|\n| `.mp3` | audio/mpeg |\n| `.wav` | audio/wav |\n| `.m4a` | audio/mp4 |\n| `.flac` | audio/flac |\n| `.aac` | audio/aac |\n| `.ogg` | audio/ogg |\n| `.wma` | audio/x-ms-wma |\n| `.aiff` / `.aif` | audio/aiff |\n\n**Source:** [src/api-client.ts:65-85](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### File Size Limits\n\n| Limit | Value |\n|-------|-------|\n| Maximum file size | 750 MB |\n| Upload timeout | 5 minutes |\n\n**Source:** [README.md:100-110](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Presigned URL Expiration\n\nS3 presigned URLs expire after **30 minutes** for security.\n\n**Source:** [README.md:130-135](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Rate Limiting\n\n| Limit | Value |\n|-------|-------|\n| Requests per minute | 10 per API key |\n| File upload timeout | 5 minutes |\n| Order processing | 10-30 minutes typical |\n\n**Source:** [README.md:100-115](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Error Handling Configuration\n\n### Error Response Structure\n\nAll API errors follow a standardized format:\n\n```json\n{\n \"error\": \"error_code\",\n \"message\": \"Human readable description\",\n \"statusCode\": 400\n}\n```\n\n**Source:** [README.md:140-155](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Error Codes\n\n| Code | Description |\n|------|-------------|\n| `invalid_api_key` | API key is missing, invalid, or revoked |\n| `insufficient_credits` | Not enough credits or subscription minutes |\n| `validation_failed` | File failed pre-checks (not enough speech, music detected) |\n| `file_too_large` | File exceeds 750MB limit |\n| `rate_limited` | Too many requests (limit: 10/minute) |\n\n**Source:** [README.md:155-170](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Development Configuration\n\n### Local Development Setup\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Watch mode (auto-rebuild on changes)\nnpm run dev\n\n# Start production server\nnpm start\n```\n\n**Source:** [README.md:175-190](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Package Configuration\n\n| Property | Value |\n|----------|-------|\n| Package Name | barevalue-mcp |\n| Version | 1.0.3 |\n| Entry Point | dist/index.js |\n| CLI Bin | barevalue-mcp |\n| Node Requirement | >=18.0.0 |\n\n**Source:** [package.json:1-20](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Configuration Flow\n\n```mermaid\ngraph TD\n A[Start] --> B{API Key Set?}\n B -->|No| C[Error: API key required]\n B -->|Yes| D{Valid Format bv_sk_*?}\n D -->|No| E[Error: Invalid format]\n D -->|Yes| F{HTTPS URL?}\n F -->|No| G[Check: localhost?]\n G -->|No| H[Warning: Insecure transmission]\n G -->|Yes| I[Allow HTTP]\n H --> J[Initialize API Client]\n I --> J\n F -->|Yes| J\n J --> K[Connect via StdioTransport]\n K --> L[Server Ready]\n```\n\n## Quick Reference\n\n### Minimal Configuration (NPX)\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n### Environment Variables Summary\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | - | API key starting with `bv_sk_` |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Custom API endpoint |\n\n### Node.js Requirements\n\n- **Minimum version:** Node.js 18.0.0\n- **Recommended:** Latest LTS version\n\n---\n\n\n\n## System Architecture\n\n### Related Pages\n\nRelated topics: [Data Flow](#data-flow), [Project Overview](#overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n \n\n# System Architecture\n\n## Overview\n\nThe barevalue-mcp is a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with the Barevalue podcast editing API. It provides a bridge between MCP-compatible clients and the Barevalue backend services, allowing users to submit podcast files for AI editing, monitor order status, and manage webhooks through natural language commands.\n\nThe architecture follows a client-server pattern where the MCP server acts as an intermediary, translating MCP tool calls into HTTP API requests and formatting responses for consumption by the AI assistant.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"MCP Client (Claude Code)\"\n A[User Request]\n end\n \n subgraph \"Barevalue MCP Server\"\n B[MCP Server]\n C[Tool Router]\n D[Data Sanitizer]\n E[API Client]\n end\n \n subgraph \"External Services\"\n F[Barevalue API]\n G[AWS S3]\n end\n \n A --> B\n B --> C\n C --> D\n C --> E\n E --> F\n E --> G\n```\n\n## Component Architecture\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| MCP Server | `src/index.ts` | Entry point, request routing, tool definitions |\n| API Client | `src/api-client.ts` | HTTP communication with Barevalue API |\n| Type Definitions | `src/types.ts` | TypeScript interfaces for all data models |\n| Tool Registry | `src/index.ts` | Tool definitions and input schema validation |\n| Error Handler | `src/api-client.ts` | Custom error class and error handling |\n\n### MCP Server (`src/index.ts`)\n\nThe MCP server is built using the `@modelcontextprotocol/sdk` package and implements the server-side of the MCP protocol. It handles two primary request types: `ListToolsRequestSchema` and `CallToolRequestSchema`.\n\n**Server Initialization** (lines 1-100):\n```typescript\nconst server = new Server(\n {\n name: 'barevalue-mcp',\n version: '1.0.0',\n },\n {\n capabilities: {\n tools: {},\n },\n }\n);\n```\n\n**Request Handling Flow:**\n\n```mermaid\ngraph TD\n A[Incoming Request] --> B{Route to Handler}\n B -->|ListTools| C[Return Tool Definitions]\n B -->|CallTool| D[Extract Tool Name]\n D --> E[Extract Arguments]\n E --> F[Validate Input Schema]\n F -->|Invalid| G[Return Error]\n F -->|Valid| H[Execute Tool Handler]\n H --> I[Sanitize Output]\n I --> J[Return MCP Response]\n```\n\nThe server defines 12 tools organized into three functional categories:\n\n1. **Account & Billing Tools**\n - `barevalue_account` - Get account information\n - `barevalue_estimate` - Calculate order cost\n\n2. **Order Workflow Tools**\n - `barevalue_upload` - Upload local files\n - `barevalue_validate` - Validate external URLs\n - `barevalue_submit` - Submit for editing\n - `barevalue_submit_url` - Submit via URL\n - `barevalue_status` - Check order status\n - `barevalue_list_orders` - List recent orders\n\n3. **Webhook Management Tools**\n - `barevalue_list_webhooks` - List webhooks\n - `barevalue_create_webhook` - Create webhook\n - `barevalue_delete_webhook` - Delete webhook\n - `barevalue_webhook_rotate_secret` - Rotate webhook secret\n\n### API Client (`src/api-client.ts`)\n\nThe `BarevalueApiClient` class encapsulates all HTTP communication with the Barevalue API. It uses native Node.js `http` and `https` modules for making requests.\n\n**Class Structure:**\n\n```typescript\nexport class BarevalueApiClient {\n private readonly apiKey: string;\n private readonly baseUrl: string;\n private readonly timeout: number;\n\n constructor(apiKey: string, baseUrl?: string, timeout?: number) {\n // Initialization\n }\n \n // Request methods\n private async request(method: string, endpoint: string, body?: Record): Promise\n \n // Order methods\n async getAccount(): Promise\n async estimateCost(durationMinutes: number): Promise\n async getUploadUrl(): Promise\n async uploadFile(uploadUrl: string, filePath: string): Promise\n async validateUrl(fileUrl: string): Promise\n async submitOrder(params: SubmitParams): Promise\n async submitExternalUrl(params: SubmitUrlParams): Promise\n async getOrderStatus(orderId: number): Promise\n async listOrders(params?: ListOrdersParams): Promise\n \n // Webhook methods\n async listWebhooks(): Promise\n async createWebhook(url: string, events: string[]): Promise\n async getWebhook(webhookId: number): Promise\n async updateWebhook(webhookId: number, updates: WebhookUpdates): Promise\n async deleteWebhook(webhookId: number): Promise<{ success: boolean }>\n async rotateWebhookSecret(webhookId: number): Promise\n}\n```\n\n**HTTP Request Flow:**\n\n```mermaid\nsequenceDiagram\n participant Tool as Tool Handler\n participant Client as API Client\n participant API as Barevalue API\n participant S3 as AWS S3\n\n Tool->>Client: call method(params)\n Client->>Client: validateApiKey()\n Client->>Client: buildRequest()\n Client->>API: HTTP Request\n API-->>Client: JSON Response\n Client->>Client: checkStatusCode()\n Client-->>Tool: parsed response\n Note over Tool,Client: For uploads\n Tool->>Client: uploadFile()\n Client->>S3: Presigned URL PUT\n S3-->>Client: Upload Complete\n```\n\n**Security Features** (lines 30-40):\n\nThe API client implements several security measures:\n\n1. **API Key Validation** - Verifies keys start with `bv_sk_`\n2. **HTTPS Enforcement** - Warns if using non-HTTPS for non-localhost URLs\n3. **Timeout Protection** - Configurable request timeout (default: 5 minutes)\n4. **Error Sanitization** - Raw API responses are not exposed in error messages\n\n```typescript\n// Security: Don't expose S3 error response data\nreject(new Error(`S3 upload failed with status ${res.statusCode}`));\n\n// Security: Don't expose raw API response data in error messages\nreject(new Error('Failed to parse API response'));\n```\n\n### Error Handling Architecture\n\nThe `BarevalueApiError` class provides structured error handling:\n\n```typescript\nexport class BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n}\n```\n\n**Error Response Format:**\n\n| Error Code | Status | Meaning |\n|------------|--------|---------|\n| `invalid_api_key` | 401 | API key is missing, invalid, or revoked |\n| `insufficient_credits` | 402 | Not enough credits or subscription minutes |\n| `validation_failed` | 400 | File failed pre-checks |\n| `file_too_large` | 413 | File exceeds 750MB limit |\n| `rate_limited` | 429 | Too many requests (10/minute limit) |\n\n## Data Flow Architecture\n\n### Order Submission Flow\n\n```mermaid\ngraph LR\n A[User Request] --> B[Upload Local File]\n B --> C[Get Presigned URL]\n C --> D[Upload to S3]\n D --> E[Submit Order]\n E --> F[Get Order ID]\n F --> G[Poll Status]\n G --> H[Return Results]\n```\n\n### Complete Order Workflow\n\n```mermaid\nstateDiagram-v2\n [*] --> Uploaded: barevalue_upload\n Uploaded --> Validating: barevalue_validate (optional)\n Uploaded --> Submitting: barevalue_submit\n Validating --> Submitting: validation passed\n Validating --> [*]: validation failed\n Submitting --> Processing: order created\n Processing --> Downloading: file download\n Downloading --> Transcribing: download complete\n Transcribing --> Editing: transcription complete\n Editing --> Completed: editing finished\n Completed --> [*]\n Processing --> Failed: error occurred\n Failed --> Refunded: refund processed\n Refunded --> [*]\n```\n\n## Type System Architecture\n\n### Response Types (`src/types.ts`)\n\nThe type system is organized into response types and input types:\n\n**Account Information:**\n```typescript\ninterface AccountInfo {\n user: {\n id: number;\n email: string;\n name: string | null;\n is_verified: boolean;\n locale: string;\n };\n credits: {\n balance: number;\n currency: string;\n };\n ai_subscription: {\n tier: string | null;\n status: string | null;\n minutes_limit: number | null;\n minutes_used: number | null;\n minutes_remaining: number | null;\n period_end: string | null;\n pending_tier: string | null;\n } | null;\n ai_bonus_minutes: {\n balance: number;\n expires_at: string | null;\n };\n pricing: {\n audio_per_minute: number;\n currency: string;\n };\n}\n```\n\n**Order Status:**\n```typescript\ninterface OrderStatus {\n order_id: number;\n status: 'pending' | 'downloading' | 'processing' | 'transcribing' | 'editing' | 'completed' | 'failed' | 'refunded';\n created_at: string;\n updated_at: string;\n // Present when completed\n edited_audio_url?: string;\n transcript_pdf_url?: string;\n transcript_docx_url?: string;\n show_notes_url?: string;\n}\n```\n\n### Tool Input Schemas\n\nEach tool has a corresponding input schema defined in the tool definition:\n\n| Tool | Required Parameters | Optional Parameters |\n|------|---------------------|---------------------|\n| `barevalue_estimate` | `duration_minutes` | - |\n| `barevalue_upload` | `file_path` | `filename` |\n| `barevalue_validate` | `file_url` | - |\n| `barevalue_submit` | `order_id`, `s3_key`, `podcast_name`, `episode_name` | `episode_number`, `special_instructions`, `processing_style`, `host_names`, `guest_names` |\n| `barevalue_submit_url` | `file_url`, `podcast_name`, `episode_name` | `episode_number`, `special_instructions`, `processing_style`, `host_names`, `guest_names` |\n| `barevalue_status` | `order_id` | - |\n| `barevalue_list_orders` | - | `page`, `per_page`, `status` |\n| `barevalue_create_webhook` | `url`, `events` | - |\n| `barevalue_delete_webhook` | `webhook_id` | - |\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | - | API key (starts with `bv_sk_`) |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\n### MCP Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n## Data Sanitization\n\nThe server implements input sanitization to prevent injection attacks. The `sanitizeString` function handles string escaping:\n\n```typescript\nfunction sanitizeString(input: unknown): string {\n if (typeof input !== 'string') return '';\n return input\n .replace(/[<>]/g, '')\n .slice(0, 10000);\n}\n```\n\nThis sanitization is applied to:\n- Error messages\n- Tool output data\n- Key-value pairs in objects\n\n## Transport Layer\n\nThe MCP server uses STDIO transport for communication with the client:\n\n```typescript\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\nThis architecture allows:\n- Standard input/output based communication\n- No network configuration required\n- Easy integration with CLI tools and AI assistants\n\n## Build and Development\n\n| Command | Purpose |\n|---------|---------|\n| `npm install` | Install dependencies |\n| `npm run build` | Compile TypeScript to JavaScript |\n| `npm run dev` | Watch mode compilation |\n| `npm start` | Run compiled server |\n| `npm run prepublishOnly` | Build before npm publish |\n\nSource: [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Summary\n\nThe barevalue-mcp system architecture consists of three primary layers:\n\n1. **Presentation Layer** - MCP tool definitions and request handling in `src/index.ts`\n2. **Business Logic Layer** - API client with security features and error handling in `src/api-client.ts`\n3. **Type Layer** - TypeScript interfaces for type safety in `src/types.ts`\n\nThe architecture prioritizes security through API key validation, HTTPS enforcement, and response sanitization, while maintaining a clean separation of concerns that facilitates testing and maintenance.\n\n---\n\n\n\n## Data Flow\n\n### Related Pages\n\nRelated topics: [System Architecture](#system-architecture), [Order Workflow Tools](#order-workflow)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n \n\n# Data Flow\n\nThis document describes the data flow architecture of the barevalue-mcp server, covering how data moves from the client through the MCP protocol layer, through the API client, and ultimately to the Barevalue API.\n\n## Overview\n\nThe barevalue-mcp server implements a Model Context Protocol (MCP) server that acts as a bridge between AI assistants (like Claude Code) and the Barevalue podcast editing API. Data flows through several distinct layers, each with specific responsibilities for validation, transformation, and security. Source: [src/index.ts:1-200](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Architecture Layers\n\nThe data flow consists of four primary layers:\n\n| Layer | Component | Responsibility |\n|-------|-----------|----------------|\n| Transport | StdioServerTransport | JSON-RPC communication with MCP client |\n| Protocol | Server (MCP SDK) | Request routing and capability negotiation |\n| Application | Tool Handlers | Business logic and data transformation |\n| External | ApiClient | HTTP communication with Barevalue API |\n\nSource: [src/index.ts:280-320](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Request Flow\n\n```mermaid\ngraph TD\n A[\"MCP Client
(Claude Code)\"] --> B[\"StdioServerTransport\"]\n B --> C[\"Server
MCP Protocol Handler\"]\n C --> D[\"handleToolCall
Router\"]\n D --> E1[\"Account Handler\"]\n D --> E2[\"Estimate Handler\"]\n D --> E3[\"Upload Handler\"]\n D --> E4[\"Submit Handler\"]\n D --> E5[\"Status Handler\"]\n D --> E6[\"Webhook Handler\"]\n E1 --> F[\"ApiClient\"]\n E2 --> F\n E3 --> F\n E4 --> F\n E5 --> F\n E6 --> F\n F --> G[\"Barevalue API\"]\n G --> F\n F --> H[\"sanitizeData\"]\n H --> I[\"MCP Response\"]\n I --> B\n B --> A\n```\n\n### Step-by-Step Data Flow\n\n1. **Client Request**: The MCP client sends a JSON-RPC request via stdio containing the tool name and arguments.\n2. **Transport Reception**: The StdioServerTransport receives the raw JSON-RPC message.\n3. **Protocol Parsing**: The MCP Server parses the request and extracts tool name and parameters.\n4. **Routing**: The `handleToolCall` function routes to the appropriate handler based on the tool name.\n5. **Handler Processing**: Each handler invokes the corresponding ApiClient method.\n6. **API Communication**: The ApiClient makes HTTP requests to the Barevalue API.\n7. **Data Sanitization**: All responses pass through `sanitizeData` before being returned.\n8. **Response Serialization**: The server serializes the response as JSON-RPC and sends it back.\n\nSource: [src/index.ts:220-280](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Input Data Sanitization\n\nAll incoming data undergoes sanitization before processing. The `sanitizeData` function recursively processes data structures to prevent injection attacks and ensure consistent formatting.\n\n```typescript\nfunction sanitizeData(data: unknown): unknown {\n if (typeof data === 'string') {\n return sanitizeString(data);\n }\n if (Array.isArray(data)) {\n return data.map(sanitizeData);\n }\n if (data !== null && typeof data === 'object') {\n const result: Record = {};\n for (const [key, value] of Object.entries(data)) {\n result[sanitizeString(key)] = sanitizeData(value);\n }\n return result;\n }\n return data;\n}\n```\n\nSource: [src/index.ts:10-26](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\nThe sanitization process:\n- Recursively processes all strings using `sanitizeString`\n- Maps over arrays applying sanitization to each element\n- Creates new objects with sanitized keys and values\n- Returns primitives unchanged\n\n## API Client Data Flow\n\nThe ApiClient class manages all external API communication. It handles authentication, request construction, response parsing, and error handling.\n\n```mermaid\ngraph LR\n A[\"Tool Handler\"] --> B[\"ApiClient.request\"]\n B --> C[\"URL Construction\"]\n C --> D[\"HTTPS Request\"]\n D --> E[\"Response Parser\"]\n E -->|Success| F[\"Typed Response\"]\n E -->|Error| G[\"BarevalueApiError\"]\n F --> H[\"Tool Handler\"]\n G --> H\n```\n\n### Request Construction\n\nThe `request` method constructs HTTP requests with the following components:\n\n| Component | Value | Purpose |\n|-----------|-------|---------|\n| Authorization | `Bearer ${apiKey}` | API authentication |\n| Content-Type | `application/json` | Request body format |\n| Accept | `application/json` | Response format |\n| User-Agent | `barevalue-mcp/1.0.0` | Client identification |\n| Timeout | 30000ms | Request timeout |\n\nSource: [src/api-client.ts:120-150](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### URL Resolution\n\nThe base URL defaults to `https://barevalue.com/api/v1` but can be overridden via the `BAREVALUE_API_URL` environment variable. The request method constructs the full URL by appending the endpoint:\n\n```typescript\nconst cleanEndpoint = endpoint.startsWith('/') ? endpoint.slice(1) : endpoint;\nconst cleanBase = this.baseUrl.endsWith('/') ? this.baseUrl : this.baseUrl + '/';\nconst fullUrl = cleanBase + cleanEndpoint;\n```\n\nSource: [src/api-client.ts:95-105](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## File Upload Flow\n\nFile uploads follow a two-phase process: first obtaining a presigned URL, then uploading directly to S3.\n\n```mermaid\nsequenceDiagram\n participant C as Tool Handler\n participant AC as ApiClient\n participant BV as Barevalue API\n participant S3 as AWS S3\n\n C->>AC: uploadFile(filePath)\n AC->>BV\nError with Openai API: output new_sensitive (1027)\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n\n\n## Account and Billing Tools\n\n### Related Pages\n\nRelated topics: [Order Workflow Tools](#order-workflow), [Error Handling and Rate Limits](#error-handling)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n \n\n# Account and Billing Tools\n\nThe Account and Billing Tools constitute the foundational layer of the Barevalue MCP server, providing essential functionality for monitoring account resources, checking credit balances, and estimating order costs before submission. These tools enable AI assistants to make informed decisions about podcast editing orders by providing real-time visibility into account status and available resources.\n\n## Overview\n\nThe Account and Billing module consists of two primary MCP tools that interact with the Barevalue API's account endpoints:\n\n| Tool Name | Purpose | API Endpoint |\n|-----------|---------|--------------|\n| `barevalue_account` | Retrieve comprehensive account information including balance and subscription status | `GET /account` |\n| `barevalue_estimate` | Calculate cost breakdown for a potential order based on audio duration | `POST /orders/estimate` |\n\nThese tools are designed to support the typical workflow pattern where an AI assistant checks available resources before uploading and submitting podcast files for AI editing. By providing cost estimation before submission, users can avoid the `insufficient_credits` error that results from attempting orders without adequate resources.\n\n## Architecture\n\nThe Account and Billing module follows a layered architecture where MCP tool definitions in the presentation layer delegate to the API client layer, which handles HTTP communication with the Barevalue API.\n\n```mermaid\ngraph TD\n A[MCP Client
e.g., Claude Code] --> B[Tool Handler
src/index.ts]\n B --> C[API Client
src/api-client.ts]\n C --> D[Barevalue API
barevalue.com/api/v1]\n \n B --> B1[barevalue_account tool]\n B --> B2[barevalue_estimate tool]\n \n C --> C1[getAccount method]\n C --> C2[estimate method]\n \n D --> D1[/account endpoint]\n D --> D2[/orders/estimate endpoint]\n \n B1 -->|\"Empty input schema\"| B\n B2 -->|\"duration_minutes\"| B\n```\n\n### Data Flow\n\nThe following sequence illustrates how account information flows through the system when an AI assistant queries the account status:\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as MCP Server\n participant APIClient as API Client\n participant API as Barevalue API\n \n Client->>Server: barevalue_account()\n Server->>APIClient: getAccount()\n APIClient->>API: GET /account
Authorization: Bearer \n API-->>APIClient: AccountInfo JSON\n APIClient-->>Server: AccountInfo object\n Server-->>Client: AccountInfo JSON\n```\n\n## Tool Specifications\n\n### barevalue_account\n\nThe `barevalue_account` tool retrieves complete account information for the authenticated user, including credit balances, AI subscription details, and current pricing information.\n\n#### Input Schema\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"required\": []\n}\n```\n\nThis tool accepts no input parameters. The authenticated user is determined by the `BAREVALUE_API_KEY` environment variable configured during server setup. Source: [src/index.ts:30-38](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts#L30-L38)\n\n#### Return Type\n\nThe tool returns an `AccountInfo` object containing the following structure:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `user` | `User` | User profile information |\n| `credits` | `Credits` | Standard credit balance |\n| `ai_subscription` | `AISubscription \\| null` | AI editing subscription details |\n| `ai_bonus_minutes` | `AIBonusMinutes` | Promotional bonus minutes balance |\n| `pricing` | `Pricing` | Current pricing information |\n\nSource: [src/types.ts:9-38](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts#L9-L38)\n\n#### User Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `number` | Unique user identifier |\n| `email` | `string` | User's email address |\n| `name` | `string \\| null` | Display name if set |\n| `is_verified` | `boolean` | Whether the account is verified |\n| `locale` | `string` | User's preferred locale |\n\n#### Credits Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `balance` | `number` | Available credit amount |\n| `currency` | `string` | Currency code (e.g., \"USD\") |\n\n#### AI Subscription Object\n\nThe `ai_subscription` field may be `null` for users without an AI subscription. When present, it contains:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `tier` | `string \\| null` | Subscription tier name |\n| `status` | `string \\| null` | Subscription status |\n| `minutes_limit` | `number \\| null` | Monthly minute allowance |\n| `minutes_used` | `number \\| null` | Minutes consumed this period |\n| `minutes_remaining` | `number \\| null` | Minutes left in current period |\n| `period_end` | `string \\| null` | ISO 8601 end date of billing period |\n| `pending_tier` | `string \\| null` | Upcoming tier if upgrade is scheduled |\n\n#### AI Bonus Minutes Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `balance` | `number` | Available bonus minutes |\n| `expires_at` | `string \\| null` | Expiration date for bonus minutes |\n\n#### Pricing Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `audio_per_minute` | `number` | Cost per audio minute (for informational purposes) |\n| `currency` | `string` | Currency code |\n\n### barevalue_estimate\n\nThe `barevalue_estimate` tool calculates a detailed cost breakdown for a potential podcast editing order based on the audio duration. This tool is essential for preventing `insufficient_credits` errors before submitting orders.\n\n#### Input Schema\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"duration_minutes\": {\n \"type\": \"number\",\n \"description\": \"Audio duration in minutes (1-300)\"\n }\n },\n \"required\": [\"duration_minutes\"]\n}\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `duration_minutes` | `number` | Yes | Duration of the audio file in minutes, between 1 and 300 |\n\nSource: [src/index.ts:40-53](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts#L40-L53)\n\n#### Return Type\n\nThe tool returns an `EstimateResponse` object:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `duration_minutes` | `number` | The requested duration |\n| `can_afford` | `boolean` | Whether the user can afford the order |\n| `minutes_available` | `MinutesBreakdown` | Available minutes by category |\n| `minutes_applied` | `MinutesBreakdown` | Minutes that will be consumed |\n| `minutes_remaining_after` | `number` | Total minutes remaining after order |\n| `subscription_tier` | `string` | Current subscription tier name |\n\nSource: [src/types.ts:40-66](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts#L40-L66)\n\n#### Conditional Fields\n\nThe following fields are only present when `can_afford` is `false`:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `minutes_short` | `number` | How many minutes short the user is |\n| `upgrade_required` | `boolean` | Whether an upgrade is needed |\n| `message` | `string` | Human-readable explanation |\n| `available_upgrades` | `UpgradeOption[]` | Available subscription upgrades |\n\n#### Minutes Breakdown Object\n\nBoth `minutes_available` and `minutes_applied` contain:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `bonus` | `number` | AI bonus minutes |\n| `student` | `number` | Student plan minutes (if applicable) |\n| `subscription` | `number` | Subscription minutes |\n| `total` | `number` | Total minutes |\n\n#### Upgrade Option Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `string` | Plan name |\n| `minutes_limit` | `number` | Monthly minute allowance |\n| `price_monthly` | `number` | Monthly price |\n\n## API Client Implementation\n\nThe API client layer provides the underlying HTTP communication for the Account and Billing tools. The implementation is located in `src/api-client.ts`.\n\n### getAccount Method\n\n```typescript\nasync getAccount(): Promise {\n return this.request('GET', '/account');\n}\n```\n\nThe `getAccount` method performs a simple GET request to the `/account` endpoint, passing the Bearer token authentication header. Source: [src/api-client.ts:180-183](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L180-L183)\n\n### estimate Method\n\n```typescript\nasync estimate(durationMinutes: number): Promise {\n return this.request('POST', '/orders/estimate', {\n duration_minutes: durationMinutes,\n });\n}\n```\n\nThe `estimate` method performs a POST request to the `/orders/estimate` endpoint with the duration parameter in the request body. Source: [src/api-client.ts:186-192](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L186-L192)\n\n### HTTP Request Handling\n\nThe API client uses Node.js built-in `http` and `https` modules for HTTP communication. Key security features include:\n\n- Bearer token authentication via the `Authorization` header\n- HTTPS enforcement warning for non-localhost connections\n- JSON request/response handling\n- Configurable request timeout (default 5 minutes)\n- Comprehensive error handling with structured `BarevalueApiError` responses\n\n## Usage Patterns\n\n### Pre-Order Balance Check\n\nThe most common usage pattern involves checking the account balance before submitting a podcast for editing:\n\n```mermaid\ngraph TD\n A[Start] --> B[Call barevalue_account]\n B --> C{Response received}\n C -->|Success| D[Check credits and minutes]\n C -->|Failure| E[Handle error]\n D --> F{Sufficient resources?}\n F -->|Yes| G[Proceed to upload]\n F -->|No| H[Inform user]\n H --> I[Suggest upgrade or wait]\n G --> J[Upload file]\n J --> K[Submit order]\n```\n\n### Pre-Order Cost Estimation\n\nBefore uploading a file, users can estimate costs to understand the resource consumption:\n\n```\nUser: I want to edit a 45-minute podcast episode\n\nClaude: [calls barevalue_estimate duration_minutes=45]\n\nBased on your 45-minute episode:\n- Minutes to be used: 45\n- Available: 120 minutes (bonus + subscription)\n- Remaining after: 75 minutes\n- Can afford: Yes\n```\n\n### Workflow with Insufficient Credits\n\nWhen a user lacks sufficient resources, the estimation provides upgrade options:\n\n```\nUser: Edit this podcast: /path/to/episode.mp3\n\nClaude: [calls barevalue_estimate duration_minutes=32]\n\nEstimate Result:\n- Minutes required: 32\n- Minutes available: 18\n- Short by: 14 minutes\n\nAvailable upgrades:\n| Plan | Monthly Minutes | Price |\n|------|-----------------|-------|\n| Pro | 60 | $29/mo |\n| Team | 150 | $79/mo |\n\nWould you like me to help you upgrade your plan first?\n```\n\n## Rate Limits and Security\n\n### Rate Limits\n\nThe Account and Billing tools share the global rate limit of the MCP server:\n\n| Limit | Value |\n|-------|-------|\n| Requests per minute | 10 |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Security Considerations\n\nThe Account and Billing module implements several security measures:\n\n1. **API Key Protection**: The API key is transmitted exclusively via the `Authorization` header using the Bearer token scheme. Source: [src/api-client.ts:63-69](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L63-L69)\n\n2. **Environment Variable Storage**: API keys must be stored in environment variables, never hardcoded. This is enforced through the server configuration in `server.json`:\n\n```json\n{\n \"environmentVariables\": [\n {\n \"name\": \"BAREVALUE_API_KEY\",\n \"isSecret\": true,\n \"format\": \"string\"\n }\n ]\n}\n```\n\nSource: [server.json:17-24](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json#L17-L24)\n\n3. **HTTPS Enforcement**: The API client warns users when connecting over non-HTTPS connections (except localhost for development):\n\n```typescript\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\nSource: [src/api-client.ts:42-45](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L42-L45)\n\n## Error Handling\n\nThe Account and Billing tools may encounter the following errors:\n\n| Error Code | Description | HTTP Status |\n|------------|-------------|-------------|\n| `invalid_api_key` | API key is missing, invalid, or revoked | 401/403 |\n| `rate_limited` | Too many requests (limit: 10/minute) | 429 |\n| `server_error` | Internal server error | 500 |\n\nErrors are wrapped in the custom `BarevalueApiError` class, which provides structured error information:\n\n```typescript\nexport class BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n}\n```\n\nSource: [src/api-client.ts:238-248](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L238-L248)\n\n## Configuration\n\n### Required Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BAREVALUE_API_KEY` | Yes | Barevalue API key (starts with `bv_sk_`) |\n| `BAREVALUE_API_URL` | No | Override API base URL (default: `https://barevalue.com/api/v1`) |\n\n### MCP Server Configuration\n\nTo use the Account and Billing tools, configure the MCP server in your Claude Code settings (`~/.claude/settings.json`):\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Summary\n\nThe Account and Billing Tools provide essential functionality for managing Barevalue resources through the MCP interface:\n\n| Component | Description |\n|-----------|-------------|\n| `barevalue_account` | Retrieves full account information including user details, credit balance, AI subscription status, bonus minutes, and pricing |\n| `barevalue_estimate` | Calculates cost breakdown for orders, showing available minutes, consumption by category, and potential upgrade options |\n| API Client | Handles HTTP communication with Bearer token authentication, HTTPS enforcement, and structured error handling |\n\nThese tools enable AI assistants to perform informed resource management, preventing failed orders due to insufficient credits and providing users with clear visibility into their account status and consumption patterns.\n\n---\n\n\n\n## Order Workflow Tools\n\n### Related Pages\n\nRelated topics: [Account and Billing Tools](#account-tools), [Data Flow](#data-flow), [Webhook Management](#webhook-management)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n \n\n# Order Workflow Tools\n\n## Overview\n\nThe Order Workflow Tools provide the core functionality for submitting podcast audio files to the Barevalue AI editing service and monitoring their processing status. These tools form the primary interface for the audio editing pipeline, enabling users to upload local files, validate external URLs, submit orders for processing, and track completion.\n\nThe workflow consists of six primary MCP tools that handle the complete lifecycle of an editing order from initial upload through final delivery. Each tool corresponds to specific API endpoints in the underlying `BarevalueApiClient` class, which manages HTTP communication with the Barevalue API.\n\nSource: [src/index.ts:36-170](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User] --> B[barevalue_upload
or barevalue_validate]\n B --> C{File Source}\n C -->|Local File| D[Get Presigned S3 URL]\n C -->|External URL| E[Validate File]\n D --> F[Upload to S3]\n E --> G{Validation Result}\n G -->|Pass| H[barevalue_submit
or barevalue_submit_url]\n G -->|Fail| Z[Error: validation_failed]\n F --> H\n H --> I[Order Created
Status: pending]\n I --> J[barevalue_status]\n J --> K{Processing State}\n K -->|pending| L[Downloading]\n K -->|processing| M[Transcribing
+ Editing]\n K -->|completed| N[Deliverables Ready]\n K -->|failed| O[Error Response]\n N --> P[barevalue_list_orders
for history]\n```\n\nThe `BarevalueApiClient` class encapsulates all API interactions and provides type-safe methods for each endpoint. It handles authentication via Bearer tokens, manages request timeouts, and implements error handling with custom `BarevalueApiError` exceptions.\n\nSource: [src/api-client.ts:1-80](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## File Upload Tool\n\n### barevalue_upload\n\nUploads a local audio file to S3 storage using a presigned URL mechanism. This tool handles the two-step upload process: first requesting a presigned URL from the API, then uploading the file directly to S3.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `file_path` | `string` | Yes | Absolute path to the local audio file |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `order_id` | `number` | Numeric identifier for tracking |\n| `s3_key` | `string` | S3 storage key for submission |\n| `upload_url` | `string` | Presigned URL for direct upload |\n\n**Supported Formats:** mp3, wav, m4a, flac, aac, ogg\n\n**Maximum File Size:** 750MB\n\nSource: [src/index.ts:66-80](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\nSource: [src/api-client.ts:145-180](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Content Type Mapping\n\nThe client automatically detects file format from extension and sets appropriate MIME types:\n\n| Extension | Content-Type |\n|-----------|--------------|\n| `.mp3` | audio/mpeg |\n| `.wav` | audio/wav |\n| `.m4a` | audio/mp4 |\n| `.flac` | audio/flac |\n| `.aac` | audio/aac |\n| `.ogg` | audio/ogg |\n| `.wma` | audio/x-ms-wma |\n| `.aiff` / `.aif` | audio/aiff |\n\nSource: [src/api-client.ts:195-210](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## File Validation Tool\n\n### barevalue_validate\n\nPerforms pre-submission validation on files hosted at external URLs. This tool checks speech content percentage and detects music-only files without consuming credits.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `file_url` | `string` | Yes | Public URL to the audio file |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `valid` | `boolean` | Whether the file passes validation |\n| `speech_detected` | `number` | Percentage of speech content (minimum 10% required) |\n| `music_only` | `boolean` | Whether music-only content was detected |\n| `duration_minutes` | `number` | Total audio duration |\n\n**Note:** This tool is for external URLs only. Files uploaded via `barevalue_upload` do not require validation.\n\nSource: [src/index.ts:82-95](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\nSource: [README.md:85-95](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n```mermaid\ngraph LR\n A[External URL] --> B[POST /orders/validate]\n B --> C{Validation Rules}\n C -->|Speech ≥ 10%| D[✓ Valid]\n C -->|Speech < 10%| E[✗ validation_failed]\n C -->|Music only| E\n```\n\n## Order Submission Tools\n\n### barevalue_submit\n\nSubmits an order for processing using a file previously uploaded via `barevalue_upload`. This is the final step that triggers the AI editing pipeline.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `order_id` | `number` | Yes | Order ID from upload step |\n| `s3_key` | `string` | Yes | S3 key from upload step |\n| `podcast_name` | `string` | Yes | Name of the podcast |\n| `episode_name` | `string` | Yes | Name of this episode |\n| `episode_number` | `string` | No | Episode number for organization |\n| `special_instructions` | `string` | No | Custom editing instructions (max 2000 chars) |\n| `processing_style` | `string` | No | `standard`, `minimal`, or `aggressive` |\n| `host_names` | `string[]` | No | Array of host names (max 5) |\n| `guest_names` | `string[]` | No | Array of guest names (max 10) |\n\nSource: [src/index.ts:97-130](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n**Processing Styles:**\n\n| Style | Description |\n|-------|-------------|\n| `standard` | Default editing level |\n| `minimal` | Light editing, preserves more original content |\n| `aggressive` | Heavy editing, removes more filler |\n\n### barevalue_submit_url\n\nSubmits an order directly from an external URL without requiring a separate upload step. Combines validation and submission in one operation.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `file_url` | `string` | Yes | Public URL to the audio file |\n| `podcast_name` | `string` | Yes | Name of the podcast |\n| `episode_name` | `string` | Yes | Name of this episode |\n| `episode_number` | `string` | No | Episode number |\n| `special_instructions` | `string` | No | Custom editing instructions |\n| `processing_style` | `string` | No | `standard`, `minimal`, or `aggressive` |\n| `host_names` | `string[]` | No | Host names for speaker labels |\n| `guest_names` | `string[]` | No | Guest names for speaker labels |\n\n**Response Fields:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `order_id` | `number` | Assigned order identifier |\n| `status` | `string` | Current order status |\n| `cost_breakdown` | `object` | AI minutes, credits, and payment details |\n| `estimated_completion` | `string` | ISO timestamp for expected completion |\n\nSource: [src/types.ts:45-60](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Order Status Tools\n\n### barevalue_status\n\nRetrieves the current processing state of an order and provides download URLs when processing is complete.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `order_id` | `number` | Yes | Order ID to check |\n\n**Order Status Values:**\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Order received, awaiting download |\n| `downloading` | Fetching source file from S3/URL |\n| `processing` | Initial processing phase |\n| `transcribing` | Converting speech to text |\n| `editing` | AI editing in progress |\n| `completed` | Processing finished, deliverables ready |\n| `failed` | Processing error occurred |\n| `refunded` | Order was refunded |\n\nSource: [src/types.ts:62-80](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n**Response with Downloads (when completed):**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `order_id` | `number` | Order identifier |\n| `status` | `string` | Current status |\n| `podcast_name` | `string` | Podcast name |\n| `episode_name` | `string` | Episode name |\n| `duration_minutes` | `number` | Audio duration |\n| `downloads.edited_audio` | `string` | URL to edited audio file |\n| `downloads.transcript_pdf` | `string` | URL to PDF transcript |\n| `downloads.transcript_docx` | `string` | URL to Word transcript |\n| `downloads.show_notes` | `string` | URL to show notes (nullable) |\n| `error` | `object` | Error details if failed |\n\nSource: [src/index.ts:132-150](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n### barevalue_list_orders\n\nRetrieves a paginated list of recent orders with optional status filtering.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | `number` | No | 1 | Page number |\n| `per_page` | `number` | No | 20 | Results per page (max 100) |\n| `status` | `string` | No | - | Filter: `pending`, `processing`, `completed`, `failed` |\n\n**Response Structure:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `orders` | `OrderListItem[]` | Array of order summaries |\n| `pagination.page` | `number` | Current page |\n| `pagination.per_page` | `number` | Items per page |\n| `pagination.total` | `number` | Total matching orders |\n| `pagination.total_pages` | `number` | Total pages available |\n\n**Order List Item Fields:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `order_id` | `number` | Order identifier |\n| `status` | `string` | Current status |\n| `podcast_name` | `string` | Podcast name |\n| `episode_name` | `string` | Episode name |\n| `duration_minutes` | `number` | Audio duration |\n| `created_at` | `string` | ISO timestamp |\n| `completed_at` | `string` | ISO timestamp or null |\n\nSource: [src/index.ts:152-175](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\nSource: [src/types.ts:82-95](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Complete Workflow Patterns\n\n### Local File Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as barevalue-mcp\n participant API as Barevalue API\n participant S3 as AWS S3\n\n User->>MCP: barevalue_upload(file_path)\n MCP->>API: GET /orders/upload-url\n API->>S3: Generate presigned URL\n S3-->>API: Presigned URL\n API-->>MCP: {order_id, s3_key, upload_url}\n MCP->>S3: PUT file to presigned URL\n S3-->>MCP: 200 OK\n MCP-->>User: {order_id, s3_key}\n\n User->>MCP: barevalue_submit(params)\n MCP->>API: POST /orders/submit\n API-->>MCP: {order_id, status, estimated_completion}\n MCP-->>User: Order submitted\n\n loop Poll until completed\n User->>MCP: barevalue_status(order_id)\n MCP->>API: GET /orders/{id}\n API-->>MCP: {status, downloads?}\n MCP-->>User: Current status\n end\n```\n\n### External URL Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as barevalue-mcp\n participant API as Barevalue API\n\n User->>MCP: barevalue_validate(file_url)\n MCP->>API: POST /orders/validate\n API-->>MCP: {valid, speech_detected, duration}\n MCP-->>User: Validation result\n\n alt Validation passed\n User->>MCP: barevalue_submit_url(params)\n MCP->>API: POST /orders/submit\n API-->>MCP: {order_id, status}\n MCP-->>User: Order submitted\n else Validation failed\n MCP-->>User: Error: validation_failed\n end\n```\n\n## Error Handling\n\nThe API client throws `BarevalueApiError` for failed requests with structured error responses:\n\n```typescript\nexport class BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n}\n```\n\n**Common Error Codes:**\n\n| Error Code | HTTP Status | Description |\n|------------|-------------|-------------|\n| `invalid_api_key` | 401 | API key missing, invalid, or revoked |\n| `insufficient_credits` | 402 | Not enough credits or subscription minutes |\n| `validation_failed` | 400 | File failed pre-checks (insufficient speech or music-only) |\n| `file_too_large` | 413 | File exceeds 750MB limit |\n| `rate_limited` | 429 | Too many requests (limit: 10/minute) |\n\nSource: [src/api-client.ts:90-120](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\nSource: [README.md:55-65](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Rate Limits\n\n| Limit | Value |\n|-------|-------|\n| Requests per minute | 10 per API key |\n| File upload timeout | 5 minutes |\n| Order processing | 10-30 minutes typical |\n\n## Security Considerations\n\nThe API client implements several security measures:\n\n1. **API Key Validation**: Keys must start with `bv_sk_` prefix\n2. **HTTPS Enforcement**: Warns when using non-HTTPS for non-localhost connections\n3. **S3 Upload Security**: Presigned URLs expire after 30 minutes\n4. **Error Sanitization**: Raw API responses are not exposed in error messages\n5. **Timeout Protection**: All requests have configurable timeouts\n\nSource: [src/api-client.ts:40-60](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n---\n\n\n\n## Webhook Management\n\n### Related Pages\n\nRelated topics: [Order Workflow Tools](#order-workflow), [Error Handling and Rate Limits](#error-handling)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [test-webhooks.js](https://github.com/quietnotion/barevalue-mcp/blob/main/test-webhooks.js)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n \n\n# Webhook Management\n\n## Overview\n\nWebhook Management in barevalue-mcp provides a comprehensive system for subscribing to and receiving real-time notifications about order lifecycle events. The MCP server exposes five distinct webhook management tools that allow clients to create, read, update, delete, and rotate secrets for webhooks configured against the Barevalue API.\n\nWebhooks serve as the primary mechanism for asynchronous order status notifications. When orders complete, fail, or are refunded, the Barevalue API delivers signed HTTP POST payloads to registered webhook endpoints, enabling automated downstream processing without polling. Source: [src/api-client.ts:109-134]()\n\n## Architecture\n\n### Component Overview\n\nThe webhook management system consists of three primary layers:\n\n1. **API Client Layer** (`BarevalueApiClient`) - Handles HTTP communication with the Barevalue API\n2. **Tool Definition Layer** (`src/index.ts`) - Exposes MCP-compatible tool interfaces\n3. **Type System** (`src/types.ts`) - Provides TypeScript interfaces for type safety\n\n### Data Flow\n\n```mermaid\ngraph TD\n A[MCP Client] -->|barevalue_webhook_*| B[barevalue-mcp Server]\n B -->|HTTP Request| C[Barevalue API]\n C -->|Webhook Payload| D[Client Endpoint]\n D -->|HMAC Verification| E[Process Event]\n \n F[Order Events] -->|triggers| C\n G[order.completed] --> F\n H[order.failed] --> F\n I[order.refunded] --> F\n```\n\n### Tool-to-API Mapping\n\n| MCP Tool | HTTP Method | API Endpoint | Source |\n|----------|-------------|--------------|--------|\n| `barevalue_webhooks_list` | GET | `/webhooks` | [src/index.ts:89-97]() |\n| `barevalue_webhook_create` | POST | `/webhooks` | [src/index.ts:99-123]() |\n| `barevalue_webhook_update` | PATCH | `/webhooks/{id}` | [src/index.ts:125-151]() |\n| `barevalue_webhook_delete` | DELETE | `/webhooks/{id}` | [src/index.ts:153-167]() |\n| `barevalue_webhook_rotate_secret` | POST | `/webhooks/{id}/rotate-secret` | [src/index.ts:169-189]() |\n\n## Available Webhook Events\n\nThe Barevalue API supports three distinct event types that clients can subscribe to:\n\n| Event | Description | Trigger Condition |\n|-------|-------------|-------------------|\n| `order.completed` | Order finished processing | AI editing completed successfully |\n| `order.failed` | Order processing failed | Error during processing or validation |\n| `order.refunded` | Order was refunded | Credit reversal processed |\n\nSource: [src/index.ts:108-112]()\n\n## Data Models\n\n### Webhook Interface\n\n```typescript\ninterface Webhook {\n id: number;\n url: string;\n events: string[];\n is_active: boolean;\n failure_count: number;\n last_triggered_at: string | null;\n created_at: string;\n secret?: string; // Only returned on create\n}\n```\n\nSource: [src/types.ts:67-76]()\n\n### WebhookListResponse Interface\n\n```typescript\ninterface WebhookListResponse {\n webhooks: Webhook[];\n}\n```\n\nSource: [src/types.ts:78-80]()\n\n### Input Type Definitions\n\n```typescript\ninterface WebhookCreateInput {\n url: string;\n events: string[];\n}\n\ninterface WebhookUpdateInput {\n webhook_id: number;\n url?: string;\n events?: string[];\n is_active?: boolean;\n}\n\ninterface WebhookDeleteInput {\n webhook_id: number;\n}\n\ninterface WebhookRotateSecretInput {\n webhook_id: number;\n}\n```\n\nSource: [src/types.ts:121-143]()\n\n## Tool Specifications\n\n### List Webhooks\n\nRetrieves all configured webhooks for the authenticated account.\n\n**Tool Name:** `barevalue_webhooks_list`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"required\": []\n}\n```\n\n**Behavior:** Returns an array of all webhooks including their URLs, subscribed events, active status, failure counts, and timestamps. The `secret` field is omitted for security reasons. Source: [src/index.ts:89-97]()\n\n### Create Webhook\n\nRegisters a new webhook endpoint to receive event notifications.\n\n**Tool Name:** `barevalue_webhook_create`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"description\": \"HTTPS URL to receive webhook payloads\"\n },\n \"events\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\"order.completed\", \"order.failed\", \"order.refunded\"]\n },\n \"description\": \"Events to subscribe to\"\n }\n },\n \"required\": [\"url\", \"events\"]\n}\n```\n\n**Response Note:** The `secret` field is returned only on creation and is displayed with a warning to save it immediately. The secret is never shown again. Source: [src/index.ts:227-237]()\n\n### Update Webhook\n\nModifies an existing webhook's configuration.\n\n**Tool Name:** `barevalue_webhook_update`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"webhook_id\": {\n \"type\": \"number\",\n \"description\": \"Webhook ID to update\"\n },\n \"url\": {\n \"type\": \"string\",\n \"description\": \"New HTTPS URL\"\n },\n \"events\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" },\n \"description\": \"New events list\"\n },\n \"is_active\": {\n \"type\": \"boolean\",\n \"description\": \"Enable or disable the webhook\"\n }\n },\n \"required\": [\"webhook_id\"]\n}\n```\n\n**Behavior:** All update fields are optional. Only provided fields are sent to the API. The webhook ID must be specified to identify the target webhook. Source: [src/index.ts:239-249]()\n\n### Delete Webhook\n\nPermanently removes a webhook configuration.\n\n**Tool Name:** `barevalue_webhook_delete`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"webhook_id\": {\n \"type\": \"number\",\n \"description\": \"Webhook ID to delete\"\n }\n },\n \"required\": [\"webhook_id\"]\n}\n```\n\n**Warning:** This operation is irreversible. The webhook is deleted immediately and cannot be recovered. Source: [src/index.ts:153-167]()\n\n### Rotate Webhook Secret\n\nGenerates a new HMAC signing secret for webhook payload verification.\n\n**Tool Name:** `barevalue_webhook_rotate_secret`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"webhook_id\": {\n \"type\": \"number\",\n \"description\": \"Webhook ID to rotate secret for\"\n }\n },\n \"required\": [\"webhook_id\"]\n}\n```\n\n**Behavior:** Immediately invalidates the previous secret. The new secret is returned once and cannot be retrieved again. Clients must update their webhook handlers with the new secret before the rotation is performed. Source: [src/index.ts:251-261]()\n\n## Security\n\n### Signature Verification\n\nWebhook payloads are signed using HMAC-SHA256 to ensure authenticity and integrity. The signature is included in the `X-Barevalue-Signature` header of each webhook request. Source: [README.md:143-145]()\n\n**Verification Process:**\n```mermaid\ngraph LR\n A[Receive Payload] --> B[Extract Signature Header]\n B --> C[Compute HMAC-SHA256]\n C --> D[Compare with Header]\n D -->|Match| E[Process Payload]\n D -->|Mismatch| F[Reject Request]\n```\n\n### Secret Management\n\n| Operation | Secret Behavior |\n|-----------|-----------------|\n| Create | Secret generated and returned (one-time view) |\n| List | Secret omitted from response |\n| Update | Secret unchanged |\n| Rotate | New secret generated, old immediately invalid |\n| Delete | Secret destroyed |\n\n### Presigned URL Security\n\nPresigned S3 URLs for order downloads expire after 30 minutes. Webhook secrets follow the same security model with immediate invalidation upon rotation. Source: [README.md:143-145]()\n\n## API Client Implementation\n\n### Webhook Methods in BarevalueApiClient\n\n```typescript\n// List all webhooks\nasync listWebhooks(): Promise {\n return this.request('GET', '/webhooks');\n}\n\n// Create a webhook\nasync createWebhook(url: string, events: string[]): Promise {\n return this.request('POST', '/webhooks', { url, events });\n}\n\n// Get a specific webhook\nasync getWebhook(webhookId: number): Promise {\n return this.request('GET', `/webhooks/${webhookId}`);\n}\n\n// Update a webhook\nasync updateWebhook(\n webhookId: number,\n updates: { url?: string; events?: string[]; is_active?: boolean }\n): Promise {\n return this.request('PATCH', `/webhooks/${webhookId}`, updates);\n}\n\n// Delete a webhook\nasync deleteWebhook(webhookId: number): Promise<{ success: boolean }> {\n return this.request<{ success: boolean }>('DELETE', `/webhooks/${webhookId}`);\n}\n\n// Rotate webhook secret\nasync rotateWebhookSecret(webhookId: number): Promise {\n return this.request('POST', `/webhooks/${webhookId}/rotate-secret`);\n}\n```\n\nSource: [src/api-client.ts:109-134]()\n\n### HTTP Request Configuration\n\nThe API client uses Node.js native `http` and `https` modules with the following security headers:\n\n```typescript\nconst options: https.RequestOptions = {\n hostname: url.hostname,\n port: url.port || (isHttps ? 443 : 80),\n path: url.pathname + url.search,\n method,\n headers: {\n 'Authorization': `Bearer ${this.apiKey}`,\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'User-Agent': 'barevalue-mcp/1.0.0',\n },\n timeout: this.timeout,\n};\n```\n\nSource: [src/api-client.ts:48-70]()\n\n## Testing\n\n### Integration Test Coverage\n\nThe repository includes a comprehensive test suite for webhook operations in `test-webhooks.js`. Tests verify:\n\n| Test | Operation | Assertions |\n|------|-----------|------------|\n| 1 | Create Webhook | Returns `id`, `secret`, validates response structure |\n| 2 | Update Webhook | Event list updates to 3 items |\n| 3 | Rotate Secret | New secret differs from original |\n| 4 | Delete Webhook | Successful deletion confirmation |\n\nSource: [test-webhooks.js:20-90]()\n\n### Test Execution Flow\n\n```mermaid\ngraph TD\n A[Start Test Server] --> B[Create Webhook]\n B -->|wait 2s| C[Update Webhook]\n C -->|wait 2s| D[Rotate Secret]\n D -->|wait 2s| E[Delete Webhook]\n E --> F[Print Results]\n \n B -->|success| G[passed++]\n C -->|success| G\n D -->|success| G\n E -->|success| G\n \n B -->|failure| H[failed++]\n C -->|failure| H\n D -->|failure| H\n E -->|failure| H\n```\n\n### Test Output Example\n\n```\n1. Create Webhook... ✅\n Response: {\n \"id\": 123,\n \"url\": \"https://httpbin.org/post\",\n \"events\": [\"order.completed\", \"order.failed\"],\n \"secret\": \"whsec_...\"\n }\n\n2. Update Webhook... ✅\n Response: {\n \"id\": 123,\n \"events\": [\"order.completed\", \"order.failed\", \"order.refunded\"]\n }\n\n3. Rotate Webhook Secret... ✅\n Response: { \"id\": 123, \"secret\": \"whsec_new...\" }\n\n4. Delete Webhook... ✅\n Response: { \"success\": true }\n\n=== Results ===\nPassed: 4\nFailed: 0\nWebhook operations: 100% verified ✅\n```\n\n## Error Handling\n\n### API Error Response Format\n\n```typescript\nclass BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n}\n```\n\nSource: [src/api-client.ts:86-94]()\n\n### Common Error Codes\n\n| HTTP Status | Error Code | Description |\n|-------------|------------|-------------|\n| 400 | `invalid_request` | Malformed request body |\n| 401 | `invalid_api_key` | Missing or invalid API key |\n| 404 | `not_found` | Webhook ID does not exist |\n| 422 | `validation_failed` | Invalid URL or events format |\n| 429 | `rate_limited` | Exceeded rate limit (10/minute) |\n| 500 | `internal_error` | Server-side error |\n\n### Error Sanitization\n\nThe MCP server sanitizes all error responses to prevent leakage of sensitive data:\n\n```typescript\nreturn {\n content: [{\n type: 'text',\n text: JSON.stringify({\n error: error.code,\n message: sanitizeString(error.message),\n statusCode: error.statusCode,\n details: sanitizeData(error.details),\n }, null, 2)\n }]\n};\n```\n\nSource: [src/index.ts:275-292]()\n\n## Usage Examples\n\n### Complete Webhook Lifecycle\n\n```javascript\n// 1. Create a webhook\nconst webhook = await callTool('barevalue_webhook_create', {\n url: 'https://your-server.com/webhooks/barevalue',\n events: ['order.completed', 'order.failed', 'order.refunded']\n});\n// Save webhook.secret securely - only shown once!\n\n// 2. List webhooks to verify\nconst webhooks = await callTool('barevalue_webhooks_list');\nconsole.log('Configured webhooks:', webhooks.webhooks.length);\n\n// 3. Update webhook to disable during maintenance\nawait callTool('barevalue_webhook_update', {\n webhook_id: webhook.id,\n is_active: false\n});\n\n// 4. Re-enable and rotate secret periodically\nawait callTool('barevalue_webhook_update', {\n webhook_id: webhook.id,\n is_active: true\n});\n\nconst newWebhook = await callTool('barevalue_webhook_rotate_secret', {\n webhook_id: webhook.id\n});\n// Update your server with newWebhook.secret\n\n// 5. Delete when no longer needed\nawait callTool('barevalue_webhook_delete', {\n webhook_id: webhook.id\n});\n```\n\n### Handling Webhook Payloads\n\n```javascript\n// Example webhook handler (server-side)\nconst crypto = require('crypto');\n\nfunction handleWebhook(payload, signature, secret) {\n // Verify signature\n const expectedSig = crypto\n .createHmac('sha256', secret)\n .update(JSON.stringify(payload))\n .digest('hex');\n \n if (signature !== expectedSig) {\n return { error: 'Invalid signature', status: 401 };\n }\n \n // Process based on event type\n switch (payload.event) {\n case 'order.completed':\n downloadEditedAudio(payload.order_id);\n break;\n case 'order.failed':\n notifySupport(payload.order_id, payload.error);\n break;\n case 'order.refunded':\n updateCredits(payload.account_id, payload.amount);\n break;\n }\n \n return { status: 200 };\n}\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | - | API key with `bv_sk_` prefix |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\nSource: [server.json:16-22]()\n\n### MCP Server Registration\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n## Rate Limits\n\nWebhook management operations are subject to the following limits:\n\n| Limit | Value | Scope |\n|-------|-------|-------|\n| API Requests | 10/minute | Per API key |\n| File Uploads | 5-minute timeout | Per upload |\n| Webhook Delivery | Best effort | Per endpoint |\n\nSource: [README.md:147-150]()\n\n## See Also\n\n- [Account & Billing](README.md#account--billing) - Check credits before webhook-triggered operations\n- [Order Workflow](README.md#order-workflow) - Understand order lifecycle events\n- [Security](README.md#security) - General security practices\n\n---\n\n\n\n## Error Handling and Rate Limits\n\n### Related Pages\n\nRelated topics: [Account and Billing Tools](#account-tools), [Order Workflow Tools](#order-workflow)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n \n\n# Error Handling and Rate Limits\n\nThe barevalue-mcp server implements comprehensive error handling and rate limiting mechanisms to ensure reliable communication with the Barevalue API while protecting against misuse and providing meaningful feedback to clients.\n\n## Overview\n\nThe error handling system in barevalue-mcp serves three primary purposes:\n\n1. **API Error Propagation** - Translating Barevalue API errors into structured, actionable responses\n2. **Client-Side Validation** - Catching issues before they reach the API (format validation, file size limits)\n3. **Security Enforcement** - Preventing sensitive data exposure and flagging insecure configurations\n\nRate limiting controls resource consumption and ensures fair access to the Barevalue API infrastructure.\n\n## Error Architecture\n\n### Error Class Hierarchy\n\nThe `BarevalueApiError` class extends the standard `Error` type with additional context specific to API failures:\n\n```typescript\nexport class BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n\n toJSON() {\n return {\n error: this.code,\n message: this.message,\n statusCode: this.statusCode,\n details: this.details\n };\n }\n}\n```\n\n**Source:** [src/api-client.ts:180-195](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L180-L195)\n\n### Error Response Flow\n\n```mermaid\ngraph TD\n A[API Request] --> B{HTTP Status Code}\n B -->|2xx| C[Parse JSON Response]\n B -->|4xx/5xx| D[Create BarevalueApiError]\n C -->|Parse Success| E[Return Data]\n C -->|Parse Failure| F[Create Generic Error]\n D --> G[Return Error to Client]\n E --> H[Return Data to Client]\n F --> G\n```\n\n## Common Error Codes\n\nThe Barevalue API returns structured error responses with standardized error codes:\n\n| Error Code | HTTP Status | Description | Resolution |\n|------------|-------------|-------------|------------|\n| `invalid_api_key` | 401 | API key missing, invalid format, or revoked | Verify API key starts with `bv_sk_` and is active |\n| `insufficient_credits` | 402 | Not enough credits or subscription minutes | Check account balance, upgrade plan if needed |\n| `validation_failed` | 400 | File failed pre-checks (insufficient speech, music-only detected) | Ensure audio has >10% speech content |\n| `file_too_large` | 413 | File exceeds 750MB limit | Compress or split the audio file |\n| `rate_limited` | 429 | Too many requests | Wait before retrying (limit: 10/minute) |\n| `unknown_error` | varies | Unhandled server error | Contact support with error details |\n\n**Source:** [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Error Response Structure\n\nAPI errors are returned with the following JSON structure:\n\n```json\n{\n \"error\": \"error_code\",\n \"message\": \"Human-readable error description\",\n \"statusCode\": 402,\n \"details\": {\n \"current_balance\": 0,\n \"required_credits\": 3.15,\n \"has_subscription\": true\n }\n}\n```\n\n**Source:** [src/api-client.ts:100-108](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L100-L108)\n\n## Input Validation\n\n### API Key Format Validation\n\nThe server validates API key format before making any requests:\n\n```typescript\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\n**Source:** [src/api-client.ts:30-34](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L30-L34)\n\n### Security Warnings\n\nNon-HTTPS connections trigger console warnings to prevent insecure key transmission:\n\n```typescript\nconst url = new URL(this.baseUrl);\nconst isHttps = url.protocol === 'https:';\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\n**Source:** [src/api-client.ts:35-39](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L35-L39)\n\n### Content-Type Detection\n\nFile uploads use extension-based content type detection:\n\n| Extension | MIME Type |\n|-----------|-----------|\n| `.mp3` | audio/mpeg |\n| `.wav` | audio/wav |\n| `.m4a` | audio/mp4 |\n| `.flac` | audio/flac |\n| `.aac` | audio/aac |\n| `.ogg` | audio/ogg |\n| `.wma` | audio/x-ms-wma |\n| `.aiff` / `.aif` | audio/aiff |\n\nUnknown extensions default to `application/octet-stream`.\n\n**Source:** [src/api-client.ts:165-178](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L165-L178)\n\n## Timeout Configuration\n\n### Request Timeouts\n\nAll HTTP requests are subject to timeout constraints to prevent hanging connections:\n\n| Operation | Timeout | Behavior on Expiry |\n|-----------|---------|-------------------|\n| Standard API requests | Default HTTP timeout | Request destroyed, error thrown |\n| S3 file uploads | Upload timeout | Request destroyed, error thrown |\n\n```typescript\nreq.on('timeout', () => {\n req.destroy();\n reject(new Error('API request timed out'));\n});\n```\n\n**Source:** [src/api-client.ts:113-115](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L113-L115)\n\n### Timeout Error Handling\n\nBoth S3 upload and API request handlers implement consistent timeout behavior:\n\n```typescript\nreq.on('timeout', () => {\n req.destroy();\n reject(new Error('S3 upload timed out'));\n});\n```\n\n**Source:** [src/api-client.ts:144-146](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L144-L146)\n\n## Security Measures\n\n### Data Sanitization\n\nError messages are sanitized before being returned to clients to prevent information leakage:\n\n```typescript\nfunction sanitizeData(data: unknown): unknown {\n if (typeof data === 'string') {\n return sanitizeString(data);\n }\n if (Array.isArray(data)) {\n return data.map(sanitizeData);\n }\n if (data !== null && typeof data === 'object') {\n const result: Record = {};\n for (const [key, value] of Object.entries(data)) {\n result[sanitizeString(key)] = sanitizeData(value);\n }\n return result;\n }\n return data;\n}\n```\n\n**Source:** [src/index.ts:1-18](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts#L1-L18)\n\n### Error Response Protection\n\nS3 upload errors do not expose raw response data to prevent leaking internal implementation details:\n\n```typescript\nif (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {\n resolve();\n} else {\n // Security: Don't expose S3 error response data\n reject(new Error(`S3 upload failed with status ${res.statusCode}`));\n}\n```\n\n**Source:** [src/api-client.ts:140-143](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L140-L143)\n\n### API Response Parsing Protection\n\nMalformed API responses are handled without exposing raw data:\n\n```typescript\ntry {\n const parsed = JSON.parse(data);\n // ... process response\n} catch {\n // Security: Don't expose raw API response data in error messages\n reject(new Error('Failed to parse API response'));\n}\n```\n\n**Source:** [src/api-client.ts:100-108](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L100-L108)\n\n## Rate Limiting\n\n### API Rate Limits\n\nThe Barevalue API enforces the following rate limits:\n\n| Limit Type | Value | Scope |\n|------------|-------|-------|\n| Requests per minute | 10 | Per API key |\n| File upload timeout | 5 minutes | Per upload |\n| Order processing | 10-30 minutes | Per order |\n\n**Source:** [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Rate Limit Handling\n\nWhen rate limited, the API returns a `429 Too Many Requests` response:\n\n```json\n{\n \"error\": \"rate_limited\",\n \"message\": \"Too many requests. Please wait before retrying.\",\n \"statusCode\": 429\n}\n```\n\nClients should implement exponential backoff when encountering rate limits.\n\n## Error Handling in Tool Calls\n\n### Tool Execution Error Flow\n\nAll tool calls are wrapped in try-catch blocks that sanitize errors before returning responses:\n\n```typescript\ntry {\n // Tool execution logic\n const result = await executeTool(args);\n return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };\n} catch (error) {\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(\n {\n error: 'tool_error',\n message: sanitizeString(error instanceof Error ? error.message : 'Unknown error occurred'),\n },\n null,\n 2\n ),\n },\n ],\n };\n}\n```\n\n**Source:** [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n### Error Response Format\n\nTool errors are always returned in a consistent format:\n\n```json\n{\n \"error\": \"tool_error\",\n \"message\": \"Sanitized error message without sensitive data\"\n}\n```\n\n## Webhook Security\n\n### HMAC-SHA256 Verification\n\nWebhook payloads use HMAC-SHA256 signatures for verification:\n\n> Webhook signatures use HMAC-SHA256 for verification\n\n**Source:** [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Secret Rotation\n\nWebhooks support secret rotation to maintain security without service interruption:\n\n```typescript\nasync rotateWebhookSecret(webhookId: number): Promise {\n return this.request('POST', `/webhooks/${webhookId}/rotate-secret`);\n}\n```\n\n**Source:** [src/api-client.ts:175-178](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L175-L178)\n\n### Presigned URL Expiration\n\nS3 presigned URLs expire after 30 minutes for security:\n\n> Presigned S3 URLs expire after 30 minutes\n\n**Source:** [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Best Practices\n\n### Client-Side Error Handling\n\n1. **Always check the `error` field** in responses before processing data\n2. **Implement retry logic** with exponential backoff for transient errors\n3. **Monitor rate limits** by tracking request counts per API key\n4. **Validate files locally** before upload (format, size, speech content)\n\n### Error Recovery Strategies\n\n| Error Type | Recommended Action |\n|------------|-------------------|\n| `invalid_api_key` | Verify key format and regenerate if needed |\n| `insufficient_credits` | Check account balance or upgrade plan |\n| `validation_failed` | Pre-validate audio with `barevalue_validate` tool |\n| `rate_limited` | Wait and retry with exponential backoff |\n| Network timeout | Retry once, then investigate connectivity |\n\n### Security Checklist\n\n- [ ] API keys stored in environment variables, never hardcoded\n- [ ] HTTPS used for all non-localhost connections\n- [ ] Error responses sanitized before logging\n- [ ] Webhook signatures verified on receipt\n- [ ] Presigned URLs used within 30-minute window\n\n---\n\n\n\n## Security\n\n### Related Pages\n\nRelated topics: [Configuration Reference](#configuration), [Webhook Management](#webhook-management)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n \n\n# Security\n\nThis page documents the security architecture, measures, and best practices implemented in the barevalue-mcp project. The barevalue-mcp is a Model Context Protocol (MCP) server that enables programmatic interaction with the Barevalue AI podcast editing API.\n\n## Overview\n\nThe barevalue-mcp server implements multiple layers of security to protect sensitive data during API communication. The primary security concerns include:\n\n- **API Key Protection**: Preventing exposure of authentication credentials\n- **Transport Security**: Ensuring encrypted communication channels\n- **Input Sanitization**: Protecting against injection attacks\n- **Error Handling**: Avoiding information leakage in error messages\n- **Webhook Security**: Verifying authenticity of incoming webhook requests\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Environment Variables\n\nEnvironment variables are the sole mechanism for configuring sensitive credentials. The server does not support hardcoded values or configuration files for secrets.\n\n| Variable | Required | Type | Description |\n|----------|----------|------|-------------|\n| `BAREVALUE_API_KEY` | Yes | String | Your Barevalue API key. Must start with `bv_sk_`. Marked as secret in MCP configuration. |\n| `BAREVALUE_API_URL` | No | String | Override API base URL. Defaults to `https://barevalue.com/api/v1` |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n## API Key Protection\n\n### Format Validation\n\nThe API client validates the format of incoming API keys to ensure they conform to the expected pattern. Keys must begin with the `bv_sk_` prefix.\n\n```typescript\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\nSource: [src/api-client.ts:1-100](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Secret Handling\n\nThe `BAREVALUE_API_KEY` environment variable is declared as a secret in the MCP server configuration:\n\n```json\n{\n \"name\": \"BAREVALUE_API_KEY\",\n \"isSecret\": true,\n \"isRequired\": true\n}\n```\n\nThis ensures that MCP clients handle the credential with appropriate confidentiality measures.\n\nSource: [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n## Transport Security\n\n### HTTPS Enforcement\n\nAll production API communication uses HTTPS to encrypt data in transit. The client explicitly uses the Node.js `https` module for secure connections:\n\n```typescript\nconst isHttps = url.protocol === 'https:';\nconst httpModule = isHttps ? https : http;\n```\n\nFor non-localhost URLs, a warning is emitted if a non-HTTPS connection is detected:\n\n```typescript\nconst isHttps = url.protocol === 'https:';\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\nThis warning mechanism alerts operators to potentially insecure configurations while allowing local development with HTTP.\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Request Headers\n\nEvery API request includes security-relevant headers:\n\n| Header | Value | Purpose |\n|--------|-------|---------|\n| `Authorization` | `Bearer {apiKey}` | Authentication token |\n| `Content-Type` | `application/json` | Ensures JSON parsing on server |\n| `Accept` | `application/json` | Expects JSON response |\n| `User-Agent` | `barevalue-mcp/1.0.0` | Server identification |\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Input Sanitization\n\nThe server implements input sanitization to protect against injection attacks and ensure safe data handling.\n\n### Sanitization Functions\n\n```typescript\nfunction sanitizeString(str: string): string {\n return str.replace(/[\\u0000-\\u001F\\u007F-\\u009F]/g, (char) => \n char.charCodeAt(0) < 0x20 || char.charCodeAt(0) > 0x7E \n ? `\\\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`\n : char\n );\n}\n\nfunction sanitizeData(data: unknown): unknown {\n if (typeof data === 'string') {\n return sanitizeString(data);\n }\n if (Array.isArray(data)) {\n return data.map(sanitizeData);\n }\n if (data !== null && typeof data === 'object') {\n const result: Record = {};\n for (const [key, value] of Object.entries(data)) {\n result[sanitizeString(key)] = sanitizeData(value);\n }\n return result;\n }\n return data;\n}\n```\n\nThe sanitization process:\n1. Removes control characters from strings (bytes 0x00-0x1F and 0x7F-0x9F)\n2. Recursively processes arrays and objects\n3. Preserves printable ASCII characters and Unicode content\n\nSource: [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n### Sanitization Application Points\n\nSanitization is applied in two primary locations:\n\n1. **Tool Call Error Responses**: When a tool call fails, error messages are sanitized before being returned to clients\n2. **Webhook Payloads**: Incoming webhook data is sanitized to prevent injection attacks\n\nSource: [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Error Handling Security\n\n### Information Leakage Prevention\n\nThe server is designed to avoid exposing sensitive information in error messages. Two specific safeguards are implemented:\n\n**S3 Upload Errors**:\n```typescript\n// Security: Don't expose S3 error response data\nreject(new Error(`S3 upload failed with status ${res.statusCode}`));\n```\n\n**API Response Parsing Failures**:\n```typescript\n// Security: Don't expose raw API response data in error messages\nreject(new Error('Failed to parse API response'));\n```\n\nThese measures ensure that internal system details, stack traces, or sensitive payload content are never exposed to end users or potential attackers.\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Error Response Structure\n\nAll tool call errors follow a standardized format:\n\n```json\n{\n \"error\": \"tool_error\",\n \"message\": \"sanitized error message\"\n}\n```\n\nSource: [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Webhook Security\n\nThe Barevalue API provides webhook functionality for order status notifications. The MCP server includes full webhook management capabilities.\n\n### HMAC-SHA256 Signature Verification\n\nIncoming webhook requests are verified using HMAC-SHA256 signatures:\n\n> Webhook signatures use HMAC-SHA256 for verification\n\nThis ensures that webhook payloads originate from the legitimate Barevalue API server and have not been tampered with in transit.\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Webhook Secret Rotation\n\nThe server supports webhook secret rotation to maintain security after potential compromises:\n\n```\nbarevalue_webhook_rotate_secret webhook_id=1\n```\n\nRotating secrets immediately invalidates the previous secret, ensuring that any previously leaked credentials stop working immediately.\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Webhook Management API\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| `GET` | `/webhooks` | List all webhooks |\n| `POST` | `/webhooks` | Create a webhook |\n| `GET` | `/webhooks/{id}` | Get specific webhook |\n| `PATCH` | `/webhooks/{id}` | Update webhook configuration |\n| `DELETE` | `/webhooks/{id}` | Delete a webhook |\n| `POST` | `/webhooks/{id}/rotate-secret` | Rotate webhook secret |\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## S3 Upload Security\n\n### Presigned URL Expiration\n\nFile uploads use S3 presigned URLs that automatically expire:\n\n> Presigned S3 URLs expire after 30 minutes\n\nThis temporal limitation reduces the risk of unauthorized access to uploaded files even if a presigned URL is intercepted.\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Content Type Validation\n\nThe client validates file content types based on extension:\n\n```typescript\nconst types: Record = {\n '.mp3': 'audio/mpeg',\n '.wav': 'audio/wav',\n '.m4a': 'audio/mp4',\n '.flac': 'audio/flac',\n '.aac': 'audio/aac',\n '.ogg': 'audio/ogg',\n '.wma': 'audio/x-ms-wma',\n '.aiff': 'audio/aiff',\n '.aif': 'audio/aiff',\n};\nreturn types[ext] || 'application/octet-stream';\n```\n\nSupported formats are limited to audio files, preventing upload of potentially malicious file types.\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Timeout Protection\n\nThe server implements timeout protection for all network operations:\n\n```typescript\ntimeout: this.timeout\n```\n\nIf a request exceeds the configured timeout, the connection is destroyed and an error is returned:\n\n```typescript\nreq.on('timeout', () => {\n req.destroy();\n reject(new Error('API request timed out'));\n});\n```\n\nThis prevents resource exhaustion attacks that attempt to hold connections open indefinitely.\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Rate Limiting\n\nThe API enforces rate limiting to prevent abuse:\n\n- **10 requests per minute** per API key\n- File uploads have a **5-minute timeout**\n- Order processing typically completes in **10-30 minutes**\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Security Architecture Diagram\n\n```mermaid\ngraph TD\n subgraph \"Client Environment\"\n ENV[Environment Variables
BAREVALUE_API_KEY
BAREVALUE_API_URL]\n end\n\n subgraph \"barevalue-mcp Server\"\n SV[Server Startup]\n SV -->|Read| ENV\n \n subgraph \"API Client\"\n KVF[API Key Validation
bv_sk_ prefix check]\n HTTPS_CHK[HTTPS Check
Non-localhost warning]\n REQ[Request Builder
Auth headers
User-Agent]\n TO[Timeout Handler]\n end\n \n ENV --> KVF\n KVF --> HTTPS_CHK\n HTTPS_CHK --> REQ\n REQ --> TO\n end\n\n subgraph \"Barevalue API\"\n AUTH[Authentication]\n RATE[Rate Limiting
10 req/min]\n WEBHOOK[Webhook HMAC-SHA256
Signature Verification]\n S3[S3 Presigned URLs
30 min expiration]\n end\n \n TO -->|HTTPS| AUTH\n AUTH --> RATE\n RATE -->|Success| WEBHOOK\n \n subgraph \"File Upload Flow\"\n PRE[Get Presigned URL]\n UPLOAD[Upload to S3]\n PRE --> UPLOAD\n UPLOAD -->|30 min expiry| S3\n end\n```\n\n## Best Practices\n\n### For Users\n\n1. **Never hardcode API keys** — Always use environment variables\n2. **Use HTTPS in production** — The warning system alerts to insecure configurations\n3. **Rotate webhook secrets** — Periodically rotate to maintain security\n4. **Monitor rate limits** — Implement backoff logic for 429 responses\n5. **Validate file formats** — Ensure uploaded files are legitimate audio content\n\n### For Developers\n\n1. **Preserve sanitization** — Don't remove input sanitization for convenience\n2. **Maintain error secrecy** — Don't expose internal details in error messages\n3. **Keep secrets as secrets** — Never log API keys or webhook secrets\n4. **Update dependencies** — Keep the `@modelcontextprotocol/sdk` package current\n\n## Summary\n\nThe barevalue-mcp implements defense-in-depth security measures across multiple layers:\n\n| Layer | Protection Mechanism |\n|-------|---------------------|\n| Authentication | Bearer token with `bv_sk_` prefix validation |\n| Transport | HTTPS enforcement with localhost exceptions |\n| Input | Control character sanitization for all string inputs |\n| Errors | No sensitive data exposure in error messages |\n| Webhooks | HMAC-SHA256 signature verification |\n| File Uploads | S3 presigned URLs with 30-minute expiration |\n| Network | Request timeouts to prevent resource exhaustion |\n| API | Rate limiting at 10 requests per minute |\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: quietnotion/barevalue-mcp\n\nSummary: Found 7 potential pitfall items; 0 are high/blocking. Highest priority: capability - 能力判断依赖假设.\n\n## 1. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | README/documentation is current enough for a first validation pass.\n\n## 2. runtime · 运行可能依赖外部服务\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。\n- User impact: 本地安装成功不等于能力可用，外部服务不可用会阻断体验。\n- Suggested check: 确认是否有离线 demo、mock 数据或可替代服务。\n- Guardrail action: 外部服务依赖未明确时，不把本地安装成功等同于能力可用。\n- Evidence: packet_text.keyword_scan | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | matched external service / cloud / webhook / database keyword\n\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium\n\n## 6. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | issue_or_pr_quality=unknown\n\n## 7. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | release_recency=unknown\n\n\n",
"markdown_key": "barevalue-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "mcp_registry:io.github.quietnotion/barevalue:1.0.3",
"kind": "mcp_registry",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3"
}
],
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "barevalue-mcp 说明书",
"toc": [
"https://github.com/quietnotion/barevalue-mcp Project Manual",
"Table of Contents",
"Project Overview",
"Introduction",
"Purpose and Scope",
"Architecture",
"Available Tools",
"Complete Workflow",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "410e7bab123bd078648255e26a2347200a38b264",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"src/index.ts",
"src/types.ts",
"src/api-client.ts"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# barevalue-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 barevalue-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install -g barevalue-mcp` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `server.json`, `src/api-client.ts`, `test-mcp.js` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：10\n- 重要文件覆盖：10/10\n- 证据索引条目：10\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 barevalue-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 barevalue-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 barevalue-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **barevalue-mcp**（project_doc）：MCP Model Context Protocol server for the Barevalue https://barevalue.com AI podcast editing API. Allows Claude Code and other MCP-compatible tools to submit and manage podcast editing orders programmatically. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n\n## 证据索引\n\n- 共索引 10 条证据。\n\n- **barevalue-mcp**（documentation）：MCP Model Context Protocol server for the Barevalue https://barevalue.com AI podcast editing API. Allows Claude Code and other MCP-compatible tools to submit and manage podcast editing orders programmatically. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"barevalue-mcp\", \"version\": \"1.0.3\", \"description\": \"MCP server for Barevalue AI podcast editing API\", \"mcpName\": \"io.github.quietnotion/barevalue\", \"main\": \"dist/index.js\", \"bin\": { \"barevalue-mcp\": \"./dist/index.js\" }, \"scripts\": { \"build\": \"tsc\", \"dev\": \"tsc --watch\", \"start\": \"node dist/index.js\", \"prepublishOnly\": \"npm run build\" }, \"keywords\": \"mcp\", \"model-context-protocol\", \"barevalue\", \"podcast\", \"audio-editing\", \"ai\", \"claude\" , \"author\": \"Barevalue\", \"license\": \"MIT\", \"homepage\": \"https://barevalue.com/docs/api-v1 mcp-integration\", \"engines\": { \"node\": \" =18.0.0\" }, \"dependencies\": { \"@modelcontextprotocol/sdk\": \"^1.0.0\" }, \"devDependencies\": { \"@types/node\": \"^20.0.0\",… 证据：`package.json`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\", \"name\": \"io.github.quietnotion/barevalue\", \"title\": \"Barevalue\", \"description\": \"Submit podcast orders, check status, and manage webhooks via Barevalue editing API.\", \"repository\": { \"url\": \"https://github.com/quietnotion/barevalue-mcp\", \"source\": \"github\" }, \"version\": \"1.0.3\", \"packages\": { \"registryType\": \"npm\", \"identifier\": \"barevalue-mcp\", \"version\": \"1.0.3\", \"transport\": { \"type\": \"stdio\" }, \"environmentVariables\": { \"description\": \"Your Barevalue API key get one at barevalue.com → Settings → API Keys \", \"isRequired\": true, \"format\": \"string\", \"isSecret\": true, \"name\": \"BAREVALUE API KEY\" } }… 证据：`server.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"NodeNext\", \"moduleResolution\": \"NodeNext\", \"outDir\": \"./dist\", \"rootDir\": \"./src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\" } 证据：`tsconfig.json`\n- **Dependencies**（source_file）：Environment API keys should never be committed .env .env.local .env. .local 证据：`.gitignore`\n- **Api Client**（source_file）：/ Barevalue API Client HTTP wrapper for the Barevalue API v1 with authentication handling. / 证据：`src/api-client.ts`\n- **!/usr/bin/env node**（source_file）：/ Barevalue MCP Server Model Context Protocol server for the Barevalue AI podcast editing API. Allows Claude Code and other MCP-compatible tools to submit and manage podcast editing orders programmatically. / 证据：`src/index.ts`\n- **Types**（source_file）：/ Barevalue MCP Server - Type Definitions / 证据：`src/types.ts`\n- **!/usr/bin/env node**（source_file）：/ MCP Server Test Script Tests all tools against the real Barevalue API / 证据：`test-mcp.js`\n- **!/usr/bin/env node**（source_file）：const { spawn } = require 'child process' ; 证据：`test-webhooks.js`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `package.json`, `server.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `package.json`, `server.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Project Overview**：importance `high`\n - source_paths: README.md, package.json\n- **Installation Guide**：importance `high`\n - source_paths: README.md, package.json\n- **Configuration Reference**：importance `high`\n - source_paths: README.md, server.json\n- **System Architecture**：importance `high`\n - source_paths: src/index.ts, src/api-client.ts, src/types.ts\n- **Data Flow**：importance `medium`\n - source_paths: src/index.ts, src/api-client.ts, src/types.ts\n- **Account and Billing Tools**：importance `high`\n - source_paths: src/index.ts, src/types.ts\n- **Order Workflow Tools**：importance `high`\n - source_paths: src/index.ts, src/types.ts, test-mcp.js\n- **Webhook Management**：importance `medium`\n - source_paths: src/index.ts, test-webhooks.js\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `410e7bab123bd078648255e26a2347200a38b264`\n- inspected_files: `package.json`, `README.md`, `src/index.ts`, `src/types.ts`, `src/api-client.ts`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | README/documentation is current enough for a first validation pass.\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 运行可能依赖外部服务\n\n- Trigger: 项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。\n- Host AI rule: 确认是否有离线 demo、mock 数据或可替代服务。\n- Why it matters: 本地安装成功不等于能力可用，外部服务不可用会阻断体验。\n- Evidence: packet_text.keyword_scan | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | matched external service / cloud / webhook / database keyword\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | last_activity_observed missing\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | issue_or_pr_quality=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | release_recency=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n",
"summary": "Context and operating boundaries for host AI agents.",
"title": "AI Context Pack"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card\n\nProject: quietnotion/barevalue-mcp\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## Project-Specific Pitfalls\n\n- 能力判断依赖假设 (medium): 假设不成立时，用户拿不到承诺的能力。 Suggested check: 将假设转成下游验证清单。\n- 运行可能依赖外部服务 (medium): 本地安装成功不等于能力可用，外部服务不可用会阻断体验。 Suggested check: 确认是否有离线 demo、mock 数据或可替代服务。\n- 维护活跃度未知 (medium): 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项 (medium): 下游已经要求复核，不能在页面中弱化。 Suggested check: 进入安全/权限治理复核队列。\n- 存在评分风险 (medium): 风险会影响是否适合普通用户安装。 Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n",
"summary": "Installation, permission, validation, and pre-recommendation risks.",
"title": "Boundary & Risk Card"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/quietnotion/barevalue-mcp Project Manual\n\nGenerated on: 2026-05-24 16:52:56 UTC\n\n## Table of Contents\n\n- [Project Overview](#overview)\n- [Installation Guide](#installation)\n- [Configuration Reference](#configuration)\n- [System Architecture](#system-architecture)\n- [Data Flow](#data-flow)\n- [Account and Billing Tools](#account-tools)\n- [Order Workflow Tools](#order-workflow)\n- [Webhook Management](#webhook-management)\n- [Error Handling and Rate Limits](#error-handling)\n- [Security](#security)\n\n\n\n## Project Overview\n\n### Related Pages\n\nRelated topics: [Installation Guide](#installation), [System Architecture](#system-architecture)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n \n\n# Project Overview\n\n## Introduction\n\n**barevalue-mcp** is a Model Context Protocol (MCP) server that integrates the Barevalue AI podcast editing API into AI assistants like Claude Code. It enables programmatic submission of podcast episodes for AI-powered editing, along with order management, status tracking, and webhook configuration.\n\nThe project is implemented in TypeScript, built with the `@modelcontextprotocol/sdk`, and distributed as an npm package (`barevalue-mcp`). Source: [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Purpose and Scope\n\nThis MCP server serves as a bridge between AI assistants and the Barevalue podcast editing service, providing:\n\n- **Audio Upload**: Upload local audio files via presigned S3 URLs\n- **Order Submission**: Submit podcast episodes for AI editing with customizable options\n- **Status Tracking**: Monitor order progress through various processing stages\n- **Account Management**: Query subscription minutes, credit balances, and pricing\n- **Webhook Integration**: Configure webhooks for order completion notifications\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Architecture\n\nThe project follows a modular architecture with clear separation of concerns:\n\n```mermaid\ngraph TD\n A[Claude Code / AI Assistant] -->|MCP Protocol| B[src/index.ts
MCP Server]\n B --> C[src/api-client.ts
API Client]\n C -->|HTTPS| D[Barevalue API
barevalue.com/api/v1]\n C -->|S3 Upload| E[AWS S3]\n \n F[src/types.ts
Type Definitions] --> B\n F --> C\n \n G[package.json] -->|npm dependencies| B\n G -->|@modelcontextprotocol/sdk| C\n```\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|-----------------|\n| MCP Server | `src/index.ts` | Handles MCP protocol communication, tool definitions, and request routing |\n| API Client | `src/api-client.ts` | Encapsulates all Barevalue API calls including file uploads and webhooks |\n| Type Definitions | `src/types.ts` | TypeScript interfaces for inputs, outputs, and API responses |\n\nSource: [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts), [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts), [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Available Tools\n\nThe MCP server exposes the following tools organized by functional area:\n\n### Account & Billing\n\n| Tool | Description |\n|------|-------------|\n| `barevalue_account` | Get account information including credit balance, AI subscription status, and pricing |\n| `barevalue_estimate` | Calculate the cost of an order before submission based on duration |\n\n### Order Workflow\n\n| Tool | Description |\n|------|-------------|\n| `barevalue_upload` | Upload a local audio file; returns `order_id` and `s3_key` for submission |\n| `barevalue_validate` | Pre-check a file from a public URL before submission (external URLs only) |\n| `barevalue_submit` | Submit an uploaded file for AI editing; charges credits |\n| `barevalue_submit_url` | Submit using a public URL instead of uploading |\n| `barevalue_status` | Check order status and retrieve download URLs when complete |\n| `barevalue_list_orders` | List recent orders with pagination support |\n\n### Webhook Management\n\n| Tool | Description |\n|------|-------------|\n| `barevalue_list_webhooks` | List all configured webhooks |\n| `barevalue_create_webhook` | Create a new webhook endpoint |\n| `barevalue_get_webhook` | Get details of a specific webhook |\n| `barevalue_update_webhook` | Update webhook URL, events, or active status |\n| `barevalue_delete_webhook` | Delete a webhook |\n| `barevalue_webhook_rotate_secret` | Rotate webhook secret for security |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Complete Workflow\n\n### Local File Upload Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as barevalue-mcp\n participant BV as Barevalue API\n participant S3 as AWS S3\n \n User->>MCP: barevalue_upload(file_path)\n MCP->>BV: getUploadUrl(filename, contentType)\n BV-->>MCP: presigned S3 URL + s3_key\n MCP->>S3: PUT file to presigned URL\n S3-->>MCP: upload confirmation\n MCP-->>User: order_id, s3_key\n \n User->>MCP: barevalue_submit(order_id, s3_key, ...)\n MCP->>BV: POST /orders/submit\n BV-->>MCP: order confirmation\n MCP-->>User: order submitted\n \n User->>MCP: barevalue_status(order_id)\n loop Until completed\n MCP->>BV: GET /orders/{id}\n BV-->>MCP: status update\n MCP-->>User: current status\n end\n```\n\n### External URL Flow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as barevalue-mcp\n participant BV as Barevalue API\n \n User->>MCP: barevalue_validate(file_url)\n MCP->>BV: validate file URL\n BV-->>MCP: validation result\n MCP-->>User: speech percentage, music detection\n \n User->>MCP: barevalue_submit_url(file_url, ...)\n MCP->>BV: POST /orders/submit-url\n BV-->>MCP: order confirmation\n MCP-->>User: order submitted\n```\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Supported File Formats\n\nThe system supports the following audio formats for upload:\n\n| Format | MIME Type | Extension |\n|--------|-----------|-----------|\n| MP3 | audio/mpeg | .mp3 |\n| WAV | audio/wav | .wav |\n| M4A | audio/mp4 | .m4a |\n| FLAC | audio/flac | .flac |\n| AAC | audio/aac | .aac |\n| OGG | audio/ogg | .ogg |\n| WMA | audio/x-ms-wma | .wma |\n| AIFF | audio/aiff | .aiff, .aif |\n\n**Maximum file size:** 750MB\n**Minimum speech content:** 10% of audio must contain speech\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts), [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | — | API key starting with `bv_sk_` |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\n### Claude Code Setup\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\nOr for global installation:\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"barevalue-mcp\",\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Order Status Lifecycle\n\nOrders progress through the following states:\n\n```mermaid\nstateDiagram-v2\n [*] --> pending: Submit order\n pending --> downloading: Start processing\n downloading --> transcribing: Download complete\n transcribing --> editing: Transcription done\n editing --> completed: Processing done\n editing --> failed: Error occurred\n completed --> [*]\n failed --> refunded: Refund issued\n refunded --> [*]\n```\n\n### Status Values\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Order received, waiting to start |\n| `downloading` | Fetching audio file |\n| `processing` | General processing |\n| `transcribing` | Converting speech to text |\n| `editing` | AI editing audio |\n| `completed` | Ready for download |\n| `failed` | Processing error |\n| `refunded` | Credits refunded |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Processing Options\n\nWhen submitting an order, the following processing styles are available:\n\n| Style | Description |\n|-------|-------------|\n| `standard` | Default editing level |\n| `minimal` | Light editing, preserves more original content |\n| `aggressive` | Heavy editing, removes more filler |\n\nAdditional options include:\n- `host_names`: Array of host names for transcript speaker labels (max 5)\n- `guest_names`: Array of guest names for transcript speaker labels (max 10)\n- `special_instructions`: Custom editing instructions (max 2000 characters)\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Security\n\nThe implementation includes several security measures:\n\n| Feature | Implementation |\n|---------|----------------|\n| API Key Validation | Keys must start with `bv_sk_` |\n| HTTPS Enforcement | Warns when using non-HTTPS for non-localhost URLs |\n| Error Message Sanitization | Raw API/S3 response data not exposed in errors |\n| Environment Variable Storage | API key never hardcoded in source |\n\n```typescript\n// API key format validation\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Rate Limits\n\n| Limit | Value |\n|-------|-------|\n| Requests per minute | 10 per API key |\n| File upload timeout | 5 minutes |\n| Order processing time | 10-30 minutes typical |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Error Handling\n\nThe API returns structured errors:\n\n```json\n{\n \"error\": \"error_code\",\n \"message\": \"Human readable message\",\n \"statusCode\": 400\n}\n```\n\n### Common Error Codes\n\n| Error Code | Meaning |\n|------------|---------|\n| `invalid_api_key` | API key missing, invalid, or revoked |\n| `insufficient_credits` | Not enough credits or subscription minutes |\n| `validation_failed` | File failed pre-checks |\n| `file_too_large` | File exceeds 750MB limit |\n| `rate_limited` | Too many requests (10/minute) |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Development\n\n### Prerequisites\n\n- Node.js >= 18.0.0\n- npm\n\n### Build Commands\n\n| Command | Action |\n|---------|--------|\n| `npm install` | Install dependencies |\n| `npm run build` | Compile TypeScript to JavaScript |\n| `npm run dev` | Watch mode compilation |\n| `npm start` | Run production server |\n\n### Project Structure\n\n```\nbarevalue-mcp/\n├── src/\n│ ├── index.ts # MCP server implementation\n│ ├── api-client.ts # Barevalue API client\n│ └── types.ts # TypeScript type definitions\n├── package.json # Project metadata and dependencies\n├── server.json # MCP server configuration for registries\n├── README.md # Documentation\n└── dist/ # Compiled output (generated)\n```\n\nSource: [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json), [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Deliverables\n\nEvery completed order includes:\n\n| Deliverable | Description |\n|-------------|-------------|\n| Edited Audio | Audio with filler words, long pauses, and false starts removed |\n| Transcript PDF | Formatted transcript document |\n| Transcript DOCX | Editable Word document transcript |\n| Show Notes | Timestamped show notes |\n| Social Clips | AI-selected highlight clips |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n---\n\n\n\n## Installation Guide\n\n### Related Pages\n\nRelated topics: [Configuration Reference](#configuration), [Project Overview](#overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n \n\n# Installation Guide\n\nThis guide covers all methods for installing and configuring the **barevalue-mcp** server, which provides a Model Context Protocol (MCP) interface for the Barevalue AI podcast editing API.\n\n## Overview\n\nThe barevalue-mcp package is an MCP server that enables AI assistants like Claude Code to interact with the Barevalue podcast editing service. It exposes tools for uploading audio files, submitting editing orders, checking order status, and managing webhooks.\n\nThe server communicates with the Barevalue API over HTTPS, transmits the API key via environment variable, and uses stdio for MCP protocol communication with the host application.\n\n**Source:** [README.md:1-5](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Prerequisites\n\nBefore installation, ensure your environment meets the following requirements:\n\n| Requirement | Version | Notes |\n|-------------|---------|-------|\n| Node.js | >= 18.0.0 | Required runtime |\n| npm | Latest stable | For package management |\n| Claude Code | Compatible version | MCP host application |\n| Barevalue Account | Active | With API key access |\n\n**Source:** [package.json:19](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Obtaining an API Key\n\nAn API key is required to authenticate with the Barevalue API. Follow these steps to obtain one:\n\n1. Log in to your [Barevalue account](https://barevalue.com/login)\n2. Navigate to **Settings** → **API Keys**\n3. Click **Create API Key**\n4. Copy the key (starts with `bv_sk_`) — it is only shown once\n\nThe API key format must start with `bv_sk_`. The API client validates this format on initialization and throws an error if the format is incorrect.\n\n**Source:** [README.md:47-55](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n```typescript\n// API key validation in api-client.ts\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\n**Source:** [src/api-client.ts:34-38](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Installation Methods\n\n### Method 1: NPX (Recommended for Most Users)\n\nThe npx method downloads and executes the package without requiring a global installation. This is the simplest approach for most users.\n\nAdd the following configuration to your Claude Code settings file (`~/.claude/settings.json`):\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:1-15](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Method 2: Global Install\n\nFor environments where npx execution is not preferred, install the package globally:\n\n```bash\nnpm install -g barevalue-mcp\n```\n\nThen configure Claude Code with the global command:\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"barevalue-mcp\",\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:20-35](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Configuration\n\n### Claude Code Settings File\n\nThe MCP server configuration is stored in your Claude Code settings file. The default location is:\n\n```\n~/.claude/settings.json\n```\n\n### Configuration Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `command` | string | Yes | Executable command (`npx` or `barevalue-mcp`) |\n| `args` | array | No (npx only) | Arguments for the command (`[\"-y\", \"barevalue-mcp\"]`) |\n| `env` | object | Yes | Environment variables |\n| `env.BAREVALUE_API_KEY` | string | Yes | Your Barevalue API key |\n\n**Source:** [README.md:8-14](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | — | API key starting with `bv_sk_` |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\n**Source:** [README.md:59-62](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\nThe API client reads these environment variables on initialization:\n\n```typescript\nthis.apiKey = process.env.BAREVALUE_API_KEY || '';\nthis.baseUrl = process.env.BAREVALUE_API_URL || 'https://barevalue.com/api/v1';\n```\n\n**Source:** [src/api-client.ts:28-32](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Security Configuration\n\n### HTTPS Enforcement\n\nThe API client enforces HTTPS for non-localhost connections. If the configured base URL uses HTTP, a warning is logged:\n\n```typescript\nconst url = new URL(this.baseUrl);\nconst isHttps = url.protocol === 'https:';\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\n**Source:** [src/api-client.ts:39-45](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### API Key Transmission\n\nAPI keys are transmitted exclusively via the `Authorization` header using Bearer token authentication:\n\n```typescript\nheaders: {\n 'Authorization': `Bearer ${this.apiKey}`,\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'User-Agent': 'barevalue-mcp/1.0.0',\n}\n```\n\n**Source:** [src/api-client.ts:59-65](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Development Installation\n\nFor contributors or those who want to run from source, follow these steps:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the TypeScript project\nnpm run build\n\n# Run in watch mode during development\nnpm run dev\n\n# Start the production server\nnpm start\n```\n\n**Source:** [README.md:142-151](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Build Scripts\n\nThe following npm scripts are defined in package.json:\n\n| Script | Command | Purpose |\n|--------|---------|---------|\n| `build` | `tsc` | Compile TypeScript to JavaScript |\n| `dev` | `tsc --watch` | Watch mode for development |\n| `start` | `node dist/index.js` | Run production server |\n| `prepublishOnly` | `npm run build` | Build before publishing |\n\n**Source:** [package.json:9-14](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n### Dependencies\n\nThe project has the following runtime dependencies:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `@modelcontextprotocol/sdk` | ^1.0.0 | MCP protocol implementation |\n\n**Source:** [package.json:22-26](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Server Initialization\n\nThe MCP server starts by initializing the SDK with the server name and version:\n\n```typescript\nconst server = new Server(\n {\n name: 'barevalue-mcp',\n version: '1.0.0',\n },\n {\n capabilities: {\n tools: {},\n },\n }\n);\n```\n\n**Source:** [src/index.ts:120-130](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\nThe server registers two request handlers:\n\n1. **ListToolsRequestSchema** — Returns all available MCP tools\n2. **CallToolRequestSchema** — Executes tool calls by name\n\n```typescript\nserver.setRequestHandler(ListToolsRequestSchema, async () => {\n return { tools: TOOLS };\n});\n\nserver.setRequestHandler(CallToolRequestSchema, async (request) => {\n const { name, arguments: args } = request.params;\n return handleToolCall(name, args as Record);\n});\n```\n\n**Source:** [src/index.ts:132-142](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## MCP Server Metadata\n\nThe server.json file defines MCP registry metadata:\n\n```json\n{\n \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\",\n \"name\": \"io.github.quietnotion/barevalue\",\n \"title\": \"Barevalue\",\n \"description\": \"Submit podcast orders, check status, and manage webhooks via Barevalue editing API.\",\n \"version\": \"1.0.3\"\n}\n```\n\n**Source:** [server.json:1-7](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n### NPM Package Metadata\n\n| Field | Value |\n|-------|-------|\n| Package Name | `barevalue-mcp` |\n| Version | `1.0.3` |\n| MCP Name | `io.github.quietnotion/barevalue` |\n| Main Entry | `dist/index.js` |\n| License | MIT |\n\n**Source:** [package.json:1-6](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Installation Flow\n\nThe following diagram illustrates the complete installation and configuration flow:\n\n```mermaid\ngraph TD\n A[Start Installation] --> B{Have Node.js >= 18?}\n B -->|No| C[Install Node.js]\n C --> D\n B -->|Yes| D{Have Barevalue API Key?}\n D -->|No| E[Create API Key at barevalue.com]\n E --> F\n D -->|Yes| F{Choose Installation Method}\n F -->|npx| G[Add MCP Config to settings.json]\n F -->|global| H[Run npm install -g barevalue-mcp]\n H --> I[Add MCP Config to settings.json]\n G --> J[Restart Claude Code]\n I --> J\n J --> K[Server Ready]\n K --> L[Check with barevalue_account tool]\n```\n\n## Available Tools After Installation\n\nOnce installed and configured, the following MCP tools become available:\n\n| Tool | Purpose |\n|------|---------|\n| `barevalue_account` | Get account information and credit balance |\n| `barevalue_estimate` | Calculate order cost before submission |\n| `barevalue_upload` | Upload local audio file |\n| `barevalue_validate` | Validate external URL before submission |\n| `barevalue_submit` | Submit uploaded file for editing |\n| `barevalue_submit_url` | Submit external URL for editing |\n| `barevalue_status` | Check order status |\n| `barevalue_list_orders` | List recent orders |\n| `barevalue_webhook_*` | Webhook management tools |\n\n**Source:** [src/index.ts:54-112](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Verifying Installation\n\nAfter installation, verify the setup by checking your account balance:\n\n```\nUser: Check my Barevalue account balance\n\nClaude: [calls barevalue_account]\n\nYour account information:\n- Balance: X credits\n- Subscription: [plan name]\n- AI Minutes: [available minutes]\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `invalid_api_key` error | Ensure API key starts with `bv_sk_` |\n| Connection timeout | Check network/firewall settings |\n| Server won't start | Verify Node.js >= 18.0.0 |\n| Tools not appearing | Restart Claude Code after config changes |\n\n**Source:** [README.md:114-121](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Support\n\n- **Documentation:** https://barevalue.com/docs/api-v1\n- **Email:** support@barevalue.com\n\n**Source:** [README.md:155-156](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n---\n\n\n\n## Configuration Reference\n\n### Related Pages\n\nRelated topics: [Installation Guide](#installation), [Security](#security)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n \n\n# Configuration Reference\n\nThis page documents all configuration options available for the barevalue-mcp server, including environment variables, Claude Code integration, and runtime settings.\n\n## Overview\n\nThe barevalue-mcp server is a Model Context Protocol (MCP) server that integrates with the Barevalue AI podcast editing API. Configuration is primarily driven through environment variables and JSON configuration files for Claude Code integration.\n\n**Source:** [server.json:1-20](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n## Environment Variables\n\nThe server supports the following environment variables for configuration:\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | - | Your Barevalue API key (must start with `bv_sk_`) |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\n**Source:** [README.md:1-50](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Obtaining an API Key\n\n1. Log in to your [Barevalue account](https://barevalue.com/login)\n2. Navigate to **Settings** → **API Keys**\n3. Click **Create API Key**\n4. Copy the key (starts with `bv_sk_`)\n\n**Important:** The API key is only shown once during creation. Store it securely.\n\n**Source:** [README.md:45-60](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Claude Code Integration\n\n### Configuration File Location\n\nAdd the barevalue-mcp server to your Claude Code settings file at `~/.claude/settings.json`.\n\n**Source:** [README.md:35-45](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Option 1: NPX (Recommended)\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:1-15](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Option 2: Global Install\n\n```bash\nnpm install -g barevalue-mcp\n```\n\nThen configure with the installed command:\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"barevalue-mcp\",\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n**Source:** [README.md:20-35](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Server Metadata\n\nThe MCP server announces the following metadata to Claude Code:\n\n| Property | Value |\n|----------|-------|\n| Server Name | `io.github.quietnotion/barevalue` |\n| Display Name | `Barevalue` |\n| Version | `1.0.3` |\n| Transport | `stdio` |\n| Package | `barevalue-mcp` |\n\n**Source:** [server.json:1-25](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n## Available Tools Configuration\n\nThe server exposes the following tools, each with specific input requirements:\n\n**Source:** [src/index.ts:50-150](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n### Tool Input Schemas\n\n#### barevalue_account\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"required\": []\n}\n```\n\n**Source:** [src/index.ts:55-65](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n#### barevalue_estimate\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"duration_minutes\": {\n \"type\": \"number\",\n \"description\": \"Audio duration in minutes (1-300)\"\n }\n },\n \"required\": [\"duration_minutes\"]\n}\n```\n\n**Source:** [src/index.ts:70-85](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n#### barevalue_upload\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"file_path\": {\n \"type\": \"string\",\n \"description\": \"Path to the audio file on your local machine\"\n }\n },\n \"required\": [\"file_path\"]\n}\n```\n\n**Source:** [src/index.ts:90-105](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n#### barevalue_submit\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"order_id\": { \"type\": \"number\" },\n \"s3_key\": { \"type\": \"string\" },\n \"podcast_name\": { \"type\": \"string\" },\n \"episode_name\": { \"type\": \"string\" },\n \"episode_number\": { \"type\": \"string\" },\n \"special_instructions\": { \"type\": \"string\", \"maxLength\": 2000 },\n \"processing_style\": {\n \"type\": \"string\",\n \"enum\": [\"standard\", \"minimal\", \"aggressive\"]\n },\n \"host_names\": { \"type\": \"array\", \"items\": { \"type\": \"string\" }, \"maxItems\": 5 },\n \"guest_names\": { \"type\": \"array\", \"items\": { \"type\": \"string\" }, \"maxItems\": 10 }\n },\n \"required\": [\"order_id\", \"s3_key\", \"podcast_name\", \"episode_name\"]\n}\n```\n\n**Source:** [src/types.ts:1-30](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Security Configuration\n\n### API Key Validation\n\nThe server validates API key format on initialization:\n\n```typescript\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\n**Source:** [src/api-client.ts:20-30](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### HTTPS Enforcement\n\nNon-HTTPS connections are blocked for non-localhost URLs with a warning:\n\n```typescript\nconst isHttps = url.protocol === 'https:';\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\n**Source:** [src/api-client.ts:25-35](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Sensitive Directory Protection\n\nFile uploads are blocked from sensitive system directories:\n\n```typescript\nconst sensitivePatterns = [\n /^\\/etc\\//,\n /^\\/var\\//,\n /^\\/usr\\//,\n /^\\/root\\//,\n /[/\\\\]\\.ssh[/\\\\]/,\n /[/\\\\]\\.aws[/\\\\]/,\n /[/\\\\]\\.gnupg[/\\\\]/,\n /[/\\\\]\\.config[/\\\\]/,\n /[/\\\\]\\.env$/,\n /[/\\\\]\\.env\\./,\n];\n```\n\n**Source:** [src/api-client.ts:150-165](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## File Upload Configuration\n\n### Supported Formats\n\n| Extension | MIME Type |\n|-----------|-----------|\n| `.mp3` | audio/mpeg |\n| `.wav` | audio/wav |\n| `.m4a` | audio/mp4 |\n| `.flac` | audio/flac |\n| `.aac` | audio/aac |\n| `.ogg` | audio/ogg |\n| `.wma` | audio/x-ms-wma |\n| `.aiff` / `.aif` | audio/aiff |\n\n**Source:** [src/api-client.ts:65-85](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### File Size Limits\n\n| Limit | Value |\n|-------|-------|\n| Maximum file size | 750 MB |\n| Upload timeout | 5 minutes |\n\n**Source:** [README.md:100-110](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Presigned URL Expiration\n\nS3 presigned URLs expire after **30 minutes** for security.\n\n**Source:** [README.md:130-135](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Rate Limiting\n\n| Limit | Value |\n|-------|-------|\n| Requests per minute | 10 per API key |\n| File upload timeout | 5 minutes |\n| Order processing | 10-30 minutes typical |\n\n**Source:** [README.md:100-115](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Error Handling Configuration\n\n### Error Response Structure\n\nAll API errors follow a standardized format:\n\n```json\n{\n \"error\": \"error_code\",\n \"message\": \"Human readable description\",\n \"statusCode\": 400\n}\n```\n\n**Source:** [README.md:140-155](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Error Codes\n\n| Code | Description |\n|------|-------------|\n| `invalid_api_key` | API key is missing, invalid, or revoked |\n| `insufficient_credits` | Not enough credits or subscription minutes |\n| `validation_failed` | File failed pre-checks (not enough speech, music detected) |\n| `file_too_large` | File exceeds 750MB limit |\n| `rate_limited` | Too many requests (limit: 10/minute) |\n\n**Source:** [README.md:155-170](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Development Configuration\n\n### Local Development Setup\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Watch mode (auto-rebuild on changes)\nnpm run dev\n\n# Start production server\nnpm start\n```\n\n**Source:** [README.md:175-190](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Package Configuration\n\n| Property | Value |\n|----------|-------|\n| Package Name | barevalue-mcp |\n| Version | 1.0.3 |\n| Entry Point | dist/index.js |\n| CLI Bin | barevalue-mcp |\n| Node Requirement | >=18.0.0 |\n\n**Source:** [package.json:1-20](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Configuration Flow\n\n```mermaid\ngraph TD\n A[Start] --> B{API Key Set?}\n B -->|No| C[Error: API key required]\n B -->|Yes| D{Valid Format bv_sk_*?}\n D -->|No| E[Error: Invalid format]\n D -->|Yes| F{HTTPS URL?}\n F -->|No| G[Check: localhost?]\n G -->|No| H[Warning: Insecure transmission]\n G -->|Yes| I[Allow HTTP]\n H --> J[Initialize API Client]\n I --> J\n F -->|Yes| J\n J --> K[Connect via StdioTransport]\n K --> L[Server Ready]\n```\n\n## Quick Reference\n\n### Minimal Configuration (NPX)\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n### Environment Variables Summary\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | - | API key starting with `bv_sk_` |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Custom API endpoint |\n\n### Node.js Requirements\n\n- **Minimum version:** Node.js 18.0.0\n- **Recommended:** Latest LTS version\n\n---\n\n\n\n## System Architecture\n\n### Related Pages\n\nRelated topics: [Data Flow](#data-flow), [Project Overview](#overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n \n\n# System Architecture\n\n## Overview\n\nThe barevalue-mcp is a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with the Barevalue podcast editing API. It provides a bridge between MCP-compatible clients and the Barevalue backend services, allowing users to submit podcast files for AI editing, monitor order status, and manage webhooks through natural language commands.\n\nThe architecture follows a client-server pattern where the MCP server acts as an intermediary, translating MCP tool calls into HTTP API requests and formatting responses for consumption by the AI assistant.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"MCP Client (Claude Code)\"\n A[User Request]\n end\n \n subgraph \"Barevalue MCP Server\"\n B[MCP Server]\n C[Tool Router]\n D[Data Sanitizer]\n E[API Client]\n end\n \n subgraph \"External Services\"\n F[Barevalue API]\n G[AWS S3]\n end\n \n A --> B\n B --> C\n C --> D\n C --> E\n E --> F\n E --> G\n```\n\n## Component Architecture\n\n### Core Components\n\n| Component | File | Responsibility |\n|-----------|------|----------------|\n| MCP Server | `src/index.ts` | Entry point, request routing, tool definitions |\n| API Client | `src/api-client.ts` | HTTP communication with Barevalue API |\n| Type Definitions | `src/types.ts` | TypeScript interfaces for all data models |\n| Tool Registry | `src/index.ts` | Tool definitions and input schema validation |\n| Error Handler | `src/api-client.ts` | Custom error class and error handling |\n\n### MCP Server (`src/index.ts`)\n\nThe MCP server is built using the `@modelcontextprotocol/sdk` package and implements the server-side of the MCP protocol. It handles two primary request types: `ListToolsRequestSchema` and `CallToolRequestSchema`.\n\n**Server Initialization** (lines 1-100):\n```typescript\nconst server = new Server(\n {\n name: 'barevalue-mcp',\n version: '1.0.0',\n },\n {\n capabilities: {\n tools: {},\n },\n }\n);\n```\n\n**Request Handling Flow:**\n\n```mermaid\ngraph TD\n A[Incoming Request] --> B{Route to Handler}\n B -->|ListTools| C[Return Tool Definitions]\n B -->|CallTool| D[Extract Tool Name]\n D --> E[Extract Arguments]\n E --> F[Validate Input Schema]\n F -->|Invalid| G[Return Error]\n F -->|Valid| H[Execute Tool Handler]\n H --> I[Sanitize Output]\n I --> J[Return MCP Response]\n```\n\nThe server defines 12 tools organized into three functional categories:\n\n1. **Account & Billing Tools**\n - `barevalue_account` - Get account information\n - `barevalue_estimate` - Calculate order cost\n\n2. **Order Workflow Tools**\n - `barevalue_upload` - Upload local files\n - `barevalue_validate` - Validate external URLs\n - `barevalue_submit` - Submit for editing\n - `barevalue_submit_url` - Submit via URL\n - `barevalue_status` - Check order status\n - `barevalue_list_orders` - List recent orders\n\n3. **Webhook Management Tools**\n - `barevalue_list_webhooks` - List webhooks\n - `barevalue_create_webhook` - Create webhook\n - `barevalue_delete_webhook` - Delete webhook\n - `barevalue_webhook_rotate_secret` - Rotate webhook secret\n\n### API Client (`src/api-client.ts`)\n\nThe `BarevalueApiClient` class encapsulates all HTTP communication with the Barevalue API. It uses native Node.js `http` and `https` modules for making requests.\n\n**Class Structure:**\n\n```typescript\nexport class BarevalueApiClient {\n private readonly apiKey: string;\n private readonly baseUrl: string;\n private readonly timeout: number;\n\n constructor(apiKey: string, baseUrl?: string, timeout?: number) {\n // Initialization\n }\n \n // Request methods\n private async request(method: string, endpoint: string, body?: Record): Promise\n \n // Order methods\n async getAccount(): Promise\n async estimateCost(durationMinutes: number): Promise\n async getUploadUrl(): Promise\n async uploadFile(uploadUrl: string, filePath: string): Promise\n async validateUrl(fileUrl: string): Promise\n async submitOrder(params: SubmitParams): Promise\n async submitExternalUrl(params: SubmitUrlParams): Promise\n async getOrderStatus(orderId: number): Promise\n async listOrders(params?: ListOrdersParams): Promise\n \n // Webhook methods\n async listWebhooks(): Promise\n async createWebhook(url: string, events: string[]): Promise\n async getWebhook(webhookId: number): Promise\n async updateWebhook(webhookId: number, updates: WebhookUpdates): Promise\n async deleteWebhook(webhookId: number): Promise<{ success: boolean }>\n async rotateWebhookSecret(webhookId: number): Promise\n}\n```\n\n**HTTP Request Flow:**\n\n```mermaid\nsequenceDiagram\n participant Tool as Tool Handler\n participant Client as API Client\n participant API as Barevalue API\n participant S3 as AWS S3\n\n Tool->>Client: call method(params)\n Client->>Client: validateApiKey()\n Client->>Client: buildRequest()\n Client->>API: HTTP Request\n API-->>Client: JSON Response\n Client->>Client: checkStatusCode()\n Client-->>Tool: parsed response\n Note over Tool,Client: For uploads\n Tool->>Client: uploadFile()\n Client->>S3: Presigned URL PUT\n S3-->>Client: Upload Complete\n```\n\n**Security Features** (lines 30-40):\n\nThe API client implements several security measures:\n\n1. **API Key Validation** - Verifies keys start with `bv_sk_`\n2. **HTTPS Enforcement** - Warns if using non-HTTPS for non-localhost URLs\n3. **Timeout Protection** - Configurable request timeout (default: 5 minutes)\n4. **Error Sanitization** - Raw API responses are not exposed in error messages\n\n```typescript\n// Security: Don't expose S3 error response data\nreject(new Error(`S3 upload failed with status ${res.statusCode}`));\n\n// Security: Don't expose raw API response data in error messages\nreject(new Error('Failed to parse API response'));\n```\n\n### Error Handling Architecture\n\nThe `BarevalueApiError` class provides structured error handling:\n\n```typescript\nexport class BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n}\n```\n\n**Error Response Format:**\n\n| Error Code | Status | Meaning |\n|------------|--------|---------|\n| `invalid_api_key` | 401 | API key is missing, invalid, or revoked |\n| `insufficient_credits` | 402 | Not enough credits or subscription minutes |\n| `validation_failed` | 400 | File failed pre-checks |\n| `file_too_large` | 413 | File exceeds 750MB limit |\n| `rate_limited` | 429 | Too many requests (10/minute limit) |\n\n## Data Flow Architecture\n\n### Order Submission Flow\n\n```mermaid\ngraph LR\n A[User Request] --> B[Upload Local File]\n B --> C[Get Presigned URL]\n C --> D[Upload to S3]\n D --> E[Submit Order]\n E --> F[Get Order ID]\n F --> G[Poll Status]\n G --> H[Return Results]\n```\n\n### Complete Order Workflow\n\n```mermaid\nstateDiagram-v2\n [*] --> Uploaded: barevalue_upload\n Uploaded --> Validating: barevalue_validate (optional)\n Uploaded --> Submitting: barevalue_submit\n Validating --> Submitting: validation passed\n Validating --> [*]: validation failed\n Submitting --> Processing: order created\n Processing --> Downloading: file download\n Downloading --> Transcribing: download complete\n Transcribing --> Editing: transcription complete\n Editing --> Completed: editing finished\n Completed --> [*]\n Processing --> Failed: error occurred\n Failed --> Refunded: refund processed\n Refunded --> [*]\n```\n\n## Type System Architecture\n\n### Response Types (`src/types.ts`)\n\nThe type system is organized into response types and input types:\n\n**Account Information:**\n```typescript\ninterface AccountInfo {\n user: {\n id: number;\n email: string;\n name: string | null;\n is_verified: boolean;\n locale: string;\n };\n credits: {\n balance: number;\n currency: string;\n };\n ai_subscription: {\n tier: string | null;\n status: string | null;\n minutes_limit: number | null;\n minutes_used: number | null;\n minutes_remaining: number | null;\n period_end: string | null;\n pending_tier: string | null;\n } | null;\n ai_bonus_minutes: {\n balance: number;\n expires_at: string | null;\n };\n pricing: {\n audio_per_minute: number;\n currency: string;\n };\n}\n```\n\n**Order Status:**\n```typescript\ninterface OrderStatus {\n order_id: number;\n status: 'pending' | 'downloading' | 'processing' | 'transcribing' | 'editing' | 'completed' | 'failed' | 'refunded';\n created_at: string;\n updated_at: string;\n // Present when completed\n edited_audio_url?: string;\n transcript_pdf_url?: string;\n transcript_docx_url?: string;\n show_notes_url?: string;\n}\n```\n\n### Tool Input Schemas\n\nEach tool has a corresponding input schema defined in the tool definition:\n\n| Tool | Required Parameters | Optional Parameters |\n|------|---------------------|---------------------|\n| `barevalue_estimate` | `duration_minutes` | - |\n| `barevalue_upload` | `file_path` | `filename` |\n| `barevalue_validate` | `file_url` | - |\n| `barevalue_submit` | `order_id`, `s3_key`, `podcast_name`, `episode_name` | `episode_number`, `special_instructions`, `processing_style`, `host_names`, `guest_names` |\n| `barevalue_submit_url` | `file_url`, `podcast_name`, `episode_name` | `episode_number`, `special_instructions`, `processing_style`, `host_names`, `guest_names` |\n| `barevalue_status` | `order_id` | - |\n| `barevalue_list_orders` | - | `page`, `per_page`, `status` |\n| `barevalue_create_webhook` | `url`, `events` | - |\n| `barevalue_delete_webhook` | `webhook_id` | - |\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | - | API key (starts with `bv_sk_`) |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\n### MCP Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n## Data Sanitization\n\nThe server implements input sanitization to prevent injection attacks. The `sanitizeString` function handles string escaping:\n\n```typescript\nfunction sanitizeString(input: unknown): string {\n if (typeof input !== 'string') return '';\n return input\n .replace(/[<>]/g, '')\n .slice(0, 10000);\n}\n```\n\nThis sanitization is applied to:\n- Error messages\n- Tool output data\n- Key-value pairs in objects\n\n## Transport Layer\n\nThe MCP server uses STDIO transport for communication with the client:\n\n```typescript\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\nThis architecture allows:\n- Standard input/output based communication\n- No network configuration required\n- Easy integration with CLI tools and AI assistants\n\n## Build and Development\n\n| Command | Purpose |\n|---------|---------|\n| `npm install` | Install dependencies |\n| `npm run build` | Compile TypeScript to JavaScript |\n| `npm run dev` | Watch mode compilation |\n| `npm start` | Run compiled server |\n| `npm run prepublishOnly` | Build before npm publish |\n\nSource: [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n\n## Summary\n\nThe barevalue-mcp system architecture consists of three primary layers:\n\n1. **Presentation Layer** - MCP tool definitions and request handling in `src/index.ts`\n2. **Business Logic Layer** - API client with security features and error handling in `src/api-client.ts`\n3. **Type Layer** - TypeScript interfaces for type safety in `src/types.ts`\n\nThe architecture prioritizes security through API key validation, HTTPS enforcement, and response sanitization, while maintaining a clean separation of concerns that facilitates testing and maintenance.\n\n---\n\n\n\n## Data Flow\n\n### Related Pages\n\nRelated topics: [System Architecture](#system-architecture), [Order Workflow Tools](#order-workflow)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n \n\n# Data Flow\n\nThis document describes the data flow architecture of the barevalue-mcp server, covering how data moves from the client through the MCP protocol layer, through the API client, and ultimately to the Barevalue API.\n\n## Overview\n\nThe barevalue-mcp server implements a Model Context Protocol (MCP) server that acts as a bridge between AI assistants (like Claude Code) and the Barevalue podcast editing API. Data flows through several distinct layers, each with specific responsibilities for validation, transformation, and security. Source: [src/index.ts:1-200](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Architecture Layers\n\nThe data flow consists of four primary layers:\n\n| Layer | Component | Responsibility |\n|-------|-----------|----------------|\n| Transport | StdioServerTransport | JSON-RPC communication with MCP client |\n| Protocol | Server (MCP SDK) | Request routing and capability negotiation |\n| Application | Tool Handlers | Business logic and data transformation |\n| External | ApiClient | HTTP communication with Barevalue API |\n\nSource: [src/index.ts:280-320](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Request Flow\n\n```mermaid\ngraph TD\n A[\"MCP Client
(Claude Code)\"] --> B[\"StdioServerTransport\"]\n B --> C[\"Server
MCP Protocol Handler\"]\n C --> D[\"handleToolCall
Router\"]\n D --> E1[\"Account Handler\"]\n D --> E2[\"Estimate Handler\"]\n D --> E3[\"Upload Handler\"]\n D --> E4[\"Submit Handler\"]\n D --> E5[\"Status Handler\"]\n D --> E6[\"Webhook Handler\"]\n E1 --> F[\"ApiClient\"]\n E2 --> F\n E3 --> F\n E4 --> F\n E5 --> F\n E6 --> F\n F --> G[\"Barevalue API\"]\n G --> F\n F --> H[\"sanitizeData\"]\n H --> I[\"MCP Response\"]\n I --> B\n B --> A\n```\n\n### Step-by-Step Data Flow\n\n1. **Client Request**: The MCP client sends a JSON-RPC request via stdio containing the tool name and arguments.\n2. **Transport Reception**: The StdioServerTransport receives the raw JSON-RPC message.\n3. **Protocol Parsing**: The MCP Server parses the request and extracts tool name and parameters.\n4. **Routing**: The `handleToolCall` function routes to the appropriate handler based on the tool name.\n5. **Handler Processing**: Each handler invokes the corresponding ApiClient method.\n6. **API Communication**: The ApiClient makes HTTP requests to the Barevalue API.\n7. **Data Sanitization**: All responses pass through `sanitizeData` before being returned.\n8. **Response Serialization**: The server serializes the response as JSON-RPC and sends it back.\n\nSource: [src/index.ts:220-280](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Input Data Sanitization\n\nAll incoming data undergoes sanitization before processing. The `sanitizeData` function recursively processes data structures to prevent injection attacks and ensure consistent formatting.\n\n```typescript\nfunction sanitizeData(data: unknown): unknown {\n if (typeof data === 'string') {\n return sanitizeString(data);\n }\n if (Array.isArray(data)) {\n return data.map(sanitizeData);\n }\n if (data !== null && typeof data === 'object') {\n const result: Record = {};\n for (const [key, value] of Object.entries(data)) {\n result[sanitizeString(key)] = sanitizeData(value);\n }\n return result;\n }\n return data;\n}\n```\n\nSource: [src/index.ts:10-26](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\nThe sanitization process:\n- Recursively processes all strings using `sanitizeString`\n- Maps over arrays applying sanitization to each element\n- Creates new objects with sanitized keys and values\n- Returns primitives unchanged\n\n## API Client Data Flow\n\nThe ApiClient class manages all external API communication. It handles authentication, request construction, response parsing, and error handling.\n\n```mermaid\ngraph LR\n A[\"Tool Handler\"] --> B[\"ApiClient.request\"]\n B --> C[\"URL Construction\"]\n C --> D[\"HTTPS Request\"]\n D --> E[\"Response Parser\"]\n E -->|Success| F[\"Typed Response\"]\n E -->|Error| G[\"BarevalueApiError\"]\n F --> H[\"Tool Handler\"]\n G --> H\n```\n\n### Request Construction\n\nThe `request` method constructs HTTP requests with the following components:\n\n| Component | Value | Purpose |\n|-----------|-------|---------|\n| Authorization | `Bearer ${apiKey}` | API authentication |\n| Content-Type | `application/json` | Request body format |\n| Accept | `application/json` | Response format |\n| User-Agent | `barevalue-mcp/1.0.0` | Client identification |\n| Timeout | 30000ms | Request timeout |\n\nSource: [src/api-client.ts:120-150](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### URL Resolution\n\nThe base URL defaults to `https://barevalue.com/api/v1` but can be overridden via the `BAREVALUE_API_URL` environment variable. The request method constructs the full URL by appending the endpoint:\n\n```typescript\nconst cleanEndpoint = endpoint.startsWith('/') ? endpoint.slice(1) : endpoint;\nconst cleanBase = this.baseUrl.endsWith('/') ? this.baseUrl : this.baseUrl + '/';\nconst fullUrl = cleanBase + cleanEndpoint;\n```\n\nSource: [src/api-client.ts:95-105](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## File Upload Flow\n\nFile uploads follow a two-phase process: first obtaining a presigned URL, then uploading directly to S3.\n\n```mermaid\nsequenceDiagram\n participant C as Tool Handler\n participant AC as ApiClient\n participant BV as Barevalue API\n participant S3 as AWS S3\n\n C->>AC: uploadFile(filePath)\n AC->>BV\nError with Openai API: output new_sensitive (1027)\n\nPlease check that you have set the OPENAI_API_KEY environment variable with a valid API key.\n\n---\n\n\n\n## Account and Billing Tools\n\n### Related Pages\n\nRelated topics: [Order Workflow Tools](#order-workflow), [Error Handling and Rate Limits](#error-handling)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n \n\n# Account and Billing Tools\n\nThe Account and Billing Tools constitute the foundational layer of the Barevalue MCP server, providing essential functionality for monitoring account resources, checking credit balances, and estimating order costs before submission. These tools enable AI assistants to make informed decisions about podcast editing orders by providing real-time visibility into account status and available resources.\n\n## Overview\n\nThe Account and Billing module consists of two primary MCP tools that interact with the Barevalue API's account endpoints:\n\n| Tool Name | Purpose | API Endpoint |\n|-----------|---------|--------------|\n| `barevalue_account` | Retrieve comprehensive account information including balance and subscription status | `GET /account` |\n| `barevalue_estimate` | Calculate cost breakdown for a potential order based on audio duration | `POST /orders/estimate` |\n\nThese tools are designed to support the typical workflow pattern where an AI assistant checks available resources before uploading and submitting podcast files for AI editing. By providing cost estimation before submission, users can avoid the `insufficient_credits` error that results from attempting orders without adequate resources.\n\n## Architecture\n\nThe Account and Billing module follows a layered architecture where MCP tool definitions in the presentation layer delegate to the API client layer, which handles HTTP communication with the Barevalue API.\n\n```mermaid\ngraph TD\n A[MCP Client
e.g., Claude Code] --> B[Tool Handler
src/index.ts]\n B --> C[API Client
src/api-client.ts]\n C --> D[Barevalue API
barevalue.com/api/v1]\n \n B --> B1[barevalue_account tool]\n B --> B2[barevalue_estimate tool]\n \n C --> C1[getAccount method]\n C --> C2[estimate method]\n \n D --> D1[/account endpoint]\n D --> D2[/orders/estimate endpoint]\n \n B1 -->|\"Empty input schema\"| B\n B2 -->|\"duration_minutes\"| B\n```\n\n### Data Flow\n\nThe following sequence illustrates how account information flows through the system when an AI assistant queries the account status:\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Server as MCP Server\n participant APIClient as API Client\n participant API as Barevalue API\n \n Client->>Server: barevalue_account()\n Server->>APIClient: getAccount()\n APIClient->>API: GET /account
Authorization: Bearer \n API-->>APIClient: AccountInfo JSON\n APIClient-->>Server: AccountInfo object\n Server-->>Client: AccountInfo JSON\n```\n\n## Tool Specifications\n\n### barevalue_account\n\nThe `barevalue_account` tool retrieves complete account information for the authenticated user, including credit balances, AI subscription details, and current pricing information.\n\n#### Input Schema\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"required\": []\n}\n```\n\nThis tool accepts no input parameters. The authenticated user is determined by the `BAREVALUE_API_KEY` environment variable configured during server setup. Source: [src/index.ts:30-38](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts#L30-L38)\n\n#### Return Type\n\nThe tool returns an `AccountInfo` object containing the following structure:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `user` | `User` | User profile information |\n| `credits` | `Credits` | Standard credit balance |\n| `ai_subscription` | `AISubscription \\| null` | AI editing subscription details |\n| `ai_bonus_minutes` | `AIBonusMinutes` | Promotional bonus minutes balance |\n| `pricing` | `Pricing` | Current pricing information |\n\nSource: [src/types.ts:9-38](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts#L9-L38)\n\n#### User Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | `number` | Unique user identifier |\n| `email` | `string` | User's email address |\n| `name` | `string \\| null` | Display name if set |\n| `is_verified` | `boolean` | Whether the account is verified |\n| `locale` | `string` | User's preferred locale |\n\n#### Credits Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `balance` | `number` | Available credit amount |\n| `currency` | `string` | Currency code (e.g., \"USD\") |\n\n#### AI Subscription Object\n\nThe `ai_subscription` field may be `null` for users without an AI subscription. When present, it contains:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `tier` | `string \\| null` | Subscription tier name |\n| `status` | `string \\| null` | Subscription status |\n| `minutes_limit` | `number \\| null` | Monthly minute allowance |\n| `minutes_used` | `number \\| null` | Minutes consumed this period |\n| `minutes_remaining` | `number \\| null` | Minutes left in current period |\n| `period_end` | `string \\| null` | ISO 8601 end date of billing period |\n| `pending_tier` | `string \\| null` | Upcoming tier if upgrade is scheduled |\n\n#### AI Bonus Minutes Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `balance` | `number` | Available bonus minutes |\n| `expires_at` | `string \\| null` | Expiration date for bonus minutes |\n\n#### Pricing Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `audio_per_minute` | `number` | Cost per audio minute (for informational purposes) |\n| `currency` | `string` | Currency code |\n\n### barevalue_estimate\n\nThe `barevalue_estimate` tool calculates a detailed cost breakdown for a potential podcast editing order based on the audio duration. This tool is essential for preventing `insufficient_credits` errors before submitting orders.\n\n#### Input Schema\n\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"duration_minutes\": {\n \"type\": \"number\",\n \"description\": \"Audio duration in minutes (1-300)\"\n }\n },\n \"required\": [\"duration_minutes\"]\n}\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `duration_minutes` | `number` | Yes | Duration of the audio file in minutes, between 1 and 300 |\n\nSource: [src/index.ts:40-53](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts#L40-L53)\n\n#### Return Type\n\nThe tool returns an `EstimateResponse` object:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `duration_minutes` | `number` | The requested duration |\n| `can_afford` | `boolean` | Whether the user can afford the order |\n| `minutes_available` | `MinutesBreakdown` | Available minutes by category |\n| `minutes_applied` | `MinutesBreakdown` | Minutes that will be consumed |\n| `minutes_remaining_after` | `number` | Total minutes remaining after order |\n| `subscription_tier` | `string` | Current subscription tier name |\n\nSource: [src/types.ts:40-66](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts#L40-L66)\n\n#### Conditional Fields\n\nThe following fields are only present when `can_afford` is `false`:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `minutes_short` | `number` | How many minutes short the user is |\n| `upgrade_required` | `boolean` | Whether an upgrade is needed |\n| `message` | `string` | Human-readable explanation |\n| `available_upgrades` | `UpgradeOption[]` | Available subscription upgrades |\n\n#### Minutes Breakdown Object\n\nBoth `minutes_available` and `minutes_applied` contain:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `bonus` | `number` | AI bonus minutes |\n| `student` | `number` | Student plan minutes (if applicable) |\n| `subscription` | `number` | Subscription minutes |\n| `total` | `number` | Total minutes |\n\n#### Upgrade Option Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | `string` | Plan name |\n| `minutes_limit` | `number` | Monthly minute allowance |\n| `price_monthly` | `number` | Monthly price |\n\n## API Client Implementation\n\nThe API client layer provides the underlying HTTP communication for the Account and Billing tools. The implementation is located in `src/api-client.ts`.\n\n### getAccount Method\n\n```typescript\nasync getAccount(): Promise {\n return this.request('GET', '/account');\n}\n```\n\nThe `getAccount` method performs a simple GET request to the `/account` endpoint, passing the Bearer token authentication header. Source: [src/api-client.ts:180-183](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L180-L183)\n\n### estimate Method\n\n```typescript\nasync estimate(durationMinutes: number): Promise {\n return this.request('POST', '/orders/estimate', {\n duration_minutes: durationMinutes,\n });\n}\n```\n\nThe `estimate` method performs a POST request to the `/orders/estimate` endpoint with the duration parameter in the request body. Source: [src/api-client.ts:186-192](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L186-L192)\n\n### HTTP Request Handling\n\nThe API client uses Node.js built-in `http` and `https` modules for HTTP communication. Key security features include:\n\n- Bearer token authentication via the `Authorization` header\n- HTTPS enforcement warning for non-localhost connections\n- JSON request/response handling\n- Configurable request timeout (default 5 minutes)\n- Comprehensive error handling with structured `BarevalueApiError` responses\n\n## Usage Patterns\n\n### Pre-Order Balance Check\n\nThe most common usage pattern involves checking the account balance before submitting a podcast for editing:\n\n```mermaid\ngraph TD\n A[Start] --> B[Call barevalue_account]\n B --> C{Response received}\n C -->|Success| D[Check credits and minutes]\n C -->|Failure| E[Handle error]\n D --> F{Sufficient resources?}\n F -->|Yes| G[Proceed to upload]\n F -->|No| H[Inform user]\n H --> I[Suggest upgrade or wait]\n G --> J[Upload file]\n J --> K[Submit order]\n```\n\n### Pre-Order Cost Estimation\n\nBefore uploading a file, users can estimate costs to understand the resource consumption:\n\n```\nUser: I want to edit a 45-minute podcast episode\n\nClaude: [calls barevalue_estimate duration_minutes=45]\n\nBased on your 45-minute episode:\n- Minutes to be used: 45\n- Available: 120 minutes (bonus + subscription)\n- Remaining after: 75 minutes\n- Can afford: Yes\n```\n\n### Workflow with Insufficient Credits\n\nWhen a user lacks sufficient resources, the estimation provides upgrade options:\n\n```\nUser: Edit this podcast: /path/to/episode.mp3\n\nClaude: [calls barevalue_estimate duration_minutes=32]\n\nEstimate Result:\n- Minutes required: 32\n- Minutes available: 18\n- Short by: 14 minutes\n\nAvailable upgrades:\n| Plan | Monthly Minutes | Price |\n|------|-----------------|-------|\n| Pro | 60 | $29/mo |\n| Team | 150 | $79/mo |\n\nWould you like me to help you upgrade your plan first?\n```\n\n## Rate Limits and Security\n\n### Rate Limits\n\nThe Account and Billing tools share the global rate limit of the MCP server:\n\n| Limit | Value |\n|-------|-------|\n| Requests per minute | 10 |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Security Considerations\n\nThe Account and Billing module implements several security measures:\n\n1. **API Key Protection**: The API key is transmitted exclusively via the `Authorization` header using the Bearer token scheme. Source: [src/api-client.ts:63-69](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L63-L69)\n\n2. **Environment Variable Storage**: API keys must be stored in environment variables, never hardcoded. This is enforced through the server configuration in `server.json`:\n\n```json\n{\n \"environmentVariables\": [\n {\n \"name\": \"BAREVALUE_API_KEY\",\n \"isSecret\": true,\n \"format\": \"string\"\n }\n ]\n}\n```\n\nSource: [server.json:17-24](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json#L17-L24)\n\n3. **HTTPS Enforcement**: The API client warns users when connecting over non-HTTPS connections (except localhost for development):\n\n```typescript\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\nSource: [src/api-client.ts:42-45](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L42-L45)\n\n## Error Handling\n\nThe Account and Billing tools may encounter the following errors:\n\n| Error Code | Description | HTTP Status |\n|------------|-------------|-------------|\n| `invalid_api_key` | API key is missing, invalid, or revoked | 401/403 |\n| `rate_limited` | Too many requests (limit: 10/minute) | 429 |\n| `server_error` | Internal server error | 500 |\n\nErrors are wrapped in the custom `BarevalueApiError` class, which provides structured error information:\n\n```typescript\nexport class BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n}\n```\n\nSource: [src/api-client.ts:238-248](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L238-L248)\n\n## Configuration\n\n### Required Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BAREVALUE_API_KEY` | Yes | Barevalue API key (starts with `bv_sk_`) |\n| `BAREVALUE_API_URL` | No | Override API base URL (default: `https://barevalue.com/api/v1`) |\n\n### MCP Server Configuration\n\nTo use the Account and Billing tools, configure the MCP server in your Claude Code settings (`~/.claude/settings.json`):\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Summary\n\nThe Account and Billing Tools provide essential functionality for managing Barevalue resources through the MCP interface:\n\n| Component | Description |\n|-----------|-------------|\n| `barevalue_account` | Retrieves full account information including user details, credit balance, AI subscription status, bonus minutes, and pricing |\n| `barevalue_estimate` | Calculates cost breakdown for orders, showing available minutes, consumption by category, and potential upgrade options |\n| API Client | Handles HTTP communication with Bearer token authentication, HTTPS enforcement, and structured error handling |\n\nThese tools enable AI assistants to perform informed resource management, preventing failed orders due to insufficient credits and providing users with clear visibility into their account status and consumption patterns.\n\n---\n\n\n\n## Order Workflow Tools\n\n### Related Pages\n\nRelated topics: [Account and Billing Tools](#account-tools), [Data Flow](#data-flow), [Webhook Management](#webhook-management)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n \n\n# Order Workflow Tools\n\n## Overview\n\nThe Order Workflow Tools provide the core functionality for submitting podcast audio files to the Barevalue AI editing service and monitoring their processing status. These tools form the primary interface for the audio editing pipeline, enabling users to upload local files, validate external URLs, submit orders for processing, and track completion.\n\nThe workflow consists of six primary MCP tools that handle the complete lifecycle of an editing order from initial upload through final delivery. Each tool corresponds to specific API endpoints in the underlying `BarevalueApiClient` class, which manages HTTP communication with the Barevalue API.\n\nSource: [src/index.ts:36-170](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User] --> B[barevalue_upload
or barevalue_validate]\n B --> C{File Source}\n C -->|Local File| D[Get Presigned S3 URL]\n C -->|External URL| E[Validate File]\n D --> F[Upload to S3]\n E --> G{Validation Result}\n G -->|Pass| H[barevalue_submit
or barevalue_submit_url]\n G -->|Fail| Z[Error: validation_failed]\n F --> H\n H --> I[Order Created
Status: pending]\n I --> J[barevalue_status]\n J --> K{Processing State}\n K -->|pending| L[Downloading]\n K -->|processing| M[Transcribing
+ Editing]\n K -->|completed| N[Deliverables Ready]\n K -->|failed| O[Error Response]\n N --> P[barevalue_list_orders
for history]\n```\n\nThe `BarevalueApiClient` class encapsulates all API interactions and provides type-safe methods for each endpoint. It handles authentication via Bearer tokens, manages request timeouts, and implements error handling with custom `BarevalueApiError` exceptions.\n\nSource: [src/api-client.ts:1-80](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## File Upload Tool\n\n### barevalue_upload\n\nUploads a local audio file to S3 storage using a presigned URL mechanism. This tool handles the two-step upload process: first requesting a presigned URL from the API, then uploading the file directly to S3.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `file_path` | `string` | Yes | Absolute path to the local audio file |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `order_id` | `number` | Numeric identifier for tracking |\n| `s3_key` | `string` | S3 storage key for submission |\n| `upload_url` | `string` | Presigned URL for direct upload |\n\n**Supported Formats:** mp3, wav, m4a, flac, aac, ogg\n\n**Maximum File Size:** 750MB\n\nSource: [src/index.ts:66-80](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\nSource: [src/api-client.ts:145-180](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Content Type Mapping\n\nThe client automatically detects file format from extension and sets appropriate MIME types:\n\n| Extension | Content-Type |\n|-----------|--------------|\n| `.mp3` | audio/mpeg |\n| `.wav` | audio/wav |\n| `.m4a` | audio/mp4 |\n| `.flac` | audio/flac |\n| `.aac` | audio/aac |\n| `.ogg` | audio/ogg |\n| `.wma` | audio/x-ms-wma |\n| `.aiff` / `.aif` | audio/aiff |\n\nSource: [src/api-client.ts:195-210](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## File Validation Tool\n\n### barevalue_validate\n\nPerforms pre-submission validation on files hosted at external URLs. This tool checks speech content percentage and detects music-only files without consuming credits.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `file_url` | `string` | Yes | Public URL to the audio file |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `valid` | `boolean` | Whether the file passes validation |\n| `speech_detected` | `number` | Percentage of speech content (minimum 10% required) |\n| `music_only` | `boolean` | Whether music-only content was detected |\n| `duration_minutes` | `number` | Total audio duration |\n\n**Note:** This tool is for external URLs only. Files uploaded via `barevalue_upload` do not require validation.\n\nSource: [src/index.ts:82-95](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\nSource: [README.md:85-95](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n```mermaid\ngraph LR\n A[External URL] --> B[POST /orders/validate]\n B --> C{Validation Rules}\n C -->|Speech ≥ 10%| D[✓ Valid]\n C -->|Speech < 10%| E[✗ validation_failed]\n C -->|Music only| E\n```\n\n## Order Submission Tools\n\n### barevalue_submit\n\nSubmits an order for processing using a file previously uploaded via `barevalue_upload`. This is the final step that triggers the AI editing pipeline.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `order_id` | `number` | Yes | Order ID from upload step |\n| `s3_key` | `string` | Yes | S3 key from upload step |\n| `podcast_name` | `string` | Yes | Name of the podcast |\n| `episode_name` | `string` | Yes | Name of this episode |\n| `episode_number` | `string` | No | Episode number for organization |\n| `special_instructions` | `string` | No | Custom editing instructions (max 2000 chars) |\n| `processing_style` | `string` | No | `standard`, `minimal`, or `aggressive` |\n| `host_names` | `string[]` | No | Array of host names (max 5) |\n| `guest_names` | `string[]` | No | Array of guest names (max 10) |\n\nSource: [src/index.ts:97-130](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n**Processing Styles:**\n\n| Style | Description |\n|-------|-------------|\n| `standard` | Default editing level |\n| `minimal` | Light editing, preserves more original content |\n| `aggressive` | Heavy editing, removes more filler |\n\n### barevalue_submit_url\n\nSubmits an order directly from an external URL without requiring a separate upload step. Combines validation and submission in one operation.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `file_url` | `string` | Yes | Public URL to the audio file |\n| `podcast_name` | `string` | Yes | Name of the podcast |\n| `episode_name` | `string` | Yes | Name of this episode |\n| `episode_number` | `string` | No | Episode number |\n| `special_instructions` | `string` | No | Custom editing instructions |\n| `processing_style` | `string` | No | `standard`, `minimal`, or `aggressive` |\n| `host_names` | `string[]` | No | Host names for speaker labels |\n| `guest_names` | `string[]` | No | Guest names for speaker labels |\n\n**Response Fields:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `order_id` | `number` | Assigned order identifier |\n| `status` | `string` | Current order status |\n| `cost_breakdown` | `object` | AI minutes, credits, and payment details |\n| `estimated_completion` | `string` | ISO timestamp for expected completion |\n\nSource: [src/types.ts:45-60](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Order Status Tools\n\n### barevalue_status\n\nRetrieves the current processing state of an order and provides download URLs when processing is complete.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `order_id` | `number` | Yes | Order ID to check |\n\n**Order Status Values:**\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Order received, awaiting download |\n| `downloading` | Fetching source file from S3/URL |\n| `processing` | Initial processing phase |\n| `transcribing` | Converting speech to text |\n| `editing` | AI editing in progress |\n| `completed` | Processing finished, deliverables ready |\n| `failed` | Processing error occurred |\n| `refunded` | Order was refunded |\n\nSource: [src/types.ts:62-80](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n**Response with Downloads (when completed):**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `order_id` | `number` | Order identifier |\n| `status` | `string` | Current status |\n| `podcast_name` | `string` | Podcast name |\n| `episode_name` | `string` | Episode name |\n| `duration_minutes` | `number` | Audio duration |\n| `downloads.edited_audio` | `string` | URL to edited audio file |\n| `downloads.transcript_pdf` | `string` | URL to PDF transcript |\n| `downloads.transcript_docx` | `string` | URL to Word transcript |\n| `downloads.show_notes` | `string` | URL to show notes (nullable) |\n| `error` | `object` | Error details if failed |\n\nSource: [src/index.ts:132-150](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n### barevalue_list_orders\n\nRetrieves a paginated list of recent orders with optional status filtering.\n\n**Input Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `page` | `number` | No | 1 | Page number |\n| `per_page` | `number` | No | 20 | Results per page (max 100) |\n| `status` | `string` | No | - | Filter: `pending`, `processing`, `completed`, `failed` |\n\n**Response Structure:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `orders` | `OrderListItem[]` | Array of order summaries |\n| `pagination.page` | `number` | Current page |\n| `pagination.per_page` | `number` | Items per page |\n| `pagination.total` | `number` | Total matching orders |\n| `pagination.total_pages` | `number` | Total pages available |\n\n**Order List Item Fields:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `order_id` | `number` | Order identifier |\n| `status` | `string` | Current status |\n| `podcast_name` | `string` | Podcast name |\n| `episode_name` | `string` | Episode name |\n| `duration_minutes` | `number` | Audio duration |\n| `created_at` | `string` | ISO timestamp |\n| `completed_at` | `string` | ISO timestamp or null |\n\nSource: [src/index.ts:152-175](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\nSource: [src/types.ts:82-95](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n\n## Complete Workflow Patterns\n\n### Local File Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as barevalue-mcp\n participant API as Barevalue API\n participant S3 as AWS S3\n\n User->>MCP: barevalue_upload(file_path)\n MCP->>API: GET /orders/upload-url\n API->>S3: Generate presigned URL\n S3-->>API: Presigned URL\n API-->>MCP: {order_id, s3_key, upload_url}\n MCP->>S3: PUT file to presigned URL\n S3-->>MCP: 200 OK\n MCP-->>User: {order_id, s3_key}\n\n User->>MCP: barevalue_submit(params)\n MCP->>API: POST /orders/submit\n API-->>MCP: {order_id, status, estimated_completion}\n MCP-->>User: Order submitted\n\n loop Poll until completed\n User->>MCP: barevalue_status(order_id)\n MCP->>API: GET /orders/{id}\n API-->>MCP: {status, downloads?}\n MCP-->>User: Current status\n end\n```\n\n### External URL Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as barevalue-mcp\n participant API as Barevalue API\n\n User->>MCP: barevalue_validate(file_url)\n MCP->>API: POST /orders/validate\n API-->>MCP: {valid, speech_detected, duration}\n MCP-->>User: Validation result\n\n alt Validation passed\n User->>MCP: barevalue_submit_url(params)\n MCP->>API: POST /orders/submit\n API-->>MCP: {order_id, status}\n MCP-->>User: Order submitted\n else Validation failed\n MCP-->>User: Error: validation_failed\n end\n```\n\n## Error Handling\n\nThe API client throws `BarevalueApiError` for failed requests with structured error responses:\n\n```typescript\nexport class BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n}\n```\n\n**Common Error Codes:**\n\n| Error Code | HTTP Status | Description |\n|------------|-------------|-------------|\n| `invalid_api_key` | 401 | API key missing, invalid, or revoked |\n| `insufficient_credits` | 402 | Not enough credits or subscription minutes |\n| `validation_failed` | 400 | File failed pre-checks (insufficient speech or music-only) |\n| `file_too_large` | 413 | File exceeds 750MB limit |\n| `rate_limited` | 429 | Too many requests (limit: 10/minute) |\n\nSource: [src/api-client.ts:90-120](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\nSource: [README.md:55-65](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Rate Limits\n\n| Limit | Value |\n|-------|-------|\n| Requests per minute | 10 per API key |\n| File upload timeout | 5 minutes |\n| Order processing | 10-30 minutes typical |\n\n## Security Considerations\n\nThe API client implements several security measures:\n\n1. **API Key Validation**: Keys must start with `bv_sk_` prefix\n2. **HTTPS Enforcement**: Warns when using non-HTTPS for non-localhost connections\n3. **S3 Upload Security**: Presigned URLs expire after 30 minutes\n4. **Error Sanitization**: Raw API responses are not exposed in error messages\n5. **Timeout Protection**: All requests have configurable timeouts\n\nSource: [src/api-client.ts:40-60](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n---\n\n\n\n## Webhook Management\n\n### Related Pages\n\nRelated topics: [Order Workflow Tools](#order-workflow), [Error Handling and Rate Limits](#error-handling)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [test-webhooks.js](https://github.com/quietnotion/barevalue-mcp/blob/main/test-webhooks.js)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n \n\n# Webhook Management\n\n## Overview\n\nWebhook Management in barevalue-mcp provides a comprehensive system for subscribing to and receiving real-time notifications about order lifecycle events. The MCP server exposes five distinct webhook management tools that allow clients to create, read, update, delete, and rotate secrets for webhooks configured against the Barevalue API.\n\nWebhooks serve as the primary mechanism for asynchronous order status notifications. When orders complete, fail, or are refunded, the Barevalue API delivers signed HTTP POST payloads to registered webhook endpoints, enabling automated downstream processing without polling. Source: [src/api-client.ts:109-134]()\n\n## Architecture\n\n### Component Overview\n\nThe webhook management system consists of three primary layers:\n\n1. **API Client Layer** (`BarevalueApiClient`) - Handles HTTP communication with the Barevalue API\n2. **Tool Definition Layer** (`src/index.ts`) - Exposes MCP-compatible tool interfaces\n3. **Type System** (`src/types.ts`) - Provides TypeScript interfaces for type safety\n\n### Data Flow\n\n```mermaid\ngraph TD\n A[MCP Client] -->|barevalue_webhook_*| B[barevalue-mcp Server]\n B -->|HTTP Request| C[Barevalue API]\n C -->|Webhook Payload| D[Client Endpoint]\n D -->|HMAC Verification| E[Process Event]\n \n F[Order Events] -->|triggers| C\n G[order.completed] --> F\n H[order.failed] --> F\n I[order.refunded] --> F\n```\n\n### Tool-to-API Mapping\n\n| MCP Tool | HTTP Method | API Endpoint | Source |\n|----------|-------------|--------------|--------|\n| `barevalue_webhooks_list` | GET | `/webhooks` | [src/index.ts:89-97]() |\n| `barevalue_webhook_create` | POST | `/webhooks` | [src/index.ts:99-123]() |\n| `barevalue_webhook_update` | PATCH | `/webhooks/{id}` | [src/index.ts:125-151]() |\n| `barevalue_webhook_delete` | DELETE | `/webhooks/{id}` | [src/index.ts:153-167]() |\n| `barevalue_webhook_rotate_secret` | POST | `/webhooks/{id}/rotate-secret` | [src/index.ts:169-189]() |\n\n## Available Webhook Events\n\nThe Barevalue API supports three distinct event types that clients can subscribe to:\n\n| Event | Description | Trigger Condition |\n|-------|-------------|-------------------|\n| `order.completed` | Order finished processing | AI editing completed successfully |\n| `order.failed` | Order processing failed | Error during processing or validation |\n| `order.refunded` | Order was refunded | Credit reversal processed |\n\nSource: [src/index.ts:108-112]()\n\n## Data Models\n\n### Webhook Interface\n\n```typescript\ninterface Webhook {\n id: number;\n url: string;\n events: string[];\n is_active: boolean;\n failure_count: number;\n last_triggered_at: string | null;\n created_at: string;\n secret?: string; // Only returned on create\n}\n```\n\nSource: [src/types.ts:67-76]()\n\n### WebhookListResponse Interface\n\n```typescript\ninterface WebhookListResponse {\n webhooks: Webhook[];\n}\n```\n\nSource: [src/types.ts:78-80]()\n\n### Input Type Definitions\n\n```typescript\ninterface WebhookCreateInput {\n url: string;\n events: string[];\n}\n\ninterface WebhookUpdateInput {\n webhook_id: number;\n url?: string;\n events?: string[];\n is_active?: boolean;\n}\n\ninterface WebhookDeleteInput {\n webhook_id: number;\n}\n\ninterface WebhookRotateSecretInput {\n webhook_id: number;\n}\n```\n\nSource: [src/types.ts:121-143]()\n\n## Tool Specifications\n\n### List Webhooks\n\nRetrieves all configured webhooks for the authenticated account.\n\n**Tool Name:** `barevalue_webhooks_list`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {},\n \"required\": []\n}\n```\n\n**Behavior:** Returns an array of all webhooks including their URLs, subscribed events, active status, failure counts, and timestamps. The `secret` field is omitted for security reasons. Source: [src/index.ts:89-97]()\n\n### Create Webhook\n\nRegisters a new webhook endpoint to receive event notifications.\n\n**Tool Name:** `barevalue_webhook_create`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"url\": {\n \"type\": \"string\",\n \"description\": \"HTTPS URL to receive webhook payloads\"\n },\n \"events\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"string\",\n \"enum\": [\"order.completed\", \"order.failed\", \"order.refunded\"]\n },\n \"description\": \"Events to subscribe to\"\n }\n },\n \"required\": [\"url\", \"events\"]\n}\n```\n\n**Response Note:** The `secret` field is returned only on creation and is displayed with a warning to save it immediately. The secret is never shown again. Source: [src/index.ts:227-237]()\n\n### Update Webhook\n\nModifies an existing webhook's configuration.\n\n**Tool Name:** `barevalue_webhook_update`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"webhook_id\": {\n \"type\": \"number\",\n \"description\": \"Webhook ID to update\"\n },\n \"url\": {\n \"type\": \"string\",\n \"description\": \"New HTTPS URL\"\n },\n \"events\": {\n \"type\": \"array\",\n \"items\": { \"type\": \"string\" },\n \"description\": \"New events list\"\n },\n \"is_active\": {\n \"type\": \"boolean\",\n \"description\": \"Enable or disable the webhook\"\n }\n },\n \"required\": [\"webhook_id\"]\n}\n```\n\n**Behavior:** All update fields are optional. Only provided fields are sent to the API. The webhook ID must be specified to identify the target webhook. Source: [src/index.ts:239-249]()\n\n### Delete Webhook\n\nPermanently removes a webhook configuration.\n\n**Tool Name:** `barevalue_webhook_delete`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"webhook_id\": {\n \"type\": \"number\",\n \"description\": \"Webhook ID to delete\"\n }\n },\n \"required\": [\"webhook_id\"]\n}\n```\n\n**Warning:** This operation is irreversible. The webhook is deleted immediately and cannot be recovered. Source: [src/index.ts:153-167]()\n\n### Rotate Webhook Secret\n\nGenerates a new HMAC signing secret for webhook payload verification.\n\n**Tool Name:** `barevalue_webhook_rotate_secret`\n\n**Input Schema:**\n```json\n{\n \"type\": \"object\",\n \"properties\": {\n \"webhook_id\": {\n \"type\": \"number\",\n \"description\": \"Webhook ID to rotate secret for\"\n }\n },\n \"required\": [\"webhook_id\"]\n}\n```\n\n**Behavior:** Immediately invalidates the previous secret. The new secret is returned once and cannot be retrieved again. Clients must update their webhook handlers with the new secret before the rotation is performed. Source: [src/index.ts:251-261]()\n\n## Security\n\n### Signature Verification\n\nWebhook payloads are signed using HMAC-SHA256 to ensure authenticity and integrity. The signature is included in the `X-Barevalue-Signature` header of each webhook request. Source: [README.md:143-145]()\n\n**Verification Process:**\n```mermaid\ngraph LR\n A[Receive Payload] --> B[Extract Signature Header]\n B --> C[Compute HMAC-SHA256]\n C --> D[Compare with Header]\n D -->|Match| E[Process Payload]\n D -->|Mismatch| F[Reject Request]\n```\n\n### Secret Management\n\n| Operation | Secret Behavior |\n|-----------|-----------------|\n| Create | Secret generated and returned (one-time view) |\n| List | Secret omitted from response |\n| Update | Secret unchanged |\n| Rotate | New secret generated, old immediately invalid |\n| Delete | Secret destroyed |\n\n### Presigned URL Security\n\nPresigned S3 URLs for order downloads expire after 30 minutes. Webhook secrets follow the same security model with immediate invalidation upon rotation. Source: [README.md:143-145]()\n\n## API Client Implementation\n\n### Webhook Methods in BarevalueApiClient\n\n```typescript\n// List all webhooks\nasync listWebhooks(): Promise {\n return this.request('GET', '/webhooks');\n}\n\n// Create a webhook\nasync createWebhook(url: string, events: string[]): Promise {\n return this.request('POST', '/webhooks', { url, events });\n}\n\n// Get a specific webhook\nasync getWebhook(webhookId: number): Promise {\n return this.request('GET', `/webhooks/${webhookId}`);\n}\n\n// Update a webhook\nasync updateWebhook(\n webhookId: number,\n updates: { url?: string; events?: string[]; is_active?: boolean }\n): Promise {\n return this.request('PATCH', `/webhooks/${webhookId}`, updates);\n}\n\n// Delete a webhook\nasync deleteWebhook(webhookId: number): Promise<{ success: boolean }> {\n return this.request<{ success: boolean }>('DELETE', `/webhooks/${webhookId}`);\n}\n\n// Rotate webhook secret\nasync rotateWebhookSecret(webhookId: number): Promise {\n return this.request('POST', `/webhooks/${webhookId}/rotate-secret`);\n}\n```\n\nSource: [src/api-client.ts:109-134]()\n\n### HTTP Request Configuration\n\nThe API client uses Node.js native `http` and `https` modules with the following security headers:\n\n```typescript\nconst options: https.RequestOptions = {\n hostname: url.hostname,\n port: url.port || (isHttps ? 443 : 80),\n path: url.pathname + url.search,\n method,\n headers: {\n 'Authorization': `Bearer ${this.apiKey}`,\n 'Content-Type': 'application/json',\n 'Accept': 'application/json',\n 'User-Agent': 'barevalue-mcp/1.0.0',\n },\n timeout: this.timeout,\n};\n```\n\nSource: [src/api-client.ts:48-70]()\n\n## Testing\n\n### Integration Test Coverage\n\nThe repository includes a comprehensive test suite for webhook operations in `test-webhooks.js`. Tests verify:\n\n| Test | Operation | Assertions |\n|------|-----------|------------|\n| 1 | Create Webhook | Returns `id`, `secret`, validates response structure |\n| 2 | Update Webhook | Event list updates to 3 items |\n| 3 | Rotate Secret | New secret differs from original |\n| 4 | Delete Webhook | Successful deletion confirmation |\n\nSource: [test-webhooks.js:20-90]()\n\n### Test Execution Flow\n\n```mermaid\ngraph TD\n A[Start Test Server] --> B[Create Webhook]\n B -->|wait 2s| C[Update Webhook]\n C -->|wait 2s| D[Rotate Secret]\n D -->|wait 2s| E[Delete Webhook]\n E --> F[Print Results]\n \n B -->|success| G[passed++]\n C -->|success| G\n D -->|success| G\n E -->|success| G\n \n B -->|failure| H[failed++]\n C -->|failure| H\n D -->|failure| H\n E -->|failure| H\n```\n\n### Test Output Example\n\n```\n1. Create Webhook... ✅\n Response: {\n \"id\": 123,\n \"url\": \"https://httpbin.org/post\",\n \"events\": [\"order.completed\", \"order.failed\"],\n \"secret\": \"whsec_...\"\n }\n\n2. Update Webhook... ✅\n Response: {\n \"id\": 123,\n \"events\": [\"order.completed\", \"order.failed\", \"order.refunded\"]\n }\n\n3. Rotate Webhook Secret... ✅\n Response: { \"id\": 123, \"secret\": \"whsec_new...\" }\n\n4. Delete Webhook... ✅\n Response: { \"success\": true }\n\n=== Results ===\nPassed: 4\nFailed: 0\nWebhook operations: 100% verified ✅\n```\n\n## Error Handling\n\n### API Error Response Format\n\n```typescript\nclass BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n}\n```\n\nSource: [src/api-client.ts:86-94]()\n\n### Common Error Codes\n\n| HTTP Status | Error Code | Description |\n|-------------|------------|-------------|\n| 400 | `invalid_request` | Malformed request body |\n| 401 | `invalid_api_key` | Missing or invalid API key |\n| 404 | `not_found` | Webhook ID does not exist |\n| 422 | `validation_failed` | Invalid URL or events format |\n| 429 | `rate_limited` | Exceeded rate limit (10/minute) |\n| 500 | `internal_error` | Server-side error |\n\n### Error Sanitization\n\nThe MCP server sanitizes all error responses to prevent leakage of sensitive data:\n\n```typescript\nreturn {\n content: [{\n type: 'text',\n text: JSON.stringify({\n error: error.code,\n message: sanitizeString(error.message),\n statusCode: error.statusCode,\n details: sanitizeData(error.details),\n }, null, 2)\n }]\n};\n```\n\nSource: [src/index.ts:275-292]()\n\n## Usage Examples\n\n### Complete Webhook Lifecycle\n\n```javascript\n// 1. Create a webhook\nconst webhook = await callTool('barevalue_webhook_create', {\n url: 'https://your-server.com/webhooks/barevalue',\n events: ['order.completed', 'order.failed', 'order.refunded']\n});\n// Save webhook.secret securely - only shown once!\n\n// 2. List webhooks to verify\nconst webhooks = await callTool('barevalue_webhooks_list');\nconsole.log('Configured webhooks:', webhooks.webhooks.length);\n\n// 3. Update webhook to disable during maintenance\nawait callTool('barevalue_webhook_update', {\n webhook_id: webhook.id,\n is_active: false\n});\n\n// 4. Re-enable and rotate secret periodically\nawait callTool('barevalue_webhook_update', {\n webhook_id: webhook.id,\n is_active: true\n});\n\nconst newWebhook = await callTool('barevalue_webhook_rotate_secret', {\n webhook_id: webhook.id\n});\n// Update your server with newWebhook.secret\n\n// 5. Delete when no longer needed\nawait callTool('barevalue_webhook_delete', {\n webhook_id: webhook.id\n});\n```\n\n### Handling Webhook Payloads\n\n```javascript\n// Example webhook handler (server-side)\nconst crypto = require('crypto');\n\nfunction handleWebhook(payload, signature, secret) {\n // Verify signature\n const expectedSig = crypto\n .createHmac('sha256', secret)\n .update(JSON.stringify(payload))\n .digest('hex');\n \n if (signature !== expectedSig) {\n return { error: 'Invalid signature', status: 401 };\n }\n \n // Process based on event type\n switch (payload.event) {\n case 'order.completed':\n downloadEditedAudio(payload.order_id);\n break;\n case 'order.failed':\n notifySupport(payload.order_id, payload.error);\n break;\n case 'order.refunded':\n updateCredits(payload.account_id, payload.amount);\n break;\n }\n \n return { status: 200 };\n}\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `BAREVALUE_API_KEY` | Yes | - | API key with `bv_sk_` prefix |\n| `BAREVALUE_API_URL` | No | `https://barevalue.com/api/v1` | Override API base URL |\n\nSource: [server.json:16-22]()\n\n### MCP Server Registration\n\n```json\n{\n \"mcpServers\": {\n \"barevalue\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"barevalue-mcp\"],\n \"env\": {\n \"BAREVALUE_API_KEY\": \"bv_sk_your_api_key_here\"\n }\n }\n }\n}\n```\n\n## Rate Limits\n\nWebhook management operations are subject to the following limits:\n\n| Limit | Value | Scope |\n|-------|-------|-------|\n| API Requests | 10/minute | Per API key |\n| File Uploads | 5-minute timeout | Per upload |\n| Webhook Delivery | Best effort | Per endpoint |\n\nSource: [README.md:147-150]()\n\n## See Also\n\n- [Account & Billing](README.md#account--billing) - Check credits before webhook-triggered operations\n- [Order Workflow](README.md#order-workflow) - Understand order lifecycle events\n- [Security](README.md#security) - General security practices\n\n---\n\n\n\n## Error Handling and Rate Limits\n\n### Related Pages\n\nRelated topics: [Account and Billing Tools](#account-tools), [Order Workflow Tools](#order-workflow)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n \n\n# Error Handling and Rate Limits\n\nThe barevalue-mcp server implements comprehensive error handling and rate limiting mechanisms to ensure reliable communication with the Barevalue API while protecting against misuse and providing meaningful feedback to clients.\n\n## Overview\n\nThe error handling system in barevalue-mcp serves three primary purposes:\n\n1. **API Error Propagation** - Translating Barevalue API errors into structured, actionable responses\n2. **Client-Side Validation** - Catching issues before they reach the API (format validation, file size limits)\n3. **Security Enforcement** - Preventing sensitive data exposure and flagging insecure configurations\n\nRate limiting controls resource consumption and ensures fair access to the Barevalue API infrastructure.\n\n## Error Architecture\n\n### Error Class Hierarchy\n\nThe `BarevalueApiError` class extends the standard `Error` type with additional context specific to API failures:\n\n```typescript\nexport class BarevalueApiError extends Error {\n constructor(\n message: string,\n public readonly code: string,\n public readonly statusCode: number,\n public readonly details?: Record\n ) {\n super(message);\n this.name = 'BarevalueApiError';\n }\n\n toJSON() {\n return {\n error: this.code,\n message: this.message,\n statusCode: this.statusCode,\n details: this.details\n };\n }\n}\n```\n\n**Source:** [src/api-client.ts:180-195](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L180-L195)\n\n### Error Response Flow\n\n```mermaid\ngraph TD\n A[API Request] --> B{HTTP Status Code}\n B -->|2xx| C[Parse JSON Response]\n B -->|4xx/5xx| D[Create BarevalueApiError]\n C -->|Parse Success| E[Return Data]\n C -->|Parse Failure| F[Create Generic Error]\n D --> G[Return Error to Client]\n E --> H[Return Data to Client]\n F --> G\n```\n\n## Common Error Codes\n\nThe Barevalue API returns structured error responses with standardized error codes:\n\n| Error Code | HTTP Status | Description | Resolution |\n|------------|-------------|-------------|------------|\n| `invalid_api_key` | 401 | API key missing, invalid format, or revoked | Verify API key starts with `bv_sk_` and is active |\n| `insufficient_credits` | 402 | Not enough credits or subscription minutes | Check account balance, upgrade plan if needed |\n| `validation_failed` | 400 | File failed pre-checks (insufficient speech, music-only detected) | Ensure audio has >10% speech content |\n| `file_too_large` | 413 | File exceeds 750MB limit | Compress or split the audio file |\n| `rate_limited` | 429 | Too many requests | Wait before retrying (limit: 10/minute) |\n| `unknown_error` | varies | Unhandled server error | Contact support with error details |\n\n**Source:** [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Error Response Structure\n\nAPI errors are returned with the following JSON structure:\n\n```json\n{\n \"error\": \"error_code\",\n \"message\": \"Human-readable error description\",\n \"statusCode\": 402,\n \"details\": {\n \"current_balance\": 0,\n \"required_credits\": 3.15,\n \"has_subscription\": true\n }\n}\n```\n\n**Source:** [src/api-client.ts:100-108](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L100-L108)\n\n## Input Validation\n\n### API Key Format Validation\n\nThe server validates API key format before making any requests:\n\n```typescript\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\n**Source:** [src/api-client.ts:30-34](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L30-L34)\n\n### Security Warnings\n\nNon-HTTPS connections trigger console warnings to prevent insecure key transmission:\n\n```typescript\nconst url = new URL(this.baseUrl);\nconst isHttps = url.protocol === 'https:';\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\n**Source:** [src/api-client.ts:35-39](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L35-L39)\n\n### Content-Type Detection\n\nFile uploads use extension-based content type detection:\n\n| Extension | MIME Type |\n|-----------|-----------|\n| `.mp3` | audio/mpeg |\n| `.wav` | audio/wav |\n| `.m4a` | audio/mp4 |\n| `.flac` | audio/flac |\n| `.aac` | audio/aac |\n| `.ogg` | audio/ogg |\n| `.wma` | audio/x-ms-wma |\n| `.aiff` / `.aif` | audio/aiff |\n\nUnknown extensions default to `application/octet-stream`.\n\n**Source:** [src/api-client.ts:165-178](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L165-L178)\n\n## Timeout Configuration\n\n### Request Timeouts\n\nAll HTTP requests are subject to timeout constraints to prevent hanging connections:\n\n| Operation | Timeout | Behavior on Expiry |\n|-----------|---------|-------------------|\n| Standard API requests | Default HTTP timeout | Request destroyed, error thrown |\n| S3 file uploads | Upload timeout | Request destroyed, error thrown |\n\n```typescript\nreq.on('timeout', () => {\n req.destroy();\n reject(new Error('API request timed out'));\n});\n```\n\n**Source:** [src/api-client.ts:113-115](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L113-L115)\n\n### Timeout Error Handling\n\nBoth S3 upload and API request handlers implement consistent timeout behavior:\n\n```typescript\nreq.on('timeout', () => {\n req.destroy();\n reject(new Error('S3 upload timed out'));\n});\n```\n\n**Source:** [src/api-client.ts:144-146](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L144-L146)\n\n## Security Measures\n\n### Data Sanitization\n\nError messages are sanitized before being returned to clients to prevent information leakage:\n\n```typescript\nfunction sanitizeData(data: unknown): unknown {\n if (typeof data === 'string') {\n return sanitizeString(data);\n }\n if (Array.isArray(data)) {\n return data.map(sanitizeData);\n }\n if (data !== null && typeof data === 'object') {\n const result: Record = {};\n for (const [key, value] of Object.entries(data)) {\n result[sanitizeString(key)] = sanitizeData(value);\n }\n return result;\n }\n return data;\n}\n```\n\n**Source:** [src/index.ts:1-18](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts#L1-L18)\n\n### Error Response Protection\n\nS3 upload errors do not expose raw response data to prevent leaking internal implementation details:\n\n```typescript\nif (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {\n resolve();\n} else {\n // Security: Don't expose S3 error response data\n reject(new Error(`S3 upload failed with status ${res.statusCode}`));\n}\n```\n\n**Source:** [src/api-client.ts:140-143](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L140-L143)\n\n### API Response Parsing Protection\n\nMalformed API responses are handled without exposing raw data:\n\n```typescript\ntry {\n const parsed = JSON.parse(data);\n // ... process response\n} catch {\n // Security: Don't expose raw API response data in error messages\n reject(new Error('Failed to parse API response'));\n}\n```\n\n**Source:** [src/api-client.ts:100-108](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L100-L108)\n\n## Rate Limiting\n\n### API Rate Limits\n\nThe Barevalue API enforces the following rate limits:\n\n| Limit Type | Value | Scope |\n|------------|-------|-------|\n| Requests per minute | 10 | Per API key |\n| File upload timeout | 5 minutes | Per upload |\n| Order processing | 10-30 minutes | Per order |\n\n**Source:** [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Rate Limit Handling\n\nWhen rate limited, the API returns a `429 Too Many Requests` response:\n\n```json\n{\n \"error\": \"rate_limited\",\n \"message\": \"Too many requests. Please wait before retrying.\",\n \"statusCode\": 429\n}\n```\n\nClients should implement exponential backoff when encountering rate limits.\n\n## Error Handling in Tool Calls\n\n### Tool Execution Error Flow\n\nAll tool calls are wrapped in try-catch blocks that sanitize errors before returning responses:\n\n```typescript\ntry {\n // Tool execution logic\n const result = await executeTool(args);\n return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };\n} catch (error) {\n return {\n content: [\n {\n type: 'text',\n text: JSON.stringify(\n {\n error: 'tool_error',\n message: sanitizeString(error instanceof Error ? error.message : 'Unknown error occurred'),\n },\n null,\n 2\n ),\n },\n ],\n };\n}\n```\n\n**Source:** [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n### Error Response Format\n\nTool errors are always returned in a consistent format:\n\n```json\n{\n \"error\": \"tool_error\",\n \"message\": \"Sanitized error message without sensitive data\"\n}\n```\n\n## Webhook Security\n\n### HMAC-SHA256 Verification\n\nWebhook payloads use HMAC-SHA256 signatures for verification:\n\n> Webhook signatures use HMAC-SHA256 for verification\n\n**Source:** [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Secret Rotation\n\nWebhooks support secret rotation to maintain security without service interruption:\n\n```typescript\nasync rotateWebhookSecret(webhookId: number): Promise {\n return this.request('POST', `/webhooks/${webhookId}/rotate-secret`);\n}\n```\n\n**Source:** [src/api-client.ts:175-178](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts#L175-L178)\n\n### Presigned URL Expiration\n\nS3 presigned URLs expire after 30 minutes for security:\n\n> Presigned S3 URLs expire after 30 minutes\n\n**Source:** [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Best Practices\n\n### Client-Side Error Handling\n\n1. **Always check the `error` field** in responses before processing data\n2. **Implement retry logic** with exponential backoff for transient errors\n3. **Monitor rate limits** by tracking request counts per API key\n4. **Validate files locally** before upload (format, size, speech content)\n\n### Error Recovery Strategies\n\n| Error Type | Recommended Action |\n|------------|-------------------|\n| `invalid_api_key` | Verify key format and regenerate if needed |\n| `insufficient_credits` | Check account balance or upgrade plan |\n| `validation_failed` | Pre-validate audio with `barevalue_validate` tool |\n| `rate_limited` | Wait and retry with exponential backoff |\n| Network timeout | Retry once, then investigate connectivity |\n\n### Security Checklist\n\n- [ ] API keys stored in environment variables, never hardcoded\n- [ ] HTTPS used for all non-localhost connections\n- [ ] Error responses sanitized before logging\n- [ ] Webhook signatures verified on receipt\n- [ ] Presigned URLs used within 30-minute window\n\n---\n\n\n\n## Security\n\n### Related Pages\n\nRelated topics: [Configuration Reference](#configuration), [Webhook Management](#webhook-management)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n- [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n- [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n- [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n- [src/types.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/types.ts)\n- [package.json](https://github.com/quietnotion/barevalue-mcp/blob/main/package.json)\n \n\n# Security\n\nThis page documents the security architecture, measures, and best practices implemented in the barevalue-mcp project. The barevalue-mcp is a Model Context Protocol (MCP) server that enables programmatic interaction with the Barevalue AI podcast editing API.\n\n## Overview\n\nThe barevalue-mcp server implements multiple layers of security to protect sensitive data during API communication. The primary security concerns include:\n\n- **API Key Protection**: Preventing exposure of authentication credentials\n- **Transport Security**: Ensuring encrypted communication channels\n- **Input Sanitization**: Protecting against injection attacks\n- **Error Handling**: Avoiding information leakage in error messages\n- **Webhook Security**: Verifying authenticity of incoming webhook requests\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Environment Variables\n\nEnvironment variables are the sole mechanism for configuring sensitive credentials. The server does not support hardcoded values or configuration files for secrets.\n\n| Variable | Required | Type | Description |\n|----------|----------|------|-------------|\n| `BAREVALUE_API_KEY` | Yes | String | Your Barevalue API key. Must start with `bv_sk_`. Marked as secret in MCP configuration. |\n| `BAREVALUE_API_URL` | No | String | Override API base URL. Defaults to `https://barevalue.com/api/v1` |\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md), [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n## API Key Protection\n\n### Format Validation\n\nThe API client validates the format of incoming API keys to ensure they conform to the expected pattern. Keys must begin with the `bv_sk_` prefix.\n\n```typescript\nif (!this.apiKey.startsWith('bv_sk_')) {\n throw new Error(\n 'Invalid API key format. Barevalue API keys must start with \"bv_sk_\".'\n );\n}\n```\n\nSource: [src/api-client.ts:1-100](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Secret Handling\n\nThe `BAREVALUE_API_KEY` environment variable is declared as a secret in the MCP server configuration:\n\n```json\n{\n \"name\": \"BAREVALUE_API_KEY\",\n \"isSecret\": true,\n \"isRequired\": true\n}\n```\n\nThis ensures that MCP clients handle the credential with appropriate confidentiality measures.\n\nSource: [server.json](https://github.com/quietnotion/barevalue-mcp/blob/main/server.json)\n\n## Transport Security\n\n### HTTPS Enforcement\n\nAll production API communication uses HTTPS to encrypt data in transit. The client explicitly uses the Node.js `https` module for secure connections:\n\n```typescript\nconst isHttps = url.protocol === 'https:';\nconst httpModule = isHttps ? https : http;\n```\n\nFor non-localhost URLs, a warning is emitted if a non-HTTPS connection is detected:\n\n```typescript\nconst isHttps = url.protocol === 'https:';\nif (!isHttps && url.hostname !== 'localhost' && url.hostname !== '127.0.0.1') {\n console.error('WARNING: Using non-HTTPS connection. API key may be transmitted insecurely.');\n}\n```\n\nThis warning mechanism alerts operators to potentially insecure configurations while allowing local development with HTTP.\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Request Headers\n\nEvery API request includes security-relevant headers:\n\n| Header | Value | Purpose |\n|--------|-------|---------|\n| `Authorization` | `Bearer {apiKey}` | Authentication token |\n| `Content-Type` | `application/json` | Ensures JSON parsing on server |\n| `Accept` | `application/json` | Expects JSON response |\n| `User-Agent` | `barevalue-mcp/1.0.0` | Server identification |\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Input Sanitization\n\nThe server implements input sanitization to protect against injection attacks and ensure safe data handling.\n\n### Sanitization Functions\n\n```typescript\nfunction sanitizeString(str: string): string {\n return str.replace(/[\\u0000-\\u001F\\u007F-\\u009F]/g, (char) => \n char.charCodeAt(0) < 0x20 || char.charCodeAt(0) > 0x7E \n ? `\\\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`\n : char\n );\n}\n\nfunction sanitizeData(data: unknown): unknown {\n if (typeof data === 'string') {\n return sanitizeString(data);\n }\n if (Array.isArray(data)) {\n return data.map(sanitizeData);\n }\n if (data !== null && typeof data === 'object') {\n const result: Record = {};\n for (const [key, value] of Object.entries(data)) {\n result[sanitizeString(key)] = sanitizeData(value);\n }\n return result;\n }\n return data;\n}\n```\n\nThe sanitization process:\n1. Removes control characters from strings (bytes 0x00-0x1F and 0x7F-0x9F)\n2. Recursively processes arrays and objects\n3. Preserves printable ASCII characters and Unicode content\n\nSource: [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n### Sanitization Application Points\n\nSanitization is applied in two primary locations:\n\n1. **Tool Call Error Responses**: When a tool call fails, error messages are sanitized before being returned to clients\n2. **Webhook Payloads**: Incoming webhook data is sanitized to prevent injection attacks\n\nSource: [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Error Handling Security\n\n### Information Leakage Prevention\n\nThe server is designed to avoid exposing sensitive information in error messages. Two specific safeguards are implemented:\n\n**S3 Upload Errors**:\n```typescript\n// Security: Don't expose S3 error response data\nreject(new Error(`S3 upload failed with status ${res.statusCode}`));\n```\n\n**API Response Parsing Failures**:\n```typescript\n// Security: Don't expose raw API response data in error messages\nreject(new Error('Failed to parse API response'));\n```\n\nThese measures ensure that internal system details, stack traces, or sensitive payload content are never exposed to end users or potential attackers.\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n### Error Response Structure\n\nAll tool call errors follow a standardized format:\n\n```json\n{\n \"error\": \"tool_error\",\n \"message\": \"sanitized error message\"\n}\n```\n\nSource: [src/index.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/index.ts)\n\n## Webhook Security\n\nThe Barevalue API provides webhook functionality for order status notifications. The MCP server includes full webhook management capabilities.\n\n### HMAC-SHA256 Signature Verification\n\nIncoming webhook requests are verified using HMAC-SHA256 signatures:\n\n> Webhook signatures use HMAC-SHA256 for verification\n\nThis ensures that webhook payloads originate from the legitimate Barevalue API server and have not been tampered with in transit.\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Webhook Secret Rotation\n\nThe server supports webhook secret rotation to maintain security after potential compromises:\n\n```\nbarevalue_webhook_rotate_secret webhook_id=1\n```\n\nRotating secrets immediately invalidates the previous secret, ensuring that any previously leaked credentials stop working immediately.\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Webhook Management API\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| `GET` | `/webhooks` | List all webhooks |\n| `POST` | `/webhooks` | Create a webhook |\n| `GET` | `/webhooks/{id}` | Get specific webhook |\n| `PATCH` | `/webhooks/{id}` | Update webhook configuration |\n| `DELETE` | `/webhooks/{id}` | Delete a webhook |\n| `POST` | `/webhooks/{id}/rotate-secret` | Rotate webhook secret |\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## S3 Upload Security\n\n### Presigned URL Expiration\n\nFile uploads use S3 presigned URLs that automatically expire:\n\n> Presigned S3 URLs expire after 30 minutes\n\nThis temporal limitation reduces the risk of unauthorized access to uploaded files even if a presigned URL is intercepted.\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n### Content Type Validation\n\nThe client validates file content types based on extension:\n\n```typescript\nconst types: Record = {\n '.mp3': 'audio/mpeg',\n '.wav': 'audio/wav',\n '.m4a': 'audio/mp4',\n '.flac': 'audio/flac',\n '.aac': 'audio/aac',\n '.ogg': 'audio/ogg',\n '.wma': 'audio/x-ms-wma',\n '.aiff': 'audio/aiff',\n '.aif': 'audio/aiff',\n};\nreturn types[ext] || 'application/octet-stream';\n```\n\nSupported formats are limited to audio files, preventing upload of potentially malicious file types.\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Timeout Protection\n\nThe server implements timeout protection for all network operations:\n\n```typescript\ntimeout: this.timeout\n```\n\nIf a request exceeds the configured timeout, the connection is destroyed and an error is returned:\n\n```typescript\nreq.on('timeout', () => {\n req.destroy();\n reject(new Error('API request timed out'));\n});\n```\n\nThis prevents resource exhaustion attacks that attempt to hold connections open indefinitely.\n\nSource: [src/api-client.ts](https://github.com/quietnotion/barevalue-mcp/blob/main/src/api-client.ts)\n\n## Rate Limiting\n\nThe API enforces rate limiting to prevent abuse:\n\n- **10 requests per minute** per API key\n- File uploads have a **5-minute timeout**\n- Order processing typically completes in **10-30 minutes**\n\nSource: [README.md](https://github.com/quietnotion/barevalue-mcp/blob/main/README.md)\n\n## Security Architecture Diagram\n\n```mermaid\ngraph TD\n subgraph \"Client Environment\"\n ENV[Environment Variables
BAREVALUE_API_KEY
BAREVALUE_API_URL]\n end\n\n subgraph \"barevalue-mcp Server\"\n SV[Server Startup]\n SV -->|Read| ENV\n \n subgraph \"API Client\"\n KVF[API Key Validation
bv_sk_ prefix check]\n HTTPS_CHK[HTTPS Check
Non-localhost warning]\n REQ[Request Builder
Auth headers
User-Agent]\n TO[Timeout Handler]\n end\n \n ENV --> KVF\n KVF --> HTTPS_CHK\n HTTPS_CHK --> REQ\n REQ --> TO\n end\n\n subgraph \"Barevalue API\"\n AUTH[Authentication]\n RATE[Rate Limiting
10 req/min]\n WEBHOOK[Webhook HMAC-SHA256
Signature Verification]\n S3[S3 Presigned URLs
30 min expiration]\n end\n \n TO -->|HTTPS| AUTH\n AUTH --> RATE\n RATE -->|Success| WEBHOOK\n \n subgraph \"File Upload Flow\"\n PRE[Get Presigned URL]\n UPLOAD[Upload to S3]\n PRE --> UPLOAD\n UPLOAD -->|30 min expiry| S3\n end\n```\n\n## Best Practices\n\n### For Users\n\n1. **Never hardcode API keys** — Always use environment variables\n2. **Use HTTPS in production** — The warning system alerts to insecure configurations\n3. **Rotate webhook secrets** — Periodically rotate to maintain security\n4. **Monitor rate limits** — Implement backoff logic for 429 responses\n5. **Validate file formats** — Ensure uploaded files are legitimate audio content\n\n### For Developers\n\n1. **Preserve sanitization** — Don't remove input sanitization for convenience\n2. **Maintain error secrecy** — Don't expose internal details in error messages\n3. **Keep secrets as secrets** — Never log API keys or webhook secrets\n4. **Update dependencies** — Keep the `@modelcontextprotocol/sdk` package current\n\n## Summary\n\nThe barevalue-mcp implements defense-in-depth security measures across multiple layers:\n\n| Layer | Protection Mechanism |\n|-------|---------------------|\n| Authentication | Bearer token with `bv_sk_` prefix validation |\n| Transport | HTTPS enforcement with localhost exceptions |\n| Input | Control character sanitization for all string inputs |\n| Errors | No sensitive data exposure in error messages |\n| Webhooks | HMAC-SHA256 signature verification |\n| File Uploads | S3 presigned URLs with 30-minute expiration |\n| Network | Request timeouts to prevent resource exhaustion |\n| API | Rate limiting at 10 requests per minute |\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: quietnotion/barevalue-mcp\n\nSummary: Found 7 potential pitfall items; 0 are high/blocking. Highest priority: capability - 能力判断依赖假设.\n\n## 1. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | README/documentation is current enough for a first validation pass.\n\n## 2. runtime · 运行可能依赖外部服务\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。\n- User impact: 本地安装成功不等于能力可用，外部服务不可用会阻断体验。\n- Suggested check: 确认是否有离线 demo、mock 数据或可替代服务。\n- Guardrail action: 外部服务依赖未明确时，不把本地安装成功等同于能力可用。\n- Evidence: packet_text.keyword_scan | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | matched external service / cloud / webhook / database keyword\n\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium\n\n## 6. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | issue_or_pr_quality=unknown\n\n## 7. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "Human Manual"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log\n\nProject: quietnotion/barevalue-mcp\n\nSummary: Found 7 potential pitfall items; 0 are high/blocking. Highest priority: capability - 能力判断依赖假设.\n\n## 1. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | README/documentation is current enough for a first validation pass.\n\n## 2. runtime · 运行可能依赖外部服务\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。\n- User impact: 本地安装成功不等于能力可用，外部服务不可用会阻断体验。\n- Suggested check: 确认是否有离线 demo、mock 数据或可替代服务。\n- Guardrail action: 外部服务依赖未明确时，不把本地安装成功等同于能力可用。\n- Evidence: packet_text.keyword_scan | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | matched external service / cloud / webhook / database keyword\n\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | no_demo; severity=medium\n\n## 6. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | issue_or_pr_quality=unknown\n\n## 7. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | mcp_registry:io.github.quietnotion/barevalue:1.0.3 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3 | release_recency=unknown\n",
"summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.",
"title": "Pitfall Log"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# barevalue-mcp - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for quietnotion/barevalue-mcp.\n\nProject:\n- Name: barevalue-mcp\n- Repository: https://github.com/quietnotion/barevalue-mcp\n- Summary: Submit podcast orders, check status, and manage webhooks via Barevalue editing API.\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Submit podcast orders, check status, and manage webhooks via Barevalue editing API.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Submit podcast orders, check status, and manage webhooks via Barevalue editing API.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Project Overview. Produce one small intermediate artifact and wait for confirmation.\n2. configuration: Configuration Reference. Produce one small intermediate artifact and wait for confirmation.\n3. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. account-tools: Account and Billing Tools. Produce one small intermediate artifact and wait for confirmation.\n5. order-workflow: Order Workflow Tools. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3\n- README.md\n- package.json\n- server.json\n- src/index.ts\n- src/api-client.ts\n- src/types.ts\n- test-mcp.js\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start\n\nProject: quietnotion/barevalue-mcp\n\n## Official Entry Points\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx barevalue-mcp\n```\n\nSource：https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3\n\n## Sources\n\n- mcp_registry: https://registry.modelcontextprotocol.io/v0.1/servers/io.github.quietnotion%2Fbarevalue/versions/1.0.3\n",
"summary": "Entry points extracted from official README or installation documentation.",
"title": "Quick Start"
}
},
"validation_id": "dval_323ab2998e1149cbb8c3c0d5054c9da2"
}