vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/mongodb-mcp-setup/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: mongodb-mcp-setup
+description: Guide users through configuring key MongoDB MCP server options. Use this skill when a user has the MongoDB MCP server installed but hasn't configured the required environment variables, or when they ask about connecting to MongoDB/Atlas and don't have the credentials set up.
+license: Apache-2.0
+metadata:
+  version: "1.0.0"
+---
+
+# MongoDB MCP Server Setup
+
+This skill guides users through configuring the MongoDB MCP server for use with an agentic client.
+
+## Overview
+
+The MongoDB MCP server requires authentication. Users have three options:
+
+1. **Connection String** (Option A): Direct connection to a specific cluster
+   - Quick setup for single cluster
+   - Requires `MDB_MCP_CONNECTION_STRING` environment variable
+
+2. **Service Account Credentials** (Option B): MongoDB Atlas Admin API access
+   - **Recommended for Atlas users** - simplifies authentication and data access
+   - Access to Atlas Admin API and dynamic cluster connection via `atlas-connect-cluster`
+   - No manual DB user credential management
+   - Requires `MDB_MCP_API_CLIENT_ID` and `MDB_MCP_API_CLIENT_SECRET` environment variables
+
+3. **Atlas Local** (Option C): Local development with Docker
+   - **Best for local testing** - zero configuration required
+   - Runs Atlas locally in Docker, requires Docker installed
+   - No credentials or cloud cluster access
+
+This is an interactive step-by-step guide. The agent detects the user's environment and provides tailored instructions, but **never asks for or handles credentials** — users add those directly to their shell profile or agentic client config in Step 5. Make this clear to the user whenever credentials come up in Steps 3a and 3b.
+
+## Step 0: Detect Client
+
+Before anything else, determine which agentic client the user is running. This controls how credentials are configured in Step 1 and Step 5.
+
+Run:
+
+```bash
+env | grep "^CODEX_"
+```
+
+- **If no `CODEX_*` variables are present** → the user is running a **shell-based client** (Claude, Cursor, Gemini CLI, Copilot CLI, etc.). Credentials are configured via shell profile environment variables.
+- **If any `CODEX_*` variables are present** → the user is running **Codex**. Credentials are stored in `~/.codex/config.toml` (macOS/Linux) or `%USERPROFILE%\.codex\config.toml` (Windows), not in shell environment variables. The desktop app does not inherit shell env vars when launched from Finder, Launchpad, or the Windows Start menu.
+
+Carry this **client type** (Codex vs. shell-based) forward through every subsequent step.
+
+## Step 1: Check Existing Configuration
+
+Check whether credentials are already configured.
+
+**For shell-based clients** — check the current environment:
+
+```bash
+env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'
+```
+
+**For Codex** — search `~/.codex/config.toml` (macOS/Linux) or `%USERPROFILE%\.codex\config.toml` (Windows):
+
+```bash
+grep -E 'MDB_MCP_(CONNECTION_STRING|API_CLIENT_ID|API_CLIENT_SECRET|READ_ONLY)' ~/.codex/config.toml 2>/dev/null | sed '/MDB_MCP_READ_ONLY/!s/[[:space:]]*=[[:space:]].*/ = "[set]"/'
+```
+
+**Interpretation (both):**
+
+- If `MDB_MCP_CONNECTION_STRING` appears → connection string auth is configured
+- If both `MDB_MCP_API_CLIENT_ID` and `MDB_MCP_API_CLIENT_SECRET` appear → service account auth is configured. If only one is present, treat it as incomplete.
+- If `MDB_MCP_READ_ONLY` appears → read-only mode is enabled
+
+**Partial Configuration Handling:**
+
+- User wants to add read-only to existing setup (has auth, no read-only flag) → skip to Step 4
+- User wants to switch authentication methods → explain they should remove the old credentials first (from `config.toml` for Codex, from their shell profile for shell-based clients), then proceed with Steps 2–5
+- User wants to update credentials → skip to Step 5
+
+**Important**: If the user wants an Atlas Admin API action (managing clusters, creating users, performance advisor) but only has `MDB_MCP_CONNECTION_STRING`, explain they need service account credentials and offer to walk through setup.
+
+## Step 2: Present Configuration Options
+
+If no valid configuration exists, present the options:
+
+**Connection String (Option A)** — Best for:
+
+- Single cluster access
+- Existing database credentials
+- Self-hosted MongoDB or no Atlas Admin API needs
+
+**Service Account Credentials (Option B)** — Best for:
+
+- MongoDB Atlas users (recommended)
+- Multi-cluster switching
+- Atlas Admin API access (cluster management, user creation, performance monitoring)
+
+**Atlas Local (Option C)** — Best for:
+
+- Local development/testing without cloud setup
+- Fastest setup with Docker, no credentials required
+
+Ask the user which option they'd like to proceed with.
+
+## Step 3a: Connection String Setup
+
+If the user chooses Option A:
+
+### 3a.1: Explain How to Find the Connection String
+
+Explain where and how to obtain their connection string:
+
+**For MongoDB Atlas:**
+
+1. Go to [cloud.mongodb.com](https://cloud.mongodb.com)
+2. Select your cluster → click **Connect**
+3. Choose **Drivers** or **Shell** → copy the connection string
+4. Replace `<username>` and `<password>` with your database user credentials
+
+**For self-hosted MongoDB:**
+
+- The connection string is typically configured by your DBA or in your application config
+- Format: `mongodb://username:password@host:port/database`
+
+**Expected formats:**
+
+- `mongodb://username:password@host:port/database`
+- `mongodb+srv://username:password@cluster.mongodb.net/database`
+- `mongodb://host:port` (local, no auth)
+
+Proceed to Step 4 (Determine Read-Only Access).
+
+## Step 3b: Service Account Setup
+
+If the user chooses Option B:
+
+### 3b.1: Guide Through Atlas Service Account Creation
+
+Direct the user to create a MongoDB Atlas Service Account:
+
+**Full documentation**: https://www.mongodb.com/docs/mcp-server/prerequisites/
+
+Walk them through the key steps:
+
+1. **Navigate to MongoDB Atlas** — [cloud.mongodb.com](https://cloud.mongodb.com)
+2. **Select your organization** from the ORGANIZATION section near the top of the page
+3. **Go to "Project Identity and Access"** on the left sidebar → **Applications** → **Create Service Account**
+4. **Set Permissions** — Grant Organization Member or Project Owner (see docs for exact permission mappings)
+5. **Generate Credentials** — Create Client ID and Secret
+   - ⚠️ The **Client Secret is shown only once** — save it immediately before leaving the page
+5. **Note both values** — you'll need Client ID and Client Secret for Step 5
+
+### 3b.2: API Access List Configuration
+
+⚠️ **CRITICAL**: The user MUST add their IP address to the service account's API Access List, or all Atlas Admin API operations will fail.
+
+Steps:
+
+1. On the service account details page, find **API Access List**
+2. Click **Add Access List Entry**
+3. Add your current IP address. Use a specific IP or CIDR range whenever possible.
+   - ⚠️ **`0.0.0.0/0` allows access from any IP — this is a significant security risk.** Only use it as a last resort for temporary testing and remove it immediately afterward. It should never be used in production.
+4. Save changes
+
+This is more secure than global Network Access settings as it only affects API access, not database connections.
+
+Proceed to Step 4 (Determine Read-Only Access).
+
+## Step 3c: Atlas Local Setup
+
+If the user chooses Option C:
+
+### 3c.1: Check Docker Installation
+
+Verify Docker is installed:
+
+```bash
+docker info
+```
+
+If not installed, direct them to: https://www.docker.com/get-started
+
+### 3c.2: Confirm Setup Complete
+
+Atlas Local requires no credentials — the user is ready to go:
+
+- Create deployments: `atlas-local-create-deployment`
+- List deployments: `atlas-local-list-deployments`
+- All operations work out of the box with Docker
+
+**Skip Steps 4 and 5** (no configuration needed) and proceed to Step 6 (Next Steps).
+
+## Step 4: Determine Read-Only vs Read-Write Access
+
+**Only applies to Options A and B. Skip to Step 6 for Option C.**
+
+Ask whether they want read-only or read-write access:
+
+- **Read-Write** (default): Full data access, modifications allowed
+  - Best for: Development, testing, administrative tasks
+
+- **Read-Only**: Data reads only, no modifications
+  - Best for: Production data safety, reporting, compliance
+
+**If read-only**: include the read-only flag in the credential snippet in Step 5.
+**If read-write**: omit it (defaults to read-write).
+
+Proceed to Step 5 (Configure Credentials).
+
+## Step 5: Configure Credentials
+
+**Do not ask for or handle credentials** — provide exact instructions so the user can add them directly.
+
+### 5.1: Add credentials
+
+**For shell-based clients** — store credentials in a dedicated `~/.mcp-env` file (not directly in the shell profile), then source it from the profile. This keeps credentials out of files that are often group/world readable by default and prevents accidentally committing them to git.
+
+**For Codex** — add to `~/.codex/config.toml` (macOS/Linux) or `%USERPROFILE%\.codex\config.toml` (Windows).
+
+Show the user the appropriate snippet:
+
+**For Connection String (Option A):**
+
+Shell-based clients (`~/.mcp-env`):
+
+```bash
+export MDB_MCP_CONNECTION_STRING="<paste-your-connection-string-here>"
+```
+
+Codex (`config.toml`):
+
+```toml
+[mcp_servers.mongodb.env]
+MDB_MCP_CONNECTION_STRING = "<paste-your-connection-string-here>"
+```
+
+**For Service Account (Option B):**
+
+Shell-based clients (`~/.mcp-env`):
+
+```bash
+export MDB_MCP_API_CLIENT_ID="<paste-your-client-id-here>"
+export MDB_MCP_API_CLIENT_SECRET="<paste-your-client-secret-here>"
+```
+
+Codex (`config.toml`):
+
+```toml
+[mcp_servers.mongodb.env]
+MDB_MCP_API_CLIENT_ID = "<paste-your-client-id-here>"
+MDB_MCP_API_CLIENT_SECRET = "<paste-your-client-secret-here>"
+```
+
+**If read-only was chosen (Step 4), also add:**
+
+Shell-based: `export MDB_MCP_READ_ONLY="true"` in `~/.mcp-env`.
+
+Codex: `MDB_MCP_READ_ONLY = "true"` under the same `[mcp_servers.mongodb.env]` section.
+
+⚠️ Both `config.toml` and `~/.mcp-env` are stored in plaintext. Do not commit them to version control.
+
+### 5.2: Finalize (shell-based clients only)
+
+Restrict permissions on `~/.mcp-env`:
+
+```bash
+# adjust for windows if needed
+chmod 600 ~/.mcp-env
+```
+
+Add `source ~/.mcp-env` to the shell profile (e.g. `~/.zshrc`). Adjust for the detected shell (e.g. for fish: `bass source ~/.mcp-env` or `set -x`; for PowerShell: dot-source a `.ps1` file instead).
+
+Detect the shell and profile file by running `echo $SHELL` if needed.
+
+### 5.3: Verify
+
+**Shell-based clients** — reload the profile first, then verify:
+
+```bash
+source ~/.zshrc  # adjust to match the profile file
+env | grep "^MDB_MCP" | sed '/^MDB_MCP_READ_ONLY=/!s/=.*/=[set]/'
+```
+
+**Codex:**
+
+```bash
+# adjust path if on Windows
+grep -E 'MDB_MCP_(CONNECTION_STRING|API_CLIENT_ID|API_CLIENT_SECRET|READ_ONLY)' ~/.codex/config.toml 2>/dev/null | sed '/MDB_MCP_READ_ONLY/!s/[[:space:]]*=[[:space:]].*/ = "[set]"/'
+```
+
+Expected output shows the configured key(s) with values redacted to `[set]`. If nothing appears, check that credentials were saved and (for shell-based clients) that the profile was reloaded.
+
+Proceed to Step 6 (Next Steps).
+
+## Step 6: Next Steps
+
+### For Options A & B (Connection String / Service Account):
+
+1. **Restart the agentic client**:
+   - **Shell-based clients**: Fully quit the client, then run `source <profile-file>` to load the new variables, and reopen the client from that same terminal session so it inherits the environment.
+   - **Codex**: Fully quit and relaunch the app. No terminal session needed — credentials come from `config.toml`.
+
+2. **Verify MCP Server**: After restart, test by performing a MongoDB operation.
+
+3. **Using the Tools**:
+   - Option A: Direct database access tools available
+   - Option B: Additionally has Atlas Admin API tools and `atlas-connect-cluster`
+   - **Important (Option B)**: Ensure your IP is in the service account's API Access List or all API calls will fail
+
+### For Option C (Atlas Local):
+
+1. **Ready to use**: No restart or configuration needed!
+
+2. **Next steps**:
+   - Create deployments: `atlas-local-create-deployment`
+   - List deployments: `atlas-local-list-deployments`
+   - Use standard database operations once connected
+
+## Troubleshooting
+
+- **Variables not appearing after `source`** (shell-based clients): Check the profile file path and confirm the file was saved
+- **Client doesn't pick up variables**: Ensure full restart (quit + reopen), not just a reload
+- **Codex desktop app not picking up credentials**: If launched from Finder, Launchpad, or the Windows Start menu, Codex does not inherit shell environment variables from `.zshrc`/`.zprofile`/PowerShell profiles. Use `~/.codex/config.toml` (macOS/Linux) or `%USERPROFILE%\.codex\config.toml` (Windows) instead (see Step 5)
+- **Invalid connection string format**: Re-check the format; must start with `mongodb://` or `mongodb+srv://`
+- **Atlas Admin API errors (Option B)**: Verify your IP is in the service account's API Access List
+- **Read-only mode not working**: Check that `MDB_MCP_READ_ONLY` is set — in `config.toml` under `[mcp_servers.mongodb.env]` for Codex, or via `env | grep ^MDB_MCP_READ_ONLY` for shell-based clients
+- **fish/PowerShell**: Syntax differs — use `set -x` (fish) or `$env:` (PowerShell) instead of `export`

package/dist/global-skills/mongodb-natural-language-querying/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: mongodb-natural-language-querying
+description: Generate read-only MongoDB queries (find) or aggregation pipelines using natural language, with collection schema context and sample documents. Use this skill whenever the user asks to write, create, or generate MongoDB queries, wants to filter/query/aggregate data in MongoDB, asks "how do I query...", needs help with query syntax, or discusses finding/filtering/grouping MongoDB documents. Also use for translating SQL-like requests to MongoDB syntax. Does NOT handle Atlas Search ($search operator), vector/semantic search ($vectorSearch operator), fuzzy matching, autocomplete indexes, or relevance scoring - use search-and-ai for those. Does NOT analyze or optimize existing queries - use mongodb-query-optimizer for that. Does NOT handle aggregation pipelines that involve write operations. Requires MongoDB MCP server.
+license: Apache-2.0
+metadata:
+  version: "1.0.0"
+allowed-tools: mcp__mongodb__*
+---
+
+# MongoDB Natural Language Querying
+
+You are an expert MongoDB read-only query and aggregation pipeline generator.
+
+## Query Generation Process
+
+### 1. Gather Context Using MCP Tools
+
+**Required Information:**
+- Database name and collection name (use `mcp__mongodb__list-databases` and `mcp__mongodb__list-collections` if not provided)
+- User's natural language description of the query
+
+**Fetch in this order:**
+
+1. **Indexes** (for query optimization):
+   ```
+   mcp__mongodb__collection-indexes({ database, collection })
+   ```
+
+2. **Schema** (for field validation):
+   ```
+   mcp__mongodb__collection-schema({ database, collection, sampleSize: 50 })
+   ```
+   - Returns flattened schema with field names and types
+   - Includes nested document structures and array fields
+
+3. **Sample documents** (for understanding data patterns):
+   ```
+   mcp__mongodb__find({ database, collection, limit: 4 })
+   ```
+   - Shows actual data values and formats
+   - Reveals common patterns (enums, ranges, etc.)
+
+### 2. Analyze Context and Validate Fields
+
+Before generating a query, always validate field names against the schema you fetched. MongoDB won't error on nonexistent field names - it will simply return no results or behave unexpectedly, making bugs hard to diagnose. By checking the schema first, you catch these issues before the user tries to run the query.
+
+Also review the available indexes to understand which query patterns will perform best.
+
+### 3. Choose Query Type: Find vs Aggregation
+
+Prefer find queries over aggregation pipelines because find queries are simpler and easier for other developers to understand.
+
+**Use Find Query when:**
+- Simple filtering on one or more fields
+- Basic sorting, limiting, or projecting specific fields
+- No need for grouping, complex transformations, or multi-stage processing
+
+**Use Aggregation Pipeline when the request requires:**
+- Grouping or aggregation functions (sum, count, average, etc.)
+- Multiple transformation stages
+- Joins with other collections ($lookup)
+- Array unwinding or complex array operations
+
+### 4. Format Your Response
+
+Output queries using the user-requested language or driver syntax; if no language or expected format is supplied, always use MongoDB shell syntax (with unquoted keys and single quotes) for readability and compatibility with MongoDB tools.
+
+**Find Query Response:**
+```json
+{
+  "query": {
+    "filter": "{ age: { $gte: 25 } }",
+    "projection": "{ name: 1, age: 1, _id: 0 }",
+    "sort": "{ age: -1 }",
+    "limit": "10"
+  }
+}
+```
+
+**Aggregation Pipeline Response:**
+```json
+{
+  "aggregation": {
+    "pipeline": "[{ $match: { status: 'active' } }, { $group: { _id: '$category', total: { $sum: '$amount' } } }]"
+  }
+}
+```
+
+## Best Practices
+
+### Query Quality
+1. **Generate correct queries** - Build queries that match user requirements, then check index coverage:
+   - Generate the query to correctly satisfy all user requirements
+   - After generating the query, check if existing indexes can support it
+   - If no appropriate index exists, mention this in your response (user may want to create one)
+   - Never use `$where` because it prevents index usage
+   - Do not use `$text` without a text index
+   - `$expr` should only be used when necessary (use sparingly)
+2. **Avoid redundant operators** - Never add operators that are already implied by other conditions:
+   - Don't add `$exists` when you already have an equality or inequality check (e.g., `status: "active"` or `age: { $gt: 25 }` already implies the field exists)
+   - Don't add overlapping range conditions (e.g., don't use both `$gte: 0` and `$gt: -1`)
+   - Each condition should add meaningful filtering that isn't already covered
+3. **Project only needed fields** - Reduce data transfer with projections
+   - Add `_id: 0` to the projection when `_id` field is not needed
+4. **Validate field names** against the schema before using them
+5. **Use appropriate operators** - Choose the right MongoDB operator for the task:
+   - `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte` for comparisons
+   - `$in`, `$nin` for matching against a list of possible values (equivalent to multiple $eq/$ne conditions OR'ed together)
+   - `$and`, `$or`, `$not`, `$nor` for logical operations
+   - `$regex` for case-sensitive text pattern matching (prefer left-anchored patterns like `/^prefix/` when possible, as they can use indexes efficiently)
+   - `$exists` for field existence checks (prefer `a: {$ne: null}` to `a: {$exists: true}` to leverage available indexes)
+   - `$type` for type matching
+6. **Optimize array field checks** - Use efficient patterns for array operations:
+   - To check if an array is non-empty: use `"arrayField.0": {$exists: true}` instead of `arrayField: {$exists: true, $type: "array", $ne: []}`
+   - Checking for the first element's existence is simpler, more readable, and more efficient than combining existence, type, and inequality checks
+   - For matching array elements with multiple conditions, use `$elemMatch`
+   - For array length checks, use `$size` when you need an exact count
+
+### Aggregation Pipeline Quality
+1. **Filter early** - Use `$match` as early as possible to reduce documents
+2. **Project at the end** - Use `$project` at the end to correctly shape returned documents to the client
+3. **Limit when possible** - Add `$limit` after `$sort` when appropriate
+4. **Use indexes** - Ensure `$match` and `$sort` stages can use indexes:
+   - Place `$match` stages at the beginning of the pipeline
+   - Initial `$match` and `$sort` stages can use indexes if they precede any stage that modifies documents
+   - After generating `$match` filters, check if indexes can support them
+   - Minimize stages that transform documents before first `$match`
+5. **Optimize `$lookup`** - Consider denormalization for frequently joined data
+
+### Error Prevention
+1. **Validate all field references** against the schema
+2. **Quote field names correctly** - Use dot notation for nested fields
+3. **Escape special characters** in regex patterns
+4. **Check data types** - Ensure field values match field types from schema
+5. **Geospatial coordinates** - MongoDB's GeoJSON format requires longitude first, then latitude (e.g., `[longitude, latitude]` or `{type: "Point", coordinates: [lng, lat]}`). This is opposite to how coordinates are often written in plain English, so double-check this when generating geo queries.
+
+## Schema Analysis
+
+When provided with sample documents, analyze:
+1. **Field types** - String, Number, Boolean, Date, ObjectId, Array, Object
+2. **Field patterns** - Required vs optional fields (check multiple samples)
+3. **Nested structures** - Objects within objects, arrays of objects
+4. **Array elements** - Homogeneous vs heterogeneous arrays
+5. **Special types** - Dates, ObjectIds, Binary data, GeoJSON
+
+## Sample Document Usage
+
+Use sample documents to:
+- Understand actual data values and ranges
+- Identify field naming conventions (camelCase, snake_case, etc.)
+- Detect common patterns (e.g., status enums, category values)
+- Estimate cardinality for grouping operations
+- Validate that your query will work with real data
+
+## Error Handling
+
+If you cannot generate a query:
+1. **Explain why** - Missing schema, ambiguous request, impossible query
+2. **Ask for clarification** - Request more details about requirements
+3. **Suggest alternatives** - Propose different approaches if available
+4. **Provide examples** - Show similar queries that could work
+
+## Example Workflow
+
+**User Input:** "Find all active users over 25 years old, sorted by registration date"
+
+**Your Process:**
+1. Check schema for fields: `status`, `age`, `registrationDate` or similar
+2. Verify field types match the query requirements
+3. Generate query based on user requirements
+4. Check if available indexes can support the query
+5. Suggest creating an index if no appropriate index exists for the query filters
+
+**Generated Query:**
+```json
+{
+  "query": {
+    "filter": "{ status: 'active', age: { $gt: 25 } }",
+    "sort": "{ registrationDate: -1 }"
+  }
+}
+```
+
+## Managing Context Size
+
+Fetching large or numerous sample documents wastes context and can degrade query quality.
+
+**Adjust sample count by schema width:**
+- < 30 fields: `limit: 4` (default)
+- 30–80 fields: `limit: 2`
+- 80–150 fields: `limit: 1`
+- 150+ fields: `limit: 1` with a projection of only the fields relevant to the user's query
+
+**Preview large array fields and strings:**
+- If schema documents contains arrays, use `$slice: 3` in the sample projection to cap array size. Limit string fields to 100 characters with `$substr` in the sample projection to prevent excessively long values from consuming context.

package/dist/global-skills/mongodb-query-optimizer/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: mongodb-query-optimizer
+description: >-
+  Help with MongoDB query optimization and indexing. Use only when the user asks for optimization or performance: "How do I optimize this query?", "How do I index this?", "Why is this query slow?", "Can you fix my slow queries?", "What are the slow queries on my cluster?", etc. Do not invoke for general MongoDB query writing unless user asks for performance or index help. Prefer indexing as optimization strategy. Use MongoDB MCP when available.
+compatibility: >-
+  Best with MongoDB MCP server. Uses collection-indexes and explain when the connection string works; uses Atlas Performance Advisor when Atlas API is configured. Without either, suggest indexes from query shape only. User creates indexes in Atlas or migrations unless tooling allows otherwise.
+license: Apache-2.0
+metadata:
+  version: "1.0.0"
+---
+
+# MongoDB Query Optimizer
+
+## When this skill is invoked
+
+Invoke **only** when the user wants:
+
+- Query/index **optimization** or **performance** help  
+- **Why** a query is slow or **how to speed it up**  
+- **Slow queries** on their cluster and/or **how to optimize them**
+
+Do **not** invoke for routine query authoring unless the user has requested help with optimization, slow queries, or indexing.
+
+## High Level Workflow
+
+### General Performance Help
+
+If the user wants to examine slow queries, or is looking for general performance suggestions (not regarding any particular query):
+
+- Use MongoDB MCP server **atlas-get-performance-advisor** tool to fetch slow query logs and performance advisor output  
+- Make suggestions based on this information
+
+If Atlas MCP Server for Atlas is not configured or you don’t have enough information to run **atlas-get-performance-advisor** against the correct cluster, tell the user that general performance analysis requires Atlas MCP Server configuration with API credentials, and suggest they configure it or ask about a specific query instead.
+
+### Help with a Specific Query
+
+If the user is asking about a particular query:
+
+- Use **collection-indexes**, **explain**, and **find** MCP tools to get existing indexes on the collection, explain() output for the query, and a sample document from the collection  
+- Use **atlas-get-performance-advisor MCP** tool to fetch slow query logs and performance advisor output
+
+Then make an optimization suggestion based on collected information and MongoDB best practices and examples from reference files. Prefer creating an index that fully covers the query if possible. If you cannot use MongoDB MCP Server then still try to make a suggestion.
+
+## MCP: available tools
+
+**How to invoke.** Call the **MongoDB MCP server** with the **exact tool name** as `toolName` and a single **arguments object** as `arguments`. Do not pass the tool name as an option, query param, or nested key; pass it as the MCP tool name and the parameters as the arguments object. Full MCP Server tool reference: [MongoDB MCP Server Tools](https://www.mongodb.com/docs/mcp-server/tools/).
+
+**Database tools** (when the MCP cluster connection works):
+
+| Tool name (exact) | Arguments object |
+| :---- | :---- |
+| `collection-indexes` | `{ "database": "<db>", "collection": "<coll>" }` — both required strings. |
+| `explain` | `{ "database": "<db>", "collection": "<coll>", "method": [ { "name": "find", "arguments": { "filter": {...}, "sort": {...}, "limit": N } } ], "verbosity": "executionStats" }`. `method` is an array of one object: `name` is `"find"`, `"aggregate"`, or `"count"`; `arguments` holds that method's params (e.g. find: `filter`, `sort`, `limit`; aggregate: `pipeline`; count: `query`). Optional `verbosity`: `"queryPlanner"` (default), `"executionStats"`, `"queryPlannerExtended"`, `"allPlansExecution"`. |
+| `find` |  `{ "database": "<db>", "collection": "<coll>", "filter": {...}, "projection": {...}, "sort": {...}, "limit": N }` — `database`, `collection`, and `filter` are required. Optional: `projection`, `sort`, `limit`. |
+
+**Atlas tools** (when Atlas API credentials are configured):
+
+| Tool name (exact) | Arguments object |
+| :---- | :---- |
+| `atlas-list-projects` | `{}` or `{ "orgId": "<24-char hex>" }`. Returns projects with their IDs; use to get `projectId` for Performance Advisor. |
+| `atlas-get-performance-advisor` | **Required:** `"projectId"` (24-character hex string), `"clusterName"` (string, 1–64 chars, alphanumeric/underscore/dash). **Optional:** `"operations"` — array of strings from `"suggestedIndexes"`, `"dropIndexSuggestions"`, `"slowQueryLogs"`, `"schemaSuggestions"` (request only what you need); for slowQueryLogs only: `"since"` (ISO 8601 date-time), `"namespaces"` (array of `"db.coll"` strings). |
+
+For a user question, try to fetch information from both the connection string and Atlas API related to the query you are optimizing.
+
+### 1\. DB connection string works for MongoDB MCP
+
+Typical flow: call `collection-indexes` → `explain` → `find` (sample doc).
+
+- **`collection-indexes`** — Use the result's `classicIndexes` (each has `name`, `key`) to see if the query can already use an existing index.
+- **`explain`** — Run in `"queryPlanner"` mode first to check for COLLSCAN. If the query uses an index or the collection is very small, run again with `"executionStats"` (10-second timeout) to get docs scanned vs. returned.
+
+### 2\. Atlas API access works for MongoDB MCP
+
+If you need a project ID, call `atlas-list-projects` first. Then call `atlas-get-performance-advisor` with only the `operations` you need:
+
+| Operation value | Use when |
+| :---- | :---- |
+| `slowQueryLogs` | Fetching slow queries—**prioritize by slowest and most frequent**. Optional: `namespaces` to scope to a collection; `since` for a time window. |
+| `suggestedIndexes` | Fetching cluster index recommendations |
+| `dropIndexSuggestions` | User asks what to remove or reduce index overhead |
+| `schemaSuggestions` | User asks for schema/query-structure advice alongside indexes |
+
+Do not pass the MCP tool name as an `operations` value—`operations` is a separate argument listing what data to fetch.
+
+## Example workflow 1 (help with specific query)
+
+**User:** "Why is this query slow? `db.orders.find({status: 'shipped', region: 'US'}).sort({date: -1})`"
+
+**If MCP db connection is configured and the database + collection names are known**, run steps 1–3. Otherwise skip to step 4.
+
+1. **Check existing collection indexes:**
+   - Call `collection-indexes` with database=`store`, collection=`orders`
+   - Result shows: `{_id: 1}`, `{status: 1}`, `{date: -1}`
+
+2. **Run explain:**
+   - Call `explain` with method=`find`, filter=`{status: 'shipped', region: 'US'}`, sort=`{date: -1}`, verbosity=`queryPlanner` and `executionStats`
+   - Result: Uses `{status: 1}` index, then in-memory SORT, `totalKeysExamined: 50000`, `nReturned: 100`
+
+3. **Run find:**
+   - Call `find` with limit=1 to fetch a sample document to impute the schema.
+
+**If MCP Atlas connection is configured**, run step 4. Otherwise skip to step 5.
+
+4. **Run atlas-get-performance-advisor:**
+   - Try to get the cluster name from the MCP connection string, or ask the user for projectId/clusterName
+   - Use slowQueryLogs to fetch slow query logs from database=`store`, collection=`orders` in the past 24 hours
+   - Use suggestedIndexes to check for index suggestions for the query
+
+5. **Diagnose:** Based on explain output and slow query logs, this query targets 100 docs but scans 50K index entries (poor selectivity: 0.002). In-memory sort adds overhead. Index doesn't support both filter fields or sort.
+
+6. **Recommend:** Create compound index `{status: 1, region: 1, date: -1}` following ESR (two equality fields, then sort). This eliminates in-memory sort and improves selectivity by filtering on both status and region.
+
+If the MongoDB MCP server is not set up, follow best indexing practices.
+
+## Example workflow 2 (general database performance help)
+
+**User:** "Can you help with optimizing slow queries on my cluster?”
+
+1. **Run atlas-get-performance-advisor:**  
+   - Try to get the cluster name from the connection string and deduce the project name you need in atlas-list-projects; if you are not sure, then ask the user for cluster name and project id.
+   - Use slowQueryLogs to fetch slow query logs from the past 24 hours  
+   - Use suggestedIndexes  
+   - Use dropIndexSuggestions  
+   - Use schemaSuggestions  
+2. **Diagnose and Recommend:** Based on slow query logs and performance advisor advice, you can create the compound index `{status: 1, region: 1, date: -1}` on the `db.orders` collection to optimize queries such as `find({status: 'shipped', region: 'US'}).sort({date: -1})`
+
+Examine all performance advisor output as well as slow query logs. Provide information on what is being improved and why, and focus on suggestions that have the potential for greatest impact (e.g., indexes that affect the most queries, or queries that have the worst performance).
+
+## Load references
+
+Before beginning diagnosis and recommendation, load reference files.
+
+Always load:
+
+- `references/core-indexing-principles.md`
+- `references/antipattern-examples.md`
+
+Conditionally load these files:
+
+- **If diagnosing aggregation pipelines** → `references/aggregation-optimization.md`
+- **If diagnosing queries that change docs such as replaceOne, findOneAndUpdate, etc.** → `references/update-query-examples.md` for oplog-efficient updates and common update anti-patterns
+
+## Output
+
+- Keep answers short and clear: a few sentences on index and optimization suggestions, and reasoning behind them (e.g. general indexing principles, observing slow query logs in the cluster, or seeing advice in Performance Advisor)
+- Focus on highest impact indexes or optimizations - if you've omitted some optimizations let the user know and present them if asked.
+- Do not use strong language, such as saying “You should create these indexes and they will definitely improve application performance” \-  Explain they are suggestions for certain queries, and give the reasoning behind them.
+- Consider how many indexes already exist on the collection (if known) \- there shouldn’t generally be more than 20
+- Suggest removing indexes only if the suggestion comes from Atlas Performance Advisor
+- Do not create indexes directly via MCP unless the user gives approval