MCP Tools Introduction

This section introduces the three core tools of the Financial MCP service: company lookup, keyword search, and page-level reading.

Recommended call order: use searchCompanyInfo first to resolve stockCode and market; then financialKeywordSearch to locate pages (or read the first 3–5 pages for the TOC); finally getFinancialReportPages for the original text. To locate the core financial statements, search the statement name with matchMode=ALL.

1. Company Profile Query

Look up listed companies by name or stock code. Returns stockCode, short name, market, and listing date. Call this first when the user mentions a company name or an unknown code, then pass the returned stockCode and market to the other tools.

Parameter	Type	Required	Default	Description
query	String	Yes	-	Company name or stock code. CN-A: 6 digits (000001); HK: 5 digits (00700); US: uppercase ticker (AAPL)
market	String	Yes	-	Required market: CN-A / HK / US. Query one market per call
size	Integer	No	5	Number of results to return, max 100

Request Parameters Example (AI Generated)

{
  "name": "searchCompanyInfo",
  "arguments": {
    "query": "Ping An Bank",
    "market": "CN-A"
  }
}

Response Data Example (Backend Output)

[
  {
    "stockCode": "000001",
    "stockName": "Ping An Bank",
    "market": "CN-A",
    "listingDate": "1991-04-03"
  }
]

2. Financial Keyword Search

Full-text keyword search across financial reports. Extract 1–5 core keywords (never full sentences) and get matching fragments with page numbers. Use Simplified Chinese financial terms for CN-A and English for HK/US. reportType is required when stockCode is omitted. To locate a statement or chapter, use its name as the keyword with matchMode=ALL.

Parameter	Type	Required	Default	Description
keywords	List<String>	Yes	-	1–5 core keywords; do not pass full sentences
stockCode	String	No	-	Prefer the code from searchCompanyInfo. Omit for cross-company search
reportType	String	No	-	Annual e.g. 2025a4, interim e.g. 2026h2. Required when stockCode is omitted
market	String	No	-	Optional: CN-A / HK / US. Omit to search all markets
matchMode	String	No	ANY	Match mode: ANY (default) / ALL / MOST (at least 70%)
size	Integer	No	5	Number of fragments to return, max 1000
pageMin	Integer	No	-	Minimum page number (inclusive)
pageMax	Integer	No	-	Maximum page number (inclusive)

Request Parameters Example (AI Generated)

Example 1 — company search:
{
  "name": "financialKeywordSearch",
  "arguments": {
    "keywords": ["net profit", "YoY growth"],
    "stockCode": "000001",
    "reportType": "2024a4",
    "market": "CN-A"
  }
}

Example 2 — locate a statement:
{
  "name": "financialKeywordSearch",
  "arguments": {
    "keywords": ["consolidated balance sheet"],
    "stockCode": "000001",
    "reportType": "2024a4",
    "matchMode": "ALL",
    "market": "CN-A"
  }
}

Response Data Example (Backend Output)

Found 3 matching fragments (total score range: 12.5 - 8.1):

--- Fragment 1 (Score: 12.5) ---
Report: Ping An Bank 2024 Annual Report
market: CN-A
stock_code: 000001
report_type: 2024a4
Page: 45
Content: ...The company realized a net profit of 50.238 billion yuan in 2024...

3. Page-Level Content Reading

Read original report text by page range. Use a known page number directly; to discover the TOC, call with startPage=1 and pageCount=3–5, then call again at the target page. pageCount defaults to 5 and maxes at 5. For specific facts, prefer financialKeywordSearch first, then read the returned page.

Parameter	Type	Required	Default	Description
stockCode	String	Yes	-	Prefer the code from searchCompanyInfo. CN-A 6 digits, HK 5 digits, US uppercase ticker
reportType	String	Yes	-	Annual e.g. 2025a4, interim e.g. 2026h2
startPage	Integer	Yes	-	Starting page number (1-based)
pageCount	Integer	No	5	Number of pages to fetch, default 5, max 5
market	String	No	-	Optional: CN-A / HK / US. Omit to search all markets

Request Parameters Example (AI Generated)

{
  "name": "getFinancialReportPages",
  "arguments": {
    "stockCode": "000001",
    "reportType": "2024a4",
    "startPage": 1,
    "pageCount": 5,
    "market": "CN-A"
  }
}

Response Data Example (Backend Output)

Found 5 documents. Showing 5 pages starting from 1:

--- Page 1 ---
[TOC and front-page original text...]
[stock_code]: 000001
[report_type]: 2024a4
[market]: CN-A