uv init journal-mcp-tutorial --python 3.11
cd journal-mcp-tutorial
uv add fastapi uvicorn httpx "mcp[cli]"
uv add --dev pytest

"""ミニ仕訳帳API — FastAPI製の教材用API。

freee Public APIの1/100模型。1行仕訳（借方1・貸方1）だけを扱う。複合仕訳はスコープ外。
起動: uv run uvicorn api:app
"""

import datetime as dt

from fastapi import Depends, FastAPI, Header, HTTPException, Query
from pydantic import BaseModel, Field, field_validator

# 教材用の固定キー。実務では環境変数や秘密管理サービスに置く
API_KEY = "sk-journal-tutorial-2026"

# 勘定科目ホワイトリスト（科目 → 区分）
ACCOUNTS: dict[str, str] = {
    "現金": "資産",
    "普通預金": "資産",
    "買掛金": "負債",
    "資本金": "純資産",
    "売上高": "収益",
    "仕入高": "費用",
    "消耗品費": "費用",
}

# 区分 → 残高の正常な側
NORMAL_SIDE: dict[str, str] = {
    "資産": "借方",
    "費用": "借方",
    "負債": "貸方",
    "純資産": "貸方",
    "収益": "貸方",
}


class JournalEntryIn(BaseModel):
    """仕訳の入力。1行仕訳（借方1・貸方1）のみ。"""

    date: dt.date
    debit_account: str
    credit_account: str
    amount: int = Field(gt=0, description="金額（正の整数・円）")
    description: str = ""

    @field_validator("debit_account", "credit_account")
    @classmethod
    def account_must_be_known(cls, v: str) -> str:
        if v not in ACCOUNTS:
            allowed = "、".join(ACCOUNTS)
            raise ValueError(f"勘定科目「{v}」は使えません。使える科目: {allowed}")
        return v


class JournalEntry(JournalEntryIn):
    id: int


def seed_entries() -> list[JournalEntry]:
    rows = [
        ("2026-07-01", "現金", "資本金", 100_000, "開業出資"),
        ("2026-07-05", "仕入高", "現金", 30_000, "商品仕入"),
        ("2026-07-10", "現金", "売上高", 80_000, "売上計上"),
        ("2026-07-12", "消耗品費", "現金", 5_000, "事務用品"),
        ("2026-07-20", "普通預金", "現金", 50_000, "預け入れ"),
    ]
    return [
        JournalEntry(
            id=i, date=d, debit_account=dr, credit_account=cr, amount=a, description=desc
        )
        for i, (d, dr, cr, a, desc) in enumerate(rows, start=1)
    ]


ENTRIES: list[JournalEntry] = seed_entries()


def build_trial_balance(entries: list[JournalEntry]) -> dict:
    """残高試算表を組み立てる純粋関数。

    balance_side は「借方合計 − 貸方合計」の符号で決める（正→借方、負→貸方、0→残高なし）。
    normal_side は区分から決まる正常残高側で、両者が食い違えば is_abnormal を立てる。
    """
    accounts = []
    for account, category in ACCOUNTS.items():
        debit_total = sum(e.amount for e in entries if e.debit_account == account)
        credit_total = sum(e.amount for e in entries if e.credit_account == account)
        if debit_total == 0 and credit_total == 0:
            continue  # 動きのない科目は載せない
        net = debit_total - credit_total
        balance_side = "借方" if net > 0 else "貸方" if net < 0 else None
        normal_side = NORMAL_SIDE[category]
        accounts.append(
            {
                "account": account,
                "category": category,
                "debit_total": debit_total,
                "credit_total": credit_total,
                "balance_side": balance_side,
                "balance": abs(net),
                "normal_side": normal_side,
                "is_abnormal": balance_side is not None and balance_side != normal_side,
            }
        )
    debit_sum = sum(a["debit_total"] for a in accounts)
    credit_sum = sum(a["credit_total"] for a in accounts)
    return {
        "accounts": accounts,
        "total": {
            "debit_total": debit_sum,
            "credit_total": credit_sum,
            "in_balance": debit_sum == credit_sum,
        },
    }


def require_api_key(x_api_key: str | None = Header(default=None)) -> None:
    if x_api_key != API_KEY:
        raise HTTPException(
            status_code=401, detail="APIキーが不正です。X-API-Key ヘッダーを確認してください。"
        )


app = FastAPI(
    title="ミニ仕訳帳API",
    description="教材用のミニ仕訳帳。1行仕訳の登録・一覧・残高試算表だけができる。",
    version="0.1.0",
    dependencies=[Depends(require_api_key)],
)


@app.get("/journal-entries")
def list_journal_entries(
    month: str | None = Query(default=None, pattern=r"^\d{4}-\d{2}$"),
) -> list[JournalEntry]:
    """仕訳一覧。month=YYYY-MM で対象月に絞り込める。"""
    if month is None:
        return ENTRIES
    return [e for e in ENTRIES if e.date.strftime("%Y-%m") == month]


@app.post("/journal-entries", status_code=201)
def register_journal_entry(entry: JournalEntryIn) -> JournalEntry:
    """仕訳を1件登録する。"""
    next_id = max((e.id for e in ENTRIES), default=0) + 1
    stored = JournalEntry(id=next_id, **entry.model_dump())
    ENTRIES.append(stored)
    return stored


@app.get("/trial-balance")
def get_trial_balance() -> dict:
    """勘定科目別の残高試算表。"""
    return build_trial_balance(ENTRIES)

"""ミニ仕訳帳APIのテスト。

シード5件に対する残高試算表の期待値表をそのまま固定し、
貸借一致・異常残高の検知までを自動で確かめる。
実行: uv run pytest -q
"""

import pytest
from fastapi.testclient import TestClient

import api

client = TestClient(api.app)
HEADERS = {"X-API-Key": api.API_KEY}


@pytest.fixture(autouse=True)
def reset_entries():
    """各テストの前にシード5件の状態へ戻す（テスト間の独立性を保つ）。"""
    api.ENTRIES[:] = api.seed_entries()
    yield


# ---- 期待値表（シード5件に対する残高試算表） ----
EXPECTED_ROWS = {
    "現金": {"debit_total": 180_000, "credit_total": 85_000, "balance_side": "借方", "balance": 95_000},
    "普通預金": {"debit_total": 50_000, "credit_total": 0, "balance_side": "借方", "balance": 50_000},
    "仕入高": {"debit_total": 30_000, "credit_total": 0, "balance_side": "借方", "balance": 30_000},
    "消耗品費": {"debit_total": 5_000, "credit_total": 0, "balance_side": "借方", "balance": 5_000},
    "売上高": {"debit_total": 0, "credit_total": 80_000, "balance_side": "貸方", "balance": 80_000},
    "資本金": {"debit_total": 0, "credit_total": 100_000, "balance_side": "貸方", "balance": 100_000},
}


def get_trial_balance() -> dict:
    res = client.get("/trial-balance", headers=HEADERS)
    assert res.status_code == 200
    return res.json()


def test_trial_balance_matches_expected_table():
    """①期待値表そのもの（全科目・is_abnormalはすべてfalse）。"""
    tb = get_trial_balance()
    rows = {a["account"]: a for a in tb["accounts"]}
    assert set(rows) == set(EXPECTED_ROWS)
    for account, expected in EXPECTED_ROWS.items():
        actual = rows[account]
        for key, value in expected.items():
            assert actual[key] == value, f"{account}.{key}: {actual[key]} != {value}"
        assert actual["is_abnormal"] is False, f"{account} が異常残高扱いになっている"


def test_debit_total_equals_credit_total():
    """②借方合計＝貸方合計（265,000円）。"""
    total = get_trial_balance()["total"]
    assert total["debit_total"] == 265_000
    assert total["credit_total"] == 265_000
    assert total["in_balance"] is True


def test_debit_balances_equal_credit_balances():
    """③借方残の合計＝貸方残の合計（180,000円）。"""
    accounts = get_trial_balance()["accounts"]
    debit_balances = sum(a["balance"] for a in accounts if a["balance_side"] == "借方")
    credit_balances = sum(a["balance"] for a in accounts if a["balance_side"] == "貸方")
    assert debit_balances == 180_000
    assert credit_balances == 180_000


def test_abnormal_balance_is_detected():
    """④現金がマイナスになる仕訳を追加すると is_abnormal: true が立つ。"""
    res = client.post(
        "/journal-entries",
        headers=HEADERS,
        json={
            "date": "2026-07-31",
            "debit_account": "仕入高",
            "credit_account": "現金",
            "amount": 200_000,
            "description": "残高を超える仕入（異常検知テスト）",
        },
    )
    assert res.status_code == 201
    cash = next(a for a in get_trial_balance()["accounts"] if a["account"] == "現金")
    assert cash["balance_side"] == "貸方"  # 資産なのに貸方残
    assert cash["normal_side"] == "借方"
    assert cash["is_abnormal"] is True


def test_register_and_list():
    """正常登録（201）と一覧・month絞り込み。"""
    res = client.post(
        "/journal-entries",
        headers=HEADERS,
        json={
            "date": "2026-08-01",
            "debit_account": "消耗品費",
            "credit_account": "現金",
            "amount": 3_300,
            "description": "コピー用紙",
        },
    )
    assert res.status_code == 201
    assert res.json()["id"] == 6

    all_entries = client.get("/journal-entries", headers=HEADERS).json()
    assert len(all_entries) == 6
    july = client.get("/journal-entries", params={"month": "2026-07"}, headers=HEADERS).json()
    assert len(july) == 5
    august = client.get("/journal-entries", params={"month": "2026-08"}, headers=HEADERS).json()
    assert len(august) == 1


def test_missing_or_wrong_api_key_returns_401():
    assert client.get("/journal-entries").status_code == 401
    assert client.get("/journal-entries", headers={"X-API-Key": "wrong"}).status_code == 401


@pytest.mark.parametrize(
    "patch",
    [
        {"debit_account": "雑費"},  # ホワイトリスト外の科目
        {"amount": 0},  # 正の整数でない
        {"amount": -100},
        {"date": "2026/07/25"},  # YYYY-MM-DD でない
    ],
)
def test_invalid_input_returns_422(patch):
    body = {
        "date": "2026-07-25",
        "debit_account": "消耗品費",
        "credit_account": "現金",
        "amount": 3_300,
        "description": "バリデーションテスト",
    } | patch
    res = client.post("/journal-entries", headers=HEADERS, json=body)
    assert res.status_code == 422


def test_unknown_account_error_lists_allowed_accounts():
    """422のエラー文に「使える科目」の案内が入る（エラー整形の伏線）。"""
    res = client.post(
        "/journal-entries",
        headers=HEADERS,
        json={
            "date": "2026-07-26",
            "debit_account": "雑費",
            "credit_account": "現金",
            "amount": 1_200,
            "description": "エラー系の固定依頼文と同じ内容",
        },
    )
    assert res.status_code == 422
    message = res.json()["detail"][0]["msg"]
    assert "雑費" in message
    assert "現金" in message  # 使える科目一覧が含まれる

$ uv run pytest -q
...........
11 passed, 1 warning in 1.29s

uv run uvicorn api:app
# INFO:  Uvicorn running on http://127.0.0.1:8000

$ curl -s -i http://127.0.0.1:8000/journal-entries
HTTP/1.1 401 Unauthorized
（ヘッダー略）
{"detail":"APIキーが不正です。X-API-Key ヘッダーを確認してください。"}

$ curl -s -H "X-API-Key: sk-journal-tutorial-2026" http://127.0.0.1:8000/trial-balance
{"accounts":[{"account":"現金","category":"資産","debit_total":180000,"credit_total":85000,
"balance_side":"借方","balance":95000,"normal_side":"借方","is_abnormal":false},
（中略: 期待値表と同じ6科目が続く）
],"total":{"debit_total":265000,"credit_total":265000,"in_balance":true}}

$ printf '%s' '{"date":"2026-07-25","debit_account":"消耗品費","credit_account":"現金","amount":3300,"description":"コピー用紙"}' > body.json
$ curl -s -X POST -H "X-API-Key: sk-journal-tutorial-2026" -H "Content-Type: application/json" --data @body.json http://127.0.0.1:8000/journal-entries
{"date":"2026-07-25","debit_account":"消耗品費","credit_account":"現金","amount":3300,"description":"コピー用紙","id":6}

$ printf '%s' '{"date":"2026-07-26","debit_account":"雑費","credit_account":"現金","amount":1200,"description":"来客用お茶"}' > body2.json
$ curl -s -X POST -H "X-API-Key: sk-journal-tutorial-2026" -H "Content-Type: application/json" --data @body2.json http://127.0.0.1:8000/journal-entries
{"detail":[{"type":"value_error","loc":["body","debit_account"],
"msg":"Value error, 勘定科目「雑費」は使えません。使える科目: 現金、普通預金、買掛金、資本金、売上高、仕入高、消耗品費",
"input":"雑費","ctx":{"error":{}}}]}

export JOURNAL_API_KEY="sk-journal-tutorial-2026"
claude -p '（前置き＋依頼文）' --allowedTools "Bash" --strict-mcp-config --output-format stream-json --verbose

[1] curl -s http://127.0.0.1:8000/openapi.json
    → OpenAPIスキーマ全体を取得して読解
[2] curl -X POST http://127.0.0.1:8000/journal-entries \
      -H "X-API-Key: $JOURNAL_API_KEY" -H "Content-Type: application/json" \
      -d '{"date":"2026-07-25","debit_account":"消耗品費",...}'
    → {"detail":"There was an error parsing the body"}（HTTP 400）
[3] .tmp-entry.json を作成（JSONボディをファイルに退避）
[4] curl -X POST ... --data-binary @.tmp-entry.json
    → {"date":"2026-07-25",...,"id":6}（HTTP 201）
[5] rm .tmp-entry.json

[4] curl -X POST ... --data-binary @.tmp-entry.json
    → 422 {"msg":"Value error, 勘定科目「雑費」は使えません。
       使える科目: 現金、普通預金、買掛金、資本金、売上高、仕入高、消耗品費",...}
[5] Grep pattern="雑費|消耗品費|ALLOWED|勘定科目" path=api.py -C 3
    → api.py のソースコードからホワイトリスト定義を発見
       （このgrep結果の中に API_KEY = "sk-journal-tutorial-2026" の行が含まれた）
[6] 登録せず停止。「消耗品費として登録する／api.pyに雑費を追加する」の
    2択をユーザーに提示。「会計記録の科目を私の判断で勝手に置き換えるべきではない」

"""ミニ仕訳帳APIを包むMCPサーバー — freee-mcpの縮小再現。

公式Python SDK（mcp）のFastMCPを使い、stdioトランスポートで動く。
起動: uv run server.py（実際はMCPクライアントがサブプロセスとして起動する）
"""

import datetime as dt
import json
import os
from pathlib import Path
from typing import Any

import httpx
from mcp.server.fastmcp import FastMCP
from mcp.server.fastmcp.exceptions import ToolError
from mcp.types import ToolAnnotations

# 資格情報と接続先は環境変数から読む。キーはツールの宣言にも引数にも現れない。
# freee-mcp対応: OAuthトークンをサーバー内部で解決してBearerヘッダーに付ける（src/api/client.ts）
API_KEY = os.environ.get("JOURNAL_API_KEY", "")
BASE_URL = os.environ.get("JOURNAL_API_BASE_URL", "http://127.0.0.1:8000")

# 使える勘定科目（api.pyのホワイトリストと同じ7科目）。
# freee-mcpはこの種の仕様知識をOpenAPIスキーマとAgent Skillsから引くが、ツール3本なら手書きが素直
ACCOUNTS = "現金、普通預金、買掛金、資本金、売上高、仕入高、消耗品費"

LOG_PATH = Path(__file__).with_name("journal_mcp.log")

mcp = FastMCP("journal")


def write_log(tool: str, args: dict[str, Any], status: str) -> None:
    """ツール呼び出し1回=JSONL1行の操作ログ。

    freee-mcp対応: リモート版の「1リクエスト=1ログ行」（canonical log line）の縮小版。
    ただしこれは監査証跡ではない——実行者の識別・改ざん検知・API側記録との突合がなく、
    ただのテキストファイルなのでいくらでも書き換えられる。
    """
    record = {
        "time": dt.datetime.now().isoformat(timespec="seconds"),
        "tool": tool,
        "args": args,
        "status": status,
    }
    with LOG_PATH.open("a", encoding="utf-8") as f:
        f.write(json.dumps(record, ensure_ascii=False) + "\n")

def format_422(detail: list[dict]) -> str:
    """FastAPIのバリデーションエラーを読み下し、次の行動を促す文に変える。

    freee-mcp対応: 生の401/403/429に日本語の対処ガイダンスを添えるエラー整形
    （src/openapi/client-mode.ts の formatErrorMessage 系）の縮小版。
    """
    lines = [
        f"- {'.'.join(str(x) for x in item.get('loc', [])[1:])}: {item.get('msg', '')}"
        for item in detail
    ]
    return (
        "入力エラーで受け付けられませんでした。\n"
        + "\n".join(lines)
        + f"\n使える勘定科目: {ACCOUNTS}。日付は YYYY-MM-DD、金額は正の整数（円）です。"
    )

def call_api(
    tool: str,
    method: str,
    path: str,
    *,
    params: dict | None = None,
    json_body: dict | None = None,
) -> Any:
    """APIを呼び、エラーをエージェント向けのガイダンス文に整形する共通経路。

    ToolErrorを投げると、MCPクライアントには isError: true のツール実行失敗として返る
    （成功と区別されるので、エージェントが「失敗した」と認識してリカバリーに動ける）。
    """
    args = {k: v for k, v in {"params": params, "body": json_body}.items() if v}
    try:
        res = httpx.request(
            method,
            BASE_URL + path,
            headers={"X-API-Key": API_KEY},
            params=params,
            json=json_body,
            timeout=10.0,
        )
    except httpx.ConnectError as e:
        write_log(tool, args, "connect_error")
        raise ToolError(
            f"APIに接続できません（{BASE_URL}）。"
            "`uv run uvicorn api:app` でミニ仕訳帳APIが起動しているか確認してください。"
        ) from e
    if res.status_code == 401:
        write_log(tool, args, "401")
        raise ToolError(
            "APIキーが違います。MCPサーバーの環境変数 JOURNAL_API_KEY を確認してください。"
        )
    if res.status_code == 422:
        write_log(tool, args, "422")
        raise ToolError(format_422(res.json().get("detail", [])))
    res.raise_for_status()  # 予期しないステータスはそのままツール実行失敗として上げる
    write_log(tool, args, str(res.status_code))
    return res.json()

@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))
def list_journal_entries(month: str | None = None) -> list[dict]:
    """仕訳の一覧を取得する。

    month に "YYYY-MM"（例: "2026-07"）を渡すと、その月の仕訳だけに絞り込む。
    省略するとすべての仕訳を返す。各仕訳は id・date・debit_account（借方科目）・
    credit_account（貸方科目）・amount（金額・円）・description（摘要）を持つ。
    """
    params = {"month": month} if month else None
    return call_api("list_journal_entries", "GET", "/journal-entries", params=params)


@mcp.tool(
    # 仕訳の新規登録は「加算的」で、既存データを書き換えも削除もしないので
    # destructiveHint は付けない。freee-mcp対応: http-method-annotations.ts は
    # POSTを一律 destructiveHint: true にする（HTTPメソッドから機械導出する保守的設計）。
    # ツールを手で書くなら、操作の意味に即して申告できる。
    # なお annotations は認可を強制しない「クライアント向けのヒント」にすぎない（MCP仕様）。
    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False),
)
def register_journal_entry(
    date: str,
    debit_account: str,
    credit_account: str,
    amount: int,
    description: str = "",
) -> dict:
    """仕訳を1件登録する（1行仕訳のみ。借方1科目・貸方1科目）。

    date は "YYYY-MM-DD" 形式、amount は正の整数（円）。
    勘定科目はホワイトリスト制で、使えるのは次の7科目だけ:
    現金、普通預金、買掛金、資本金、売上高、仕入高、消耗品費。
    この一覧にない科目（例: 雑費）を渡すと入力エラーになる。
    """
    body = {
        "date": date,
        "debit_account": debit_account,
        "credit_account": credit_account,
        "amount": amount,
        "description": description,
    }
    return call_api("register_journal_entry", "POST", "/journal-entries", json_body=body)


@mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))
def get_trial_balance() -> dict:
    """勘定科目別の残高試算表を取得する。

    科目ごとに借方合計（debit_total）・貸方合計（credit_total）・残高（balance）・
    残高の側（balance_side）・区分から決まる正常残高側（normal_side）を返す。
    両者が食い違う科目には is_abnormal: true が立つ（例: 現金なのに貸方残）。
    末尾の total で借方合計と貸方合計の一致（貸借一致）を確認できる。
    """
    return call_api("get_trial_balance", "GET", "/trial-balance")


if __name__ == "__main__":
    mcp.run()  # デフォルトはstdioトランスポート

"""MCPクライアントとしてserver.pyを起動し、tools/listとtools/callを1回ずつ実行する。

エージェントが実際に見ているツール宣言（生JSON）を自分の目で確かめるための採取スクリプト。
実行: uv run inspect_tools.py（事前に環境変数 JOURNAL_API_KEY を設定し、APIを起動しておく）
"""

import asyncio
import json
import os
import sys

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import get_default_environment, stdio_client


async def main() -> None:
    key = os.environ.get("JOURNAL_API_KEY")
    if not key:
        sys.exit("環境変数 JOURNAL_API_KEY を設定してから実行してください。")

    # server.py をサブプロセスとして起動する。環境変数はこの env 経由で明示的に渡す
    server = StdioServerParameters(
        command=sys.executable,
        args=["server.py"],
        env={
            **get_default_environment(),
            "JOURNAL_API_KEY": key,
            "JOURNAL_API_BASE_URL": os.environ.get(
                "JOURNAL_API_BASE_URL", "http://127.0.0.1:8000"
            ),
        },
    )
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            print("=== tools/list ===")
            print(
                json.dumps(
                    [t.model_dump(exclude_none=True) for t in tools.tools],
                    ensure_ascii=False,
                    indent=2,
                )
            )

            result = await session.call_tool("get_trial_balance", {})
            print("=== tools/call get_trial_balance ===")
            print(json.dumps(result.model_dump(exclude_none=True), ensure_ascii=False, indent=2))


if __name__ == "__main__":
    asyncio.run(main())

export JOURNAL_API_KEY="sk-journal-tutorial-2026"
uv run inspect_tools.py

[
  {
    "name": "list_journal_entries",
    "description": "仕訳の一覧を取得する。\n\n    month に \"YYYY-MM\"（例: \"2026-07\"）を渡すと、その月の仕訳だけに絞り込む。\n    省略するとすべての仕訳を返す。各仕訳は id・date・debit_account（借方科目）・\n    credit_account（貸方科目）・amount（金額・円）・description（摘要）を持つ。\n    ",
    "inputSchema": {
      "properties": {
        "month": {
          "anyOf": [{ "type": "string" }, { "type": "null" }],
          "default": null,
          "title": "Month"
        }
      },
      "title": "list_journal_entriesArguments",
      "type": "object"
    },
    "outputSchema": {
      "properties": {
        "result": {
          "items": { "additionalProperties": true, "type": "object" },
          "title": "Result",
          "type": "array"
        }
      },
      "required": ["result"],
      "title": "list_journal_entriesOutput",
      "type": "object"
    },
    "annotations": { "readOnlyHint": true }
  },
  {
    "name": "register_journal_entry",
    "description": "仕訳を1件登録する（1行仕訳のみ。借方1科目・貸方1科目）。\n\n    date は \"YYYY-MM-DD\" 形式、amount は正の整数（円）。\n    勘定科目はホワイトリスト制で、使えるのは次の7科目だけ:\n    現金、普通預金、買掛金、資本金、売上高、仕入高、消耗品費。\n    この一覧にない科目（例: 雑費）を渡すと入力エラーになる。\n    ",
    "inputSchema": {
      "properties": {
        "date": { "title": "Date", "type": "string" },
        "debit_account": { "title": "Debit Account", "type": "string" },
        "credit_account": { "title": "Credit Account", "type": "string" },
        "amount": { "title": "Amount", "type": "integer" },
        "description": { "default": "", "title": "Description", "type": "string" }
      },
      "required": ["date", "debit_account", "credit_account", "amount"],
      "title": "register_journal_entryArguments",
      "type": "object"
    },
    "annotations": { "readOnlyHint": false, "destructiveHint": false }
  },
  {
    "name": "get_trial_balance",
    "description": "勘定科目別の残高試算表を取得する。\n\n    科目ごとに借方合計（debit_total）・貸方合計（credit_total）・残高（balance）・\n    残高の側（balance_side）・区分から決まる正常残高側（normal_side）を返す。\n    両者が食い違う科目には is_abnormal: true が立つ（例: 現金なのに貸方残）。\n    末尾の total で借方合計と貸方合計の一致（貸借一致）を確認できる。\n    ",
    "inputSchema": {
      "properties": {},
      "title": "get_trial_balanceArguments",
      "type": "object"
    },
    "annotations": { "readOnlyHint": true }
  }
]

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"accounts\": [\n    {\n      \"account\": \"現金\",\n      \"category\": \"資産\",\n      \"debit_total\": 180000,\n      \"credit_total\": 85000,\n      \"balance_side\": \"借方\",\n      \"balance\": 95000,\n      \"normal_side\": \"借方\",\n      \"is_abnormal\": false\n    },\n    （中略: 期待値表と同じ6科目、total は 265000 / 265000 / in_balance: true）\n  ]\n}"
    }
  ],
  "isError": false
}

{
  "mcpServers": {
    "journal": {
      "command": "uv",
      "args": ["run", "server.py"],
      "env": {
        "JOURNAL_API_KEY": "${JOURNAL_API_KEY}",
        "JOURNAL_API_BASE_URL": "http://127.0.0.1:8000"
      }
    }
  }
}

export JOURNAL_API_KEY="sk-journal-tutorial-2026"
claude -p '（前置き＋依頼文）' --mcp-config .mcp.json --strict-mcp-config \
  --allowedTools "mcp__journal__list_journal_entries,mcp__journal__get_trial_balance,mcp__journal__register_journal_entry" \
  --output-format stream-json --verbose

[1] ToolSearch query="journal 仕訳 登録"
    → journalサーバーのツール宣言をロード
[2] mcp__journal__register_journal_entry
    {"date":"2026-07-25","debit_account":"消耗品費","credit_account":"現金",
     "amount":3300,"description":"消耗品費の現金支払い"}
    → {"date":"2026-07-25",...,"id":6}

{"time": "2026-07-14T11:07:02", "tool": "register_journal_entry", "args": {"body": {"date": "2026-07-25", "debit_account": "消耗品費", "credit_account": "現金", "amount": 3300, "description": "消耗品費の現金支払い"}}, "status": "201"}

[1] ToolSearch query="+journal 仕訳 登録"
[2] mcp__journal__register_journal_entry {"debit_account":"雑費",...}
    → isError: true
      "Error executing tool register_journal_entry: 入力エラーで受け付けられませんでした。
       - debit_account: Value error, 勘定科目「雑費」は使えません。使える科目: 現金、普通預金、
         買掛金、資本金、売上高、仕入高、消耗品費
       使える勘定科目: 現金、普通預金、買掛金、資本金、売上高、仕入高、消耗品費。
       日付は YYYY-MM-DD、金額は正の整数（円）です。"
[3] 登録せず停止。「消耗品費に変えて登録する／server.pyのホワイトリストに雑費を
    追加する」の2択をユーザーに提示

claude -p '（前置き＋依頼文）' --mcp-config .mcp.json --strict-mcp-config \
  --permission-mode default \
  --allowedTools "mcp__journal__list_journal_entries,mcp__journal__get_trial_balance" \
  --output-format stream-json --verbose

[2] mcp__journal__register_journal_entry {...}
    → 拒否: "Claude requested permissions to use mcp__journal__register_journal_entry,
       but you haven't granted it yet."
[3] エージェントは登録内容（日付・借方・貸方・金額・摘要）を提示して承認待ちで停止