lintbase-mcp

lintbase-mcp

为你的 AI 编码 Agent 提供实时的 Firestore 架构上下文，让它不再臆造字段名称。

---

问题

当你让 Cursor、Claude 或 Windsurf 编写 Firestore 代码时，它会猜测你的架构。

// What your AI writes:
await db.collection('users').doc(id).update({ name: value });

// What's actually in your DB:
{ displayName, uid, email, createdAt, plan }   ← no "name" field

结果就是：悄无声息的错误、运行时崩溃，以及由 AI 助手引入的架构偏移。

解决方案

lintbase-mcp 是一个 Model Context Protocol 服务，可将你的 AI Agent 直接连接到 Firestore 数据库。在编写任何代码之前，Agent 会检查实际存在的内容。

You: "Add a subscription status field to users"

Agent → lintbase_get_schema({ collection: "users" })
      ← { uid, email, createdAt, plan, displayName }

Agent: "I can see users has uid, email, createdAt, plan, displayName.
        I'll add subscriptionStatus as a string field alongside plan..."

不再臆造，不再偏移。每次都基于真实架构。

---

工具

工具	功能
lintbase_scan	全面审计数据库 — 检查架构偏移、安全问题、性能问题和成本漏洞。返回包含 0–100 风险评分的结构化报告。
lintbase_get_schema	返回一个或所有集合的真实字段名称、类型和出现率。在编写任何数据库代码前使用。
lintbase_get_issues	返回筛选后的问题。可提出有针对性的问题：“users 中有错误吗？”、“所有安全问题？”、“只看架构偏移？”

---

🤖 Agent Skill

将 LintBase Agent Skill 安装到任意项目中，让你的 AI Agent 在编写 Firestore 代码前自动使用 LintBase — 无需提示：

npx -p lintbase-mcp lintbase-mcp-install-skill

这会将 SKILL.md 文件复制到项目中的 .agent/skills/lintbase/。Cursor、Claude Code、Gemini CLI 和其他兼容 MCP 的 Agent 会在启动时读取此文件，并自动遵循其中的说明。

格式与 Firebase 官方 Agent Skills 相同。✅

---

设置

你需要为项目准备一个 Firebase 服务账号 JSON 密钥。

Cursor

将以下内容添加到项目根目录下的 .cursor/mcp.json：

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

然后在对话中输入：

"Check my Firestore schema before writing this code. Key is at ./service-account.json"

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

重启 Claude Desktop 并开始新的对话。

Windsurf

将以下内容添加到 Windsurf 的 MCP 配置中：

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

---

使用示例

连接后，你的 AI Agent 就可以使用三个工具。你可以在对话中自然地调用它们；在相关情况下，Agent 也会自动使用。

获取集合的架构

"What fields are in the users collection?"
→ lintbase_get_schema({ keyPath: "./sa.json", collection: "users" })

返回：

## users  (50 docs sampled)
| Field       | Type      | Presence | Stable |
|-------------|-----------|----------|--------|
| uid         | string    | 100%     | ✅     |
| email       | string    | 100%     | ✅     |
| createdAt   | timestamp | 100%     | ✅     |
| plan        | string    | 95%      | ✅     |
| displayName | string    | 62%      | ⚠️  ← mark as optional |

运行全面审计

"Run a full LintBase scan before I start this refactor"
→ lintbase_scan({ keyPath: "./sa.json", sampleSize: 100 })

**返回：**完整报告，包含风险评分，以及 4 个分析器发现的所有问题（架构偏移、安全、性能、成本）。

部署前检查错误

"Any blocking errors I should know about?"
→ lintbase_get_issues({ keyPath: "./sa.json", severity: "error" })

仅检查安全问题

"Are there any security problems with my database?"
→ lintbase_get_issues({ keyPath: "./sa.json", rule: "security/" })

---

安全

• 完全在本地运行 — 服务账号密钥和 Firestore 数据不会离开你的设备
• MCP 服务作为由 IDE 启动的本地 stdio 进程运行
• 检查架构期间不会向任何 LintBase 服务发送数据
• 此服务仅对 Firestore 数据库执行读取操作

---

lintbase_get_issues 的可用筛选条件

筛选条件	值	示例
severity	error、warning、info	仅显示阻断性错误
collection	任意集合名称	仅显示 users 中的问题
rule	规则前缀	schema/、security/、perf/、cost/

---

规则参考

规则	分析器	检查内容
schema/field-type-mismatch	架构	同一字段在不同文档中具有多种类型
schema/sparse-field	架构	超过 40% 的文档缺少该字段
schema/high-field-variance	架构	不同文档的字段数量差异很大
security/sensitive-collection	安全	集合名称暗示其中存有未受保护的个人身份信息
security/field-contains-secret	安全	字段名称暗示其中存储了密钥或令牌
security/debug-data-in-production	安全	调试或测试集合遗留在生产环境中
perf/excessive-nesting	性能	文档嵌套超过 5 层
perf/document-too-large	性能	文档接近 Firestore 的 1 MB 限制
cost/large-avg-document	成本	文档平均大小导致带宽成本增加
cost/logging-sink	成本	集合被用作无界写入接收器

---

相关项目

• lintbase — 命令行工具。运行 npx lintbase scan firestore --key ./sa.json，即可获取完整的终端报告。
• lintbase.com — 面向团队的仪表板：保存扫描历史记录、跟踪风险评分随时间的变化、分享报告。

---

许可证

MIT © Mamadou Dia