Metadata-Version: 2.4
Name: mcp-tw-nhi-ihqe
Version: 0.1.0
Summary: MCP server for Taiwan NHI IHQE healthcare quality indicators
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: fastmcp>=3.2.4

# MCP Taiwan NHI IHQE

MCP Taiwan NHI IHQE wraps Taiwan National Health Insurance Administration's
public **Healthcare Quality Information Disclosure** website:

https://med.nhi.gov.tw/ihqe0000/

The project fetches the public indicator index, parses metric metadata, looks
up area codes, and queries hospital-level indicator values. It exposes those
flows as a FastMCP server so an MCP client can search available quality metrics
and query metric values without manually browsing the website.

Traditional Chinese documentation is available in [README.zh-tw.md](README.zh-tw.md).

## Provided Tools

### `list_metric`

List available quality metrics parsed from the IHQE public index.

Arguments:

- `keyword`: Optional keyword to search by metric id, metric name, or section.
- `limit`: Optional maximum number of metrics to return.

Returns:

- `metrics`: Matching metric records.
- `total`: Total number of matched records.
- `returned`: Number of records returned after applying `limit`.

### `query_metric`

Query hospital values for one quality metric.

Arguments:

- `metric`: Metric id or metric name keyword, for example `1711` or `血脂`.
- `year`: ROC year/quarter string, for example `114Q4`.
- `roc_year`: ROC or Gregorian year. Use with `quarter` when `year` is omitted.
- `quarter`: Quarter value such as `4` or `Q4`. Use with `roc_year`.
- `city`: City/town code or area name, for example `12`, `1205`, `新竹市`, or `香山`.
- `hospital_name`: Optional hospital name keyword.
- `hospital_id`: Optional hospital id.
- `special`: Optional special type code.
- `branch`: Optional NHI branch code.
- `limit`: Maximum number of rows to return. Default is `20`.

Returns:

- `metric`: The resolved metric metadata.
- `city`: The resolved city/town code used in the API call.
- `rows`: Hospital-level metric rows.
- `total`: Total number of matched rows.
- `returned`: Number of rows returned after applying `limit`.

### `describe_metric`

Return the indicator introduction and description for one quality metric.

Arguments:

- `metric`: Metric id or metric name keyword, for example `1711` or `血脂`.

Returns:

- `metric`: The resolved metric metadata.
- `title`: The indicator page title.
- `introduction`: Structured introduction sections (each with `title` and `content`).

### `health_education`

Return the health education content for one quality metric.

Arguments:

- `metric`: Metric id or metric name keyword.

Returns:

- `metric`: The resolved metric metadata.
- `title`: The indicator page title.
- `health_education`: Structured health education sections (each with `title` and `content`).

## Usage

### Install Dependencies

```bash
uv sync
```

### Run as an MCP Server

This repository includes a local MCP configuration:

```json
{
  "mcpServers": {
    "tw-nhi-ihqe": {
      "command": "uv",
      "args": ["run", "ihqe-mcp"]
    }
  }
}
```

You can also run the server directly:

```bash
uv run ihqe-mcp
```

The IHQE website currently fails Python's default certificate validation in
some environments, so SSL verification is disabled by default for the MCP
server. To force verification, set:

```bash
IHQE_VERIFY_SSL=true uv run ihqe-mcp
```

### Try the CLI

List available metrics:

```bash
uv run ihqe list-metrics
uv run ihqe list-metrics --keyword 血脂
```

Look up area codes:

```bash
uv run ihqe list-areas
uv run ihqe list-areas --keyword 香山
uv run ihqe list-areas --towns
```

Query a metric:

```bash
uv run ihqe query-metric 1711 --year 114Q4 --city 12 --limit 5
uv run ihqe query-metric 1711 --year 114Q4 --city 香山 --keyword 台大 --limit 5
```

Use JSON output when inspecting raw data:

```bash
uv run ihqe query-metric 1711 --year 114Q4 --city 12 --json
```

Describe an indicator (introduction and methodology):

```bash
uv run ihqe describe-metric 1711
uv run ihqe describe-metric 血脂
```

Show health education content for an indicator:

```bash
uv run ihqe health-education 1711
uv run ihqe health-education 血脂 --json
```

## Development

### Project Layout

- `src/mcp_tw_nhi_ihqe/parser.py`: HTML parsers for the public index and metric content pages.
- `src/mcp_tw_nhi_ihqe/api.py`: Low-level API client and higher-level cached IHQE client.
- `src/mcp_tw_nhi_ihqe/cli.py`: Command-line workflow for local testing.
- `src/mcp_tw_nhi_ihqe/mcp.py`: FastMCP server and tool definitions.
- `tests/`: Unit tests and fixed HTML fixtures.

### Run Tests

```bash
uv run pytest
```

### Useful Local Checks

```bash
uv run ihqe list-metrics --keyword 血脂
uv run ihqe list-areas --keyword 香山
uv run ihqe query-metric 1711 --year 114Q4 --city 12 --limit 2
```

### Notes for Contributors

- Keep network-dependent behavior behind injectable clients or fixed fixtures.
- Prefer adding tests with small HTML/API samples before changing parser logic.
- The official API uses ROC year/quarter values such as `114Q4`.
- The official API accepts either city codes such as `12` or town/district codes such as `1205` in the same `city` query parameter.
