langchain-askjapan
LangChain Python tools for Ask Japan public data and MARU Japan Hands human services in Japan, operated by iHouse Co., Ltd.
Release candidate 0.1.0. This local candidate has not been published to PyPI. Python 3.11+; validated locally on Python 3.12. No LLM subscription is needed to run the direct examples.
Overview
| Class | Default tools | Sync / async | Serializable | JavaScript |
|---|---|---|---|---|
AskJapanToolkit |
Six public-data tools | Yes / yes | No | Not provided |
MaruJapanHandsToolkit |
All 11 MARU tools | Yes / yes | No | Not provided |
Built on the official langchain-mcp-adapters. Tool names, descriptions, JSON input schemas and annotations come from live MCP discovery, without renaming or manually recreating arguments. The adapter's content blocks, structured artifacts and MCP execution errors are preserved. Construction/import is offline; loading a tool and each invocation require a network connection. Each invocation opens and closes an independent MCP session; no persistent background process or automatic retries.
Endpoints are taken from the Official MCP Registry, not inferred:
- Ask Japan:
https://askjapan.senpinai.com/mcp(com.senpinai/ask-japan). Its 14 tools include eight human-service/restaurant tools; the toolkit defaults to the six public-data tools. - MARU:
https://maru.senpinai.com/mcp(io.github.ihouse-corp/maru-japan-hands). Its 11 tools include three wallet tools.
Installation
Before publication, install the provided wheel:
python -m pip install ./dist/langchain_askjapan-0.1.0-py3-none-any.whl
After publication, the registry installation command will be:
python -m pip install langchain-askjapan
Connecting, listing tools and the three examples below require no account or API key. Private gateways may be configured using the official adapter's connection mapping. Never include wallet tokens in logs or enable external tracing for sensitive calls without authorization.
Three minimal examples
Search Japanese companies (free, read-only)
from langchain_askjapan.ask_japan import search_company
tool = search_company()
print(tool.invoke({"name": "トヨタ自動車", "limit": 1}))
Name search is a partial match; the first result is not guaranteed to be Toyota Motor Corporation itself. Use the corporate number when you need an exact legal entity.
Look up a postcode (free, read-only)
from langchain_askjapan.ask_japan import lookup_postcode
tool = lookup_postcode()
print(tool.invoke({"postcode": "530-0001"}))
Read MARU's service catalogue (free information; services are paid)
import asyncio
from langchain_askjapan.maru import aload_list_services
async def main():
tool = await aload_list_services()
print(await tool.ainvoke({}))
asyncio.run(main())
In a notebook with a running event loop, use await main() instead of asyncio.run(main()).
The runnable examples/read_only.py contains these three calls.
Toolkits and individual tools
from langchain_askjapan import AskJapanToolkit, MaruJapanHandsToolkit
public_tools = AskJapanToolkit().get_tools()
service_catalogue = MaruJapanHandsToolkit(tool_names=("list_services",)).get_tools()
Every registered tool has an independently importable synchronous factory named exactly after the MCP tool in langchain_askjapan.ask_japan or langchain_askjapan.maru. Each also has an aload_<tool_name> asynchronous factory. The resulting BaseTool supports both .invoke(args) and .ainvoke(args), as well as standard LangChain batching and ToolCalls.
toolkit.get_tool(name) / await toolkit.aget_tool(name) explicitly load one tool even if it is outside the toolkit's default subset. tool_names=None loads all tools on that endpoint, including side-effectful ones. tool_names is a selection mechanism, not an authorization boundary. Unknown or removed tools raise a clear error; the package never silently falls back to stale bundled schemas.
As a ToolCall
from langchain_askjapan.ask_japan import lookup_postcode
tool = lookup_postcode()
message = tool.invoke({
"type": "tool_call", "id": "postcode-1", "name": tool.name,
"args": {"postcode": "530-0001"},
})
print(message.content)
Within an agent
Illustrative composition only; not part of the no-cost test run. Supply your own configured tool-calling model. Model-provider charges are separate.
# Requires the separate langchain package and a configured model.
from langchain.agents import create_agent
from langchain_askjapan import AskJapanToolkit
# model = your_existing_tool_calling_model
# agent = create_agent(model=model, tools=AskJapanToolkit().get_tools())
Only pass explicitly approved tools to agents. Loading a tool does not authorize a purchase, service request, wallet pairing or payment request.
Pricing and authorization
The package itself is MIT-licensed. Hosted services follow the operator's pricing policy:
- Data that the operator obtains for free is provided free.
- Paid data is offered at market price through formal agency arrangements, plus a small handling fee for avoiding separate account registration. The exact handling fee has not been set; this package does not invent one.
- MARU human services are separately charged under the existing fixed-price schedule. Read
list_servicesfor the current schedule, limits and exclusions, and confirm the task/quote/payment separately before requesting fulfillment.
The six currently documented free public-data tools are individually listed below. This does not mean all current or future data products are free.
| Free public-data tool | Source |
|---|---|
search_company |
National Tax Agency corporate-number public data |
get_company_profile |
National Tax Agency corporate/invoice public data |
check_invoice |
National Tax Agency qualified-invoice publication data |
search_listed_companies |
Financial Services Agency EDINET code list |
lookup_postcode |
Japan Post postcode data |
search_address |
Japan Post postcode data |
list_services is a free read-only catalogue query, not a purchase. check_availability, get_request_status, quote_purchase, get_menu and check_open provide information; their returned quotes or menu prices are not charges for fulfilling a service. The examples only use list_services from this group.
request_service creates a service request. place_takeout_order creates an order even if payment happens later. maru_wallet_connect pairs an agent; maru_wallet_request_payment files a payment approval request. Do not use these as installation tests or without explicit authorization. maru_wallet_request_status requires a sensitive agent token; it is not exercised in public smoke tests. Wallet approval remains with the wallet owner; this library never approves payments.
Errors, timeouts and operation
Network, session and response-conversion failures raise JapanMCPError with English and Chinese guidance. The original exception is chained for debugging; do not share full traces containing credentials. MCP application errors retain the official adapter's ToolMessage(status="error") behavior. There are no automatic retries, because a timeout does not prove a side-effectful request was not accepted.
timeout=30.0 configures the default HTTP and stream-read timeouts. A custom connection takes precedence and must carry its own timeout settings. Sync calls block the caller; inside an existing event loop they run in a short-lived worker thread. Prefer the async API in async applications. Cancellation propagates normally on the async path.
API reference
AskJapanToolkit(**config)/MaruJapanHandsToolkit(**config):tool_names,timeout, optionalendpoint, optional official-adapterconnection..get_tools()/await .aget_tools(): discover and return selected LangChain tools..get_tool(name)/await .aget_tool(name): discover a single named tool.- Per-tool factories: see complete tool export inventory.
- Service documentation: Ask Japan and MARU Japan Hands.
Development and verification
python -m pip install -e '.[test]' build twine
python -m pytest tests/unit_tests
# Explicitly opt in: only postcode, company search and catalogue on production.
ASKJAPAN_LIVE_TESTS=1 python -m pytest tests/integration_tests
python examples/read_only.py
python -m build
python -m twine check dist/*
Offline tests use a real local stdio MCP server and captured tool definitions. Official langchain-tests==1.1.9 tool suites are applied to all 25 endpoint/tool combinations; see the local verification report for narrowly scoped incompatibility skips. No live write, order, service request, wallet operation or paid-model call is part of verification. Hosted implementation and third-party data are not licensed by this package's MIT license.
日本語
Ask Japan の公開データ検索と MARU Japan Hands を LangChain から使う Python パッケージです。ツール名・説明・引数は実際の MCP サーバーから取得します。現在の公開データ検索6種類とサービス一覧の参照は無料です。有料データは正式な代理条件・市場価格と少額の手数料、人的代行は既存料金表に従います。手数料の具体額は未定です。依頼・注文・ウォレット操作には別途明示的な承認が必要です。本版はローカルの公開準備版です。
中文
这是供 LangChain 使用的 Ask Japan/MARU Python 工具包,名称、说明和参数直接取自线上 MCP。当前六个公开数据查询和服务目录查询免费;不能概括成所有数据免费。收费数据按市场价、正式代理并加少量手续费,手续费具体金额尚未定;真人代办按现有价格另算。委托、下单、钱包操作必须另获明确授权。当前是本地待发布版本。
Metadata
Release files for langchain-askjapan 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| langchain_askjapan-0.1.0.tar.gz | 18.2 kB | With provenance | Details for langchain_askjapan-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| langchain_askjapan-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for langchain_askjapan-0.1.0-py3-none-any.whl |
Total release size: 29.6 kB
Release files / langchain_askjapan-0.1.0.tar.gz
| Download URL | langchain_askjapan-0.1.0.tar.gz |
|---|---|
| Size | 18.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
914ebc4b8e2cc5a6bf30bf9e809895ce7c274d6763cb5511e36971d0f8110848
|
|
BLAKE2b-256 checksum How to use checksums |
eb1e900e51f11fced9fdb931f0c4bb052d7c17111eafd1ce856db2188a69ac9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / langchain_askjapan-0.1.0-py3-none-any.whl
| Download URL | langchain_askjapan-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
70ce30f8e10f25c3ef6c1f5d9c4b2a2aed79fe08b8d4d680c9c6bc19a209e3bf
|
|
BLAKE2b-256 checksum How to use checksums |
06391544b3414b64d494a5dc5533fdaf41b9a3ecf3fea9c00dbbe32628081d56
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for langchain-askjapan 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for langchain_askjapan-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.