# Annualmetrics Mcp

> Open-source MCP server for verified financial metrics from annual reports.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jefferychenjy-annualmetrics-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JefferyChenjy](https://agentstack.voostack.com/s/jefferychenjy)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JefferyChenjy](https://github.com/JefferyChenjy)
- **Source:** https://github.com/JefferyChenjy/annualmetrics-mcp

## Install

```sh
agentstack add mcp-jefferychenjy-annualmetrics-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```text
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

```bash
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

```text
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: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.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](https://github.com/JefferyChenjy)
- **Source:** [JefferyChenjy/annualmetrics-mcp](https://github.com/JefferyChenjy/annualmetrics-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jefferychenjy-annualmetrics-mcp
- Seller: https://agentstack.voostack.com/s/jefferychenjy
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.