Skip to main content
Glama
README.md
# NSE MCP

Explore NSE market data with a local analytics engine and an AI assistant that can discover and use its tools through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). The project covers the path from raw market files to validated Parquet, time-aware analytics, and an optional AWS-hosted MCP endpoint.

![Block diagram of the NSE market analytics MCP system](images/block-diagram.svg)

## What you can do

- **Prepare a clean dataset:** validate raw OHLCV files against the NIFTY 50 symbol index and write partitioned Parquet for efficient queries.
- **Ask focused market questions:** retrieve candles, session statistics, price extremes, volume buckets, common indicators, and daily symbol comparisons.
- **Connect AI clients through MCP:** discover typed analytics tools at runtime over local stdio or Streamable HTTP, then answer questions with one or more tool calls.
- **Inspect the work:** optionally trace model and tool activity with Langfuse, and independently compare remote results with local calculations.
- **Run the service on AWS:** deploy the read-only analytics server as a Lambda container behind an authenticated Function URL, with Terraform-managed infrastructure and CloudWatch logs.

## Architecture

The local Python client discovers analytics tools over MCP. For remote use, an authenticated Lambda Function URL fronts a stateless Lambda service; Terraform manages the disposable service resources while the processed S3 dataset remains read-only.

![AWS architecture, deployment flow, and IAM boundaries](images/architecture-v4.png)

## Data flow

Ingestion validates raw OHLCV files against the NIFTY 50 index and writes partitioned Parquet. DuckDB and PyArrow read only the needed partitions to answer typed MCP tool calls; the client turns tool results into a natural-language response. Optional traces and AWS logs support inspection.

![Offline ingestion and online request data flow](images/data-flow-v4.png)

The analytics layer uses predefined, parameterized queries. Timestamps are timezone-aware; trading dates and session buckets follow India time. Missing values remain explicit, and invalid inputs return stable errors. The same tools work against local files or the read-only S3 dataset.

## Future development scope

The roadmap prioritizes an interactive CLI, reusable investment prompts, and MCP data-discovery tools (P0); a web UI, interactive charts, expanded analytics, and a market screener (P1); portfolio simulation, research workspaces, and advanced screening (P2); and conversation memory, multi-tool query handling, and answer verification (P3). The MCP analytics server remains independent of the frontend, while CLI and web clients share a service layer. Tool contracts should use typed parameters, bounded outputs, predictable errors, and explicit data-availability metadata. See the [full future development scope](docs/future-development-scope.md).

## Try it locally

Install dependencies and process the raw files indexed by `data/index/NIFTY50.csv`:

```sh
uv sync
uv run python scripts/ingestion.py
```

Start the MCP server:

```sh
uv run uvicorn server.main:app --host 127.0.0.1 --port 8000
```

In another terminal, configure `OPENAI_API_KEY` in your environment and ask a question about a symbol and date present in your dataset:

```sh
uv run python -m client.main --server http://127.0.0.1:8000/mcp \
  --prompt 'Summarize RELIANCE on January 15, 2025, including open, close, return, VWAP, and number of bars.'
```

The client discovers the server's tools and schemas at runtime, validates model arguments, and executes the selected analytics calls. See the [tutorial](docs/tutorial.md) for analytics examples, MCP inspection, tracing, remote verification, and deployment workflows.


## Documentation

- [Tutorial](docs/tutorial.md): run ingestion, analytics, the local MCP client, and optional remote workflows.
- [Remote demo](docs/demo.md): walk through the AWS-hosted MCP analytics flow and its verification steps.
- [Project documentation](docs/documentation.md): architecture, tool contracts, deployment boundaries, and verification evidence.
- [Feature records](docs/): retained requirements, plans, implementation journals, and focused feature tutorials.

## Development

Run the test suite with the project's Python environment:

```sh
uv run --no-project --with pytest --python .venv/bin/python -- python -m pytest tests/ -q
```

TDQS

B3.3/5.0

Scored across 6 tools

Disambiguation4/5

The six tools have mostly distinct purposes: raw candles, session summary, price extremes, volume aggregates, indicators, and cross-symbol comparison. Some overlap exists around volume and high/low summaries, especially between intraday_stats, get_volume_stats, and get_price_extremes, but the descriptions clarify the intended outputs.

Naming Consistency4/5

Five tools follow a clear verb_noun snake_case pattern (get_price_extremes, get_volume_stats, get_bars, compute_indicators, compare_symbols). intraday_stats is the minor deviation as a noun-only name, but the set remains readable and predictable.

Tool Count5/5

Six tools are well-scoped for an NSE market-data analysis server. Each tool covers a distinct analytical need without excessive granularity.

Completeness4/5

The surface covers OHLCV retrieval, session/volume summaries, price extremes, indicators, and symbol comparison, which supports core market-analysis workflows. Minor gaps exist around symbol discovery or a direct latest-quote tool, but agents can work around these using get_bars and known symbols.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues