Lintbase Mcp

LintBase

AI 编码 Agent 的真实依据。 LintBase 为 AI Agent 提供数据库架构、安全规则和架构的实时信息，让它们不再对你的代码库产生幻觉。

npx lintbase export-context firestore --key ./service-account.json

---

为什么选择 LintBase？

开发者不断向 Cursor、Windsurf、Copilot Workspace 和 Claude Code 等 AI 工具提供上下文文件。 如果你的 Agent 不了解数据库的真实架构，它就会编写在生产环境中无法运行的代码。

LintBase 充当桥梁。它直接连接到你的数据库，读取实时文档中的真实依据，并生成针对 AI 优化的结构化上下文。

• 🤖 阻止 AI 产生幻觉 — 生成准确的架构、字段存在率和类型。
• 📐 发现架构漂移 — 使用 lintbase check 对照架构快照提供 CI 保护。
• 🔒 安全上下文 — 在 AI 编写查询前，突出显示缺失的规则或暴露的 PII。
• 💸 成本意识 — 防止 AI 对包含 200 万条以上文档的集合编写无界查询。
• 🍃 通用 NoSQL — 轻松支持 Firestore 和 MongoDB。

为什么不直接让 Agent 读取代码？

因为在文档数据库中，代码并不可信。真实架构就是实时文档实际包含的内容，而每一次未完成的迁移、每一个重命名的字段，以及之前 AI 会话中每一次仓促编写的代码，都会让它与代码逐渐偏离。根据 TypeScript 接口推断架构的 Agent，会针对一个早已不存在的数据库编写看似合理的查询。问题悄无声息：结果为空、值未定义、新字段变体与旧字段并存。LintBase 读取的是文档，而不是代码。

局限性（如实说明）

• 仅支持 Firestore 和 MongoDB。Postgres 显然尚未支持，后续会添加。
• 大型集合采用抽样，而非完整扫描。对于数百万条文档的集合，存在率是估算值。
• MCP 服务比 CLI 更新。请预期 MCP 服务会先出现一些不完善之处。

---

🤖 AI 上下文导出（适用于 Cursor、Claude、Windsurf）

为 AI Agent 提供完整数据库知识的最快方式。

npx lintbase export-context firestore --key ./service-account.json

输出：

/lintbase-context/
├── database-schema.md
├── collections.md
├── security-rules.md
├── architecture.md
└── risk-report.md

将 lintbase-context 文件夹放入 AI 的上下文窗口，或在 .cursorrules 中提及它。你的 Agent 现在就能编写完美、不会漂移的数据库查询。

---

快速开始

1. 获取服务账号密钥

Firebase Console → Project Settings → Service Accounts → Generate new private key

保存 JSON 文件。切勿将其提交到 git。

2. CI 流水线保护（架构漂移）

LintBase 就像“架构的版本控制”。运行快照命令以创建基线：

npx lintbase snapshot firestore --key ./service-account.json

将 .lintbase/schema.json 提交到你的仓库。然后，将检查命令添加到 CI/CD 流水线（GitHub Actions、GitLab CI）：

npx lintbase check firestore --key ./service-account.json --fail-on error

如果查询或部署意外删除了关键字段或更改了类型（例如，从 string 改为 number），CI 构建会立即失败。

3. 运行常规扫描

npx lintbase scan firestore --key ./service-account.json

你将在终端中看到完整报告：

 LintBase — Firestore Scan
 ─────────────────────────────────────────────
 Collections scanned:  12
 Documents sampled:    847
 Issues found:         23  (4 errors · 11 warnings · 8 infos)
 Risk score:           67 / 100  [HIGH]

 ERRORS
 ✖  users         no-auth-check        Documents readable without authentication
 ✖  orders        missing-index        Query on `status` + `createdAt` has no composite index
 ✖  debug_logs    large-collection     Collection has 2.4M docs — estimated $340/mo in reads

 WARNINGS
 ⚠  products      schema-drift         Field `price` found as both Number and String
 ⚠  sessions      ttl-missing          No expiry field — stale docs accumulate indefinitely
 ...

3. 保存到仪表板（可选）

在 lintbase.com 跟踪数据库健康状况随时间的变化：

npx lintbase scan firestore \
  --key ./service-account.json \
  --save https://www.lintbase.com \
  --token <your-api-token>

在 lintbase.com/dashboard/settings 获取令牌。

---

支持的数据库

• Firestore：npx lintbase scan firestore --key ./sa.json
• MongoDB：npx lintbase scan mongodb --uri mongodb+srv://user:[email protected]/test

---

🤖 AI Agent 集成（MCP）

正在使用 Cursor、Claude Desktop 或 Windsurf？安装 lintbase-mcp，为你的 AI Agent 提供实时 Firestore 架构上下文——这样它就不会再臆造字段名称。

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "lintbase": {
      "command": "npx",
      "args": ["-y", "lintbase-mcp"]
    }
  }
}

现在，当你让 AI “向 users 添加一个字段” 时，它会先检查你的真实架构，再开始编写代码。

→ 完整设置指南和工具参考

---

它能检测什么

🔒 安全

规则	检测内容
no-auth-check	未经身份验证即可读取或写入的集合
exposed-pii	未带加密标记的电子邮件、电话、SSN 字段
world-readable	安全规则过于宽松的文档

💸 成本

规则	检测内容
large-collection	文档数量达到 10 万以上且读取成本较高的集合
unbounded-query	未使用 limit()、会扫描整个集合的查询
missing-index	会退化为全集合扫描的筛选条件组合
debug-collection	看起来像临时数据但从未清理的集合

📐 架构漂移

规则	检测内容
type-inconsistency	不同文档中存储类型不一致的字段
missing-required-field	存在于 90% 以上文档中、但在部分文档中缺失的字段
nullable-id	有时为 null 的引用字段

⚡ 性能

规则	检测内容
deep-nesting	嵌套层级超过 3 层的文档字段
large-document	接近 Firestore 1MB 限制的文档
hot-document	多个用户同时更新的单个文档
no-pagination	缺少标准分页字段的集合

---

选项

lintbase <command> <database> [options]

Commands:
  scan <database>             Scan a database and print diagnostic report
  export-context <database>   Export schema to markdown/JSON for AI agents
  snapshot <database>         Generate local schema snapshot for CI comparison
  check <database>            Run in headless CI mode (fails on schema drift)

Options:
  --key <path>      Path to Firebase service account JSON 
  --uri <uri>       MongoDB connection URI
  --limit <n>       Max documents to sample per collection     [default: 100]
  --max-depth <n>   Firestore: tiers to recurse into subcollections
                    (1 = top-level only)                       [default: 2]
  --fail-on <lvl>   Fail pipeline if issues exceed severity (error, warning, info)
  --save <url>      Dashboard URL to save results
  --token <token>   API token for dashboard (from lintbase.com)
  --collections     Comma-separated list of collections to scan
  -h, --help        Show help

---

控制面板

CLI 永久免费。控制面板会将扫描结果可视化为交互式架构图——你的凭据绝不会离开你的设备。

Pro 通过 --save 提供的功能：

• ⬡ 架构图 — 将每个集合显示为可拖动卡片，包含真实字段名称、类型、存在率和问题徽章
• ◎ 健康雷达图 — 按集合展示架构、安全、性能和成本维度的蜘蛛图
• ⊕ 优先级象限图 — 展示影响与修复难度的 2×2 气泡图，告诉你应该先修复什么
• ≋ 漂移时间线 — 保存跨扫描的历史记录，方便你回顾架构随时间的演变。

CLI 本地工具： 100% 免费 · Pro： 39 美元/月——无限历史记录、控制面板和共享团队工作流。

---

安全

• 你的服务账号密钥绝不会离开你的设备——它只会在本地读取
• 文档采样数量严格限制在 --limit（默认为 100），以防意外产生读取成本
• --save 标志只会发送扫描摘要和问题列表——绝不会发送原始文档数据

---

许可证

MIT © Mamadou Dia