Skip to main content

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_services for 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, optional endpoint, optional official-adapter connection.
  • .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)

Source distribution for langchain-askjapan 0.1.0
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)

Table of built distributions (wheels) for langchain-askjapan 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page