Skip to main content
Glama
Gajarthan

CSE MCP Server

by Gajarthan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

CSE MCP Server

cse-mcp MCP server

@gajarthan/cse-mcp is a TypeScript Model Context Protocol server for the Colombo Stock Exchange. It gives MCP-compatible clients a clean way to search listed companies, fetch normalized single-stock quotes, and retrieve market-wide snapshots such as status, summary, top gainers, top losers, and index data. It is built for developers, analysts, and AI-tool builders who want fast access to CSE data through a stable MCP tool surface instead of scraping raw website responses inside prompts.

Key Features

  • Search listed CSE companies by symbol or company name using the local CSV catalog

  • Fetch normalized stock quote data from companyInfoSummery

  • Retrieve market-wide data from marketStatus, marketSummery, topGainers, topLooses, aspiData, and snpData

  • Validate tool inputs before making upstream requests

  • Normalize undocumented CSE payloads into AI-friendly JSON

  • Use a dedicated service layer for CSE HTTP calls and thin MCP handlers

  • Apply request timeout and basic retry handling for transient upstream failures

  • Log only to stderr so stdout stays clean for MCP transport

  • Stay compatible with MCP Inspector and local stdio-based MCP clients

Related MCP server: Financial Datasets MCP Server

Disclaimers, Security, and Privacy

  • This project uses unofficial, reverse-engineered public endpoints exposed by https://www.cse.lk/api/. Response shapes may change without notice.

  • Market data may be delayed, incomplete, or temporarily unavailable. Verify important figures against official sources before making financial decisions.

  • This server makes outbound requests to the CSE website. Symbols and request payloads sent through tools are transmitted to that external service.

  • This server does not require API keys and does not include built-in telemetry or analytics.

  • Tool outputs are returned to the MCP client you connect it to. Treat client logs, transcripts, and tool approval history as potentially sensitive.

  • The server currently supports local stdio transport only. It does not yet expose a remote HTTP or SSE MCP endpoint.

Requirements

  • Node.js 20 or newer

  • npm 10 or newer

  • Internet access to https://www.cse.lk

  • An MCP client that supports local stdio servers

Getting Started

Use a local build

Build locally:

npm install
npm run build

Minimum local MCP config:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

If you are developing locally, MCP Inspector is the fastest smoke test:

npm run inspector

Use the published npm package

If the package is published to npm, the fastest install path becomes:

{
  "mcpServers": {
    "cse": {
      "command": "npx",
      "args": ["-y", "@gajarthan/cse-mcp"]
    }
  }
}

First test prompt

Use search_company to find John Keells Holdings, then call get_stock_quote for the correct symbol.

MCP Client Configuration

This server supports local stdio usage only. In most clients, you can configure it in one of two ways:

  • local development mode: node C:/absolute/path/to/cse-mcp/dist/index.js

  • published package mode: npx -y @gajarthan/cse-mcp

Local stdio vs remote HTTP

  • Supported now: local stdio MCP clients that launch a process with command and args

  • Not supported yet: remote-only MCP clients that require SSE or streaming HTTP transport

Claude Code

Claude Code documents MCP support and works well with local stdio servers.

Add the server directly:

claude mcp add-json cse "{\"type\":\"stdio\",\"command\":\"node\",\"args\":[\"C:/absolute/path/to/cse-mcp/dist/index.js\"]}"

Published-package variant:

claude mcp add-json cse "{\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"@gajarthan/cse-mcp\"]}"

Or use .mcp.json:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

If Claude Desktop is already configured, you can also import those MCP entries into Claude Code:

claude mcp add-from-claude-desktop

Codex

OpenAI documents MCP configuration in ~/.codex/config.toml, and the Codex CLI and IDE extension share it.

CLI setup:

codex mcp add cse -- node C:/absolute/path/to/cse-mcp/dist/index.js

Published-package CLI setup:

codex mcp add cse -- npx -y @gajarthan/cse-mcp

config.toml setup:

[mcp_servers.cse]
command = "node"
args = ["C:/absolute/path/to/cse-mcp/dist/index.js"]

Published-package config.toml setup:

[mcp_servers.cse]
command = "npx"
args = ["-y", "@gajarthan/cse-mcp"]

Cursor

Cursor MCP support is version-dependent. In versions that support local MCP servers, use a config equivalent to:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

If the client supports npx, you can usually replace the command with:

{
  "mcpServers": {
    "cse": {
      "command": "npx",
      "args": ["-y", "@gajarthan/cse-mcp"]
    }
  }
}

Verify the exact config path and UI flow in your installed Cursor version.

VS Code / Copilot

VS Code and GitHub Copilot MCP support is version-dependent. In builds that support local MCP servers, the common pattern is a workspace or user mcp.json-style config using command and args:

{
  "servers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

Verify the exact file location and schema for your VS Code or Copilot version before relying on this example.

Cline

Cline MCP support is version-dependent. In versions that support local MCP stdio servers, use the same process-launch pattern:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

Verify the current config file name and location in the Cline docs or extension UI.

Continue

Continue support is version-dependent and may be configured through its YAML or UI-based MCP settings. The practical local setup is still the same:

mcpServers:
  cse:
    command: node
    args:
      - C:/absolute/path/to/cse-mcp/dist/index.js

Verify the current Continue config format for your installed version.

Roo Code

Roo Code MCP support is version-dependent. Use the same local stdio command pattern in the version-specific MCP settings:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

TODO: verify and document the exact current Roo Code config path.

Gemini CLI

Gemini CLI MCP support is version-dependent. For versions that support local MCP servers, configure this server as a local stdio process:

{
  "mcpServers": {
    "cse": {
      "command": "node",
      "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
    }
  }
}

Verify the current Gemini CLI config path and schema in the version you are using.

Smithery Publishing

This project is intended for Smithery publishing through the GitHub repository integration path.

What is verified:

  • The server is a local stdio MCP server

  • The npm package is published as @gajarthan/cse-mcp

  • The repository is public on GitHub

What is intentionally not supported today:

  • public HTTPS MCP deployment

  • SSE transport

  • hosted remote MCP URL publishing

For Smithery, that means the practical route is to connect the GitHub repo and let Smithery build from the repository, branch, and base directory instead of requiring a public MCP URL.

Recommended Smithery settings for this repo:

  • repository: Gajarthan/cse-mcp

  • branch: master

  • base directory: .

  • auto deploy: enable only after the first successful publish

See SMITHERY.md for the full GitHub-to-Smithery workflow, checklists, and common failure points.

Releases

This repository already includes tag-driven release automation in .github/workflows/release.yml.

To create a GitHub release:

  1. Update package.json, src/index.ts, server.json, and glama.json to the intended version

  2. Add release notes to CHANGELOG.md

  3. Run npm run release:check

  4. Create and push a semver tag such as v2.0.1

  5. Open the draft GitHub release created by Actions, review the generated notes, and publish it

The workflow validates the release on both Ubuntu and Windows before drafting the GitHub release.

Tool Reference

search_company

Search the local CSV catalog by company name or ticker symbol.

Input:

{
  "query": "john keells"
}

Returns:

  • normalized query

  • ranked matches

  • symbol, company name, and match score

get_stock_quote

Fetch a normalized quote for a valid CSE symbol.

Input:

{
  "symbol": "JKH.N0000"
}

Returns:

  • last price and previous close

  • price change and percentage change

  • day range and 52-week range

  • volume, turnover, market cap, and beta values

  • source metadata and fetched timestamp

get_market_status

Fetch the current market session string from CSE and normalize it to a status plus inferred open/closed signal.

Input:

{}

get_market_summary

Fetch market-wide turnover, share volume, trade count, and trade date.

Input:

{}

get_top_gainers

Fetch the top market gainers.

Input:

{
  "limit": 10
}

Notes:

  • default limit is 10

  • maximum limit is 25

get_top_losers

Fetch the top market losers.

Input:

{
  "limit": 10
}

Notes:

  • default limit is 10

  • maximum limit is 25

get_index_summary

Fetch one or both supported index summaries.

Input:

{
  "index": "all"
}

Allowed values:

  • aspi

  • snp

  • all

Configuration, Flags, and Environment Variables

Current runtime configuration

  • Transport: stdio only

  • Required environment variables: none

  • Required API keys: none

  • Default upstream timeout: 10000ms

  • Default retry count for transient failures: 2

CLI flags

This project does not currently expose custom CLI flags. Run it with:

node dist/index.js

Environment variables

This project does not currently require or document custom environment variables.

TODO

If timeout, retry count, base URL override, or CSV path override should become user-configurable, they should be added explicitly and documented here rather than inferred from source code.

Known Limitations

  • This server supports stdio transport only

  • The upstream CSE API is unofficial and may change without notice

  • Market data correctness and availability depend on the CSE website

  • Hosted HTTP/SSE deployment is not implemented yet

  • Smithery GitHub publishing is documentation-aligned here, but the final build behavior should still be verified in your Smithery project UI and deployment logs

Troubleshooting

The client shows no tools

  • Make sure the client supports local stdio MCP servers

  • Make sure the path in args is absolute

  • Run npm run build before pointing the client at dist/index.js

  • Restart the MCP client after changing config

  • If you are using the npm package path, make sure npx @gajarthan/cse-mcp works from your terminal

The server fails to start

Run the server directly to inspect stderr:

node dist/index.js

Check:

  • Node.js version is 20 or newer

  • dependencies are installed

  • dist/index.js exists

  • the client config uses the correct path separator and quoting for your OS

Quote lookup fails for a symbol

  • Use search_company first to confirm the exact CSE symbol

  • Symbols are validated against the bundled CSV catalog before quote calls

  • If the symbol exists in CSE but not in the CSV, update cse_companies.csv

Upstream timeouts or unexpected response errors

  • The CSE API is unofficial and response shapes can change

  • Retry a few minutes later to rule out transient issues

  • Re-run with MCP Inspector or direct local execution to inspect stderr logs

  • If the response shape changed, update the Zod parsing and normalization logic in src/services/cseApi.ts

ChatGPT does not connect to this server

That is expected for now. This server is stdio-only, while ChatGPT's documented remote MCP flow expects SSE or streaming HTTP.

Windows path issues

Use an absolute path and forward slashes in JSON config when possible:

{
  "command": "node",
  "args": ["C:/absolute/path/to/cse-mcp/dist/index.js"]
}

If you do not want to deal with local paths, prefer the published package form:

{
  "command": "npx",
  "args": ["-y", "@gajarthan/cse-mcp"]
}

If a client has trouble launching the package directly, use the explicit npm package form:

{
  "command": "npx",
  "args": ["-y", "-p", "@gajarthan/cse-mcp", "cse-mcp"]
}

Development

Install and build:

npm install
npm run build

Useful scripts:

  • npm run dev - watch-mode development with tsx

  • npm run build - compile TypeScript to dist/

  • npm run typecheck - run TypeScript checks without emitting files

  • npm run start - start the compiled server

  • npm run inspector - launch MCP Inspector against the local build

  • npm run pack:check - verify npm package contents without publishing

  • npm run release:check - run typecheck, build, tests, and npm pack validation

Recommended local workflow:

  1. Run npm install

  2. Run npm run typecheck

  3. Run npm run build

  4. Run npm run inspector

  5. Test at least:

    • search_company

    • get_stock_quote

    • get_market_summary

    • get_index_summary

Project layout:

  • src/index.ts - MCP server bootstrap and stdio transport

  • src/services/companyLookup.ts - CSV-backed symbol and company search

  • src/services/cseApi.ts - CSE API HTTP calls, validation, retries, and normalization

  • src/tools/*.ts - individual MCP tool definitions

  • src/utils/errors.ts - safe error handling and stderr logging

  • src/utils/formatters.ts - output formatting and normalization helpers

Changelog

See CHANGELOG.md.

Contributing

This is an open source project, and contributions are welcome.

See CONTRIBUTING.md for local setup, validation steps, and pull request expectations.

Suggested contribution flow:

  1. Fork the repository

  2. Create a feature branch

  3. Run npm install

  4. Run npm run typecheck

  5. Run npm run build

  6. Test with MCP Inspector

  7. Open a pull request with a clear summary

High-value contribution areas:

  • new tools such as chartData, allSectors, and announcements

  • stronger automated tests for normalization and error handling

  • better handling of CSE response shape drift

  • clearer client configuration docs as MCP client support evolves

If you discover a changed CSE response shape, include a sanitized example payload in the issue or PR whenever possible.

Available Tools

7 tools
get_index_summaryGet Index SummaryC

Return ASPI, S&P SL20, or both as concise index summaries.

ParametersJSON Schema
NameRequiredDescriptionDefault
indexNoOptional index selector. Use aspi, snp, or all. Defaults to all.

TDQS

C2.9/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 states the tool returns 'concise index summaries,' which implies a read-only operation, but doesn't clarify aspects like data freshness, rate limits, error conditions, or authentication needs. This leaves significant gaps in understanding how the tool behaves beyond its basic function.

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 that directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it easy for an agent to parse quickly.

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 the lack of annotations and output schema, the description is incomplete for effective tool use. It doesn't explain what the 'concise index summaries' contain, their format, or any behavioral traits like performance or limitations. For a tool with no structured metadata, this leaves too much undefined for reliable agent invocation.

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

Parameters3/5

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

The input schema has 100% description coverage, clearly documenting the optional 'index' parameter with enum values and a default. The description adds minimal value by mentioning the same indices but doesn't provide additional semantic context beyond what the schema already covers, meeting the baseline for high schema coverage.

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 clearly states the action ('Return') and resources ('ASPI, S&P SL20, or both as concise index summaries'), making the tool's purpose understandable. However, it doesn't explicitly differentiate from sibling tools like get_market_summary, which might overlap in functionality, preventing a perfect score.

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 provides no guidance on when to use this tool versus alternatives like get_market_summary or get_market_status. It mentions what the tool does but offers no context for selection among siblings, leaving the agent to infer usage scenarios.

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

get_market_statusGet Market StatusA

Return the current Colombo Stock Exchange trading session status.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/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 states the tool returns current status but lacks details on data freshness, rate limits, error conditions, or response format, which are important for a real-time market data tool.

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 that directly states the tool's purpose without any redundant or verbose language. It is appropriately sized and front-loaded with essential information.

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?

Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but has gaps. It explains what the tool does but lacks behavioral context like response format or reliability details, which would be helpful for an agent using this in a financial 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 tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, earning a baseline score of 4 for not adding unnecessary information.

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 specific action ('Return') and resource ('current Colombo Stock Exchange trading session status'), distinguishing it from siblings like get_index_summary or get_market_summary by focusing specifically on session status rather than broader market data.

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?

No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, timing considerations, or differentiate from similar tools like get_market_summary, leaving the agent to infer usage context.

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

get_market_summaryGet Market SummaryB

Return concise market-wide volume, turnover, trade-count, and trade-date data.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/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 states the tool returns data but doesn't describe important behavioral traits such as whether it's real-time or historical data, rate limits, authentication requirements, error conditions, or response format. The description is minimal and lacks essential operational context.

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 that immediately states the tool's purpose without any wasted words. It's appropriately sized for a simple data retrieval tool and front-loads the essential information about what data is returned.

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 the tool's simplicity (zero parameters) but lack of annotations and output schema, the description is insufficiently complete. It doesn't explain the return format, data freshness, or how this market-wide summary differs from sibling tools. For a financial data tool that agents will need to use appropriately, more contextual information would be helpful.

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 parameters with 100% schema description coverage, so the schema already fully documents the parameter situation. The description appropriately doesn't discuss parameters, maintaining focus on what the tool returns rather than what it accepts. This meets the baseline expectation for a zero-parameter tool.

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 clearly states the tool's purpose with a specific verb ('Return') and resource ('concise market-wide...data'), listing the exact data types returned (volume, turnover, trade-count, trade-date). However, it doesn't explicitly differentiate from sibling tools like get_index_summary or get_market_status, which likely provide related but different market data.

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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like get_index_summary or get_market_status, nor does it specify use cases, prerequisites, or exclusions for this market-wide summary tool.

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

get_stock_quoteGet Stock QuoteA

Get a normalized stock quote for a single CSE symbol, including price movement, volume, turnover, market cap, and beta values.

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolYesCSE ticker symbol such as JKH.N0000.

TDQS

A3.5/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 burden of behavioral disclosure. While it states the tool retrieves a 'normalized stock quote' and lists data fields, it doesn't cover critical behavioral aspects such as rate limits, authentication requirements, error handling, or whether the data is real-time or delayed. For a read operation with zero annotation coverage, this leaves significant gaps in transparency.

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, well-structured sentence that efficiently conveys the tool's purpose, scope, and included data fields without any redundant or unnecessary information. It's appropriately sized and front-loaded, with every element serving a clear purpose in helping the agent understand the tool.

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?

Given the tool's moderate complexity (single parameter, read operation) and lack of annotations or output schema, the description is partially complete. It covers the basic purpose and data fields but misses behavioral details like response format, error cases, or performance characteristics. For a tool with no output schema, more information about return values would be beneficial, though the listed data fields provide some guidance.

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

Parameters3/5

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

Schema description coverage is 100%, with the parameter 'symbol' fully documented in the schema (including type, constraints, and example). The description adds minimal value beyond the schema by specifying 'CSE symbol' and implying it's for a single symbol, but doesn't provide additional syntax, format details, or usage context that isn't already covered in the structured 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 specific action ('Get a normalized stock quote') and resource ('for a single CSE symbol'), distinguishing it from siblings like get_index_summary or get_market_summary by focusing on individual stock data. It explicitly lists the included data fields (price movement, volume, turnover, market cap, beta values), making the purpose highly specific and differentiated.

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 detailed quote data for a single CSE symbol, but provides no explicit guidance on when to use this tool versus alternatives like search_company or get_top_gainers. It mentions the symbol type (CSE) which offers some context, but lacks clear when/when-not instructions or named alternatives for different use cases.

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

get_top_gainersGet Top GainersB

Return the top CSE gainers with normalized price, percentage change, and timestamps.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoOptional number of rows to return. Defaults to 10 and caps at 25.

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden but offers minimal behavioral context. It mentions 'normalized price' and 'timestamps' but doesn't explain what normalization entails, data freshness, rate limits, authentication needs, or error conditions. This leaves significant gaps for a tool returning financial data.

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 that front-loads the core purpose. Every word contributes meaning without redundancy, making it appropriately sized for this simple tool.

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 simple read-only tool with one optional parameter and no output schema, the description is minimally adequate. However, it lacks details about data sources, update frequency, or example outputs that would help an agent understand what to expect, especially given the absence of annotations.

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

Parameters3/5

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

Schema description coverage is 100%, so the parameter 'limit' is fully documented in the schema. The description adds no additional parameter information beyond what the schema provides, meeting the baseline for high schema coverage.

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 clearly states the action ('Return') and resource ('top CSE gainers') with specific data fields (price, percentage change, timestamps). It distinguishes from siblings like 'get_top_losers' by specifying gainers, but doesn't explicitly differentiate from other market data tools like 'get_market_summary'.

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?

No guidance is provided on when to use this tool versus alternatives like 'get_top_losers' for losers, 'get_market_summary' for broader data, or 'search_company' for specific stocks. The description only states what it does, not when it's appropriate.

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

get_top_losersGet Top LosersB

Return the top CSE losers with normalized price, percentage change, and timestamps.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoOptional number of rows to return. Defaults to 10 and caps at 25.

TDQS

B3.1/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 burden of behavioral disclosure. It states what data is returned but doesn't mention performance characteristics (e.g., real-time vs. delayed data), rate limits, authentication requirements, or error conditions. For a financial data tool with no annotations, this leaves significant behavioral gaps.

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 that front-loads the core purpose and includes key data fields. Every word earns its place with no wasted text, making it easy to parse quickly.

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?

Given the tool's moderate complexity (financial data retrieval with one parameter), no annotations, and no output schema, the description is minimally adequate. It covers what data is returned but lacks details on data freshness, source, format, or error handling. It meets basic requirements but leaves room for improvement.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema fully documents the single parameter (limit). The description doesn't add any parameter-specific information beyond what's in the schema, such as typical usage patterns or implications of different limit values. Baseline 3 is appropriate when schema does the heavy lifting.

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 clearly states the verb ('Return') and resource ('top CSE losers') with specific data fields (normalized price, percentage change, timestamps). It distinguishes from some siblings like get_market_status or get_stock_quote but doesn't explicitly differentiate from get_top_gainers, which is a direct counterpart.

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?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention when to prefer this over get_top_gainers for loser data, or how it differs from get_market_summary which might include similar information. The description lacks any usage context or exclusions.

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

search_companySearch CSE CompaniesB

Search Colombo Stock Exchange companies by name or symbol using ranked matching.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesCompany name or ticker symbol to search for.

TDQS

B3.3/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 full burden. It mentions 'ranked matching' which adds useful behavioral context about result ordering. However, it doesn't disclose critical traits like pagination, rate limits, authentication needs, error conditions, or what the return format looks like (especially without an output schema). For a search tool with zero annotation coverage, this leaves significant gaps.

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?

Single sentence, zero waste. Front-loaded with clear purpose, includes resource scope and method. Every word earns its place with no redundant information or fluff. Perfectly concise for a simple search tool.

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 single-parameter search tool with 100% schema coverage but no annotations and no output schema, the description is minimally adequate. It covers the basic purpose and method, but lacks details about return format, error handling, or behavioral constraints that would be needed for full completeness. The absence of output schema means the description should ideally explain what results look like, but it doesn't.

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

Parameters3/5

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

Schema description coverage is 100%, with the single parameter 'query' well-documented in the schema as 'Company name or ticker symbol to search for.' The description adds the context of 'ranked matching' which helps interpret how the query is used, but doesn't provide additional syntax, format examples, or constraints beyond what the schema already states. Baseline 3 is appropriate when schema does the heavy lifting.

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 clearly states the action ('Search'), target resource ('Colombo Stock Exchange companies'), and method ('by name or symbol using ranked matching'). It distinguishes from siblings like get_stock_quote (specific quote) or get_top_gainers (predefined list), but doesn't explicitly differentiate them. Purpose is specific but sibling differentiation is implied rather than explicit.

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 when searching for companies by name or symbol, but provides no explicit guidance on when to use this versus alternatives like get_stock_quote (for specific symbols) or get_top_gainers/losers (for performance lists). No when-not-to-use instructions or prerequisites are mentioned. Usage context is clear but alternatives are not addressed.

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 updatesv2.0.1
    • First observedget_index_summary
    • First observedget_market_status
    • First observedget_market_summary
    • First observedget_stock_quote
    • First observedget_top_gainers
    • First observedget_top_losers
    • First observedsearch_company
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

A3.6/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: get_index_summary for index data, get_market_status for session status, get_market_summary for market-wide metrics, get_stock_quote for individual stock details, get_top_gainers/losers for performance rankings, and search_company for company lookup. No overlap or ambiguity exists between these functions.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with 'get_' or 'search_' prefixes (e.g., get_index_summary, search_company). The naming is uniform, predictable, and clearly indicates each tool's action and target resource without any stylistic deviations.

Tool Count5/5

With 7 tools, the server is well-scoped for providing stock exchange data. Each tool serves a specific, non-redundant function, covering key areas like market overviews, individual quotes, rankings, and search. This count is appropriate and efficient for the domain.

Completeness4/5

The toolset covers essential read-only operations for market data: summaries, status, quotes, rankings, and search. Minor gaps exist, such as no historical data retrieval or portfolio management tools, but these are not critical for the stated purpose of providing current CSE information. Agents can perform core tasks without dead ends.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • AlphaVantage-MCP

    berlinbra
    A
    license
    B
    quality
    F
    maintenance
    A Model Context Protocol (MCP) server that provides real-time access to financial market data through the free Alpha Vantage API. This server implements a standardized interface for retrieving stock quotes and company information.
    12
    104
    MIT
  • Financial Datasets MCP Server by financial-datasets

    Financial Datasets MCP Serverofficial

    financial-datasets
    A
    license
    B
    quality
    C
    maintenance
    MCP server that provides AI assistants access to stock market data including financial statements, stock prices, and market news through a Model Context Protocol interface.
    11
    2,290
    MIT

  • Yahoo Finance MCP Server

    16Coffee
    A
    license
    C
    quality
    D
    maintenance
    A Model Context Protocol server providing comprehensive financial data from Yahoo Finance, allowing users to retrieve detailed stock information, financial statements, options data, and market news.
    34
    MIT

  • CSE MCP Server

    Shaveen12
    A
    license
    A
    quality
    C
    maintenance
    Provides real-time stock market data and company search functionality for the Colombo Stock Exchange (CSE). It enables AI assistants to retrieve current prices, change percentages, and ticker information for Sri Lankan listed companies.
    2
    7
    12 npm
    13
    ISC