Keiri Files (Japanese receipt filer)

keiri-files-mcp（会计文件整理 MCP）

粘贴到 AI 中的导入提示词

请将以下文本原样粘贴到 AI（Claude Code／Codex／Gemini CLI 等可操作文件的 AI）中。

このリポジトリのREADMEとsrcを読んで、外部通信・削除・許可フォルダ外アクセスがないか要約してください。
問題なければ、私の環境（Claude Desktop／Claude Code／Codex 等）に合う導入手順を示し、私の承認を得てから実行してください。
許可フォルダには、レシート・請求書を置く専用のフォルダだけを指定してください。

---

这是一个本地 MCP 服务，可根据你的 AI 读取的内容，整理电脑中的收据、发票（PDF/图片）：

0. 将内容展示给 AI（read_file。JPG/PNG 为图片，PDF 为嵌入文本）
1. 复制（或重命名）为规范的文件名 YYYYMMDD_取引先_金額_書類種別.拡張子
2. 追加到台账 CSV（带 UTF-8 BOM，可直接用 Excel 打开）
3. 按日期、金额、交易对象搜索

• 不执行文字识别（OCR）。read_file 只会将图片或 PDF 中的文本原样交给 AI，由你的 AI 读取
• 不进行外部通信、不删除文件、不执行子进程。依赖项只有官方 MCP SDK 和 zod（SDK 内部依赖的 express 等程序包也会一并打包到 .mcpb 中，但本工具的代码不会使用它们，也不会启动用于通信的服务器）
• 不会在授权文件夹之外进行读写（也会拒绝通过 ../ 或符号链接逃逸）
• 涉及写入的工具需要通过 AI 客户端的确认界面（不过，根据客户端设置（例如自动批准），确认界面可能不会出现）

免责声明

• 这是用于整理文件名和清单的辅助工具，不保证满足《电子账簿保存法》的要求。
• 不提供税务判断（例如确定会计科目、判断是否可作为经费等）。读取结果和台账内容由使用者负责确认。
• 本软件按现状提供，作者不对使用本软件造成的损害承担责任（参见 LICENSE）。

工具

工具	内容	写入
scan_folder(subdir?, recursive?)	PDF/JPG/PNG/HEIC 文件列表（相对路径、大小、修改日期、是否已登记到台账）。最多 500 个文件。整理済み 不在扫描范围内。recursive 默认为 true	否
read_file(path)	返回 1 份凭证的内容。JPG/PNG → MCP image（base64）。PDF → 嵌入文本（见下文）。不支持 HEIC（会提示转换为 JPG）。图片大小上限约为 3.7 MB（base64 后为 5 MB）	否
propose_names(items[])	返回命名方案和格式错误（日付、金额、登记号码、文件类型），并生成 plan_id。同名文件会通过 _2 等后缀避免冲突。日期、交易对象、金额均相同的项目（同一请求内及台账中的现有行）会在 warnings 中标记为“可能重复”	否
apply_renames(plan_id, mode)	仅执行 plan_id 对应的方案。默认 copy 会复制到 整理済み；rename 会更改原文件名（不会覆盖文件）。记录到 整理済み/log.csv	是
ledger_append(entries[], include_quotes?)	追加到 整理済み/ledger.csv。如果凭证文件名重复，或凭证文件名不存在（整理済み 中没有，且 log.csv 中也没有 copy/rename 的目标记录），会发出警告并跳过追加。默认不追加报价单（使用 include_quotes: true 可追加）。追加送货单时会提示重复记账风险。日期、交易对象、金额均相同的行会在警告中标记为“可能重复”后追加	是（仅追加）
search_ledger(date_from?, date_to?, amount_min?, amount_max?, vendor?)	按组合条件搜索。返回件数、金额总计和匹配行	否

• items 中的每个元素：path、date（YYYY-MM-DD）、vendor、amount（整数，日元）、doc_type（收据／发票／报价单／送货单／其他）、invoice_no（可选，T＋13 位数字）
• 台账列：日期、收款方、科目、内容、金额、支付方式、是否有发票、登记号码、凭证文件名、业务比例（%）、文件类型、原始文件、登记日期
  • 是否有发票填写为“あり”或“なし”，业务比例填写为“50%”（在 Excel 中打开时会识别为 0.5 并以百分比显示。未指定时留空）。截至 v0.3.0 的“有”“无”行也可照常读取并用于重复判定
  • A〜J 列（日期〜业务比例）的排列也适用于粘贴到另售的台账 Excel 中。粘贴到台账 Excel 时，只复制 A〜J 列（日期〜业务比例），并作为值粘贴到“経費”工作表第 5 行及之后。不要粘贴 K 列及之后的列（文件类型、原始文件、登记日期）（台账 Excel 的 K 列是台账侧的公式）
• plan_id 仅保存在服务的内存中，重启后会消失。每个 plan_id 只能执行一次
• 提案生成后，如果原文件被修改或移动，则不会执行对应行
• 只检查登记号码的格式（T＋13 位数字），不确认其是否真实存在
• “可能重复”是在日期、交易对象、金额都相同时发出的警告（比较交易对象时忽略前后空格以及全角／半角差异）。这不是错误，是否停止由使用者和 AI 决定
• 报价单不是付款记录，因此 ledger_append 默认不追加，并会通过警告返回原因。若要录入台账，请指定 include_quotes: true。送货单可能与同一交易的发票或收据重复记账，因此追加后会返回提示
• 如果交易对象名称是 Windows 保留名称（CON、PRN、AUX、NUL、COM1〜9、LPT1〜9），会在名称前加上 _
• 使用 rename 模式整理的文件，只要仍存在于 整理済み/log.csv 记录的目标位置，就可以通过 ledger_append 追加（如果从记录位置移动或重命名，则会发出警告）

read_file 返回 PDF 的方式

• 对于可提取嵌入文本的 PDF（例如用电脑制作的发票），会以文本形式返回。 提取功能为不增加依赖项的简易实现（仅使用 node:zlib，支持 FlateDecode、ASCII85、ASCIIHex、ToUnicode 和对象流）。文本布局可能会错乱
• 对于没有文本的 PDF（例如只有扫描图像的 PDF）或加密 PDF，会通过 MCP resource（blob，application/pdf）返回 PDF 文件本身。 AI 客户端是否能显示 PDF 取决于客户端。如果无法显示，请先转换为 JPG/PNG 再读取（结果中会说明这一点）
• 不会缩小图片（因为不使用外部库）。超过上限（约 3.7 MB）的图片会报错。手机拍摄等较大的图片，请先缩小（或降低分辨率并重新保存）再读取

文件夹结构（示例）

<許可フォルダ>/
  受信/                 ← レシート・請求書を置く
  整理済み/             ← ツールが作る
    20261001_架空商事テスト株式会社_55000_請求書.pdf
    ledger.csv          ← 台帳
    log.csv             ← 実行ログ

使用流程（面向 AI 的操作步骤请参阅 SKILL.md）

1. 使用 scan_folder 生成文件列表
2. AI 打开各文件，读取日期、交易对象、金额、文件类型和登记号码（对不确定的项目询问使用者）
3. 使用 propose_names 生成命名方案，由使用者确认并批准
4. 使用 apply_renames 执行（默认复制）
5. 使用 ledger_append 追加到台账（科目、支付方式等由使用者决定）
6. 使用 search_ledger 确认

导入

要求：Node.js 20 或更高版本。

npm ci
npm run build
npm test

启动命令为 node dist/index.js <許可フォルダ> [<許可フォルダ2> ...]。也可以通过环境变量 KEIRI_ALLOWED_DIRS 指定（Windows 使用 ; 分隔，macOS/Linux 使用 : 分隔）。请将以下 <...> 替换为自己的绝对路径。Windows 路径也可以使用 / 作为分隔符。

Claude Desktop（.mcpb）

使用 GitHub Releases 中的 keiri-files-mcp-<版>.mcpb，或自行构建。

npm ci
npm run build
npm test
npm run pack

npm run pack（scripts/pack-mcpb.mjs）会将 dist、manifest.json、README 等文件复制到临时文件夹，只安装生产依赖，并创建 keiri-files-mcp-<版>.mcpb。不会包含开发依赖（如 typescript、用于制作测试用虚构凭证的 pdfkit 等）。

双击生成的 .mcpb（或将其拖到 Claude Desktop 的设置界面），然后选择允许访问的文件夹。v0.3.0 已在 Windows 版 Claude Desktop 上确认可以安装和运行（macOS 版尚未确认）。

Claude Code

claude mcp add keiri-files -- node <keiri-files-mcpの場所>/dist/index.js <許可フォルダ>

未经确认（命令格式基于官方文档）。

Codex（~/.codex/config.toml）

[mcp_servers.keiri-files]
command = "node"
args = ["<keiri-files-mcpの場所>/dist/index.js", "<許可フォルダ>"]

未经确认。

Gemini CLI（~/.gemini/settings.json）

{
  "mcpServers": {
    "keiri-files": {
      "command": "node",
      "args": ["<keiri-files-mcpの場所>/dist/index.js", "<許可フォルダ>"]
    }
  }
}

未经确认。

安全设计

• 将路径解析为实际路径后，再判断其是否位于允许的文件夹下
• 列出文件时不会跟随符号链接
• 复制不会覆盖现有文件（同名时使用 _2 等）。重命名也不会覆盖文件
• 台账 CSV 会在以 = + - @ 开头的字符串前加上 '，避免被 Excel 当作公式执行
• 源码仅包含 src/ 中的几个文件。可以让 AI 读取并检查

开发

• npm test：运行单元测试，并使用 SDK 的 MCP 客户端对 10 份虚构凭证进行集成测试（包括 v0.2 的 read_file、保留名称和台账存在性检查）
• node test/make_fixtures.mjs [日本語TTF] [欧文TTF]：重新生成 10 份测试用虚构凭证（日文收据图片 6 份、含文本 PDF 4 份，位于 test/fixtures/receipts）以及印刷内容 doc_texts.json。公司名称和收件人名称均为虚构，注册编号也是以 0 开头的虚构编号。pdfkit、pureimage、pngjs、jpeg-js 属于开发依赖（devDependencies），不会包含在 .mcpb 中

English（摘要）

一个本地 MCP 服务，可向你的 AI 展示收据／发票内容（read_file：JPG/PNG 以图片形式呈现，PDF 以嵌入文本或 PDF 资源形式呈现）；根据你自己的 AI 客户端从文档中读取的内容，将文件（PDF/JPG/PNG/HEIC）重命名／复制为 YYYYMMDD_vendor_amount_type.ext，并向兼容 Excel 的 CSV 台账追加行。无需 OCR，不访问网络，不删除文件；只会操作你允许访问的文件夹。它是用于整理文件名和清单的辅助工具，并不保证符合日本电子账簿保存法，也不会做出任何税务判断。许可证：MIT。