Metadata-Version: 2.4
Name: vaquill-mcp
Version: 0.1.0
Summary: MCP server for Vaquill legal research API - search 13M+ Indian court judgments via AI
Project-URL: Homepage, https://www.vaquill.ai
Project-URL: Documentation, https://www.vaquill.ai/docs/api-reference
Project-URL: Repository, https://github.com/vaquill/vaquill-mcp
Project-URL: Issues, https://github.com/vaquill/vaquill-mcp/issues
Project-URL: Changelog, https://github.com/vaquill/vaquill-mcp/blob/main/CHANGELOG.md
Author-email: Vaquill <dev@vaquill.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,india,law,legal,mcp,rag,research,vaquill
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastmcp>=3.0.0
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Description-Content-Type: text/markdown

# vaquill-mcp

MCP server for [Vaquill](https://www.vaquill.ai) legal research API. Search 13M+ Indian court judgments, ask AI-powered legal questions, resolve citations, and traverse citation networks — all from your AI tools.

## Quick Start

### Prerequisites

Get your API key from [vaquill.ai/dashboard/api-keys](https://www.vaquill.ai/dashboard/api-keys)

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add vaquill -- uvx vaquill-mcp
# Then set the env var in your shell: export VAQUILL_API_KEY=vq_key_...
```

Or add to `.claude/settings.json`:

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}
```

### Cursor

Add to Cursor Settings > MCP Servers:

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}
```

### VS Code (Copilot)

Add to `.vscode/settings.json`:

```json
{
  "mcp": {
    "servers": {
      "vaquill": {
        "command": "uvx",
        "args": ["vaquill-mcp"],
        "env": {
          "VAQUILL_API_KEY": "vq_key_your_key_here"
        }
      }
    }
  }
}
```

### Windsurf

Add to `~/.windsurf/settings.json`:

```json
{
  "mcpServers": {
    "vaquill": {
      "command": "uvx",
      "args": ["vaquill-mcp"],
      "env": {
        "VAQUILL_API_KEY": "vq_key_your_key_here"
      }
    }
  }
}
```

## Available Tools

| Tool | Description | Credits |
|------|-------------|---------|
| `ask_legal_question` | AI-powered legal Q&A grounded in court judgments. Standard (fast) or deep (thorough) modes. | 0.5 - 2.0 |
| `search_legal_cases` | Boolean keyword search with AND/OR/NOT operators. Filter by court, year, country. | 1.0 |
| `quick_search` | Fast compact search returning top 3-5 results with essentials only. | 0.1 |
| `resolve_citation` | Resolve any citation format (SCC, AIR, SCR, MANU) to canonical case record. | 0.1 |
| `search_cases_by_citation` | Search cases by citation text or case name with filters. | 0.1 |
| `lookup_case` | Full case details with citation treatment stats (followed, overruled, etc.). | 0.1 |
| `get_citation_network` | Traverse citation graph: which cases cite/are cited by a case. 1-3 hops. | 0.2 |
| `get_pricing` | Get current API credit pricing (no auth required). | Free |

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `VAQUILL_API_KEY` | Yes | - | API key (`vq_key_...`) from dashboard |
| `VAQUILL_BASE_URL` | No | `https://api.vaquill.ai` | API base URL |
| `VAQUILL_TIMEOUT` | No | `120` | Request timeout in seconds |

## Example Usage

Once configured, you can ask your AI assistant things like:

- "Search for Supreme Court cases on Section 302 IPC"
- "What is the legal test for negligence in Indian tort law?"
- "Resolve the citation AIR 1978 SC 597"
- "Look up the case Maneka Gandhi vs Union of India and show treatment stats"
- "Show the citation network around ADM Jabalpur vs Shivkant Shukla"
- "Compare murder and culpable homicide under IPC" (uses deep mode)

## Development

```bash
# Clone and install
git clone https://github.com/vaquill/vaquill-mcp.git
cd vaquill-mcp
uv sync --all-extras

# Run locally
VAQUILL_API_KEY=vq_key_... uv run vaquill-mcp

# Run tests
uv run pytest

# Test with FastMCP inspector
uv run fastmcp dev src/vaquill_mcp/server.py
```

## How It Works

This package is a thin MCP wrapper around the [Vaquill Developer API](https://api.vaquill.ai/external/docs). At startup, it fetches the OpenAPI spec from the live API and auto-generates MCP tools using [FastMCP](https://github.com/jlowin/fastmcp). Tool names and descriptions are customized for optimal LLM performance.

Because the spec is fetched at startup (not bundled), tools automatically reflect any API changes without a package update.

## Credits & Pricing

API calls consume credits. Check current pricing at [vaquill.ai/pricing](https://www.vaquill.ai/pricing) or use the `get_pricing` tool.

1 credit = $0.10 USD = 10 INR

## License

MIT
