Maplith Bridge

为你的 Agent 打造的 Maplith

Maplith 会梳理公司各系统之间的关系，让任何 AI Agent 都能找到所需数据、了解要使用哪个键，以及每一步的可信程度。本仓库包含在你自己的环境中运行的开源部分，与你的 Agent 和数据相邻。一个产品，三个部分：

部分	功能	位置
Claude Code 和 Codex 插件	只需安装一次，即可在你的编码 Agent 中使用 Maplith：通过 MCP 提供托管地图（登录即可，无需粘贴任何内容）、用于本地文件夹的 Maplith Bridge，以及说明何时以及如何使用它们的技能。	plugins/maplith/
Maplith Bridge	以只读方式将数据库连接到 AI Agent，无需向任何人提供密码。	本页，从快速入门开始
Maplith Wake	通过你自己账户中的轻量级中继，在有任务需要处理时立即启动你自己的 Claude Agent。	wake-relay/

所有内容都包含在一个 npm 包 maplith 中，只需一条命令：maplith setup 即可在你的 Agent 中设置 Maplith，maplith bridge 则是 Maplith Bridge。

在你的 Agent 中设置 Maplith

没有账户？在登录时打开的浏览器窗口中创建账户，然后立即返回。接着，你的 Agent 会与你一起构建第一张地图。

只需一条命令，需要 Node.js 24 或更高版本。它会运行 Agent 自带的命令，不会在任何地方写入密钥：

npx --yes [email protected] setup claude
npx --yes [email protected] setup codex

也可以手动设置。 Claude Code：

/plugin marketplace add Maplith/agents
/plugin install maplith@maplith

然后运行 /mcp，选择 maplith 和 Authenticate。OpenAI Codex：

codex plugin marketplace add Maplith/agents
codex plugin add maplith@maplith
codex mcp login maplith

Codex 不会将你的环境传递给插件的服务端，因此如需通过 Bridge 与 Codex 共享文件夹，只需指定一次： npx --yes [email protected] setup codex --dir <folder>。

此处所有内容均采用 Apache-2.0 许可。

Maplith Bridge

以只读方式将数据库连接到 AI Agent，无需向任何人提供密码。

Bridge 在你自己的网络中运行。它通过 MCP（Model Context Protocol）共享一个包含数据文件的文件夹，并由你创建的令牌保护；它还可以使用仅具备读取权限的数据库角色，从 PostgreSQL 填充该文件夹。

• 端到端只读。 服务端没有写入方法，也不接受任何文件。提取器拒绝在权限超出读取范围的角色下运行。
• 密码由你保管。 数据库密码不会离开运行提取器的机器，而面向网络的服务端也不会持有该密码。
• 代码精简易读。 仅包含六个 TypeScript 文件：四个用于 Bridge，另外两个用于 maplith 命令及其 setup。服务端只依赖 Node.js 运行；提取器只有一个依赖，即固定版本的 PostgreSQL 客户端。

任何 MCP 客户端都可以使用它：Claude Code、Codex、Claude Desktop 或你自己的 Agent。它与 Maplith 搭配效果最佳，后者会读取该文件夹，以梳理各系统之间的关系。

快速开始

你需要 Node.js 24 或更高版本。

npx --yes [email protected] bridge rotate-token
npx --yes [email protected] bridge serve --dir ./exports

第一个命令会将随机令牌写入 maplith-bridge.token，只有你可以读取。第二个命令会在本机将 ./exports 中的文件提供在 http://127.0.0.1:8787/mcp。将任何 MCP 客户端指向该地址，并设置请求头 Authorization: Bearer <the token>。使用 Claude Code 时：

claude mcp add --transport http bridge http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer $(cat maplith-bridge.token)"

要以只读角色从 PostgreSQL 填充文件夹：

PGHOST=db.example.com PGDATABASE=shop PGUSER=bridge_reader \
  npx --yes [email protected] bridge extract postgres --out ./exports --check

--check 会验证角色，但不会写入任何内容。再次运行时去掉 --check，即可为每个表写入一个 CSV 文件。

除了各文件夹中的 CSV 文件，提取器还会写入 maplith-schema.json，服务器会像共享其他文件一样共享它：对每个表，记录其文件、带有 PostgreSQL 属性编号和类型的列、键以及估算行数。它只包含名称和编号，从不包含值；数据库仅通过其身份的摘要标识（见下文）。读者可以据此判断，重命名的列仍是同一列（其属性编号保持不变），而删除后重新添加的列则是新列（它会获得新的编号）。

恢复操作会保留原有的关系 ID 和属性编号，而后续的 ADD COLUMN 可能会重复使用某个编号，该编号在之后的状态中已分配给另一列。因此，摘要由服务器系统标识符和时间线、统计信息最近一次重置的时间、数据库的 ID 和名称，以及提取器保存在文件夹中的一个纪元组成。如果提取器发现数据库的历史记录并非从上次运行时延续而来，摘要就会改变：例如换了服务器或数据库、出现新的时间线（时间点恢复或提升）、服务器统计信息被重置（任何需要恢复的启动都会重置统计信息：崩溃后，或从恢复的快照或基础备份启动时）、表或列的目录条目在本次运行前被重新写入（恢复了较早的副本，之后又进行了更改），或者文件夹中没有该次运行的记录（首次运行、新安装或使用另一个文件夹：该文件夹的记录会从随机生成的独立纪元开始，因此绝不会产生另一个文件夹曾用过的摘要）。有一种恢复情况无法被检测到：在服务器停止时复制数据目录，然后原样重新启动，且只在其事务计数器超过提取器上次运行时的值后才进行更改（或者与提取器文件夹一同恢复）。在这种情况下，同一摘要下的相同编号可能会指向其他列。

如果该角色无权读取系统标识符、时间线或统计信息最近一次重置的时间，文件会将数据库记为 ("database": null)，其中的编号仅描述本次运行：恢复到一台全新的服务器时，关系 ID 可能会再次相同，而属性编号会重新分配。

运行任何命令并添加 --help，即可查看所有选项。

正式部署

• RUNBOOK.md：面向服务器运行人员的逐步安装指南，涵盖两个系统用户、只读角色、TLS 和 systemd 服务。
• INSTALL-WITH-YOUR-AGENT.md：只需一个提示词，即可让你自己的 AI Agent 执行相同的安装流程；每遇到决策、密码和 sudo 时都会暂停，等你处理。

它如何保护你的数据安全

风险	Bridge 的处理方式
有人从互联网调用它	每个请求都需要令牌：256 个随机位，并采用恒定时间比较。错误令牌会被计数并受到限流。除非你为它配置 TLS，或指定前置的反向代理，否则它只监听本机；它也会拒绝来自任何其他地址的纯 HTTP 请求。
令牌泄露	它只打开一个文件夹，且仅限只读，不会访问其他内容。rotate-token 可通过一条命令替换令牌，无需重启。--allow 可限制允许调用它的对象。
收到有害内容	不会写入、上传或运行任何内容。请求最多只能包含 64 KB 的 JSON，且绝不会被执行。
请求试图访问文件夹之外的内容	无法通过 ..、符号链接或隐藏文件实现。只提供 CSV、TSV、JSON、JSONL、Markdown 和文本文件。
你的数据库密码	密码保留在提取程序所在的机器上，不会被打印或写入，且只会发送到数据库：当数据库位于另一台机器上时，默认通过经过验证的 TLS 传输。
被篡改的软件包	发布版本在公开 CI 中构建，具有来源证明，并附带校验和及构建证明。发布的软件包不会运行安装脚本。
文件试图指示 Agent	服务端会告知每个客户端，文件内容是数据，而非指令。

THREAT-MODEL.md 列出了每一行对应的测试。

验证发布版本

GitHub 上的每个发布版本都附带 tarball、其 SHA-256 校验和以及构建证明。同一个 tarball 也会带有来源证明发布到 npm，因此 npm 对其计算的摘要必须与 GitHub 上的文件一致：下方两行 sha512- 内容相同。

sha256sum -c maplith-1.2.0-rc.1.tgz.sha256
echo "sha512-$(openssl dgst -sha512 -binary maplith-1.2.0-rc.1.tgz | openssl base64 -A)"
npm view [email protected] dist.integrity
gh attestation verify maplith-1.2.0-rc.1.tgz --repo Maplith/agents \
  --bundle maplith-1.2.0-rc.1.tgz.sigstore.json

从 npm 安装后，npm audit signatures 会检查注册表签名和来源证明。

在任意 MCP 客户端中使用

Bridge 通过 Streamable HTTP 支持 MCP 2025-06-18（以及 2025-03-26、2024-11-05）：通过 POST 向 /mcp 发送 JSON-RPC 2.0 请求。它提供：

• 资源：resources/list（每页 100 个，并带游标）和 resources/read；
• 两个共用同一代码路径的只读工具：list_files 和 read_file。

每个顶层文件夹代表一个系统：exports://shop/orders.csv 是系统 shop 中的文件 orders.csv。只有能在一条最多 8 MB 的回复中返回的文件才会列出。GET /healthz 会为健康检查返回 204。

文件内容来自你的系统。请告知你的 Agent 将其视为数据，绝不要视为指令；Bridge 也会在其 instructions 中作出同样说明。

在本机上的 Agent 中使用

像 Claude Code 这样以本地命令启动 MCP 服务的 Agent，可以自行启动 Bridge：

npx -y [email protected] bridge stdio --dir ./exports

stdio 会通过该 Agent 的标准输入和标准输出，将文件夹提供给它：它与 serve 使用的是同一个服务端，仅监听 127.0.0.1，并使用仅存在于其进程中的令牌。没有令牌文件，也无需输入任何内容。文件夹由 --dir 或 EXPORT_DIR 指定；若未指定，它会提供一个空文件夹，并说明如何指定文件夹。Maplith 插件会以这种方式启动它：在 Claude Code 中使用来自 MAPLITH_BRIDGE_DIR 的文件夹，在 Codex 中使用 setup codex --dir 指定的文件夹。旧命令 maplith-bridge 仍然有效，与 maplith bridge 相同。若要与 Maplith 或另一台机器上的 Agent 共享文件夹，请使用 serve。

面向 MCP 目录

MCP 服务目录（例如 Glama）会在沙箱中构建此仓库，并通过标准输入/输出检查服务，不会提供文件夹或令牌。glama-stdio.ts 专为此用途提供入口：

• 它会自行创建一个空文件夹，因此没有内容可共享；
• 它会生成一个仅存于内存中的随机令牌：绝不写入文件、参数、环境变量或日志；
• 它会在 127.0.0.1 上使用一个空闲端口启动 Bridge 自带的服务，并在该令牌保护下提供此文件夹；
• 它会在标准输入、标准输出与该服务之间转发 MCP 消息，每行一条 JSON-RPC 消息，并且只向标准错误输出日志；
• 标准输入结束或收到 SIGTERM 时，它会停止服务并移除文件夹。

目录看到的 Bridge 与实际一致：它的 initialize 回复和 instructions、list_files 与 read_file 工具，以及一个空文件列表。此入口不接受参数，也无法共享文件夹；serve 可以做到这一点。它位于此仓库中，不在 npm 包内。

使用 Node.js 24 或更高版本，在仓库检出目录中运行：

npm ci --ignore-scripts
node glama-stdio.ts

通过 HTTP 与其沙箱通信的目录会在前面放置 mcp-proxy： mcp-proxy -- node glama-stdio.ts。在 Glama 上，服务的设置如下：

设置	值
Node.js 版本	24
构建步骤	["npm ci --ignore-scripts"]
CMD	["mcp-proxy", "--", "node", "glama-stdio.ts"]
环境变量	无

限制

• PostgreSQL 是提取器读取的唯一数据库。其他任何系统都可以用自己的导出文件填充文件夹。
• 服务启动时会读取 TLS 证书：证书续期后请重启服务。
• 如果依次经过两个代理，请使用 --behind-proxy 指定两者。

版本管理

Bridge 遵循语义化版本。所有变更都记录在 CHANGELOG.md 中。

贡献、安全与许可

• CONTRIBUTING.md：如何提出变更（需通过 DCO 签署）。
• SECURITY.md：通过 [email protected] 或 GitHub 私下报告漏洞。
• Apache License 2.0（LICENSE）。“Maplith”和 Maplith 徽标是 Maplith 的商标（TRADEMARK.md）。