npmplus-mcp-server/docs/MCP_USAGE_INDICATORS.md

Production-ready MCP server for intelligent JavaScript package management. Works with Claude, Windsurf, Cursor, VS Code, and any MCP-compatible AI editor.

# How to Know if NPM Plus MCP is Being Used

## 🔍 Visual Indicators in Each Editor

### Claude Desktop
**Look for these signs:**
- 🔧 **Tool use blocks** appear in the conversation
- Shows "Using search_packages..." or similar messages
- Results appear in structured format with icons
- You'll see "MCP" or tool names in the response

**Example:**
```
You: Search for React testing libraries

Claude: I'll search for React testing libraries for you.

[Tool use: search_packages with query "React testing"]

🔍 Search results for "React testing":

1. 📦 **@testing-library/react**
   Version: 14.1.2
   Description: Simple and complete React DOM testing utilities
```

### Windsurf
**Look for these signs:**
- 🤖 **"AI is using tools"** indicator in the UI
- Tool names appear in the activity bar
- Structured responses with package data
- Progress indicators during tool execution

**Visual cues:**
- Loading spinner with tool name
- "Executing npmplus-mcp..." status
- Results in formatted tables or lists

### Cursor
**Look for these signs:**
- 📊 **Tool usage** shown in chat sidebar
- "Using MCP server: npmplus-mcp" message
- Formatted output with package details
- Tool execution time displayed

**Example:**
```
You: What's the bundle size of lodash?

Cursor: Let me check the bundle size of lodash for you.

→ Using npmplus-mcp.check_bundle_size
→ Execution time: 1.2s

📊 Bundle Size Analysis for lodash:
Minified: 69.4 KB
Minified + Gzipped: 24.7 KB
```

### VS Code + Cline
**Look for these signs:**
- 🔗 **@npmplus-mcp** tag is highlighted
- "Invoking MCP tool..." notification
- Output shows in OUTPUT panel
- Tool results in formatted blocks

**Example:**
```
You: @npmplus-mcp search for express middleware

Cline: Invoking npmplus-mcp.search_packages...

[MCP Tool Output]
🔍 Search results for "express middleware":
1. body-parser - Parse incoming request bodies
2. cors - Enable CORS with various options
```

## 📊 How to Verify MCP is Active

### 1. **Check Configuration Status**

**Claude Desktop:**
- Open developer tools (Ctrl+Shift+I)
- Look for MCP connections in console
- Check for "npmplus-mcp" in active servers

**Windsurf:**
```bash
# In Windsurf terminal
windsurf --list-mcp-servers
```

**Cursor:**
- Command Palette → "Developer: Show Logs"
- Look for MCP initialization messages

**VS Code + Cline:**
- View → Output → Select "Cline"
- Look for "MCP server started: npmplus-mcp"

### 2. **Test Commands**

Try these test commands to verify MCP is working:

```
// Simple test
"MCP status"
"List available MCP tools"
"@npmplus-mcp test"

// Functional test
"Search for a package called express"
"What tools does npmplus-mcp provide?"
```

### 3. **Check Response Format**

**With MCP Active:**
- Structured data with icons
- Detailed package information
- Real-time data from npm registry
- Execution time shown

**Without MCP:**
- Generic text responses
- No real package data
- AI knowledge cutoff limitations
- No execution indicators

## 🎯 MCP Usage Patterns

### Direct Invocation
```
@npmplus-mcp search packages    ✅ Definitely using MCP
@npmplus-mcp.search_packages     ✅ Definitely using MCP
```

### Natural Language (Auto-detection)
```
"Search for React packages"      ⚡ May use MCP (check indicators)
"Install express"                ⚡ May use MCP (check indicators)
"Check bundle size"              ⚡ May use MCP (check indicators)
```

### Explicit Request
```
"Use NPM Plus to search"         ✅ Will use MCP if available
"With npmplus-mcp, check..."     ✅ Will use MCP if available
```

## 🚨 When MCP is NOT Being Used

**You'll see:**
- Generic responses without real data
- "I would help you..." instead of actual results
- No tool usage indicators
- Knowledge cutoff limitations mentioned
- Suggestions to run npm commands manually

**Example without MCP:**
```
You: Search for React testing libraries

AI: To search for React testing libraries, you can use npm search:
`npm search react testing`

Some popular React testing libraries include:
- @testing-library/react (based on my knowledge)
- enzyme (note: may be outdated)
- react-test-renderer

For current information, please check npm directly.
```

## 📈 MCP Activity Monitoring

### Analytics Dashboard
If analytics are enabled, you can see:
- Tool usage frequency
- Success/failure rates
- Response times
- Most used tools

### Log Files
Check these locations:
- **Claude**: `~/Library/Logs/Claude/`
- **Windsurf**: `.windsurf/logs/`
- **Cursor**: `.cursor/logs/`
- **VS Code**: `.vscode/logs/`

Look for entries like:
```
[MCP] Tool invoked: search_packages
[MCP] Server: npmplus-mcp
[MCP] Duration: 523ms
[MCP] Status: success
```

## 🔧 Troubleshooting No MCP Usage

If MCP isn't being used when expected:

1. **Verify Configuration**
   ```json
   // Should see npmplus-mcp in config
   {
     "mcpServers": {
       "npmplus-mcp": { ... }
     }
   }
   ```

2. **Restart Editor**
   - Configuration changes require restart
   - Check for initialization errors

3. **Test Explicitly**
   ```
   @npmplus-mcp test connection
   @npmplus-mcp list tools
   ```

4. **Check Permissions**
   - Firewall blocking for hosted service
   - NPX permissions for local install

## 💡 Best Practices

1. **Be Explicit** when you want MCP:
   - "Use NPM Plus to..."
   - "@npmplus-mcp ..."
   - "With the MCP tool..."

2. **Watch for Indicators**:
   - Tool usage messages
   - Structured output
   - Real-time data

3. **Verify Important Operations**:
   - Security audits
   - Package installations
   - Bundle size checks

Always look for the visual indicators and structured output to confirm MCP is being used!