lintbase-mcp

lintbase-mcp

Give your AI coding agent real-time Firestore schema context — so it stops hallucinating field names.

---

The Problem

When you ask Cursor, Claude, or Windsurf to write Firestore code, it guesses your schema.

// 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

The result: silent bugs, runtime crashes, and schema drift baked in by your AI assistant.

The Fix

lintbase-mcp is a Model Context Protocol server that connects your AI agent directly to your Firestore database. Before writing any code, the agent checks what's actually there.

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..."

No hallucinations. No drift. Ground-truth schema, every time.

---

Tools

Tool	What it does
lintbase_scan	Full database audit — schema drift, security issues, performance problems, cost leaks. Returns a structured report with a 0–100 risk score.
lintbase_get_schema	Returns real field names, types, and presence rates for one or all collections. Use before writing any DB code.
lintbase_get_issues	Returns filtered issues. Ask targeted questions: "any errors in users?", "all security issues?", "schema drift only?"

---

🤖 Agent Skill

Install the LintBase Agent Skill into any project so your AI agent automatically uses LintBase before writing Firestore code — no prompting required:

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

This copies a SKILL.md file into .agent/skills/lintbase/ in your project. Cursor, Claude Code, Gemini CLI, and other MCP-compatible agents read this file on startup and follow its instructions automatically.

Same format as the Firebase official Agent Skills. ✅

---

Setup

You'll need a Firebase service account JSON key for your project.

Cursor

Add to .cursor/mcp.json in your project root:

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

Then in your conversation:

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop and start a new conversation.

Windsurf

Add to your Windsurf MCP config:

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

---

Usage Examples

Once connected, your AI agent has three tools available. You can trigger them naturally in conversation or the agent will use them automatically when relevant.

Get the schema of a collection

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

Returns:

## 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 audit

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

Returns: Complete report with risk score, all issues across 4 analyzers (schema drift, security, performance, cost).

Check for errors before deploying

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

Check security issues only

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

---

Security

• Runs 100% locally — your service account key and Firestore data never leave your machine
• The MCP server runs as a local stdio process spawned by your IDE
• No data is sent to any LintBase servers during schema inspection
• The server only performs read operations on your Firestore database

---

Available Filters for lintbase_get_issues

Filter	Values	Example
severity	error, warning, info	Only blocking errors
collection	any collection name	Only issues in users
rule	rule prefix	schema/, security/, perf/, cost/

---

Rule Reference

Rule	Analyzer	What it catches
schema/field-type-mismatch	Schema	Same field holds multiple types across documents
schema/sparse-field	Schema	Field missing from >40% of documents
schema/high-field-variance	Schema	Wildly different field counts between documents
security/sensitive-collection	Security	Collection name suggests unprotected PII
security/field-contains-secret	Security	Field name suggests stored secrets/tokens
security/debug-data-in-production	Security	Debug/test collections left in production
perf/excessive-nesting	Performance	Documents nested >5 levels deep
perf/document-too-large	Performance	Documents approaching Firestore's 1MB limit
cost/large-avg-document	Cost	Average document size driving up bandwidth costs
cost/logging-sink	Cost	Collection used as an unbounded write sink

---

Related

• lintbase — The CLI tool. Run npx lintbase scan firestore --key ./sa.json for a full terminal report.
• lintbase.com — Dashboard for teams: save scan history, track risk score over time, share reports.

---

License

MIT © Mamadou Dia