# Flipkart Seller MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard-green.svg)](https://modelcontextprotocol.io/)

A high-performance, token-optimized **Model Context Protocol (MCP) server** for the **Flipkart Seller v3 API**. Built using Python (`FastMCP` + `Pydantic`), this server enables AI agents (Claude Desktop, Antigravity, OpenCode, Cursor, AutoGen) to manage order fulfillment, listing inventory & pricing CRUD, customer returns, ad campaigns, and payout settlements.

---

## 📚 Table of Contents

- [Features](#features)
- [⚡ Token Optimization Architecture](#-token-optimization-architecture)
- [🔑 How to Get Flipkart Credentials](#-how-to-get-flipkart-credentials)
- [Installation & Setup](#installation--setup)
- [🤖 Guidance for AI Agents](#-guidance-for-ai-agents)
- [Available Domain Tools](#available-domain-tools)
- [🔮 Future Scope & Roadmap](#-future-scope--roadmap)
- [Development & Testing](#development--testing)
- [License](#license)

---

## Features

- **Token-Optimized Architecture**: Returns clean, concise Markdown tables (~100–300 tokens) by default, saving up to 90% context tokens for LLM reasoning loops.
- **Consolidated Master Domain Tools**: Exposes 5 unified master tools (`shipments`, `inventory`, `returns`, `ads`, `financials`) with strict action parameters to prevent tool schema clutter in agent prompts.
- **Full Catalog & Listings CRUD**: Search, create, update details/prices/stock, and deactivate catalog listings.
- **Auto OAuth Lifecycle**: Proactive OAuth2 client-credentials authentication with 5-minute pre-expiration token auto-refresh.
- **Out-of-the-Box Mock Mode**: Runs seamlessly in mock mode if API credentials are missing, making development and agent testing instant.

---

## ⚡ Token Optimization Architecture

`flipkart-seller-mcp` was architected from the ground up to minimize context token usage for LLM agents:

1. **Schema Consolidation (5 Master Tools vs 30+ Micro-Tools)**:
   By grouping endpoints into 5 master domain tools (`flipkart_manage_shipments`, `flipkart_manage_inventory`, `flipkart_manage_returns`, `flipkart_manage_ads`, `flipkart_manage_financials`), we reduce the tool schema footprint in the agent's system prompt from **~4,000 tokens down to ~500 tokens**.
2. **`detail_level: "summary"` Defaulting**:
   Raw API payloads for Flipkart orders/listings can exceed **5,000 tokens** per single API call. Every tool defaults to `detail_level="summary"`, extracting only essential columns (e.g. `shipmentId`, `orderId`, `sku`, `status`, `dispatchByDate`) formatted into Markdown tables (~100–300 tokens).
3. **Pydantic Type Compression**:
   Field annotations and descriptions are written concisely without redundant verbose prose, avoiding schema inflation during agent initialization.
4. **Pagination & Output Capping**:
   Responses cap summary listings at 10 items per page by default, preventing unexpected context window overflows.

---

## 🔑 How to Get Flipkart Credentials

To connect to a live Flipkart Seller Hub account, you need a **Client ID** and **Client Secret**.

👉 **[Read the Step-by-Step Credentials Guide](docs/FLIPKART_CREDENTIALS_GUIDE.md)**

### Quick Overview:
1. Log in to [Flipkart Seller Hub](https://seller.flipkart.com/).
2. Go to **Manage Profile > Developer Access**.
3. Create a **Self Access Application** and enable required scopes (`Orders`, `Listings`, `Returns`, `Financials`, `Ads`).
4. Copy your **Application ID** (`FLIPKART_CLIENT_ID`) and **Application Secret** (`FLIPKART_CLIENT_SECRET`).

---

## Installation & Setup

### 1. Prerequisites
- Python 3.10+
- `uv`, `pip`, or `npx`

### 2. Environment Setup

Create a `.env` file in your workspace root:

```env
FLIPKART_CLIENT_ID=your_flipkart_application_id
FLIPKART_CLIENT_SECRET=your_flipkart_application_secret
# Optional: defaults to https://api.flipkart.net
FLIPKART_API_BASE_URL=https://api.flipkart.net
```

### 3. Usage with MCP Clients

#### Claude Desktop / Antigravity / OpenCode Configuration

```json
{
  "mcpServers": {
    "flipkart": {
      "command": "uvx",
      "args": ["flipkart-seller-mcp"],
      "env": {
        "FLIPKART_CLIENT_ID": "your_client_id_here",
        "FLIPKART_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}
```

Or via Node/NPM runner:

```json
{
  "mcpServers": {
    "flipkart": {
      "command": "npx",
      "args": ["-y", "flipkart-seller-mcp"],
      "env": {
        "FLIPKART_CLIENT_ID": "your_client_id_here",
        "FLIPKART_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}
```

---

## 🤖 Guidance for AI Agents

When interacting with `flipkart-seller-mcp`, follow these best practices for maximum performance and token efficiency:

1. **Use `action` Parameters**:
   Each master tool uses a required `action` switch (e.g. `flipkart_manage_shipments(action="search")`). Check the tool docstrings for supported actions.
2. **Leverage Token Efficiency (`detail_level`)**:
   - `detail_level="summary"` (Default): Returns a compact Markdown summary table (~100–300 tokens). Ideal for scanning and planning.
   - `detail_level="full"`: Returns the un-truncated raw API JSON response. Use only when deep data extraction is required.
3. **Multi-Step Fulfillment Flow**:
   - Step 1: `flipkart_manage_shipments(action="search", state="APPROVED")` to list new orders.
   - Step 2: `flipkart_manage_shipments(action="inspect", shipment_ids=["SHIP_ID"])` to view item & SLA details.
   - Step 3: `flipkart_manage_shipments(action="mark_rtd", shipment_ids=["SHIP_ID"])` to pack and mark Ready for Dispatch.
   - Step 4: `flipkart_manage_shipments(action="get_label", shipment_ids=["SHIP_ID"])` to fetch printable PDF label & invoice.
4. **Listings & Inventory CRUD Flow**:
   - Use `flipkart_manage_inventory(action="create_listing", sku="SKU123", title="...", selling_price=499.0)` to create new products.
   - Use `update_stock` or `update_price` for quick operational changes.

---

## Available Domain Tools

| Tool Name | Actions Supported | Primary Description |
| :--- | :--- | :--- |
| **`flipkart_manage_shipments`** | `search`, `inspect`, `mark_rtd`, `get_label`, `cancel` | Order fulfillment, packing, SLA inspection, label & invoice PDF retrieval, cancellations. |
| **`flipkart_manage_inventory`** | `search`, `get_details`, `update_stock`, `update_price`, `create_listing`, `update_listing`, `delete_listing` | Catalog listings CRUD, warehouse stock updates, MRP and Selling Price management. |
| **`flipkart_manage_returns`** | `list_returns`, `track_rto`, `approve_return`, `spf_claim` | Customer return requests, courier RTO tracking, return approvals, Seller Protection Fund (SPF) claims. |
| **`flipkart_manage_ads`** | `list_campaigns`, `get_metrics`, `update_budget`, `update_bid` | Ad campaign performance (PLA/PCA), daily spend, ROAS tracking, budget & bid updates. |
| **`flipkart_manage_financials`** | `get_settlements`, `request_report`, `download_report` | Bank payouts, settlement summaries, tax/sales report generation & download links. |

---

## 🔮 Future Scope & Roadmap

1. **Unified Multi-Marketplace Adapter (`unified-ecom-mcp`)**:
   Extraction of `FlipkartClient` into a unified e-commerce protocol alongside Amazon SP-API, Shopify, and Meesho adapters.
2. **AI-Powered SPF Dispute & Claims Assistant**:
   Automated filing of Seller Protection Fund (SPF) claims with AI image verification for wrong/damaged return items.
3. **Dynamic Re-Pricing Rules**:
   Rule-based automated price adjustments according to competitor listings and buy-box status.
4. **Bulk CSV Batch Uploads**:
   Batch listing creation and inventory sync via CSV/Excel parsing tool actions.

---

## Development & Testing

```bash
git clone https://github.com/ron2111/flipkart-seller-mcp.git
cd flipkart-seller-mcp
python -m venv .venv
source .venv/bin/activate  # Or .venv\Scripts\activate on Windows

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run full pytest suite
pytest
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.