Skip to main content
Glama

Madoguchi 窓口

ci TypeScript MCP Locks Benchmark License: MIT

A read-only MCP server that gives AI agents governed access to CRM data, a commercial calendar and an SEO auditor, and a benchmark that scores those agents against a known answer key.

Madoguchi is the service window of a Japanese office: one counter, clear rules, nothing goes behind it. Here the agent is on one side; on the other side are three tools I built in three languages:

  • Tsunagu (Python): a fictional cross-border CRM world (France, Japan, Taiwan), with the hidden truth of why every order happened;

  • Koyomi (Go): the commercial calendar of Japan, Taiwan, Korea and France, computed from astronomy;

  • Kensa (Rust): a multilingual and AI-search SEO auditor.

日本語 · 繁體中文 · Français

Why

Connecting an agent to company data raises two questions before any demo: what is the worst it can do, and how often is it right. Madoguchi answers both with tests, not promises.

  • It hands the agent a governed copy: no answer key, no names, pseudonymised identifiers, read-only, no file or network access, bounded queries, every call logged. madoguchi check tries 23 ways around these locks and fails if one works.

  • It ships a benchmark whose answers are computed independently of the server. A script that uses only the tools must score 100 % on every push, so the tools are proven right; then any model can be measured on the same questions.

flowchart LR
    A[AI agent<br/>Claude Desktop, Claude Code,<br/>a local model...] <-->|MCP, stdio| M
    subgraph M[Madoguchi]
      T[tools<br/>query_metric · run_sql · campaign_lift<br/>calendar_events · lunar_date · seo_audit]
      L[locks<br/>guard · read-only · no I/O · limits · audit log]
    end
    M --> G[(governed copy<br/>ref + raw_* + marts<br/>no truth, no names)]
    S[(Tsunagu world<br/>DuckDB)] -->|built at start| G
    M --> K[koyomi<br/>Go binary]
    M --> E[kensa<br/>Rust binary]
    B[benchmark<br/>27 questions] -->|answer key| S
    B <-->|MCP| M

Related MCP server: RecoSearch

Quick start

Node 20.10 or later, Python 3.11 or later for Tsunagu.

git clone https://github.com/thibaultbordrie-cloud/madoguchi.git && cd madoguchi
npm ci && npm run build

python -m pip install "tsunagu @ git+https://github.com/thibaultbordrie-cloud/tsunagu"
tsunagu generate --out data/tsunagu.duckdb          # the two-year world, about 20 s

node dist/src/cli.js check --tsunagu data/tsunagu.duckdb
npm link                                            # optional: a `madoguchi` command

Koyomi and Kensa are optional: download them from their releases (Koyomi, Kensa) and point to them in a configuration file such as madoguchi.example.json.

Claude Desktop: add to claude_desktop_config.json, with absolute paths:

{
  "mcpServers": {
    "madoguchi": {
      "command": "node",
      "args": ["/path/to/madoguchi/dist/src/cli.js", "serve", "--config", "/path/to/madoguchi.json"]
    }
  }
}

Claude Code: claude mcp add madoguchi -- node /path/to/madoguchi/dist/src/cli.js serve --config /path/to/madoguchi.json

Then ask, for example: "Did our French e-mails really sell anything over the last two years?"

Tools

Tool

What it does

describe_data

period, markets, tables, the metric catalogue, what was removed for privacy

query_metric

12 metrics with one definition each (orders, buyers, gross revenue in EUR, average basket, last-click share, open rate with and without Apple MPP, click rate…), split by market, month, channel, theme or UTM source

run_sql

one guarded DuckDB SELECT, at most 200 rows, 15 s

campaign_lift

recipients against holdout groups: uplift with a 95% interval, incremental orders, and what last-click credits, for contrast

calendar_events, lunar_date

Koyomi: 春節, 설날, 中秋, 節分, 土用の丑の日, soldes… for any date range

seo_audit

Kensa on an allowed host only

A resource (madoguchi://catalogue) and a prompt (weekly_brief) come with them.

The tool that matters most is campaign_lift. On the two-year world, for French e-mails:

{
  "recipients": 907147, "holdouts": 48097,
  "uplift_pts": 0.042, "uplift_ci95_pts": [-0.022, 0.106],
  "incremental_orders_ci95": [-197.6, 962.7],
  "last_click_orders": 755,
  "verdict": "The holdout cannot tell the effect from zero: the 95% interval goes from -198 to 963 incremental orders. Last-click credits 755 orders, which says nothing about cause."
}

The simulation's hidden answer is 488 orders: inside the interval, and far from the 755 that last-click attribution would report. An agent that answers "755" is confident and wrong; the benchmark catches it.

Security

Seven locks, each tested on every push. Details and limits: docs/SECURITY_MODEL.md.

  1. No answer key: the truth schema is never copied.

  2. No personal data: names dropped; e-mail addresses and LINE ids replaced by salted pseudonyms, new at every start. A new column that looks personal stops the build until it has a rule.

  3. One SELECT only: the agent's SQL is parsed by DuckDB itself (json_serialize_sql) before it runs.

  4. Read-only, no I/O: even a SELECT cannot read a file, attach a database, load an extension or reach the network; the configuration is locked.

  5. Bounds: time limit, row limit, two threads.

  6. No injection: tool arguments are checked against fixed lists and bound as parameters.

  7. A trace: every call logged, without its results.

$ madoguchi check --tsunagu data/tsunagu.duckdb
ok    no truth schema in the governed copy
ok    no e-mail address in any text column  (0 found)
ok    guard: DDL (CREATE TABLE)  (only SELECT statements are allowed)
ok    engine: read a file with read_csv  (Permission Error: ... file system operations are disabled)
ok    engine: re-enable file access  (Invalid Input Error: Cannot change configuration option ...)
ok    a runaway query is stopped by the time limit  (the query was stopped after 2 s)
...
23/23 locks hold

Benchmark

27 questions in six categories (KPIs, comparisons, causal effects, privacy, calendar, SEO), answered from sources independent of the server: plain SQL on the raw tables, the simulation's hidden truth, the holidays package, Kensa's answer key. Details: docs/EVAL.md.

madoguchi eval --config madoguchi.json --runner oracle                    # the tools alone: 27/27 with Koyomi and Kensa
madoguchi eval --config madoguchi.json --runner openai --model qwen3:8b   # a local model through Ollama
madoguchi eval --config madoguchi.json --runner replay --answers a.jsonl  # any agent, scored by hand

Scoring is strict where it matters: an interval must contain the truth and stay narrow; UNKNOWN is right only when the data cannot answer (personal data, what LINE caused), and wrong everywhere else.

Develop

npm run build
MADOGUCHI_TEST_DB=data/tiny.duckdb npm test     # tsunagu generate --scenario tiny --out data/tiny.duckdb
# optional: MADOGUCHI_TEST_KOYOMI=bin/koyomi MADOGUCHI_TEST_KENSA=bin/kensa

CI runs the tests on Linux, macOS and Windows, then downloads Koyomi and Kensa from their releases and runs the oracle on the two-year world. Three dependencies: the official MCP SDK, DuckDB and zod.

Limits

  • Fictional data only. The locks are designed for real data, but the project has only been run on Tsunagu.

  • A pseudonym is stable within a session, so an agent can follow one customer. Aggregate-only tools would be the next step for real customer data.

  • The benchmark is small (27 questions): enough to catch a broken tool or a careless agent, not to rank close models.

  • No model results are published: run your own; the numbers depend on the model and the machine.

日本語での概要

Madoguchi(窓口)は、AIエージェントにCRMデータ・商戦カレンダー・SEO監査ツールへの「安全な窓口」を提供する読み取り専用の MCP サーバーです(TypeScript)。エージェントが見るのは、正解データ(truth)と氏名を除き、メールアドレスと LINE ID を仮名化したコピーだけです。SQL は SELECT 1文のみ、ファイル・ネットワークへのアクセスは不可、時間と行数に上限があり、すべての呼び出しが記録されます。madoguchi check が 23 通りの突破方法を試し、すべて防がれることを確認します。さらに、サーバーとは独立に答えを計算した 27 問のベンチマークで、エージェントの正確さを測れます。ラストクリックの数字を「効果」と答えるエージェントは、ここで不正解になります。

中文簡介(繁體)

Madoguchi(窓口)是一個唯讀的 MCP 伺服器(TypeScript),讓 AI 代理安全地存取 CRM 資料、行銷行事曆與 SEO 稽核工具。代理只看得到一份受控的副本:沒有模擬的標準答案(truth)、沒有姓名,電子郵件與 LINE ID 都經過假名化;SQL 只能是一條 SELECT,不能讀檔案或連網,有時間與筆數上限,每次呼叫都有紀錄。madoguchi check 會嘗試 23 種繞過方式,確認全部被擋下。另附 27 題的評測,答案獨立於伺服器計算,用來衡量代理到底答對多少。把最終點擊歸因當成「成效」的代理,在這裡會被判錯。

En bref (français)

Madoguchi (窓口, « le guichet ») est un serveur MCP en lecture seule, écrit en TypeScript, qui donne à des agents IA un accès encadré à des données CRM, à un calendrier commercial et à un auditeur SEO. L'agent ne voit qu'une copie gouvernée : sans le corrigé de la simulation, sans noms, avec des e-mails et des identifiants LINE pseudonymisés ; une seule requête SELECT à la fois, aucun accès aux fichiers ni au réseau, des limites de temps et de lignes, et chaque appel est journalisé. madoguchi check tente 23 façons de contourner ces verrous et échoue si l'une passe. Un banc d'essai de 27 questions, dont les réponses sont calculées indépendamment du serveur, mesure la justesse des agents : celui qui présente le dernier clic comme un effet est compté faux.

License

MIT.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Secure MCP server for safe, read-only DB access by AI agents, with SQL guardrails, table allowlists, PII masking, and audit logs
      6
      52 npm
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A deterministic MCP server that governs read-only queries across multiple data sources, returning answers with full provenance (every row cited) or a typed refusal, ensuring LLM answers are traceable and contract-enforced.
      1
      Apache 2.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      A governed MCP server that enforces a trust layer between AI agents and databases, requiring sign-off on joins and metrics and producing auditable receipts for every query.
      -
    • A
      license
      A
      quality
      B
      maintenance
      This MCP server gives AI assistants over business data a provenance layer: every number in an answer traces back to specific records, auditable and tamper-evident. It enforces that the model never generates figures—only selects operations whose results are computed deterministically in SQL.
      6
      341 npm
      MIT