askDB MCP

自然言語のデータ質問を、LLMがSQLを書くために必要なスキーマコンテキストに変換するMCPサーバーです。データベースには接続せず、SQL自体も生成しません。Pineconeインデックスから適切なテーブル定義を取得し、質問しているモデル（Claude Code、Claude Desktop、ChatGPT、Cursor）に渡します。

user question
   │
   ▼
Claude Code / ChatGPT ──calls──► askDB MCP ──semantic search──► Pinecone (ask-db)
   │                                  │
   │      relevant DDL + guardrails ◄─┘
   ▼
generated SQL

ツール

すべてのレスポンスには、返されたテーブルと列のみを使用するようにモデルに指示する命令が埋め込まれているため、名前を捏造することはありません。

セットアップ

npm install
npm run setup             # creates .env from the template
#                          → then put your PINECONE_API_KEY in .env
npm run doctor            # verify connection, field mapping and retrieval quality

他の人と共有しますか？ SETUP.md を送ってください。ローカルでの実行とホスト型インスタンスへの接続の両方をカバーしています。

npm run doctor が重要なステップです。インデックス設定、レコードが実際に使用しているメタデータフィールド、サンプル検索を出力するため、クライアントに接続する前にサーバーが正しいフィールドを読み取っていることを確認できます。

npm run doctor       # connectivity + retrieval sanity check
npm run smoke        # drive the stdio server with a real MCP client
npm run smoke:http   # same over Streamable HTTP, with bearer auth

クライアントを接続する

Claude Code

CLI、デスクトップアプリ、IDE拡張機能はすべて同じ設定を共有するため、これにより3つすべてに対してサーバーが登録されます。

# from the repo root — records an absolute path, so it works in any folder
claude mcp add askdb --scope user -- node "$PWD\src\server.js"

claude mcp list（askdb: ... ✓ Connected）で確認してから、デスクトップアプリまたはIDEウィンドウを再起動してください。MCPサーバーは起動時に読み込まれます。

ユーザースコープは意図的です。目的は、他のリポジトリで作業しながらデータベースの質問をすることです。プロジェクトスコープの.mcp.jsonは、Claude Codeがこのリポジトリのルートで起動された場合にのみ解決され、両方のスコープでaskdbを定義すると、Claude Codeが重複について警告します。

Claude Desktop / Cursor

claude_desktop_config.json（またはCursorのMCP設定）に追加します：

{
  "mcpServers": {
    "askdb": {
      "command": "node",
      "args": ["D:\\working-directory\\AI\\askDB-mcp\\src\\server.js"]
    }
  }
}

認証情報はサーバーの隣にある.envから取得されるため、クライアント設定にキーは含まれません。

ChatGPT

ChatGPTコネクタはローカルプロセスを起動できません。HTTP上のリモートMCPのみを話します。HTTPトランスポートを実行して公開してください：

# set MCP_AUTH_TOKEN first: this endpoint serves your whole schema
MCP_AUTH_TOKEN=some-long-random-string npm run start:http

次に、Authorization: Bearer <token>ヘッダーを付けてコネクタをhttps://<your-host>/mcpに向けます。簡単な試用にはトンネル（cloudflared tunnel --url http://localhost:3000）を使い、長期的なものには適切にホストしてください。DEPLOY.mdはNetlifyをエンドツーエンドでカバーしています。GET /healthはロードバランサーのチェック用に認証不要です。MCP_AUTH_TOKENが設定されている場合、/mcpはベアラートークンを必要とします。

HTTPトランスポートはステートレスです。リクエストごとに1つのサーバーインスタンスが存在するため、スティッキーセッションなしでロードバランサーの背後でスケールします。

ホスティング

2つのNetlify Functionsとしてデプロイされます。netlify.tomlにビルド設定が含まれているため、リポジトリをインポートしてPINECONE_API_KEYとMCP_AUTH_TOKENを設定するだけです。ステップバイステップ: DEPLOY.md

これはトランスポートの書き換えなしで機能します。MCP SDKのWebStandardStreamableHTTPServerTransportはRequestを受け取ってResponseを返すため、Netlify Functions v2のシグネチャと一致し、netlify/functions/mcp.mjsはsrc/mcp.jsを変更せずにインポートします。同じファイルはCloudflare Workers、Deno、Bunでも動作します。src/http.jsはコンテナとVMをカバーします。

GET /healthはトークンを必要とせず、必要な環境変数が設定されているかどうかを報告します（値ではなく存在のみ）。これは起動ログを読むためのサーバーレス代替です。/mcpはフェイルクローズです。MCP_AUTH_TOKENが設定されていない場合、スキーマをインターネットに公開するのではなく503を返します。

起動すれば、チームメイトは何もインストールする必要はありません。URLとトークンだけです（SETUP.md、ルートA）。

設定

APIキー以外はすべてオプションです。.env.exampleを参照してください。

サーバーはレコードが使用するメタデータフィールドと、インデックスが統合埋め込みを持つかどうかを自動検出するため、通常はデフォルトのままで動作します。

知っておくべき2つのこと

埋め込みモデルは一致している必要があります。 EMBED_MODELがスキーマのアップサートに使用したモデルではない場合、すべてのスコアがほぼゼロに落ち込み、結果はノイズになります。ベクトルは互いに対して事実上ランダムです。npm run doctorでは、無関係なテーブルが0.8ではなく0.01前後のスコアで返ってくることで確認できます。このインデックスはmultilingual-e5-largeで構築されました。

インデックスに複数の環境が含まれる場合はDEFAULT_DATABASEを設定してください。 同じスキーマが*_liveと*_testとして存在する場合、スコープ未指定の検索ではすべてのテーブルの2つのコピーが返され、top_kスロットの半分を重複で消費し、モデルが1つのクエリで環境を混在させる可能性があります。

構成