lintbase-mcp

lintbase-mcp

AI コーディングエージェントに 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 は、AI エージェントを Firestore データベースに直接接続する Model Context Protocol サーバーです。コードを書く前に、エージェントが実際のデータを確認します。

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	1 つまたはすべてのコレクションについて、実際のフィールド名、型、存在率を返します。データベースコードを書く前に使用してください。
lintbase_get_issues	絞り込んだ問題を返します。「users にエラーはありますか？」「セキュリティ上の問題をすべて表示して」「スキーマの乖離のみ表示して」といった、対象を絞った質問ができます。

---

🤖 エージェントスキル

LintBase のエージェントスキルをプロジェクトにインストールすると、AI エージェントが Firestore コードを書く前に LintBase を自動的に使うようになります。プロンプトで指示する必要はありません。

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

これにより、プロジェクト内の .agent/skills/lintbase/ に SKILL.md ファイルがコピーされます。Cursor、Claude Code、Gemini CLI などの MCP 対応エージェントは、起動時にこのファイルを読み込み、その指示に自動的に従います。

Firebase 公式エージェントスキルと同じ形式です。✅

---

セットアップ

プロジェクト用の 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 エージェントが 3 つのツールを使えるようになります。会話の中で自然に呼び出すことも、関連する場面でエージェントに自動的に使わせることもできます。

コレクションのスキーマを取得する

"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/" })

---

セキュリティ

• 100％ローカルで実行されます。サービスアカウントキーと 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 の1MB制限に近づいている
cost/large-avg-document	コスト	ドキュメントの平均サイズによって帯域幅コストが増加している
cost/logging-sink	コスト	コレクションが上限のない書き込み先として使われている

---

関連項目

• lintbase — CLI ツールです。npx lintbase scan firestore --key ./sa.json を実行すると、詳細なターミナルレポートを確認できます。
• lintbase.com — チーム向けダッシュボードです。スキャン履歴の保存、リスクスコアの推移の追跡、レポートの共有ができます。

---

ライセンス

MIT © Mamadou Dia