# DhanHQ MCP Server

An MCP (Model Context Protocol) server for DhanHQ APIs with OAuth-based authentication for Individual Traders.

## Overview

This server implements the complete three-step DhanHQ authentication flow that generates a JWT access token for API requests. The authentication process involves:

1. **Step 1**: Generate Consent - Creates a temporary session ID
2. **Step 2**: Browser-Based Login - User authenticates with 2FA
3. **Step 3**: Consume Consent - Exchanges tokenId for access token

## Prerequisites

Before you begin, you need to generate your API Key and Secret:

1. Log in to [web.dhan.co](https://web.dhan.co)
2. Navigate to **My Profile** → **'Access DhanHQ APIs'**
3. Toggle to **'API key'**
4. Enter your:
   - App name
   - Redirect URL (e.g., `http://localhost:3000/callback`)
   - Optional Postback URL

Note: Generated API Keys and Secrets are valid for 12 months.

## Setup

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Environment Variables

Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
```

```env
DHAN_CLIENT_ID=your_dhan_client_id
DHAN_API_KEY=your_api_key
DHAN_API_SECRET=your_api_secret
REDIRECT_URL=http://localhost:3000/callback
```

### 3. Build the Project

```bash
npm run build
```

## Usage

### Development Mode

```bash
npm run dev
```

### Using MCP Inspector (Recommended for Debugging)

The MCP Inspector provides an interactive interface to test the MCP tools:

```bash
npm run inspector
```

This will:
1. Start the MCP server
2. Open the MCP Inspector in your browser
3. Allow you to call tools and see responses in real-time

## Authentication Flow

### Step 1: Start Authentication

Call the `start_authentication` tool. This will:
- Validate your API credentials
- Create a temporary session (consentAppId)
- Return a login URL

### Step 2: Browser Login

Open the provided login URL in your browser:
- Log in with your Dhan credentials
- Complete 2FA verification (OTP/PIN/Password)
- You'll be redirected to your configured Redirect URL with a `tokenId` parameter

Example redirect URL:
```
http://localhost:3000/callback?tokenId=abc123def456...
```

### Step 3: Complete Authentication

Call the `complete_authentication` tool with the `tokenId` from Step 2:
- Exchanges the tokenId for a JWT access token
- Stores token details (expiry, client info, etc.)
- Returns the access token for use in subsequent API calls

### Check Status

Use `check_auth_status` to view:
- Current authentication state
- Token validity
- Client information
- Token expiry time

## Available MCP Tools

### `start_authentication`
Initiates the DhanHQ authentication flow (Step 1).
- **Input**: None
- **Output**: consentAppId, loginUrl, instructions

### `get_login_instructions`
Gets the login instructions and URL for Step 2.
- **Input**: consentAppId (optional)
- **Output**: loginUrl, detailed instructions

### `complete_authentication`
Completes authentication with the tokenId from Step 2 (Step 3).
- **Input**: tokenId (required)
- **Output**: authToken with accessToken and client details

### `check_auth_status`
Checks the current authentication status.
- **Input**: None
- **Output**: Authentication state and token validity

### `reset_authentication`
Clears the current authentication state.
- **Input**: None
- **Output**: Success message

## API Architecture

- **Framework**: Node.js with TypeScript
- **Protocol**: Model Context Protocol (MCP)
- **Transport**: Stdio
- **Auth API**: DhanHQ OAuth endpoints
- **HTTP Client**: Axios

## Project Structure

```
src/
├── index.ts           # MCP server and tool handlers
├── authentication.ts  # Authentication logic (3-step flow)
├── config.ts         # Configuration management
└── types.ts          # TypeScript interfaces
```

## Security Considerations

- API credentials are stored in environment variables
- Access tokens are stored in-memory (session-based)
- For production, use:
  - Secure credential storage
  - Database for token persistence
  - Token refresh mechanisms
  - HTTPS for callbacks
- The MCP Inspector output redacts sensitive tokens

## Error Handling

The server includes comprehensive error handling:
- API request validation
- Network error handling
- Configuration validation
- Token expiry checking

## Next Steps

After authentication is working:
1. Add API tools for trading operations
2. Implement token refresh logic
3. Add portfolio/holdings endpoints
4. Implement order placement tools
5. Add market data tools

## Development Notes

- Logs are printed to stderr for debugging
- Authentication state is stored in-memory (lost on restart)
- For production, migrate to persistent storage
- MCP Inspector is recommended for interactive testing and debugging

## License

MIT