Skip to main content
Glama
blurryface1

tradingagents-mcp

by blurryface1
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

TradingAgents MCP Server

将 TradingAgents 多智能体金融研究引擎，以标准 MCP 协议暴露给任意 LLM Host（Codex、Claude Desktop、Cursor 等）的薄适配层。

重要边界：本服务器只产出研究报告与非执行性决策。它不连接任何券商账户，不提交、修改或取消订单。研究结果仅供参考，不构成投资建议。

为什么需要它？

TradingAgents 本身是一个 Python 框架，需要通过编写代码或命令行方式驱动，LLM Host 无法直接调用它。TradingAgents MCP Server 解决了三个问题：

  1. 零代码接入：LLM Host 通过 MCP 协议即可启动研究任务、查询进度、读取完整报告，无需理解 TradingAgents 内部结构。

  2. 异步任务模型：完整金融研究耗时较长（数分钟到数十分钟），本服务器将每次分析建模为异步任务，不阻塞 MCP 调用。

  3. 开箱即用的研究管线：内置任务队列、SQLite 持久化、幂等控制、取消与确认式删除，服务重启后任务状态不会丢失。

Related MCP server: financial-research-agent

特性亮点

  • 7 个 MCP 工具 + 1 个 MCP 资源：完整覆盖能力查询、任务启动、状态轮询、结果读取、任务列表、取消与删除。

  • 异步任务状态机：queued → running → succeeded / failed / cancelled，支持长时间研究任务。

  • 幂等创建：idempotency_key 保证同一分析请求重复提交只创建一次任务。

  • 持久化存储：任务元数据存于 SQLite，报告与中间产物存于磁盘，服务重启后可恢复。

  • 确认式删除：成果永不自动清理；删除必须传入完全匹配的 run_id 二次确认。

  • 凭证隔离：LLM API Key 等敏感配置只存在于服务端环境变量中，MCP 协议层不接触凭证。

架构概览

flowchart LR
    A[LLM Host<br/>Codex / Claude Desktop] -->|MCP stdio| B[MCP Server<br/>tradingagents_mcp.server]
    B --> C[(SQLite<br/>tasks.db)]
    B --> D[TaskRuntime<br/>单 worker 串行队列]
    D -->|子进程隔离| E[worker.py]
    E --> F[TradingAgentsGraph<br/>propagate]
    F --> G[final_state.json<br/>complete_report.md]
    G --> B
    B -->|MCP Resource| A

  • MCP Server：处理工具与资源请求，维护任务队列。

  • SQLite：存储任务元数据与幂等映射，支持原子状态迁移。

  • TaskRuntime：单 worker 串行执行任务，子进程隔离保证上游异常不影响服务器进程。

  • worker.py：子进程内运行 TradingAgentsGraph.propagate()，产出 final_state.json 与 complete_report.md。

快速开始

前置要求

  • Python 3.10+

  • 已安装 TradingAgents：pip install tradingagents（或从源码安装）

  • 已配置 LLM API Key（见下文「LLM 配置」）

安装

cd tradingagents-mcp
pip install -e .

启动

# 方式一：直接启动
python -m tradingagents_mcp.server

# 方式二：使用启动脚本（自动探测 TradingAgents 源码位置）
./start_server.sh

LLM 配置

LLM 提供商配置沿用 TradingAgents 自身的环境变量，由上游 TradingAgentsGraph 读取。MCP 适配器不接触这些凭证。

变量

说明

示例

TRADINGAGENTS_LLM_PROVIDER

LLM 提供商

openai、deepseek、custom_openai

TRADINGAGENTS_MODEL

深度思考模型名

deepseek-v4-flash

TRADINGAGENTS_QUICK_MODEL

快速思考模型名

deepseek-v4-flash

TRADINGAGENTS_BASE_URL

API 地址

https://api.example.com

TRADINGAGENTS_API_KEY

API Key（也可直接用 OPENAI_API_KEY、DEEPSEEK_API_KEY 等上游变量）

sk-...

TRADINGAGENTS_MAX_TOKENS

单次调用最大 token 数

4000

TRADINGAGENTS_TEMPERATURE

采样温度

0.7

服务端配置环境变量：

变量

说明

默认值

TRADINGAGENTS_MCP_DATA_DIR

数据目录（数据库、任务工作区）

~/.tradingagents-mcp

TRADINGAGENTS_MCP_MAX_QUEUED

最大排队任务数

20

TRADINGAGENTS_MCP_TASK_TIMEOUT

单任务超时（秒）

1800

TRADINGAGENTS_MCP_GRAPH_CLASS

上游图类导入路径（自定义安装布局时覆盖）

tradingagents.graph.trading_graph.TradingGraph

提示：所有凭证均以环境变量方式注入服务端进程，MCP 工具参数中永远不会出现 API Key。

配置到 MCP Host

Codex / Claude Desktop

{
  "mcpServers": {
    "tradingagents": {
      "command": "python",
      "args": ["-m", "tradingagents_mcp.server"]
    }
  }
}

工具与资源

工具

说明

只读

幂等

get_capabilities

查询服务器能力与配置（不含凭证）

✅

✅

start_analysis

启动分析任务

❌

✅（idempotency_key）

get_analysis_status

查询任务状态与时间戳

✅

✅

get_analysis_result

获取结果摘要（评级、置信度、报告 URI）

✅

✅

list_analyses

分页列出任务，支持状态过滤

✅

✅

cancel_analysis

取消 queued / running 任务

❌

✅

delete_analysis

永久删除任务（需 confirm_run_id 精确匹配）

❌

✅

MCP 资源：

  • tradingagents://analyses/{run_id}/report — 完整的 Markdown 研究报告（仅 succeeded 任务可访问）

支持的资产与研究参数

参数

取值

说明

symbol

AAPL、600519.SH、BTC

股票代码或加密货币符号

asset_type

stock / crypto

默认 stock；stock 分析师为 market/social/news/fundamentals，crypto 为 market/social/news

analysis_date

YYYY-MM-DD

分析日期，不可为未来日期

depth

shallow / deep

默认 shallow（更快）；deep 更深入

language

English / 中文

默认 English

analysts

分析师类型列表

默认按 asset_type 决定

idempotency_key

可选字符串

相同参数 + 相同 key 返回已有任务

使用示例

1. 查询能力

调用 get_capabilities

返回支持的资产类型、研究深度、输出语言、队列限制等。

2. 启动分析

调用 start_analysis，参数：
- symbol: "AAPL"
- analysis_date: "2025-01-15"
- asset_type: "stock"
- depth: "shallow"
- language: "English"

返回 run_id，例如 run_a1b2c3d4e5f67890。

3. 轮询状态

调用 get_analysis_status，参数：
- run_id: "run_a1b2c3d4e5f67890"

任务状态流转：queued → running → succeeded / failed / cancelled。轮询直到终态。

4. 读取结果摘要

调用 get_analysis_result，参数：
- run_id: "run_a1b2c3d4e5f67890"

返回评级、置信度与报告资源 URI。

5. 阅读完整报告

通过 MCP 资源读取：

tradingagents://analyses/run_a1b2c3d4e5f67890/report

数据存储

所有数据存储在 TRADINGAGENTS_MCP_DATA_DIR（默认 ~/.tradingagents-mcp/）：

~/.tradingagents-mcp/
├── tasks.db            # SQLite 任务元数据数据库
└── runs/
    ├── run_abc123/     # 每个任务的独立工作区
    │   ├── request.json
    │   ├── final_state.json
    │   ├── complete_report.md
    │   ├── SUCCESS.json 或 error.json
    │   └── worker_stderr.log
    └── ...

  • 任务成果永不自动清理，只有显式调用 delete_analysis 才会删除。

  • 服务重启后，中断的 running 任务会自动重新入队。

安全与边界

  • 不做交易：不连接券商，不提交、修改或取消任何订单。

  • 凭证隔离：API Key 只存在于服务端环境变量，绝不通过 MCP 协议传输。

  • 只读查询为主：除 start_analysis、cancel_analysis、delete_analysis 外，其余工具均为只读。

  • 数据默认本地：报告与数据库存储在本地数据目录，不依赖外部 SaaS。

FAQ

Q：为什么不直接在 MCP Host 里调用 TradingAgents？ A：TradingAgents 是 Python 框架，LLM Host 无法原生执行任意 Python。MCP 适配器将研究能力封装为标准化工具，且提供队列、持久化、幂等、取消等工程能力。

Q：如何配置 API Key？ A：在启动 MCP 服务器的进程环境中设置 TRADINGAGENTS_API_KEY（或 OPENAI_API_KEY / DEEPSEEK_API_KEY）等变量。服务器不会通过 MCP 工具暴露或接收凭证。

Q：研究报告可以删除吗？ A：可以，但必须显式调用 delete_analysis 并传入完全匹配的 run_id。成果不会自动清理，避免误删。

Q：分析结果会过期或被覆盖吗？ A：不会。每个任务有独立工作区与持久化存储，幂等键保证同一请求只创建一次任务。

开发与测试

pip install pytest pytest-asyncio
pytest tests/

使用 MCP Inspector 交互式调试：

npx @modelcontextprotocol/inspector python -m tradingagents_mcp.server

许可证

MIT

Available Tools

7 tools
cancel_analysisA
DestructiveIdempotent

Cancel a queued or running analysis task.

Cancellation stops the task and puts it in the 'cancelled' terminal state. The task and its partial results remain available for deletion. Cancellation of a succeeded or failed task has no effect.

Args: run_id: Task identifier to cancel.

ParametersJSON Schema
NameRequiredDescriptionDefault
run_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

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

Goes beyond annotations by explaining the task transitions to a 'cancelled' terminal state, partial results remain available, and no effect on succeeded/failed tasks. This enriches the destructiveHint and idempotentHint annotations without contradiction.

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?

Description is front-loaded with the purpose, followed by concise behavioral notes and a single parameter explanation. No unnecessary verbosity.

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?

Given the simple one-parameter schema, provided annotations, and output schema, the description fully covers the tool's behavior, state transitions, and parameter semantics. No need to describe return values since output schema exists.

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?

The input schema has 0% description coverage, but the description defines run_id as 'Task identifier to cancel,' which is sufficient for a single, simple string parameter.

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 'Cancel a queued or running analysis task,' using a specific verb and resource. It distinguishes itself from siblings like start_analysis and delete_analysis.

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 provides clear context for when cancellation applies (queued/running) and when it has no effect (succeeded/failed). It does not explicitly name alternative tools like delete_analysis, but the guidance is still useful.

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

delete_analysisA
DestructiveIdempotent

Permanently delete an analysis task and all its data.

Per ADR-0009: tasks are never auto-cleaned. You must explicitly delete them with this tool. The confirm_run_id parameter must exactly match the task ID you want to delete — this prevents accidental deletion.

Only terminal tasks (succeeded, failed, cancelled) can be deleted. Deletion removes the task record, the research report, all logs, and the idempotency mapping. This action is irreversible.

Args: confirm_run_id: Must exactly match the run_id to confirm deletion.

ParametersJSON Schema
NameRequiredDescriptionDefault
confirm_run_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (destructive, idempotent), the description discloses what is removed (task record, report, logs, idempotency mapping), confirms irreversibility, and explains the confirmation parameter's purpose. This exceeds what annotations alone provide.

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 well-structured with a front-loaded purpose, followed by essential context and a clear Args section. Every sentence adds value—no fluff or redundancy—making it appropriately sized for a destructive 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?

Given the tool's destructive nature and single parameter, the description covers all critical aspects: when deletion is allowed, what gets deleted, irreversibility, and the confirmation mechanism. The output schema exists, so return values need no explanation. The ADR reference adds useful organizational context.

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?

The schema has one parameter with zero description coverage. The description's Args section provides critical semantics: confirm_run_id must exactly match the run_id to prevent accidental deletion. This meaningfully compensates for the schema gap, though it could have elaborated on how to obtain the run_id.

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 immediately states "Permanently delete an analysis task and all its data" with a specific verb and resource. It distinguishes from siblings like cancel_analysis by specifying only terminal tasks can be deleted, making the purpose unambiguous.

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 explains when to use the tool (explicit deletion is required, no auto-cleanup per ADR-0009) and constrains usage to terminal tasks. It doesn't explicitly name alternatives like cancel_analysis for active tasks, but the context strongly implies that distinction.

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

get_analysis_resultA
Read-onlyIdempotent

Get the result summary of a completed analysis task.

Only returns the structured summary with rating and resource reference. The full markdown report is accessed through the MCP resource URI returned in the result.

Args: run_id: Task identifier for a completed analysis.

ParametersJSON Schema
NameRequiredDescriptionDefault
run_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds valuable behavior: it returns only a structured summary with rating and resource reference, and points to the resource URI for the full report. This goes beyond the schema and annotations.

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 succinct and front-loaded with the purpose. It uses a short intro, a clarifying note about return contents, and a simple Args section. Every sentence adds value with no redundant fluff.

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?

Given the tool's simplicity (one parameter), the annotations, and the existence of an output schema, the description covers the essential context: what it returns, what it doesn't return, and that the task must be completed. It sufficiently differentiates from sibling tools and provides enough guidance for correct use.

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?

The schema only defines run_id as a required string with no description, so the description carries the burden. The line 'Args: run_id: Task identifier for a completed analysis' adds meaningful context about what the parameter represents and the expected state. It does not provide format examples, but that is minor for a single identifier.

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 and resource: 'Get the result summary of a completed analysis task.' It clearly distinguishes from siblings like get_analysis_status (status) and start_analysis (initiate) by focusing on the result summary. The qualifier 'completed' adds precision.

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 clearly implies this tool should be used after an analysis completes, noting it is for a 'completed analysis task.' It also clarifies that the full markdown report is accessed via a resource URI, guiding the user away from expecting that here. However, it does not explicitly name alternatives like get_analysis_status for checking progress.

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

get_analysis_statusA
Read-onlyIdempotent

Get the current status of an analysis task.

Returns task metadata including status (queued, running, succeeded, failed, cancelled) and timestamps. Use this to poll for completion.

Args: run_id: Task identifier returned by start_analysis.

ParametersJSON Schema
NameRequiredDescriptionDefault
run_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds behavioral context by listing the possible statuses ('queued, running, succeeded, failed, cancelled') and timestamps, which helps the agent understand what the response will contain. It also frames polling behavior, going beyond the annotations.

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 concise and well-structured: a one-sentence purpose, a detailed return summary, a usage hint, and an Args block. Every sentence adds value. No fluff or repetition.

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 simple one-parameter polling tool with an output schema and rich annotations, the description is fully adequate. It covers purpose, usage, parameter semantics, and return content. It does not need to explain return structure since an output schema exists.

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

Parameters5/5

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

The schema has only run_id with a title 'Run Id', but no description. The tool description compensates fully by stating 'run_id: Task identifier returned by start_analysis.' This provides provenance and clarifies the parameter's meaning, completely covering the schema's gap.

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 and resource: 'Get the current status of an analysis task.' It clearly distinguishes from siblings like start_analysis (which starts tasks) and get_analysis_result (which likely retrieves results). The action is unambiguous and the scope is well-defined.

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 says 'Use this to poll for completion,' which explicitly tells the agent when to invoke this tool. It does not name alternative tools for exclusions, but the context is clear that polling is the intended use case. This is solid guidance, though it could mention not to use for final results.

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

get_capabilitiesA
Read-onlyIdempotent

Return the capabilities and configuration of this TradingAgents MCP server.

Describes what analyses are supported, default parameters, and server limits. All configuration listed here is non-sensitive — no credentials or API keys.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful context: the tool returns non-sensitive configuration, explicitly noting 'no credentials or API keys.' This goes beyond the structured fields, addressing safety and scope concerns.

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 brief and front-loaded: the first sentence states the core purpose, and the second paragraph adds useful specifics without repetition. Every sentence earns its place, including the non-sensitive reassurance.

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?

Given the tool has no parameters, a rich output schema, and strong annotations, the description covers all necessary aspects: what it returns, supported analyses, default parameters, server limits, and security posture. It is fully complete for a capabilities/metadata tool.

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?

The tool has zero input parameters, so the baseline is 4. The description appropriately focuses on the output content rather than parameter details, and no parameter semantics are needed.

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: 'Return the capabilities and configuration of this TradingAgents MCP server.' It clearly identifies the tool's scope and differentiates it from siblings that handle analysis lifecycle, such as start_analysis or list_analyses.

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 implies when to use the tool by stating it 'Describes what analyses are supported, default parameters, and server limits,' positioning it as a discovery/preflight tool before running analyses. It doesn't explicitly name alternatives or exclusions, but the sibling tools are clearly distinct operations and no ambiguity arises.

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

list_analysesA
Read-onlyIdempotent

List analysis tasks with pagination.

Args: status: Optional filter by status (queued, running, succeeded, failed, cancelled). cursor: Pagination cursor from a previous list call. limit: Maximum number of tasks to return (default 20, max 100).

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
cursorNo
statusNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context by mentioning pagination and the limit default/max, but it does not disclose ordering, what happens when no status filter is provided, or other behavioral traits. This is adequate but not rich, consistent with the calibration example for similar read-only list tools.

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 plus a parameter list. It front-loads the purpose and then concisely details each argument without unnecessary fluff. Every sentence earns its place.

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

Completeness4/5

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

The tool has a simple operation with three optional params and an output schema, so the description does not need to explain the return format. It covers the purpose, pagination, and parameter constraints. However, it does not specify default behavior when no status filter is provided (presumably all statuses) or any ordering, which would make it slightly more complete. Given the simplicity and presence of output schema, this is a minor gap.

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

Parameters5/5

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

Schema coverage is 0% (no descriptions in the schema), and the description fully compensates by explaining each parameter: status with allowed enum values, cursor as a pagination token from previous calls, and limit with default (20) and max (100). This adds substantial meaning beyond the raw type declarations.

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 'List analysis tasks with pagination', identifying the verb (list), resource (analysis tasks), and key behavior (pagination). This distinguishes it from sibling tools like get_analysis_status (single status), start_analysis (creation), and cancel/delete/result (different operations).

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 does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. Usage is implied by the name and the parameter details (e.g., 'cursor from a previous list call' suggests iterative use), but there is no explicit 'use this when' or 'instead of' guidance.

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

start_analysisA
Idempotent

Start a new financial research analysis for a given symbol.

Creates an asynchronous analysis task. Use get_analysis_status to check progress and get_analysis_result to retrieve the final summary once the task succeeds. The full report is available as an MCP resource.

Args: symbol: Stock ticker or crypto symbol (e.g. 'AAPL', '600519.SH', 'BTC'). analysis_date: Date to analyze as YYYY-MM-DD. Must not be in the future. Defaults to today. asset_type: 'stock' or 'crypto'. Auto-detected if omitted. depth: 'shallow' (default, faster) or 'deep' (more thorough). language: Output language: 'English' (default) or '中文'. idempotency_key: Optional stable key. Same key + same params returns existing task.

ParametersJSON Schema
NameRequiredDescriptionDefault
depthNo
symbolYes
languageNo
asset_typeNo
analysis_dateNo
idempotency_keyNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A5/5.0
Behavior5/5

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

The description adds significant behavioral context beyond annotations: it declares the task is asynchronous, mentions idempotency behavior, and notes the full report is available as an MCP resource. It also imposes a constraint on analysis_date (must not be in the future), which is not present in annotations or schema. This complements the readOnlyHint=false and idempotentHint=true annotations without contradiction.

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 well-structured: a concise purpose sentence, a clear workflow sentence, and a bulleted Args list. Every sentence adds value, and the format makes it easy for an agent to parse.

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?

Given the tool's complexity (6 parameters, async behavior), the description covers purpose, workflow, parameter constraints, and resource availability. An output schema exists, so return values are not needed. The description is complete enough for an agent to start an analysis and know how to retrieve the result.

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

Parameters5/5

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

Schema description coverage is 0%, but the description fully compensates by explaining every parameter: symbol with examples, analysis_date with format and constraint, asset_type with valid values and auto-detection, depth with values and defaults, language with values, and idempotency_key with its semantics. This provides far more meaning than the bare schema.

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's action: 'Start a new financial research analysis for a given symbol.' The verb 'start' is specific, and the resource is defined. It also distinguishes itself from sibling tools by explicitly naming get_analysis_status and get_analysis_result for follow-up steps.

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

Usage Guidelines5/5

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

The description provides explicit workflow guidance: 'Use get_analysis_status to check progress and get_analysis_result to retrieve the final summary once the task succeeds.' It names the alternative tools for subsequent actions, making the intended usage pattern clear.

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.1.0
    • First observedcancel_analysis
    • First observeddelete_analysis
    • First observedget_analysis_result
    • First observedget_analysis_status
    • First observedget_capabilities
    • First observedlist_analyses
    • First observedstart_analysis
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.6/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a distinct role in the analysis lifecycle: capabilities introspection, starting, checking status, retrieving results, listing, canceling, and deleting. There is no overlap or ambiguity between them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (get_capabilities, start_analysis, get_analysis_status, etc.). The naming clearly reflects the action and resource, making the API predictable.

Tool Count5/5

Seven tools is a well-scoped set for a task-management server. Each tool is necessary for the full lifecycle and no redundant tools exist.

Completeness5/5

The tool surface covers the complete analysis workflow: initiation, progress tracking, result retrieval, listing, cancellation, and deletion. Includes capabilities discovery and proper cleanup handling, with no obvious missing operations.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • FinClaw

    IlyasFardaouix
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that provides AI agents with financial tools including real-time quotes, backtesting, technical analysis, and multi-exchange data via a simple CLI interface.
    1
    MIT

  • financial-research-agent

    rahul-jajala
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that exposes stock research tools (fundamentals, news, technicals, analyst ratings) to AI clients, enabling autonomous generation of structured investment briefs.
    -

  • quant-research-mcp

    FlawlessByte
    A
    license
    A
    quality
    C
    maintenance
    An MCP server exposing a registry of paper-backed quantitative trading methods plus a deterministic, no-LLM decision helper for reproducible trading research.
    13
    MIT

  • TradeMCP

    Aaditya2502
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that exposes trading analytics — technical indicators, portfolio state, risk metrics, and backtest results — as tools an LLM agent can call.
    5
    MIT