Skip to main content
Glama
mjaack

VoiceBrief MCP

by mjaack
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

VoiceBrief MCP

A self-hosted Model Context Protocol server that answers spoken stock-fact questions — "what's Apple's revenue", "tell me about Tesla's financials" — grounded in the company's actual SEC 10-K filing, not a guess from a language model's training data.

Built for a voice agent, not a screen: every answer is a single natural sentence with units spelled out in full. No markdown, no tables, no $391B — a text-to-speech engine has no reliable way to pronounce an abbreviated unit letter, so this server never emits one.

> "What's Apple's revenue?"
< "AAPL's revenue, from its most recent SEC filing, is $416 billion."

> "Tell me about Tesla's financials."
< "Based on TSLA's most recent SEC filing, it reported revenue of $97.7
   billion, earnings per share of $2.01, a market cap of $1.0 trillion,
   and a book value per share of $19.32."

Why this exists

Voice assistants answering finance questions today either hallucinate a number or read out a screen-shaped string a TTS engine mangles ("three ninety one point zero B"). This server closes both gaps: it pulls figures straight from SEC EDGAR's public XBRL API — free, no key, no auth — and formats them the way a person would actually say them out loud (lib/spokenNumbers.js).

It runs as a normal MCP stdio server, which means it works with any MCP client, not just one voice platform — Claude Desktop, an Alexa+ skill's agent runtime, Cursor, or anything else that speaks the protocol.

Related MCP server: SEC EDGAR MCP Server

Run it

No account, no API key, no cloud dependency beyond sec.gov and a free quote endpoint.

git clone https://github.com/mjaack/voicebrief-mcp.git
cd voicebrief-mcp
node src/server.js

Point any MCP client at it over stdio. For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "voicebrief": {
      "command": "node",
      "args": ["/absolute/path/to/voicebrief-mcp/src/server.js"]
    }
  }
}

Tools

Tool

Use for

get_stock_metric

One specific figure: revenue, eps, book_value_per_share, market_cap, total_assets, total_liabilities, price.

get_stock_snapshot

A short spoken overview of the company's key figures.

Both accept a company name or ticker ("Apple" or "AAPL") and resolve it against SEC EDGAR's own ticker list — no hardcoded company map to fall out of date.

Protocol conformance

Implements MCP spec revision 2025-11-25:

  • Version negotiation — echoes back an older version a client pins (2025-06-18, 2025-03-26) rather than forcing the latest.

  • SEP-1303 — a bad argument (missing company, invalid metric) comes back as a normal tool result with isError: true, so the calling model can read what went wrong and self-correct, instead of a JSON-RPC protocol error it can only fail on.

  • JSON Schema 2020-12 — every inputSchema declares the $schema dialect explicitly.

test/protocol.test.js spawns the server as a real subprocess and drives the actual stdio handshake — initialize, tools/list, tools/call — the same way a real MCP client does, rather than unit-testing the handler functions in isolation.

Test

npm test

12 tests: pure-formatting unit tests for the spoken-number logic (test/voiceStockBrief.test.js, no network) plus the end-to-end protocol suite above, including one live call to SEC EDGAR to confirm the whole path returns a real, current figure.

License

MIT.

Available Tools

2 tools
get_stock_metricA
Read-only

Answer one financial metric for a US public company, spoken as a single natural-language sentence grounded in that company's most recent SEC 10-K filing (via EDGAR's XBRL data) -- not a guess. Use for a specific spoken question like "what's Tesla's revenue" or "what's Apple's earnings per share". Metric must be one of: revenue, eps, book_value_per_share, market_cap, total_assets, total_liabilities, price.

ParametersJSON Schema
NameRequiredDescriptionDefault
metricYesWhich figure to report.
companyYesCompany name or ticker, e.g. "Apple" or "AAPL".

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, and the description aligns with these. Beyond that, the description adds critical behavioral context: it is grounded in SEC filings (not a guess), spoken as a natural-language sentence, and restricts to US public companies. This is valuable transparency that goes beyond the structured annotations, especially the non-guessing and source grounding.

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

Conciseness5/5

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

The description is two sentences, front-loads the core purpose with a specific verb and resource, then gives usage context and examples. Every sentence earns its place, and it is compact without omission. The metric list is repeated from the schema, but it's essential for clarity and doesn't bloat the description.

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

Completeness5/5

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

For a read-only tool with two well-schema'd parameters (100% coverage) and no output schema, the description is complete: it specifies source (SEC filings), scope (US public companies), allowed metrics, output format (single spoken sentence), and grounding requirement (not a guess). The sibling is known but not needed for this tool's description. Nothing essential is missing.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema fully documents each parameter (metric and company). The description adds extra meaning by clarifying that the metric must be one of the enums and that company can be a name or ticker, which is already in the schema but restated. The description also explains the output as a spoken sentence, which is beyond schema. Given high coverage, a 4 is warranted, not 3, because the description enhances the semantics with the natural-language output constraint.

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

Purpose5/5

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

The description clearly states the tool answers one financial metric for a US public company, cites the regulatory source (SEC 10-K via EDGAR XBRL), and lists the specific allowed metrics. This distinguishes it from siblings by emphasizing a single metric and spoken natural-language output. The verb-resource pairing is specific: 'Answer one financial metric'.

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

Usage Guidelines4/5

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

It explicitly says to use for specific spoken questions and gives examples, but it doesn't explicitly contrast with the sibling tool get_stock_snapshot. The presence of a sibling suggests a possible alternative, but the description doesn't mention when to use the sibling instead. Still, the usage context is clear enough for an agent to select it for single-metric queries.

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

get_stock_snapshotA
Read-only

Give a short spoken financial snapshot of a US public company (revenue, earnings per share, market cap, book value per share) grounded in its most recent SEC 10-K filing. Use for a broad spoken question like "tell me about Apple's financials" rather than one specific figure.

ParametersJSON Schema
NameRequiredDescriptionDefault
companyYesCompany name or ticker, e.g. "Apple" or "AAPL".

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the output is a short spoken snapshot, grounded specifically in a 10-K filing, and includes a defined set of metrics. No contradiction with annotations exists.

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

Conciseness5/5

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

Two sentences, no filler, with the primary purpose and metric list front-loaded and the usage guidance in the second sentence. Every sentence earns its place and the description is appropriately short for a simple one-parameter tool.

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

Completeness5/5

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

With no output schema, the description appropriately explains what the tool returns: a short spoken financial snapshot with the named metrics grounded in the most recent 10-K. Given the low complexity, rich annotations, and single well-documented parameter, nothing essential for correct invocation is missing.

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

Parameters4/5

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

Schema coverage is 100% and the single company parameter is well documented with examples. The description adds meaning beyond the schema by constraining the company to a US public company with an SEC 10-K filing, which is not present in the schema. This helps the agent choose valid inputs.

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

Purpose5/5

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

The description states a specific verb ('give a short spoken financial snapshot'), a specific resource (US public company), and specific metrics (revenue, EPS, market cap, book value per share), grounding it in the most recent SEC 10-K filing. It also distinguishes itself from sibling get_stock_metric by targeting broad questions rather than a single figure.

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

Usage Guidelines4/5

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

The description gives an explicit use case ('Use for a broad spoken question like "tell me about Apple's financials"') and an explicit negative case ('rather than one specific figure'). It does not directly name the sibling alternative, but the contrast with get_stock_metric is clear enough for an agent to route correctly.

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

Tool Schema Changelog

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

  1. 2 tool updatesv1.0.0
    • First observedget_stock_metric
    • First observedget_stock_snapshot
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 2 tools

Disambiguation4/5

get_stock_metric targets a single, specified metric while get_stock_snapshot returns a fixed multi-metric overview, so their primary intents are distinct. There is slight overlap because the snapshot includes several metrics that could also be requested individually, but the descriptions clearly separate specific from broad questions.

Naming Consistency5/5

Both tools follow the same get_stock_<noun> pattern with clear, parallel names. There is no style mixing or vague verbing between the two.

Tool Count3/5

Two tools is below the typical 3-15 well-scoped range and the server feels minimal, though its narrow voice-brief purpose limits the need for many tools. Each tool earns its place, but the set remains borderline thin.

Completeness4/5

All advertised metrics are directly queryable via get_stock_metric, and get_stock_snapshot covers the common broad summary. Custom multi-metric requests require repeated calls, but there are no dead ends for the stated domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers