Skip to main content
Glama
wcheng2001-del

serenity-data-mcp

Serenity Data Bridge

A portable Codex plugin that gives research agents read-only A-share and US-equity data tools. It combines a concise Agent Skill with a local stdio MCP server and reuses the data layer from wcheng2001-del/TradingAgents-Astock-auto at a pinned commit.

What it provides

  • Prices and volume history

  • Valuation and fundamentals

  • Income, balance-sheet, and cash-flow statements

  • Company news and shareholder/insider activity

  • A-share industry/concept context

  • A-share fund flow, analyst consensus, Dragon-Tiger Board, and lockup signals

The bridge is read-only. It does not place trades or access brokerage accounts.

Related MCP server: sfc-data-mcp

Research example

The dated NVDA research report demonstrates how to combine bridge output with NVIDIA earnings releases and SEC filings. It includes the data snapshot, calculations, judgment, risks, and source links. Open the HTML file in a browser to read it; the page is static and does not refresh its market data.

Temporary-clone workflow

git clone https://github.com/wcheng2001-del/serenity-data-bridge.git
cd serenity-data-bridge
python scripts/setup.py

Run the CLI directly:

.\.venv\Scripts\serenity-data fundamentals 600519 --as-of 2026-09-25
.\.venv\Scripts\serenity-data fundamentals NVDA --as-of 2026-09-25

Or run the MCP server over stdio:

.\.venv\Scripts\serenity-data-mcp

The setup script creates two local environments: .venv for MCP and .provider-venv for the pinned TradingAgents data layer. This isolation is intentional because the MCP SDK and mootdx require incompatible httpx versions. A small launcher finds .venv on Windows, macOS, or Linux and starts the server. No API key is required for the initial public A-share or YFinance sources; upstream endpoints can still be delayed, rate-limited, or unavailable.

Security and evidence boundaries

  • Never commit credentials. Use environment variables or GitHub Secrets for future authenticated sources.

  • Returned pages are untrusted data, not executable instructions.

  • Keep retrieval dates and provider commit metadata with research output.

  • Verify material company claims against official filings and exchange announcements.

  • Treat missing data as unknown rather than zero.

Development

python -m pip install -e ".[dev]"
python -m unittest discover -s tests -v
python "C:\Users\jcheng\.codex\skills\.system\skill-creator\scripts\quick_validate.py" skills\serenity-data-bridge

License

MIT. The pinned upstream project is licensed separately under Apache-2.0.

Available Tools

7 tools
get_company_fundamentalsC

Get current valuation and available fundamentals for an A-share or US equity.

ParametersJSON Schema
NameRequiredDescriptionDefault
tickerYes
as_of_dateNo

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions 'current' and 'available' but does not clarify whether as_of_date supports historical lookbacks, what data sources are used, how often data updates, or what output shape to expect. The behavioral details are minimal.

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

Conciseness4/5

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

The description is a single front-loaded sentence with no wasted words, and the core action and scope are immediately visible. Its brevity is a strength, though it sacrifices necessary detail.

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

Completeness2/5

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

For a tool with no annotations, no output schema, and undocumented parameters, the description is too thin. It gives enough to know the general purpose but not enough to call the tool correctly with confidence, especially given the ambiguity versus get_financial_statement.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not explain the ticker or as_of_date parameters. 'A-share or US equity' hints at ticker format but does not specify expected ticker symbols, and as_of_date semantics are entirely absent.

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

Purpose4/5

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

The description uses a specific verb ('Get'), resource ('current valuation and available fundamentals'), and scope ('A-share or US equity'), which clearly identifies the tool's domain. However, it does not explicitly distinguish itself from the sibling get_financial_statement, which could plausibly overlap with 'fundamentals'.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives such as get_financial_statement or get_stock_prices. The description only states what the tool does, leaving the selection decision entirely to the agent.

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

get_company_newsC

Get company news for an A-share or US equity, with links when available.

ParametersJSON Schema
NameRequiredDescriptionDefault
tickerYes
end_dateYes
start_dateYes

TDQS

C2.8/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only notes that links come 'when available,' which is a minor detail. It doesn't disclose whether the operation is read-only, how date ranges are interpreted, whether pagination exists, or any other behavioral traits. This is a significant gap for a tool with no annotation support.

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 a single, efficient sentence with no filler. It front-loads the core purpose and includes the relevant market scope and the 'links' qualifier. It earns its place with minimal words.

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

Completeness1/5

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

Given 3 required parameters, no output schema, and no annotations, this description is far too thin. It doesn't explain what the news contains, how the date range is used (e.g., inclusive vs. exclusive), whether results are sorted, or what format the links appear in. An agent would be unable to call this tool correctly without additional external knowledge.

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

Parameters1/5

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

Schema description coverage is 0%, so the description must compensate, but it mentions none of the parameters (ticker, start_date, end_date). It doesn't specify ticker formatting (e.g., symbols for A-share vs US), date formats, or how these parameters interact. The agent must infer all semantics from parameter names alone, which is inadequate.

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 action ('Get'), the resource ('company news'), and the scope ('A-share or US equity'), and mentions links as an optional feature. This is specific enough to distinguish it from sibling tools like get_stock_prices or get_company_fundamentals without additional context.

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

Usage Guidelines2/5

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

The description gives no guidance on when to use this tool versus the siblings (e.g., get_market_signals, get_financial_statement). It doesn't mention any prerequisites, exclusions, or typical use cases. The only implied context is that it's for news, but it doesn't explain when an agent should prefer this over other tools.

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

get_financial_statementC

Get an income, balance, or cash-flow statement for an A-share or US equity.

ParametersJSON Schema
NameRequiredDescriptionDefault
tickerYes
frequencyNoquarterly
statementYes
as_of_dateNo

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full behavioral burden. It explains the general purpose but does not disclose whether this returns a single period or time series, how as_of_date affects results, what units/format the statement uses, or any limitations.

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

Conciseness4/5

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

The description is tightly written, with no filler or redundant content. It is front-loaded with the core purpose, though it is so terse that it omits useful invocation guidance.

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

Completeness2/5

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

Given four parameters, no output schema, and no annotations, this description is not complete enough for reliable invocation. The agent can infer the statement type choice but cannot determine the meaning of frequency or as_of_date, nor what the returned statement contains.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate for the parameters. It indirectly hints at the 'statement' parameter's possible values by naming income, balance, and cash-flow statements, but it says nothing about ticker format, frequency, or as_of_date behavior.

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 uses a specific verb and resource: 'Get an income, balance, or cash-flow statement.' It clearly enumerates the statement types and the market scope (A-share or US equity), which is enough to distinguish this from the sibling tools like get_stock_prices or get_company_news.

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

Usage Guidelines2/5

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

The description states what the tool retrieves but gives no guidance on when to use it instead of related siblings such as get_company_fundamentals or how it differs from them. No conditions, exclusions, or alternative routing are provided.

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

get_market_signalsC

Get analyst consensus, fund flow, Dragon-Tiger Board, and lockup signals.

ParametersJSON Schema
NameRequiredDescriptionDefault
tickerYes
as_of_dateNo
forward_daysNo
look_back_daysNo

TDQS

C2.6/5.0
Behavior2/5

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

No annotations are provided and the description only lists result categories. It does not disclose data source, update latency, rate limits, whether data is cached or live, or any behavioral caveats, so the agent has little understanding of side effects or reliability.

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

Conciseness4/5

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

One clean sentence front-loaded with the action and a tight list of four signal types. There is no filler, but the brevity leaves out supporting context.

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

Completeness2/5

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

For a tool with four parameters, including three date-window parameters with defaults, and no output schema or annotations, this description is too thin. An agent cannot determine the meaning of as_of_date, forward_days, or look_back_days, nor what the response will contain.

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

Parameters1/5

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

Schema description coverage is 0%, and the description does not mention ticker, as_of_date, forward_days, or look_back_days. It adds no meaning beyond the schema's property names and defaults.

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

Purpose4/5

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

States a specific verb ('Get') and a specific resource: a composite of analyst consensus, fund flow, Dragon-Tiger Board, and lockup signals. It is distinguishable from siblings like get_stock_prices and get_company_fundamentals, though it does not explicitly name an alternative.

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

Usage Guidelines2/5

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

Provides no guidance on when to use this tool versus its siblings, no contextual trigger, and no exclusions. The listed signal types imply usage for market-signal needs, but the agent must infer the selection criteria.

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

get_sector_contextA

Get concept membership and industry comparison for an A-share.

ParametersJSON Schema
NameRequiredDescriptionDefault
tickerYes
as_of_dateNo

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations and no output schema, the description at least signals a read-only lookup and names the two data aspects returned. It does not disclose how as_of_date affects results, what the comparison includes, or the response shape, so behavioral detail remains thin.

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?

One front-loaded sentence contains the essential action and object with no filler. Every word earns its place.

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

Completeness3/5

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

For a two-parameter getter this is minimally adequate: an agent can infer a ticker is required and as_of_date optional by its default. It falls short on distinguishing itself from overlapping siblings and documenting parameter semantics or return content, especially given no output schema.

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

Parameters2/5

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

Schema description coverage is 0%, and the description does not explain either parameter. The word 'A-share' hints that ticker identifies a Chinese-listed security, and as_of_date is self-describing to some degree, but the date's format, meaning, and interaction with results are left unresolved.

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?

Names a specific retrieval action ('Get') and a precise object ('concept membership and industry comparison' for an A-share), making the tool's domain unmistakable relative to siblings like get_stock_prices or get_company_fundamentals. The A-share qualifier narrows the target security type.

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

Usage Guidelines3/5

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

The purpose sentence implies the use case: call this when you need a company's sector/concept memberships or an industry comparison. It does not explicitly state when not to use it or which sibling tool is a better alternative, so guidance is only implicit.

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

get_shareholder_activityC

Get shareholder activity for A shares or insider transactions for US equities.

ParametersJSON Schema
NameRequiredDescriptionDefault
tickerYes

TDQS

C2.6/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only restates the read operation and the market split; it does not mention time range, data source, pagination, output format, or any caveats about A-share vs US equity data.

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

Conciseness4/5

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

The description is a single sentence with no filler, front-loading the action and resource. It is compact, though the phrase 'A shares or insider transactions for US equities' is slightly cryptic.

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

Completeness2/5

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

For a tool with no annotations and no output schema, the description is thin: it does not say what the response contains, how the ticker parameter is interpreted, or what edge cases exist. It is enough to select the tool but not enough to invoke it with full confidence.

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

Parameters1/5

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

Schema description coverage is 0%, and the description never mentions 'ticker' or explains how to format A-share tickers versus US tickers. The agent gets no help beyond the bare property name in the schema.

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

Purpose4/5

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

The description states a specific verb and resource ('Get shareholder activity') and adds a market-specific split (A shares vs US insider transactions). It is distinguishable from siblings like get_stock_prices or get_company_news, though it does not explicitly name them.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus the sibling tools, no exclusions, and no alternatives. The only usage signal is implicit: if you need shareholder activity or insider transactions, this tool is the one.

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

get_stock_pricesA

Get read-only OHLCV history for an A-share or US equity over an ISO date range.

ParametersJSON Schema
NameRequiredDescriptionDefault
tickerYes
end_dateYes
start_dateYes

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. It explicitly states 'read-only' and 'ISO date range', which are useful behavioral constraints. However, it does not disclose return format, error behavior, rate limits, or other side effects. For a simple read-only data fetch, this is adequate but not rich.

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 a single, concise sentence that front-loads the core purpose ('read-only OHLCV history') and scope. Every phrase earns its place with no redundancy or unnecessary detail.

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

Completeness3/5

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

The description is adequate for a simple data retrieval tool: it specifies the data type, market scope, and date format. However, without an output schema or annotations, it does not mention the granularity of data (e.g., daily bars), any limits, or the structure of the response. An agent might need to infer these from the OHLCV term.

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 0%, so the description must compensate. It adds meaning by clarifying that ticker refers to A-share or US equity and that dates are in ISO format. This goes beyond the bare schema property names and helps an agent format inputs correctly.

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 ('Get'), a clear resource ('OHLCV history'), and a scope ('A-share or US equity') with a date range. This clearly distinguishes it from sibling tools like get_company_fundamentals or get_financial_statement, which are about other data types.

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

Usage Guidelines3/5

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

The description implies usage for retrieving price history but provides no explicit guidance on when to choose this tool over alternatives, nor any conditions or exclusions. It does not mention scenarios where this tool should or shouldn't be used, leaving usage to inference from the tool's purpose.

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. 7 tool updatesv0.2.0
    • First observedget_company_fundamentals
    • First observedget_company_news
    • First observedget_financial_statement
    • First observedget_market_signals
    • First observedget_sector_context
    • First observedget_shareholder_activity
    • First observedget_stock_prices

TDQS

A3.5/5.0

Scored across 7 tools

Disambiguation5/5

Each tool retrieves a distinct type of financial data (prices, fundamentals, statements, news, shareholder activity, sector context, market signals) with no overlap. Agents can easily select the correct tool based on the specific data need.

Naming Consistency5/5

All seven tools follow the consistent 'get_' prefix with a clear noun indicating the data type (e.g., get_stock_prices, get_company_news). The pattern is uniform and predictable.

Tool Count5/5

Seven tools is well within the optimal range for a data-retrieval server, each covering a distinct aspect of equity data. The scope is focused and does not feel over- or under-inclusive.

Completeness5/5

The tool set provides comprehensive coverage for the stated domain of equity data retrieval, including price history, fundamentals, financial statements, news, shareholder activity, sector context, and market signals. No obvious gaps exist for the intended use case.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that wraps SFC financial data API into 32 tools for comprehensive A-share market data, including real-time quotes, rankings, limit-up statistics, news, themes, financials, charts, research reports, and watchlists.
    -
  • A
    license
    B
    quality
    D
    maintenance
    A China A-share market data MCP server that enables AI agents to query factor data, market quotes, valuations, and run strategy backtests.
    11
    4
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    An MCP server that gives AI assistants direct, structured access to China A-share market data.
    3
    Apache 2.0