Annualmetrics Mcp

AnnualMetrics MCP

Open-source MCP server for extracting, verifying, and querying financial metrics from annual reports.

Annual reports are messy. Your AI agent deserves verified numbers.

Annual report tables break. Units drift. Year columns shift. LLMs can misread rows.

AnnualMetrics MCP provides a safer workflow:

Annual report metrics
  -> source pages and source text
  -> confidence and quality flags
  -> safeOnly filtering
  -> manual verification queue
  -> verified draft workflow
  -> MCP tools for agents

Problem

Annual report metrics are hard to use reliably because:

• PDF table structures vary by year
• Unit scale is often inconsistent
• Column alignment can be wrong
• Some extracted metrics need manual verification before reuse

What AnnualMetrics MCP Does

• Serves annual-report-derived metrics through MCP tools
• Preserves source traceability (sourcePage, sourceText, sourceAvailable)
• Exposes quality signals (confidence, qualityFlags, verificationStatus)
• Defaults metric queries to safeOnly=true
• Supports manual verification drafts without overwriting production metrics
• Supports valuation inputs and scenario math templates (not recommendations)

What It Does NOT Do

• No buy/sell/hold recommendations
• No stock price prediction
• No live market data feed in this MVP
• No automatic overwrite of production metrics from draft inputs
• No claim of perfect extraction accuracy

Quickstart

npm install
npm run build
npm test
npm run dev

MCP Tool Surface

Core tools:

• list_companies
• get_company_metrics
• get_metric_trend
• compare_companies
• get_metric_source
• get_verification_queue
• create_verified_metric_draft
• get_data_quality_report

Valuation-support tools:

• get_valuation_inputs
• compare_valuation_inputs
• create_valuation_case_template
• calculate_simple_bank_valuation

Detailed tool docs: [docs/mcp-tools.md](docs/mcp-tools.md)

MCP Resources

• annualmetrics://companies
• annualmetrics://metrics/schema
• annualmetrics://quality/report
• annualmetrics://verification/queue
• annualmetrics://companies/{companyId}/{year}/metrics

MCP Prompts

• verify_metric
• compare_companies_safely
• explain_metric_trend
• prepare_manual_review

Example Prompts

• "Compare DBS, OCBC and UOB for 2024 using safe metrics only."
• "Show me the source text for DBS customer deposits in 2024."
• "List the top manual verification items for customer loans and deposits."
• "Create a verified metric draft for DBS 2024 customer deposits."
• "Get valuation inputs for OCBC 2024 with safe metrics only."
• "Create a DDM valuation case template for UOB 2024."

More examples: [docs/demo-prompts.md](docs/demo-prompts.md)

Sample Data

Sample data is intentionally mocked/sanitized and small-scale.

• Path: examples/sg-banks-2024/
• Companies: DBS, OCBC, UOB
• Scope: annual-report-style metrics for demo/testing

Details: [examples/sg-banks-2024/README.md](examples/sg-banks-2024/README.md)

Manual Verification Workflow

1. Query get_verification_queue
2. Review source pages/source text
3. Submit create_verified_metric_draft
4. Human-review draft files before any production merge

Guide: [docs/verification-workflow.md](docs/verification-workflow.md)

Valuation Support

AnnualMetrics MCP provides valuation inputs and scenario math, not investment recommendations.

• Supports DDM / Justified P/B / Residual Income template workflows
• Requires user-supplied assumptions where needed
• Returns missing-input/assumption diagnostics when calculation is not possible

Details: [docs/valuation-support.md](docs/valuation-support.md)

MCP Client Setup

See client integration guide:

• [docs/mcp-client-setup.md](docs/mcp-client-setup.md)

Demo Walkthrough

• Sample dataset notes: [examples/sg-banks-2024/README.md](examples/sg-banks-2024/README.md)
• Demo prompts: [docs/demo-prompts.md](docs/demo-prompts.md)

Safety Philosophy

• Verification-first over “auto-trust”
• Keep source trace attached to every metric
• Mark uncertainty explicitly via quality flags
• Keep manual draft write-path separate from production metric files

Safety doc: [docs/safety-and-disclaimer.md](docs/safety-and-disclaimer.md)

Architecture

Local JSON Adapter (sample data)
  -> Typed schemas (Zod)
  -> Tool handlers (safeOnly defaults)
  -> Resources and prompts
  -> Draft writer (non-destructive)
  -> MCP stdio server

Design review references: [docs/design-pattern-review.md](docs/design-pattern-review.md)

Contributing

• Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
• Code of conduct: [CODEOFCONDUCT.md](CODEOFCONDUCT.md)
• Security policy: [SECURITY.md](SECURITY.md)
• Release checklist: [docs/release-checklist.md](docs/release-checklist.md)

Roadmap (v0.x)

• Improve schema coverage across additional annual-report metrics
• Add stronger validation diagnostics for unit/scale mismatches
• Expand sample datasets and reproducible fixtures
• Improve prompt templates for verification operations

Disclaimer

This is not financial advice.

AnnualMetrics MCP is for annual report research, data quality workflows, and educational scenario analysis only.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JefferyChenjy
• Source: JefferyChenjy/annualmetrics-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.