stock-nse-india

The MCP Client includes an automatic context summarization feature to manage token usage and costs.

Mechanism:

1. Token Monitoring: The client tracks the number of tokens used in the current conversation.
2. Smart Triggering: When the token usage reaches a configurable threshold (default is often 70-80% of the maxTokens limit), the summarization process is triggered.
3. Summarization: The client summarizes the conversation history, retaining important information while significantly reducing the token count.
4. Seamless Operation: This happens transparently during the query process, allowing for much longer conversations without hitting hard context limits.

Benefits:

• Cost Savings: Can reduce token usage by up to 64%.
• Performance: Faster responses due to smaller context windows.
• Scalability: Enables virtually unlimited conversation length.

The summarization process follows a specific lifecycle to prevent token overflow while maintaining conversation continuity:

1. Token Counting: The system calculates totalTokens = systemPromptTokens + messageTokens + reservedTokens.
2. Threshold Check: Summarization triggers only if totalTokens > (maxTokens * summarizationThreshold) AND messageCount >= minMessagesToSummarize.
3. Summarization Process:
   • Recent messages (targeting ~40% of maxTokens) are kept.
   • Older messages are summarized using AI.
   • The old messages are replaced by the summary.
4. Result: Token usage drops to approximately 40% of maxTokens, preserving recent context and key information from the past.

The server uses a modular architecture to ensure consistency across different implementations (Stdio server vs. OpenAI Functions client):

• src/mcp/mcp-tools.ts: The single source of truth for common tools configuration and handler functions.
• src/mcp/server/mcp-server.ts: A Stdio-based MCP server designed for local AI assistant integration (e.g., Cursor).
• src/mcp/client/mcp-client.ts: An OpenAI Functions-based MCP client for natural language queries.

By sharing tool definitions and business logic, the project ensures that all server implementations behave identically.

To set up the server locally for development:

1. Install dependencies:

yarn install

2. Build the project:

yarn build

3. Start the stdio MCP server:

yarn start:mcp

To develop locally, ensure you have Node.js 18+ installed.

1. Clone the repository.
2. Install dependencies using npm install.
3. Use npm run start:dev for development mode with auto-reload.
4. Use npm run build to compile TypeScript to JavaScript.
5. Use npm run docs to generate TypeDoc documentation.

# Clone repository
git clone https://github.com/hi-imcodeman/stock-nse-india.git
cd stock-nse-india

# Install dependencies
npm install

# Development mode with auto-reload
npm run start:dev

To access NSE India data via the command line, install the package globally:

npm install -g stock-nse-india

If you have cloned the repository and built the project locally, use this configuration in your MCP settings:

{
  "mcpServers": {
    "nse-india-stdio": {
      "command": "node",
      "args": ["build/mcp/server/mcp-server-stdio.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Prerequisites:

• Node.js 18+ installed
• Repository cloned and dependencies installed (npm install)
• Project built (npm run build)

You can run the NSE India API server using Docker. The container exposes the main application, GraphQL endpoint, and API documentation.

# Pull and run from Docker Hub
docker run --rm -d -p 3001:3001 imcodeman/nseindia

# Or build locally
docker build -t nseindia . && docker run --rm -d -p 3001:3001 nseindia:latest

To run the demonstration suite for the NSE India Stock Market MCP Client, you must first set your OpenAI API key and build the project.

Prerequisites

• An OPENAI_API_KEY environment variable.

Setup Steps

1. Set the environment variable:

   export OPENAI_API_KEY=your-api-key

2. Build the project:

   npm run build

Running Demos

• Run all demos: npm run demo:mcp-client
• Run a specific demo (1-7): npm run demo:mcp-client <number>
• Run the memory-focused example: npm run demo:memory

# Set OpenAI API Key
export OPENAI_API_KEY=your-api-key

# Build the project
npm run build

# Run all demos
npm run demo:mcp-client

# Run a specific demo (1-7)
npm run demo:mcp-client 3

# Memory example
npm run demo:memory

To use the library in your project, install it via npm or yarn:

npm install stock-nse-india
# or
yarn add stock-nse-india

The easiest way to use the MCP server without cloning the repository is via npx.

Prerequisites:

• Node.js 18+ installed (node --version should be v18.0.0 or higher).

Steps:

1. (Optional) Install the package globally for faster startup:

   npm install -g stock-nse-india

2. Add the following configuration to your MCP settings (e.g., in Cursor or Claude Desktop):

{
  "mcpServers": {
    "npx-stock-nse-india": {
      "command": "npx",
      "args": ["stock-nse-india", "mcp"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}