ecourts-mcp-server v1.2.0

An MCP (Model Context Protocol) server that connects LLMs to the EcourtsIndia Partner API v1.3, enabling AI agents to search Indian court cases, retrieve orders, read cause lists, and access AI-generated summaries.

Tools (9 total)

Tool	Description	Billing
ecourts_get_case	Full case detail by CNR — parties, orders, IAs, notices, documents, hearings, FIR, linked cases, file AI status, case AI analysis	Per-request
ecourts_lookup_case	Workflow tool — find a case by human-readable number (e.g. "CS(OS) 123/2024") instead of CNR, returns full details	Per-request
ecourts_search_cases	Rich search with 30+ filter params, year filters, date ranges, faceted aggregations	Per-request
ecourts_get_order	Download order PDF with metadata (certified true copies)	Per-request
ecourts_get_order_ai	Extracted order text + pre-computed AI analysis (summary, outcome, key points)	Per-request
ecourts_get_court_structure	Browse state → district → complex → court hierarchy	Free
ecourts_search_causelist	Search cause list entries across all courts	₹1/request
ecourts_get_causelist_dates	Available cause list dates	Free
ecourts_refresh_case	Queue a fresh scrape of case data	Per-request

Quick Start

npm install
npm run build
export ECOURTS_API_TOKEN="eci_live_your_token_here"
npm start

Deployment

Docker

# Build
docker build -t ecourts-mcp-server .

# Run
docker run -d \
  -e ECOURTS_API_TOKEN=eci_live_your_token_here \
  -p 3000:3000 \
  ecourts-mcp-server

# Health check
curl http://localhost:3000/health

Docker Compose

# Set your token
export ECOURTS_API_TOKEN=eci_live_your_token_here

# Start
docker compose up -d

# Verify
curl http://localhost:3000/health

Cloud Deployment

The Docker image works with any container platform:

• AWS ECS / Fargate — Use the health check endpoint at /health
• Google Cloud Run — Set PORT=8080 (Cloud Run default), server auto-adapts
• Azure Container Apps — Standard HTTP container deployment
• Railway / Render / Fly.io — Push the Dockerfile, set ECOURTS_API_TOKEN in secrets

The image runs as a non-root user, includes a HEALTHCHECK, and defaults to HTTP transport on port 3000.

Claude Desktop (stdio)

{
  "mcpServers": {
    "ecourts": {
      "command": "node",
      "args": ["/path/to/ecourts-mcp-server/dist/index.js"],
      "env": {
        "ECOURTS_API_TOKEN": "eci_live_your_token_here"
      }
    }
  }
}

Claude Code (stdio)

claude mcp add ecourts -- node /path/to/ecourts-mcp-server/dist/index.js

Running Tests

npm test                # 110 unit tests via vitest
npm run test:integration  # 24 integration tests (requires ECOURTS_API_TOKEN)
npm run test:all          # both

Tests cover: query parameter serialization, all formatting functions, facet rendering, all 14 API error code branches, schema boundary validation, safeHandler wrapper, truncation, date validation, and typed fields. Integration tests cover court structure hierarchy, case search with filters/sort/years, case detail, order metadata, cause list search by date, case refresh, and error scenarios.

CI/CD

The .github/workflows/ci.yml pipeline:

1. Build & test on Node 20 and 22 (on push/PR to main)
2. Docker build + health check on push to main

Architecture

src/
├── index.ts              # Entry point, transport (stdio/HTTP), health endpoint
├── constants.ts          # Base URLs, character limits
├── types.ts              # Full TypeScript interfaces for all API responses
├── schemas/index.ts      # Zod input validation with date regex enforcement
├── services/
│   ├── api-client.ts     # HTTP client, binary download, repeated-key array serializer, error handling
│   └── formatting.ts     # Markdown formatters for case, search, causelist, order
└── tools/index.ts        # 9 tool registrations with MCP annotations

Environment Variables

Variable	Required	Description
ECOURTS_API_TOKEN	Yes	EcourtsIndia Partner API bearer token
TRANSPORT	No	stdio (default) or http
PORT	No	HTTP port (default 3000, only for http transport)

Changelog

v1.2.0 (current)

Code Quality:

• Eliminated all unsafe type casts — linkCases, subordinateCourt, and firDetails are now proper typed fields on CourtCaseData
• CauseListEntry expanded with petitionerAdvocates, respondentAdvocates, internalCaseNo, dateCreated, dateModified
• Proper AvailableDatesResponse and CaseFileSummary types replace inline anonymous types
• All date parameters validated with YYYY-MM-DD regex at schema level

New Features:

• ecourts_lookup_case — workflow tool that finds cases by human-readable number (e.g. "CS(OS) 123/2024") instead of CNR
• Order file status in case detail — ecourts_get_case now shows which orders have AI analysis available with summary previews
• Health check endpoint — GET /health for load balancers and container orchestrators
• Error-safe HTTP transport — Express handler now catches errors instead of hanging
• ecourts_get_order PDF download — returns order PDF as embedded resource with metadata (filename, file size) extracted from HTTP headers

Deployment:

• Multi-stage Dockerfile (22MB Alpine image, non-root user, HEALTHCHECK)
• docker-compose.yml with health check and token validation
• GitHub Actions CI (Node 20/22 matrix, Docker build verification)
• Test suite expanded to 110 unit tests + 24 integration tests

v1.1.0

• Fixed array parameter serialization (courtCodes, caseTypes, etc.)
• Added isError flag on MCP error responses
• Complete error code handling (11 API error codes)
• 15+ new search parameters (year filters, date ranges, categories, bench types)
• Facet counts in search output
• Comprehensive case detail formatting (all sections)

v1.0.0

• Initial release with 8 tools covering all EcourtsIndia Partner API endpoints