# NSW Parliament Hansard MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to the New South Wales Parliament Hansard API. This server enables AI assistants and applications to search, retrieve, and analyse parliamentary transcripts, debates, and proceedings from September 1991 to the present day.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Available Tools](#available-tools)
- [Available Resources](#available-resources)
- [Usage Examples](#usage-examples)
- [API Reference](#api-reference)
- [Data Coverage](#data-coverage)
- [Terms of Use](#terms-of-use)
- [License](#license)
- [Contributing](#contributing)
- [Support](#support)

## Features

- **Comprehensive Hansard Access**: Search and retrieve parliamentary transcripts from both the Legislative Assembly (Lower House) and Legislative Council (Upper House)
- **Multiple Search Methods**: Search by year, date, speaker name, or bill name
- **Multiple Output Formats**: Access data in JSON, XML, or PDF formats
- **Table of Contents**: Retrieve structured tables of contents for any sitting day
- **Speaker Search**: Find speeches by specific members with wildcard support
- **Bill Tracking**: Search for all debates and mentions related to specific legislation
- **Historical Data**: Access records dating back to September 1991
- **No Authentication Required**: Free public access to all endpoints

## Installation

### Prerequisites

- Node.js 18.0.0 or higher
- npm or yarn package manager

### Install from npm

```bash
npm install -g nsw-hansard-mcp
```

### Install from Source

```bash
git clone https://github.com/lawquarter/nsw-hansard-mcp.git
cd nsw-hansard-mcp
npm install
npm run build
```

## Configuration

### Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "nsw-hansard": {
      "command": "npx",
      "args": ["-y", "nsw-hansard-mcp"]
    }
  }
}
```

### Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "nsw-hansard": {
      "command": "npx",
      "args": ["-y", "nsw-hansard-mcp"]
    }
  }
}
```

### Local Development

If running from source:

```json
{
  "mcpServers": {
    "nsw-hansard": {
      "command": "node",
      "args": ["/path/to/nsw-hansard-mcp/dist/index.js"]
    }
  }
}
```

## Available Tools

### hansard_search_by_year

Search all Hansard records for a specific year.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | Yes | The year to search (1991 or later) |

**Example:**
```json
{
  "year": 2024
}
```

### hansard_search_by_date

Get detailed Hansard information for a specific date.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `date` | string | Yes | Date in YYYY-MM-DD format |

**Example:**
```json
{
  "date": "2024-03-15"
}
```

### hansard_get_fragment_xml

Retrieve the raw XML content of a specific Hansard fragment.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `documentId` | string | Yes | Unique document identifier |

### hansard_get_fragment_html

Retrieve a Hansard fragment as JSON with HTML content.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `documentId` | string | Yes | Unique document identifier |

### hansard_get_pdf_url

Get the URL for downloading a Hansard PDF (post-1991 documents).

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `documentId` | string | Yes | Unique document identifier |

### hansard_get_searchable_pdf_url

Get the URL for a searchable Hansard PDF (pre-1991 historical documents).

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `documentId` | string | Yes | Unique document identifier |

### hansard_get_table_of_contents_xml

Retrieve the table of contents for a sitting day in XML format.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `documentId` | string | Yes | Unique document identifier |

### hansard_get_table_of_contents_json

Retrieve the table of contents as structured JSON.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `documentId` | string | Yes | Unique document identifier |

### hansard_search_by_speaker

Search Hansard records by speaker name with optional filters.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `speakerName` | string | Yes | Speaker name (supports wildcards: `*`) |
| `parliamentSessionId` | integer | No | Limit to specific parliament session |
| `startDate` | string | No | Start date in YYYY/MM/DD format |
| `endDate` | string | No | End date in YYYY/MM/DD format |
| `houseCode` | string | No | `LH` (Lower House) or `UH` (Upper House) |
| `memberId` | integer | No | Unique member identifier |
| `rowLimit` | integer | No | Maximum results (default: 100) |

**Example:**
```json
{
  "speakerName": "Smith*",
  "startDate": "2024/01/01",
  "endDate": "2024/12/31",
  "houseCode": "LH"
}
```

### hansard_search_by_bill

Search Hansard records by bill name.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `billName` | string | Yes | Name of the bill (partial matching supported) |

**Example:**
```json
{
  "billName": "Environmental Planning"
}
```

### hansard_list_sitting_dates

List all parliamentary sitting dates.

**Parameters:** None

### hansard_list_sitting_date_types

List all types of sitting dates.

**Parameters:** None

## Available Resources

### hansard://info

Information about the NSW Parliament Hansard API, including coverage dates, available data, and usage notes.

### hansard://terms

Copyright and conditions of use for NSW Parliament Hansard data.

## Usage Examples

### Searching for Recent Debates

To find all Hansard records from 2024:

```
Use hansard_search_by_year with year: 2024
```

### Finding a Specific Day's Proceedings

To get the Hansard for a specific sitting day:

```
Use hansard_search_by_date with date: "2024-03-15"
```

### Searching by Member

To find speeches by a specific member:

```
Use hansard_search_by_speaker with:
- speakerName: "Jones*"
- startDate: "2024/01/01"
- endDate: "2024/06/30"
- houseCode: "LH"
```

### Tracking Legislation

To find all debates about a specific bill:

```
Use hansard_search_by_bill with billName: "Housing Amendment"
```

## API Reference

This MCP server interfaces with the NSW Parliament Hansard API:

**Base URL:** `https://api.parliament.nsw.gov.au/api`

### Endpoints Used

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/hansard/search/year/{year}` | GET | Search by year |
| `/hansard/search/bydate` | GET | Search by date |
| `/hansard/search/daily/fragment/{documentId}` | GET | Get XML fragment |
| `/hansard/search/daily/fragment/html/{documentId}` | POST | Get HTML fragment |
| `/hansard/search/daily/pdf/{documentId}` | GET | Get PDF |
| `/hansard/search/daily/searchablepdf/{documentId}` | GET | Get searchable PDF |
| `/hansard/search/daily/tableofcontents/{documentId}` | GET | Get TOC XML |
| `/hansard/search/daily/tableofcontentsbydate/{documentId}` | POST | Get TOC JSON |
| `/hansard/search/byspeaker` | GET | Search by speaker |
| `/hansard/search/daily/bybill` | GET | Search by bill |
| `/sittingdate` | GET | List sitting dates |
| `/sittingdatetype` | GET | List sitting date types |

For complete API documentation, visit:
- [Official Hansard API Page](https://www.parliament.nsw.gov.au/hansard/Pages/Hansard-API.aspx)
- [Detailed API Documentation](https://parliament-api-docs.readthedocs.io/en/latest/new-south-wales/)
- [Data.NSW Listing](https://data.nsw.gov.au/data/dataset/hansard-api)

## Data Coverage

### Temporal Coverage
- **Start Date:** September 1991
- **End Date:** Present (updated regularly)

### Content Types
- Daily transcripts (corrected and uncorrected)
- Table of contents
- PDF documents
- Speaker records
- Bill debates

### Chambers
- **Legislative Assembly (LH):** The Lower House of NSW Parliament
- **Legislative Council (UH):** The Upper House of NSW Parliament

## Terms of Use

### NSW Parliament Copyright Notice

The material provided through this MCP server originates from the NSW Parliament Hansard API and is subject to copyright under the **Copyright Act 1968 (Cth)**. Copyright is owned by the **State of New South Wales through the Parliament of New South Wales**.

### Permitted Use

The Parliament of NSW encourages the availability, dissemination and exchange of public information. You may copy, distribute, display, download and otherwise deal with the material on the following conditions:

1. **Non-commercial purposes**: Use must not be for advertising, satire, or ridicule
2. **No misrepresentation**: Use must not misrepresent members of Parliament
3. **Attribution required**: You must include the copyright notice:

   > © State of New South Wales through the Parliament of New South Wales

### Restrictions

- This permission **does not extend** to copyright in materials owned by others, such as papers tabled in Parliament
- Evidence, submissions and other material provided to committees should not be re-published or distributed without first being authorised by the relevant committee or House
- Use of the Parliamentary Crest is permitted only where reproduction is incidental to use of publications in accordance with the copyright notice
- The Parliament does not authorise any other use or reproduction of the Parliamentary Crest and other parliamentary symbols and logos without prior written permission
- Copyright of broadcast material belongs to NSW Parliament and no unauthorised use may be made of that material

### Disclaimer

- The Hansard API is provided on an **"as is" basis**
- The Parliament of NSW is **not liable** for loss or damage arising from use of the material or from delays or interruptions in service
- The Parliament **does not provide developers with any direct support** for API usage beyond the available documentation

### Full Terms

For the complete terms and conditions, please visit:
[NSW Parliament Copyright & Conditions of Use](https://www.parliament.nsw.gov.au/Pages/Copyright--Conditions-of-Use.aspx)

## License

This MCP server implementation is released under the **MIT License**.

```
MIT License

Copyright (c) 2025 Law Quarter

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

**Important:** While this software implementation is MIT licensed, the **data obtained through the NSW Parliament Hansard API** is subject to the NSW Parliament's copyright and conditions of use as described in the [Terms of Use](#terms-of-use) section above.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## Support

This MCP server is maintained by [Law Quarter](https://lawquarter.com.au).

For issues related to this MCP server implementation, please [open an issue](https://github.com/lawquarter/nsw-hansard-mcp/issues) on GitHub.

**Note:** The NSW Parliament does not provide direct support for API usage. For API-related queries, refer to the official documentation links provided above.

## Acknowledgements

- [NSW Parliament](https://www.parliament.nsw.gov.au/) for providing the Hansard API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- [Data.NSW](https://data.nsw.gov.au/) for API documentation and data hosting

---

**Disclaimer:** This project is not officially affiliated with or endorsed by the NSW Parliament. It is an independent implementation that interfaces with the publicly available Hansard API.