Skip to main content
Glama
houan-mcp

houan-mcp

by SHAYOUWORLD
README.md
# @codeagentjp/houan-mcp

Local stdio MCP server for searching Japanese **Diet bills (衆参議案情報)** and **committee Q&A records** via the [NDL Kokkai (国会会議録検索システム) API](https://kokkai.ndl.go.jp/).

This server does not call an LLM. It only returns source-backed Diet data, with primary URLs (NDL Kokkai, 衆議院議案情報, 参議院議案情報) so your MCP client (Claude Desktop, Claude Code, Cursor, or any other agent) can cite the original source.

Sister package: [`@codeagentjp/egov-law-mcp`](https://www.npmjs.com/package/@codeagentjp/egov-law-mcp) for current Japanese laws (e-Gov Law Search). `houan-mcp` covers the *legislative process* side: bills under deliberation, committee questionings, and full meeting transcripts.

## Status

MVP. Four tools:

- `find_diet_qa` — full-text search across all Diet committee speeches via the NDL Kokkai API. Filter by date, chamber, committee, speaker.
- `get_meeting_record` — retrieve a single committee's full transcript by `issueID`.
- `search_bills` — search current-session bills in either house by title keyword.
- `get_bill` — retrieve detail of one bill (proceedings timeline, committee assignment, full-text URL).

## Requirements

- Node.js 20 or later
- Network access to `https://kokkai.ndl.go.jp`, `https://www.shugiin.go.jp`, `https://www.sangiin.go.jp`

## Install

From npm:

```json
{
  "mcpServers": {
    "houan": {
      "command": "npx",
      "args": ["-y", "@codeagentjp/houan-mcp"]
    }
  }
}
```

From source:

```bash
git clone https://github.com/SHAYOUWORLD/houan-mcp.git
cd houan-mcp
node bin/houan-mcp.mjs
```

```json
{
  "mcpServers": {
    "houan": {
      "command": "node",
      "args": ["/absolute/path/to/houan-mcp/bin/houan-mcp.mjs"]
    }
  }
}
```

## Tools

### `find_diet_qa`

Full-text search of Diet committee speeches via the NDL Kokkai API.

```json
{
  "keyword": "クロード ミトス",
  "from": "2026-04-01",
  "until": "2026-04-25",
  "chamber": "衆議院",
  "committee": "外務委員会",
  "limit": 5
}
```

Returns matched speeches with speaker, position, committee context, and direct NDL URL.

### `get_meeting_record`

Retrieve a single full transcript by `issueID`.

```json
{
  "issueID": "122103968X00620260410"
}
```

### `search_bills`

Search 衆議院議案情報 / 参議院議案情報 by title keyword.

```json
{
  "keyword": "情報",
  "chamber": "both",
  "session": 222,
  "limit": 20
}
```

When `session` is omitted, the server reads the session list behind the 衆議院議案情報 dropdown (`.../html/gian/pulldown.htm`, one small request, cached for 5 minutes like other responses) and searches the highest session listed, for both chambers. If that list cannot be read, it searches **222** (checked 2026-10-28) and adds an entry to `warnings`. `query.sessionSource` is `latest`, `fallback`, or `argument`. Specify `session` explicitly for historical sessions; no session list is fetched then.

For Shugiin results, `session` is the searched session, `submittedSession` is the session in which the item was introduced, and `billType` distinguishes 衆法 / 参法 / 閣法 and other agenda items. `billNumber` is the official number (or `null` for unnumbered items); `status` comes from 審議状況. Unpublished proceedings/full-text links are `null`.

HTTP, network, timeout, and unrecognized Shugiin table errors are returned as an MCP tool result with `isError: true`. Its text contains `error`, `sourceErrors` (chamber, URL, message) and `warnings`, rather than a successful zero-hit result. When searching `both`, a failure in either chamber fails the whole search; request one chamber explicitly if you want to retry it alone. A successful search with no title matches still returns `matched: 0` and `results: []`.

### `get_bill`

Retrieve a bill detail page (proceedings timeline, committee assignment, full-text URL). The `proceedingURL` must be a URL returned by `search_bills` — it is validated against the chamber's allowed path prefix before fetching.

```json
{
  "chamber": "shugiin",
  "proceedingURL": "https://www.shugiin.go.jp/internet/itdb_gian.nsf/html/gian/keika/1DE..."
}
```

## Data Sources and Attribution

This package uses three Japanese public sources:

- **NDL Kokkai (国会会議録検索システム)** — <https://kokkai.ndl.go.jp/> · [API documentation](https://kokkai.ndl.go.jp/api.html). Diet records published 1947–. No auth required. The API terms ask machine clients not to send concurrent requests and to wait a few seconds between requests; this server enforces that (see [Request pacing](#request-pacing)).
- **衆議院議案情報** — <https://www.shugiin.go.jp/internet/itdb_gian.nsf/html/gian/menu.htm>
- **参議院議案情報** — <https://www.sangiin.go.jp/japanese/joho1/kousei/gian/current/gian.htm>

Tool results include the source URL. When you publish or redistribute output based on this package, include an appropriate attribution. Suggested:

> 出典: 国会会議録検索システム (https://kokkai.ndl.go.jp/) / 衆議院議案情報 / 参議院議案情報

## Request pacing

The [NDL Kokkai API terms](https://kokkai.ndl.go.jp/api.html) (section 4) ask machine clients to avoid concurrent requests and to wait a few seconds after each response before sending the next one. `find_diet_qa` and `get_meeting_record` therefore:

- send at most one request to `kokkai.ndl.go.jp` at a time, even when a client calls several tools at once or sends a JSON-RPC batch;
- start each request at least 3 seconds after the previous one finished. Set `HOUAN_MCP_NDL_INTERVAL_MS` to wait longer; values below `3000` are ignored.

Identical queries within 5 minutes are answered from an in-process cache and do not reach NDL. Several NDL calls in a row take about 3 seconds each. The pacing applies within one server process; if you run several copies, keep their combined traffic within the same terms.

`HOUAN_MCP_TIMEOUT_MS` (default `20000`) sets the per-request timeout. It starts when the request is sent, not while it waits for its turn.

## Example: pulling a Mythos Q&A

The 4/10 2026 衆議院外務委員会 questioning by 宇佐美登 (チームみらい) on Anthropic's Claude Mythos Preview can be retrieved like this:

```json
{
  "tool": "find_diet_qa",
  "arguments": {
    "keyword": "クロード",
    "from": "2026-04-01",
    "until": "2026-04-30"
  }
}
```

The response includes 花田貴裕 政府参考人's verbatim answer with `meetingURL` pointing to the canonical NDL record at `https://kokkai.ndl.go.jp/txt/122103968X00620260410`.

## Safety Notes

- This package is a **legislative reference tool, not legal/political advice**.
- It does not execute shell commands.
- It writes JSON-RPC messages only to stdout and logs only to stderr.
- It fetches only the NDL Kokkai API and 衆/参 議案情報 endpoints.
- Diet records in NDL typically appear with a 1–2 week lag after the committee meeting. If a recent meeting cannot be found, check back later or consult the chamber's video library directly.

## Development checks

```bash
npm test
```

Tests launch the stdio server with network requests replaced by local official-HTML samples. They cover Shugiin search/proceedings, failure reporting, and the existing Sangiin and NDL tools. Sample sources and capture details are in `test/fixtures/README.md`.

## Related

- Sibling MCP for current laws: [`@codeagentjp/egov-law-mcp`](https://github.com/SHAYOUWORLD/egov-law-mcp)
- Roadmap (法令diff / 自治体条例 / 判例 MCPs): [SHAYOUWORLD/egov-law-mcp#1](https://github.com/SHAYOUWORLD/egov-law-mcp/issues/1)
- Use cases (Japanese): [houan-mcp の7つの実用ユースケース (codeagent.jp)](https://codeagent.jp/posts/houan-mcp-use-cases/)
- From bills to current law (Japanese): [houan-mcpとe-Gov法令MCPの調査フロー (codeagent.jp)](https://codeagent.jp/posts/houan-egov-mcp-research-workflow/)
- Other Japanese public-data APIs and MCP servers: [codeagent.jp/guides/public-data-api/](https://codeagent.jp/guides/public-data-api/)

## License

[MIT](./LICENSE) © codeagent.jp

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct resource: speeches (find_diet_qa), bills (get_bill, search_bills), and meeting transcripts (get_meeting_record). There is no overlap in functionality, making it easy for an agent to choose the correct tool.

Naming Consistency3/5

Tool names mix verb prefixes: 'find', 'get', and 'search'. While all use snake_case, the lack of a uniform verb-noun pattern (e.g., all 'get_...' or all 'search_...') creates mild inconsistency.

Tool Count5/5

Four tools is well-scoped for the domain of Japanese Diet information retrieval. Each tool serves a clear purpose without redundancy or excessive granularity.

Completeness4/5

The tool set covers search and retrieval for bills, speeches, and meeting transcripts, which are the core needs. Minor gaps exist (e.g., listing all committees or filtering by date), but they don't hinder primary workflows.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues