MLIT Data Platform MCP Server

https://github.com/mlit-data-platform/mlit-dpf-mcp
Admin
An alpha version MCP (Model Context Protocol) server for the MLIT Data Platform, enabling...
Tokens:68,798
Snippets:449
Trust Score:4.4
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Usage Example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Example of using the MLITClient to build a search query and post it.

```APIDOC
## Usage Example

### Description
Example of using the MLITClient to build a search query and post it.

### Code
```python
from src.schemas import FileRef
from src.client import MLITClient

async def builder_usage():
    client = MLITClient()
    try:
        q = client.build_search(term="橋梁", size=10, sort_attribute_name="DPF:year")
        data = await client.post_query(q)
    finally:
        await client.close()
```
```

--------------------------------

### Example: Using file and thumbnail download methods

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Shows how to use get_data_files, file_download_urls, zipfile_download_url, and thumbnail_urls_from_data with an MLITClient instance. The example demonstrates fetching files and thumbnails for given dataset and data IDs, then obtaining download URLs. It includes a try/finally block to ensure the client is closed.

```python
from src.client import MLITClient

async def files_example():
    client = MLITClient()
    try:
        files = await client.get_data_files(dataset_id="cals_construction", data_id="<id>")
        urls = await client.file_download_urls(files=files)
        zip_url = await client.zipfile_download_url(files=files)
        thumbs = await client.thumbnail_urls_from_data(dataset_id="ndm", data_id="<id>")
    finally:
        await client.close()
```

--------------------------------

### MLITClient post_query usage example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Example of using post_query to fetch prefecture data and printing the result.

```python
from src.client import MLITClient
from src.utils import new_request_id

async def example():
    client = MLITClient()
    try:
        data = await client.post_query(
            'query { prefecture { code name } }'
        )
        print(data["prefecture"])
    finally:
        await client.close()
```

--------------------------------

### catalog_examples usage example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Example usage of get_prefectures, get_municipalities, and get_data_catalog. It fetches prefectures, municipalities for Tokyo (code '13'), and catalogs with IDs 'cals' and 'rsdb', then closes the client.

```python
async def catalog_examples():
    client = MLITClient()
    try:
        prefs = await client.get_prefectures()
        tokyo_munis = await client.get_municipalities(pref_codes=["13"])
        cats = await client.get_data_catalog(ids=["cals", "rsdb"], include_datasets=True)
    finally:
        await client.close()
```

--------------------------------

### .env.example configuration

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/configuration.md

Example .env file showing the required MLIT_API_KEY and optional MLIT_BASE_URL. The .env file is loaded by python-dotenv at module import of src/config.py.

```plaintext
MLIT_API_KEY=your_api_key_here
MLIT_BASE_URL=https://data-platform.mlit.go.jp/api/v1/

```

--------------------------------

### Usage example for search methods

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Example usage of the search methods: search_keyword, search_by_rectangle, search_by_point, and search_by_attribute_raw. Creates an MLITClient, runs the searches, and closes the client in a finally block.

```python
import asyncio
from src.client import MLITClient

async def search_examples():
    client = MLITClient()
    try:
        r1 = await client.search_keyword("橋梁", first=0, size=10)
        r2 = await client.search_by_rectangle(35.80, 139.55, 35.60, 139.85, term="", size=50)
        r3 = await client.search_by_point(35.681236, 139.767125, 500, term="バス停")
        r4 = await client.search_by_attribute_raw(attribute_name="DPF:prefecture_code", attribute_value="13", size=20)
    finally:
        await client.close()
```

--------------------------------

### Usage example for Timer

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/utils.md

Shows how to use the Timer context manager to measure and print elapsed time in milliseconds.

```python
from src.utils import Timer

with Timer() as t:
    do_work()
print(f"took {t.elapsed_ms:.1f} ms")
```

--------------------------------

### Run the MCP server from the command line

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/server.md

Use this command to start the MCP server. The module header prepends the repo root to sys.path so absolute from src.* imports work regardless of how it is launched.

```bash
python -m src.server          # or: python src/server.py
```

--------------------------------

### MLITClient usage example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Example of using MLITClient to fetch prefectures and ensure the session is closed in a finally block.

```python
import asyncio
from src.client import MLITClient

async def main():
    client = MLITClient()
    try:
        data = await client.get_prefectures()
    finally:
        await client.close()

asyncio.run(main())
```

--------------------------------

### Builder usage example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Shows how to use a builder method with an async client: build a search query and post it, ensuring the client is closed in a finally block.

```python
from src.schemas import FileRef
from src.client import MLITClient

async def builder_usage():
    client = MLITClient()
    try:
        q = client.build_search(term="橋梁", size=10, sort_attribute_name="DPF:year")
        data = await client.post_query(q)
    finally:
        await client.close()

```

--------------------------------

### MLITClient error handling example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Example of handling errors from post_query, catching TransientHttpError and RuntimeError after retries are exhausted.

```python
# Error handling: transient failures are retried automatically; catch what
# leaks out after retries are exhausted.
from src.client import MLITClient, TransientHttpError

async def example_error_handling():
    client = MLITClient()
    try:
        return await client.post_query("query { search { totalNumber } }")
    except TransientHttpError as e:
        # HTTP 429/5xx or network/timeout survived the retry budget
        print("retries exhausted:", e)
    except RuntimeError as e:
        print("protocol-level error:", e)
    finally:
        await client.close()
```

--------------------------------

### Python example: suggest and count_data

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Example usage of the suggest and count_data methods. It creates an MLITClient, calls suggest with a term and phrase_match, then count_data with a term, and prints the results. The client is closed in a finally block.

```python
from src.schemas import SuggestInput, CountDataInput

async def suggest_count_example():
    client = MLITClient()
    try:
        sug = await client.suggest(SuggestInput(term="川", phrase_match=True))
        cnt = await client.count_data(CountDataInput(term="橋梁"))
        print(sug["suggest"], cnt["countData"]["dataCount"])
    finally:
        await client.close()
```

--------------------------------

### Bulk collection usage example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Example of using get_all_data_collect to fetch data in bulk. It creates an MLITClient, builds GetAllDataInput with a dataset ID, size, max_batches, and include_metadata, then prints the count and batch count. The client is closed in a finally block.

```python
from src.schemas import GetAllDataInput

async def bulk_example():
    client = MLITClient()
    try:
        params = GetAllDataInput(
            term="", dataset_id="mlit-001",
            size=1000, max_batches=5, include_metadata=True,
        )
        result = await client.get_all_data_collect(params)
        print(result["count"], "items in", result["batches"], "batches")
    finally:
        await client.close()
```

--------------------------------

### Filter helper usage example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Example usage of filter helpers with MLITClient. Creates a rectangle filter, builds a search query with it, posts the query, and closes the client in a finally block.

```python
from src.client import MLITClient

async def filter_usage():
    client = MLITClient()
    try:
        rect = client.make_rectangle_filter(35.80, 139.55, 35.60, 139.85)
        q = client.build_search(location_filter=rect, term="", size=50)
        data = await client.post_query(q)
    finally:
        await client.close()
```

--------------------------------

### RateLimiter usage example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/utils.md

Demonstrates using RateLimiter with rps=4.0 to limit requests to 4 per second. Acquires a token 20 times and prints 'go' each time.

```python
import asyncio
from src.utils import RateLimiter

async def demo():
    limiter = RateLimiter(rps=4.0)   # max 4 requests/sec
    for _ in range(20):
        await limiter.acquire()
        print("go")

asyncio.run(demo())
```

--------------------------------

### Import dotenv and Pydantic for Settings

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/config.md

Loads the .env file with python-dotenv and imports the Pydantic classes needed to define Settings. This is the initial setup for the config module.

```python
from dotenv import load_dotenv
load_dotenv()

import os
from pydantic import BaseModel, Field, HttpUrl, ValidationError

```

--------------------------------

### GetMunicipalitiesParams usage example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/schemas.md

Shows how to instantiate GetMunicipalitiesParams with a single pref_code and fields. The pref_code is promoted to pref_codes, as shown by the printed output.

```python
from src.schemas import GetMunicipalitiesParams

p = GetMunicipalitiesParams(pref_code="13", fields=["code_as_string", "name"])
print(p.pref_codes)  # ['13']
```

--------------------------------

### safe_truncate_bytes usage example

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/utils.md

Example of calling safe_truncate_bytes with a Japanese string and a byte limit of 9. The function returns a prefix that fits within the byte budget without splitting multi-byte characters.

```python
from src.utils import safe_truncate_bytes

print(safe_truncate_bytes("日本語のテキスト", limit_bytes=9))
```

--------------------------------

### tools/call - search

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/endpoints.md

Example of invoking the 'search' tool via the MCP tools/call endpoint. The request includes a search term, result size, and optional sort parameters. The response contains a JSON string with the search results.

```APIDOC
## tools/call - search

### Description
Invokes the 'search' tool to perform a search with the given term and options.

### Method
POST

### Endpoint
tools/call

### Parameters
#### Request Body
- **name** (string) - Required - The name of the tool to call, e.g., "search".
- **arguments** (object) - Required - The arguments for the tool.
  - **term** (string) - Required - The search term.
  - **size** (integer) - Optional - The number of results to return.
  - **sort_attribute_name** (string) - Optional - The attribute to sort by.
  - **sort_order** (string) - Optional - The sort order, e.g., "dsc".

### Request Example
{
  "name": "search",
  "arguments": {
    "term": "橋梁",
    "size": 10,
    "sort_attribute_name": "DPF:year",
    "sort_order": "dsc"
  }
}

### Response
#### Success Response
- **content** (array) - List of content items.
  - **type** (string) - The type of content, e.g., "text".
  - **text** (string) - A JSON string containing the search results.
- **isError** (boolean) - Indicates if an error occurred.

#### Response Example
{
  "content": [
    {
      "type": "text",
      "text": "{\"search\": {\"totalNumber\": 5, \"searchResults\": [...]}}"
    }
  ],
  "isError": false
}
```

--------------------------------

### Normalize codes with prefecture and municipality

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Example of calling normalize_codes with Japanese prefecture and municipality names. The method returns resolved codes and names, and uses 10-minute in-memory caches. The client is closed in a finally block.

```python
from src.schemas import NormalizeCodesInput

async def normalize_example():
    client = MLITClient()
    try:
        out = await client.normalize_codes(NormalizeCodesInput(prefecture="東京", municipality="千代田区"))
        print(out.prefecture_code, out.prefecture_name, out.municipality_code, out.municipality_name)
    finally:
        await client.close()
```

--------------------------------

### Async main function for server initialization

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/server.md

Opens the stdio transport, computes capabilities with default notifications and no experimental capabilities, builds InitializationOptions with server_name 'mlit-mcp' and server_version '0.1.0', and runs the server.

```python
async def _main() -> None:
    async with stdio_server() as (read, write):
        caps = server.get_capabilities(
            notification_options=NotificationOptions(),
            experimental_capabilities={}
        )

        init_opts = InitializationOptions(
            server_name="mlit-mcp",
            server_version="0.1.0",
            capabilities=caps
        )

        await server.run(read, write, init_opts)
```

--------------------------------

### Entry point guard for running the server

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/server.md

Runs the async main function using anyio when the script is executed directly.

```python
if __name__ == "__main__":
    anyio.run(_main)
```

--------------------------------

### initialize

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/endpoints.md

MCP protocol handshake method that initializes the server connection. Returns server name and version.

```APIDOC
## initialize

### Description
Protocol handshake for the MCP server. Returns server name and version.

### Method
initialize

### Endpoint
initialize

### Parameters
None

### Response
#### Success Response
- **server_name** (string) - Server name, e.g. "mlit-mcp"
- **server_version** (string) - Server version, e.g. "0.1.0"

#### Response Example
{
  "server_name": "mlit-mcp",
  "server_version": "0.1.0"
}
```

--------------------------------

### Use load_settings and print settings

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/config.md

Shows how to use load_settings in your own code, printing the base URL, a masked API key, and the requests-per-second setting.

```python
from src.config import load_settings, Settings

def main():
    s: Settings = load_settings()
    print(s.base_url, s.api_key[:4] + "...", s.rps)

```

--------------------------------

### MLITClient constructor

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Creates a new MLITClient instance. No arguments are required; all configuration is loaded from environment variables.

```APIDOC
## MLITClient constructor

### Description
Creates a new MLITClient instance. No arguments are required; all configuration is loaded from environment variables.

### Method
Constructor

### Endpoint
N/A (client initialization)

### Parameters
None

### Request Example
```python
from src.client import MLITClient

client = MLITClient()
```

### Response
#### Success Response
- **client** (MLITClient) - The initialized client instance.

#### Response Example
```python
client = MLITClient()
```
```

--------------------------------

### Load settings with load_settings()

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/configuration.md

Loads the Settings object from environment variables and prints several fields. No constructor arguments are used; all values come from the environment.

```python
from src.config import load_settings

s = load_settings()
print(s.base_url, s.timeout_s, s.rps, s.max_retries, s.backoff_base_s)
```

--------------------------------

### Successful tools/call response

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/endpoints.md

Example successful response from the tools/call endpoint. The content[0].text field contains a JSON string of the data dict, which includes the search results and total number.

```json
{
  "content": [
    {
      "type": "text",
      "text": "{\"search\": {\"totalNumber\": 5, \"searchResults\": [...]}}"
    }
  ],
  "isError": false
}
```

--------------------------------

### tools/call search request payload

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/endpoints.md

Example JSON payload for a tools/call request to the 'search' tool. It includes arguments for the search term, result size, and sorting by DPF:year in descending order.

```json
{
  "name": "search",
  "arguments": {
    "term": "橋梁",
    "size": 10,
    "sort_attribute_name": "DPF:year",
    "sort_order": "dsc"
  }
}
```

--------------------------------

### MLITClient constructor

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Constructor for MLITClient with no parameters. All configuration is loaded from the environment via load_settings().

```python
def __init__(self):
```

--------------------------------

### RateLimiter.__init__(rps)

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/utils.md

Initializes a RateLimiter instance with a token-bucket algorithm. The capacity is set to at least 1.0 and the refill rate is set to the given requests per second.

```APIDOC
## RateLimiter.__init__(rps)

### Description
Initializes a RateLimiter instance with a token-bucket algorithm. The capacity is set to at least 1.0 and the refill rate is set to the given requests per second.

### Method
Constructor

### Parameters
- **rps** (float) - Required - Requests per second; capacity floors at 1.0

### Request Example
```python
limiter = RateLimiter(rps=4.0)
```

### Response
#### Success Response
- **None** - No return value.

```

--------------------------------

### Validate tool arguments with SearchBase.model_validate()

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/schemas.md

Server-side usage pattern: import schema classes, validate a tool argument dict into a model, and handle validation errors. The example shows a successful validation with size=100 and a failing validation for GetMunicipalitiesParams with an empty dict, which raises ValueError with the message 'Either pref_codes or muni_codes (or pref_code) must be provided.'

```python
from src.schemas import SearchBase, GetAllDataInput, FileDownloadURLsInput

# Tool argument dict → validated model, then passed to the client
p = SearchBase.model_validate({"term": "橋梁", "size": 100})
assert p.size == 100

try:
    GetMunicipalitiesParams.model_validate({})
except ValueError as e:
    print(e)  # Either pref_codes or muni_codes (or pref_code) must be provided.
```

--------------------------------

### handle_call_tool implementation

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/server.md

Decorated with @server.call_tool(), this async function processes tool calls. It creates a request ID, loads settings, instantiates MLITClient, and ensures client.close() runs in a finally block. Returns a list with one TextContent item containing JSON-serialized data, truncated to 512 KiB if larger than 1 MiB.

```python
@server.call_tool()
async def handle_call_tool(name: str, arguments: dict) -> List[types.TextContent]:
    rid = new_request_id()
    cfg = load_settings()
    client = MLITClient()
    ...
    finally:
        await client.close()
```

--------------------------------

### Define the list_tools handler

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/server.md

Registers the handler that returns the 18-tool catalog. Each tool has a name, a Japanese description, and an inputSchema.

```python
@server.list_tools()
async def handle_list_tools() -> List[types.Tool]:
```

--------------------------------

### Create the MCP server instance

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/server.md

Creates the MCP server instance named MLIT-DATA-PLATFORM-mcp-mod. Tool handlers are registered through its decorators.

```python
server = Server("MLIT-DATA-PLATFORM-mcp-mod")
```

--------------------------------

### tools/list

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/endpoints.md

Returns the catalog of 18 tools available on the MCP server.

```APIDOC
## tools/list

### Description
Returns the list of all available tools (18 tools) advertised by the server.

### Method
tools/list

### Endpoint
tools/list

### Parameters
None

### Response
#### Success Response
- **tools** (array) - List of tool definitions

#### Response Example
{
  "tools": [
    {
      "name": "search",
      "description": "...",
      "inputSchema": {}
    }
  ]
}
```

--------------------------------

### async def file_download_urls_from_data(self, *, dataset_id: str, data_id: str) -> Dict[str, Any]

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Resolves files via get_data_files and then calls file_download_urls to generate download URLs.

```APIDOC
## file_download_urls_from_data

### Description
Resolves files via get_data_files and then calls file_download_urls to generate download URLs.

### Method
async def file_download_urls_from_data(self, *, dataset_id: str, data_id: str) -> Dict[str, Any]

### Parameters
- **dataset_id** (str) - Required - Dataset ID (from `search`)
- **data_id** (str) - Required - Data ID (from `search`)

### Return
- **Dict[str, Any]** - Same shape as `file_download_urls`: `{"fileDownloadURLs": [{"ID", "URL"}, ...]}`.
```

--------------------------------

### async def zipfile_download_url_from_data(self, *, dataset_id: str, data_id: str) -> Dict[str, Any]

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Resolves files via get_data_files and then calls zipfile_download_url to generate a zip download URL.

```APIDOC
## zipfile_download_url_from_data

### Description
Resolves files via get_data_files and then calls zipfile_download_url to generate a zip download URL.

### Method
async def zipfile_download_url_from_data(self, *, dataset_id: str, data_id: str) -> Dict[str, Any]

### Parameters
- **dataset_id** (str) - Required - Dataset ID (from `search`)
- **data_id** (str) - Required - Data ID (from `search`)

### Return
- **Dict[str, Any]** - Same shape as `zipfile_download_url`: `{"zipfileDownloadURL": str | null}`.
```

--------------------------------

### async def suggest(self, params: SuggestInput) -> Dict[str, Any]

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Maps SuggestInput fields to an attribute filter and an optional rectangle locationFilter, then calls build_suggest. Returns a dictionary with a suggest key containing totalNumber and suggestions list.

```APIDOC
## async def suggest(self, params: SuggestInput) -> Dict[str, Any]

### Description
Maps `SuggestInput` fields to an attribute filter (via `make_attribute_filter_for_countdata`) and an optional rectangle `locationFilter`, then calls `build_suggest`.

### Method
async def

### Endpoint
suggest

### Parameters
#### Path Parameters
- **params** (SuggestInput) - Required - Term/filters/location/slice settings

### Return
- **Return:** `{"suggest": {"totalNumber": int, "suggestions": [{name, cnt}]}}`

```

--------------------------------

### tools/call

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/endpoints.md

Executes a specific tool by name with the provided arguments. The request includes the tool name and arguments object.

```APIDOC
## tools/call

### Description
Executes a tool by name with the given arguments. The response contains a JSON string in the text field.

### Method
tools/call

### Endpoint
tools/call

### Parameters
#### Request Body
- **name** (string) - Required - The name of the tool to call.
- **arguments** (object) - Required - The arguments for the tool.

### Request Example
{
  "name": "search",
  "arguments": {
    "term": "example"
  }
}

### Response
#### Success Response
- **content** (array) - Array of content objects, each with type and text.
- **isError** (boolean) - Indicates if the call resulted in an error.

#### Response Example
{
  "content": [
    {
      "type": "text",
      "text": "{\"search\": {\"totalNumber\": 0, \"searchResults\": []}}"
    }
  ],
  "isError": false
}

### Error Codes
- **-32601** - Unknown method or unknown tool ("Unknown tool: <name>")
- **-32602** - Invalid params (including schema ValueError)
- **-32603** - Internal error (e.g., retries exhausted, transport failures)
```

--------------------------------

### MLITClient class definition

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Defines the MLITClient class with a GraphQL endpoint and API key header. The client reads all settings from the environment via load_settings() at construction time.

```python
class MLITClient:
    """
    GraphQL client for MLIT Data Platform.
    - Endpoint: POST https://data-platform.mlit.go.jp/api/v1/
    - Header:  apikey: <MLIT_API_KEY>
    """
```

--------------------------------

### async def thumbnail_urls_from_data(self, *, dataset_id: str, data_id: str) -> Dict[str, Any]

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Resolves thumbnails via get_data_thumbnails and then calls thumbnail_urls to generate thumbnail URLs.

```APIDOC
## thumbnail_urls_from_data

### Description
Resolves thumbnails via get_data_thumbnails and then calls thumbnail_urls to generate thumbnail URLs.

### Method
async def thumbnail_urls_from_data(self, *, dataset_id: str, data_id: str) -> Dict[str, Any]

### Parameters
- **dataset_id** (str) - Required - Dataset ID (from `search`)
- **data_id** (str) - Required - Data ID (from `search`)

### Return
- **Dict[str, Any]** - Same shape as `thumbnail_urls`: `{"thumbnailURLs": [{"ID", "URL"}, ...]}`.
```

--------------------------------

### MLITClient post_query method

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Sends a GraphQL query to the MLIT Data Platform. Returns the 'data' field of the response. Raises TransientHttpError on retryable failures, RuntimeError if no 'data' key, and other errors for non-transient issues.

```python
async def post_query(self, query: str) -> Dict[str, Any]:
```

--------------------------------

### get_suggest

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/endpoints.md

Provides keyword suggestions based on a term prefix and optional filters.

```APIDOC
## get_suggest

### Description
Provides keyword suggestions based on a term prefix and optional filters.

### Method
client.suggest

### Parameters
#### Required Parameters
- **term** (string) - Required - Keyword prefix (empty not allowed)

#### Optional Parameters
- **phrase_match** (boolean) - Optional - Phrase-match mode
- **prefecture_code** (string) - Optional - Prefecture filter
- **municipality_code** (string) - Optional - Municipality filter
- **address** (string) - Optional - Address filter
- **catalog_id** (string) - Optional - Catalog filter
- **dataset_id** (string) - Optional - Dataset filter
- **location_rectangle_top_left_lat/lon** (number) - Optional - Rect NW corner
- **location_rectangle_bottom_right_lat/lon** (number) - Optional - Rect SE corner

### Response
- **suggest** (object) - Contains `totalNumber` (int) and `suggestions` (array of objects with `name` and `cnt`).

### Response Example
{
  "suggest": {
    "totalNumber": 1,
    "suggestions": [
      {
        "name": "string",
        "cnt": 0
      }
    ]
  }
}
```

--------------------------------

### MCP host configuration for mlit-dpf-mcp

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/server.md

JSON configuration for embedding the server in an MCP host, specifying the command, arguments, and environment variables including MLIT_API_KEY and MLIT_BASE_URL.

```json
{
  "mcpServers": {
    "mlit-dpf-mcp": {
      "command": "/path/to/mlit-dpf-mcp/.venv/Scripts/python.exe",
      "args": ["/path/to/mlit-dpf-mcp/src/server.py"],
      "env": {
        "MLIT_API_KEY": "your_api_key_here",
        "MLIT_BASE_URL": "https://data-platform.mlit.go.jp/api/v1/",
        "PYTHONUNBUFFERED": "1",
        "LOG_LEVEL": "WARNING"
      }
    }
  }
}
```

--------------------------------

### Define load_settings factory to validate environment

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/config.md

Factory function that reads MLIT_API_KEY from the environment, validates it via Settings, and wraps any Pydantic ValidationError in a RuntimeError. base_url is resolved via the field default.

```python
def load_settings() -> Settings:
    env = {
        "MLIT_API_KEY": os.getenv("MLIT_API_KEY"),
        # base_url is automatically set by default
    }
    try:
        return Settings.model_validate(env)
    except ValidationError as e:
        raise RuntimeError(
            "Config error: set ENV MLIT_API_KEY (and optionally MLIT_BASE_URL)."
        ) from e

```

--------------------------------

### async def file_download_urls(self, *, files: List[FileRef]) -> Dict[str, Any]

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Generates download URLs for a list of file references. If the list is empty, returns an empty list without making a request.

```APIDOC
## file_download_urls

### Description
Generates download URLs for a list of file references. If the list is empty, returns an empty list without making a request.

### Method
async def file_download_urls(self, *, files: List[FileRef]) -> Dict[str, Any]

### Parameters
- **files** (List[FileRef]) - Required - List of file references.

### Return
- **Dict[str, Any]** - `{"fileDownloadURLs": [{"ID", "URL"}, ...]}`. URLs beginning with `https://data-platform.mlit.go.jp/download/` expire in 60 seconds.
```

--------------------------------

### build_file_download_urls method signature

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Defines the build_file_download_urls method that returns a GraphQL query string for fileDownloadURLs with a list of FileRef objects.

```python
def build_file_download_urls(self, *, files: List[FileRef]) -> str:

```

--------------------------------

### async def get_data_files(self, *, dataset_id: str, data_id: str) -> List[FileRef]

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Retrieves file references for a given dataset and data. Runs a GraphQL query and flattens the files of all results.

```APIDOC
## get_data_files

### Description
Retrieves file references for a given dataset and data. Runs a GraphQL query and flattens the files of all results.

### Method
async def get_data_files(self, *, dataset_id: str, data_id: str) -> List[FileRef]

### Parameters
- **dataset_id** (str) - Required - Dataset ID (from `search`)
- **data_id** (str) - Required - Data ID (from `search`)

### Return
- **List[FileRef]** - List of file references, each with `id` and `original_path`.
```

--------------------------------

### SuggestInput class definition

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/schemas.md

Input model for the Suggest tool. Requires 'term' (non-empty string); all other fields are optional. Includes optional location rectangle coordinates.

```python
class SuggestInput(BaseModel):
    term: str
    phrase_match: Optional[bool] = None

    prefecture_code: Optional[str] = None
    municipality_code: Optional[str] = None
    address: Optional[str] = None
    catalog_id: Optional[str] = None
    dataset_id: Optional[str] = None

    location_rectangle_top_left_lat: Optional[float] = None
    location_rectangle_top_left_lon: Optional[float] = None
    location_rectangle_bottom_right_lat: Optional[float] = None
    location_rectangle_bottom_right_lon: Optional[float] = None
```

--------------------------------

### build_zipfile_download_url method signature

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Defines the build_zipfile_download_url method that returns a GraphQL query string for zipfileDownloadURL as a scalar.

```python
def build_zipfile_download_url(self, *, files: List[FileRef]) -> str:

```

--------------------------------

### GetAllDataInput

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/types.md

Input parameters for bulk collection via client.get_all_data_iter, client.get_all_data_collect, and the get_all_data tool.

```APIDOC
## GetAllDataInput

### Description
Input parameters for bulk collection. Accepted by `client.get_all_data_iter` / `client.get_all_data_collect` / `get_all_data` tool.

### Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `size` | `int` | no | Batch size; default `1000`, range `[1, 1000]` |
| `term` | `Optional[str]` | no | Keyword; `""` required for filter-only queries |
| `phrase_match` | `Optional[bool]` | no | Phrase-match mode |
| `prefecture_code` | `Optional[str]` | no | Prefecture filter |
| `municipality_code` | `Optional[str]` | no | Municipality filter |
| `address` | `Optional[str]` | no | Address filter |
| `catalog_id` | `Optional[str]` | no | Catalog filter |
| `dataset_id` | `Optional[str]` | no | Dataset filter |
| `location_rectangle_top_left_lat` | `Optional[float]` | no | Rect NW corner latitude |
| `location_rectangle_top_left_lon` | `Optional[float]` | no | Rect NW corner longitude |
| `location_rectangle_bottom_right_lat` | `Optional[float]` | no | Rect SE corner latitude |
| `location_rectangle_bottom_right_lon` | `Optional[float]` | no | Rect SE corner longitude |
| `max_batches` | `int` | no | Max pages; default `20`, range `[1, 10000]` |
| `include_metadata` | `bool` | no | Include `metadata` in items; default `True` |
```

--------------------------------

### GetAllDataInput class definition

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/schemas.md

Defines parameters for bulk data collection. Includes constraints: size between 1 and 1000 (MLIT limit), max_batches between 1 and 10000, and all filters are optional.

```python
class GetAllDataInput(BaseModel):
    size: int = Field(1000, ge=1, le=1000, description="Max 1000 per request (MLIT limit)")
    term: Optional[str] = None
    phrase_match: Optional[bool] = None

    prefecture_code: Optional[str] = None
    municipality_code: Optional[str] = None
    address: Optional[str] = None
    catalog_id: Optional[str] = None
    dataset_id: Optional[str] = None

    location_rectangle_top_left_lat: Optional[float] = None
    location_rectangle_top_left_lon: Optional[float] = None
    location_rectangle_bottom_right_lat: Optional[float] = None
    location_rectangle_bottom_right_lon: Optional[float] = None

    max_batches: int = Field(20, ge=1, le=10000)
    include_metadata: bool = True
```

--------------------------------

### async def get_data_thumbnails(self, *, dataset_id: str, data_id: str) -> List[ThumbnailRef]

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Retrieves thumbnail references for a given dataset and data. Uses the same pattern as get_data_files but over thumbnails.

```APIDOC
## get_data_thumbnails

### Description
Retrieves thumbnail references for a given dataset and data. Uses the same pattern as get_data_files but over thumbnails.

### Method
async def get_data_thumbnails(self, *, dataset_id: str, data_id: str) -> List[ThumbnailRef]

### Parameters
- **dataset_id** (str) - Required - Dataset ID (from `search`)
- **data_id** (str) - Required - Data ID (from `search`)

### Return
- **List[ThumbnailRef]** - List of thumbnail references, each with `id` and `original_path`.
```

--------------------------------

### handle_call_tool

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/server.md

Handles MCP tool calls by dispatching to the appropriate MLITClient method based on the tool name. Validates arguments, executes the client method, and returns a JSON text content item.

```APIDOC
## `async def handle_call_tool(name: str, arguments: dict) -> List[types.TextContent]`

### Description
Handles MCP tool calls by dispatching to the appropriate MLITClient method based on the tool name. Validates arguments, executes the client method, and returns a JSON text content item.

### Method
`call_tool` (MCP tool handler)

### Parameters
- **name** (`str`) - Required - Tool name from the catalog.
- **arguments** (`dict`) - Required - Tool arguments to validate.

### Return
- `List[types.TextContent]` - Exactly one text content item whose `text` is `json.dumps(data, ensure_ascii=False)`. Results larger than `1 MiB` are truncated to `512 KiB` with a `\n...<truncated>` suffix.

### Per-tool dispatch
Each tool validates arguments into a schema model, then calls the matching `MLITClient` method.

| Tool name | Model (`schemas.py`) | Client method |
|-----------|----------------------|---------------|
| `search` | `SearchBase` | `search_keyword` |
| `search_by_location_rectangle` | `SearchByRect` | `search_by_rectangle` |
| `search_by_location_point_distance` | `SearchByPoint` | `search_by_point` |
| `search_by_attribute` | `SearchByAttr` | `search_by_attribute_raw` |
| `get_data_summary` | `GetDataParams` | `get_data_summary` |
| `get_data` | `GetDataParams` | `get_data` |
| `get_data_catalog_summary` | — (no args) | `get_data_catalog_summary` |
| `get_data_catalog` | — (inline) | `get_data_catalog` |
| `get_prefecture_data` | — (no args) | `get_prefectures` |
| `get_municipality_data` | `GetMunicipalitiesParams` | `get_municipalities` |
| `get_all_data` | `GetAllDataInput` (+ `_auto_normalize_region_args`) | `get_all_data_collect` |
| `get_suggest` | `SuggestInput` (+ `_auto_normalize_region_args`) | `suggest` |
| `get_count_data` | `CountDataInput` (slice assembly + `_auto_normalize_region_args`) | `count_data` |
| `get_mesh` | `MeshParams` | `get_mesh` |
| `get_file_download_urls` | `FileDownloadURLsInput` | `file_download_urls` / `file_download_urls_from_data` |
| `get_zipfile_download_url` | `ZipfileDownloadURLInput` | `zipfile_download_url` / `zipfile_download_url_from_data` |
| `get_thumbnail_urls` | `ThumbnailURLsInput` | `thumbnail_urls` / `thumbnail_urls_from_data` |
| `normalize_codes` | `NormalizeCodesInput` | `normalize_codes` |

### Special path: `get_count_data`
Builds a `sub_dict` / `attr_dict` / `slice_setting` (plain dicts with camelCase keys `attributeName`, `size`, `subSliceSetting`, `attributeSliceSetting`, `type`) from `slice_type` / `slice_attribute_name` / `slice_size` / `slice_sub_attribute_name` / `slice_sub_size` before validating `CountDataInput`, then returns its own result dict (it early-returns the `{"content": [...], "isError": False}` envelope).

### Errors
Throws (propagate to the MCP host as errors):
- `ValueError("ids must be an array of strings")` — `get_data_catalog` with a non-list `ids`.
- `ValueError(f"Unknown tool: {name}")` — unrecognized tool name.
- Validation `ValueError`s from the schema models (see [errors.md](../errors.md)).
- `TransientHttpError` / `RuntimeError` / aiohttp errors from the client.

### Additional Behavior
- A `Timer` measures elapsed time and logs `tool_done` with the `rid`.
- `client.close()` always runs in the `finally` block.
```

--------------------------------

### Catch TransientHttpError with MLITClient

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/errors.md

Shows how to import and catch TransientHttpError when using MLITClient. Because retries are internal, catching this means the upstream was still failing after ~4 attempts.

```python
from src.client import MLITClient, TransientHttpError

client = MLITClient()
try:
    data = await client.search_keyword("橋梁")
except TransientHttpError as e:
    # upstream 429/5xx/network/timeout persisted past the retry budget
    print("temporary failure:", e)
finally:
    await client.close()
```

--------------------------------

### ZipfileDownloadURLResponse class definition

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/schemas.md

Defines the response for a ZIP download URL, containing a url string and an optional raw field.

```python
class ZipfileDownloadURLResponse(BaseModel):
    url: str
    raw: Optional[Any] = None
```

--------------------------------

### build_file_download_urls

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Builds a GraphQL query string for file download URLs from a list of file references. Returns a query string for the fileDownloadURLs operation.

```APIDOC
## build_file_download_urls

### Description
Builds a GraphQL query string for file download URLs from a list of file references. Returns a query string for the fileDownloadURLs operation.

### Method
build_file_download_urls

### Signature
```python
def build_file_download_urls(self, *, files: List[FileRef]) -> str:
```

### Parameters
- **files** (List[FileRef]) - Required - List of file references

### Return
- **str** - `fileDownloadURLs(files: [{ id, original_path }]) { ID URL }`.
```

--------------------------------

### Define Settings BaseModel with API key and limits

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/config.md

Defines the Pydantic Settings model with a required MLIT_API_KEY alias and optional fields with defaults. Two fields, max_size and max_distance_m, are defined but not referenced elsewhere.

```python
class Settings(BaseModel):
    # MLIT GraphQL endpoint & API key (REQUIRED)
    base_url: HttpUrl = Field(
        default=os.getenv("MLIT_BASE_URL") or "https://data-platform.mlit.go.jp/api/v1/"
    )
    api_key: str = Field(..., alias="MLIT_API_KEY")

    # HTTP & reliability
    timeout_s: float = 30.0
    max_retries: int = 3
    backoff_base_s: float = 0.5
    rps: float = 4.0  # light rate limit

    # simple input limits
    max_size: int = 500  # MLIT recommended upper bound per query sample
    max_distance_m: int = 50000  # precaution for geoDistance

```

--------------------------------

### async def thumbnail_urls(self, *, thumbnails: List[ThumbnailRef]) -> Dict[str, Any]

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client-methods.md

Generates URLs for a list of thumbnail references. If the list is empty, returns an empty list.

```APIDOC
## thumbnail_urls

### Description
Generates URLs for a list of thumbnail references. If the list is empty, returns an empty list.

### Method
async def thumbnail_urls(self, *, thumbnails: List[ThumbnailRef]) -> Dict[str, Any]

### Parameters
- **thumbnails** (List[ThumbnailRef]) - Required - List of thumbnail references.

### Return
- **Dict[str, Any]** - `{"thumbnailURLs": [{"ID", "URL"}, ...]}`.
```

--------------------------------

### NormalizeCodesOutput schema

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/schemas.md

Output schema for MLITClient.normalize_codes, including optional prefecture/municipality details, candidate list, warnings, and normalization metadata.

```python
class NormalizeCodesOutput(BaseModel):
    prefecture_code: Optional[str] = None
    prefecture_name: Optional[str] = None
    municipality_code: Optional[str] = None
    municipality_name: Optional[str] = None
    candidates: List[MunicipalityCandidate] = Field(default_factory=list)
    warnings: List[str] = Field(default_factory=list)
    normalization_meta: Dict[str, Any] = Field(default_factory=dict)
```

--------------------------------

### Configure module-level JSON logger

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/utils.md

Creates a module-level logging.Logger named 'mlit_mcp' with a StreamHandler emitting JSON via pythonjsonlogger. The level is hard-set to logging.INFO at import time; the LOG_LEVEL env var is not read by the code. Extra keys passed to logger.info become JSON fields.

```python
logger = logging.getLogger("mlit_mcp")
_handler = logging.StreamHandler()
_formatter = jsonlogger.JsonFormatter("%(levelname)s %(message)s %(asctime)s %(name)s")
_handler.setFormatter(_formatter)
logger.setLevel(logging.INFO)
logger.addHandler(_handler)
```

--------------------------------

### build_zipfile_download_url

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/client.md

Builds a GraphQL query string for a zip file download URL from a list of file references. Returns a scalar query string for the zipfileDownloadURL operation.

```APIDOC
## build_zipfile_download_url

### Description
Builds a GraphQL query string for a zip file download URL from a list of file references. Returns a scalar query string for the zipfileDownloadURL operation.

### Method
build_zipfile_download_url

### Signature
```python
def build_zipfile_download_url(self, *, files: List[FileRef]) -> str:
```

### Parameters
- **files** (List[FileRef]) - Required - List of file references

### Return
- **str** - `zipfileDownloadURL(files: [...])` (scalar).
```

--------------------------------

### FileDownloadURLItem class definition

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/schemas.md

Defines a single file download URL item with ID and URL fields.

```python
class FileDownloadURLItem(BaseModel):
    ID: str
    URL: str
```

--------------------------------

### SuggestResponse class definition

Source: https://github.com/mlit-data-platform/mlit-dpf-mcp/blob/main/_autodocs/api-reference/schemas.md

Response model for the Suggest tool. Contains total number, list of suggestions, and raw data.

```python
class SuggestResponse(BaseModel):
    total_number: Optional[int] = None
    suggestions: List[SuggestItem] = Field(default_factory=list)
    raw: Optional[Any] = None
```
Tokens:
Raw