# public-procure-info-mcp-server

An MCP server for the search API of [官公需情報ポータルサイト](https://www.kkj.go.jp/s/), the
Small and Medium Enterprise Agency's portal that gathers the public bid notices (入札公告)
that national agencies, incorporated administrative agencies and local governments publish
on their own websites: search the notices and read their announcement text.

官公需情報ポータルサイト（中小企業庁）の検索APIを使って、国・独立行政法人・地方公共団体の
入札公告の検索と公告文の閲覧ができる MCP サーバーです。

> **Unofficial.** This project is not affiliated with or endorsed by the Small and Medium
> Enterprise Agency (中小企業庁), which operates the portal. It is written against the
> published [検索API ガイド V1.1](https://www.kkj.go.jp/doc/ja/api_guide.pdf), listed in the
> [e-Gov API catalog](https://api-catalog.e-gov.go.jp/info/en/apicatalog/view/67), and
> against the API's observed behaviour (2026-10-20).

## Tools

| Tool | What it does |
|---|---|
| `load_guideline` | The usage guideline for the whole tool set: search strategy, reading a notice, what the portal covers and what its data lacks, and the conditions of use. It takes no arguments and always returns the whole guideline. |
| `search_notices` | Search bid notices by a full-text expression, title words, issuing organisation or prefecture, narrowed by category (物品・工事・役務), procedure type, certification grade and four date ranges. Newest first; one page of summaries with a short preview of each announcement. |
| `get_notice` | One notice from a recent search, by its key: every field, its attachments' names and URLs, and the announcement text in pieces with `next_offset` to continue. |

The server follows a *skill-style* layout. Its MCP `instructions` are one sentence
saying what the tools are for and to call `load_guideline` first. Everything that
concerns the tool set as a whole — including the conditions of use — lives in the
guideline, and each tool's description covers only that tool. Agents that load many MCP
servers keep only a short entry per server in their prompt, and read the guideline when
they need it.

### How the API shapes the tools

The API is a single `GET https://www.kkj.go.jp/api/` answering XML. It has no paging, no
sort and no record lookup: results come newest first by publication date, `Count` is the
only control, and every result carries the announcement's full text (median about
20,000 characters), so 100 results are about 9 MB and take about 20 seconds.

- `search_notices` returns summaries without the text and caps a page at 100 results, or
  200 in total through `offset`. Beyond that the guideline tells the agent to narrow by
  date (`issue_date` before the page's `oldest_issue_date`) or by prefecture.
- `get_notice` serves the text from the records the server has already seen (the last
  2,000 notices). If a key is no longer known, the notice's title as `project_name` makes
  the server search for it again.
- Attachments and the source page are URLs on the issuing agency's site. The server does
  not fetch them.

Category, procedure type and certification are filled only when the portal could extract
them from the original notice (about 60%, 20% and under 1% of notices respectively), so
filtering on them excludes notices with no value. The guideline says so.

## Run

Python 3.11 or later.

```bash
pip install -e .
public-procure-info-mcp-server --host 127.0.0.1 --port 8000      # Streamable HTTP at /mcp
public-procure-info-mcp-server --transport stdio                # for clients that start it themselves
```

Behind a reverse proxy, accept the public host name as well; otherwise the server's DNS
rebinding protection rejects requests whose `Host` is not localhost:

```bash
public-procure-info-mcp-server --host 127.0.0.1 --port 8000 --allowed-host demo.mcp.gotoai.com
```

When bound to a non-loopback address (for example `--host 0.0.0.0` on a LAN), that
protection is off; restrict access with a firewall or a proxy.

### In Kari

Add a custom extension of type **Streamable HTTP** with the URL `http://<host>:<port>/mcp`.
Give it an ASCII name such as `kkj` — the name becomes part of every tool name the
agent sees.

## Conditions of use

These are in the guideline the agent reads; they apply to anyone presenting the results:

- Credit the source as 「出典：官公需情報ポータルサイト（中小企業庁） https://www.kkj.go.jp/s/ 」.
  The portal's terms ask any site or application using the API to say so and to link to
  the portal.
- Treat the information as a reference; confirm the latest details on the issuing
  agency's page (`source_url`) before taking part in a tender.
- Avoid excessive repeated access to the API; concurrent requests are limited.

The portal's terms of use are at <https://www.kkj.go.jp/s/?tc=1>; they apply to whoever
runs this server. This project itself uses the portal's API.

## Development

```bash
pip install -e ".[dev]"
pytest                          # offline tests
PUBLIC_PROCURE_LIVE=1 pytest    # also the live tests against the real API
ruff check src tests
```

## License

MIT — see [LICENSE](LICENSE).