# MCP Tools Documentation

Your MCP server now has **4 specialized tools** for working with the MS SQL Server Infra database.

## 🔧 Available Tools

### 1. `execute_sql`
**Description:** Execute custom read-only SQL queries

**Parameters:**
- `query` (string, required): SQL SELECT query to execute

**Example:**
```javascript
{
  "query": "SELECT TOP 10 Teil, Bez, Hersteller FROM TEILE WHERE Hersteller LIKE '%Bosch%'"
}
```

**Use Cases:**
- Complex queries with JOINs
- Aggregations (COUNT, SUM, AVG, etc.)
- Custom filtering and sorting
- Any read-only data analysis

---

### 2. `list_tables`
**Description:** List all available tables in the Infra database

**Parameters:** None

**Example:**
```javascript
{}
```

**Returns:**
```json
[
  { "TABLE_NAME": "TEILE" },
  ...
]
```

**Use Cases:**
- Discover what tables exist
- Explore database structure
- Find table names for queries

---

### 3. `describe_table`
**Description:** Get detailed schema information for a specific table

**Parameters:**
- `table_name` (string, required): Name of the table to describe

**Example:**
```javascript
{
  "table_name": "TEILE"
}
```

**Returns:**
```json
[
  {
    "COLUMN_NAME": "Teil",
    "DATA_TYPE": "nchar",
    "CHARACTER_MAXIMUM_LENGTH": 15,
    "IS_NULLABLE": "YES",
    "COLUMN_DEFAULT": null
  },
  {
    "COLUMN_NAME": "Bez",
    "DATA_TYPE": "nchar",
    "CHARACTER_MAXIMUM_LENGTH": 160,
    "IS_NULLABLE": "YES",
    "COLUMN_DEFAULT": null
  },
  ...
]
```

**Use Cases:**
- Understand table structure before querying
- Check column data types
- Verify column names
- See which columns allow NULL values

---

### 4. `search_parts`
**Description:** Quick search across the TEILE table

**Parameters:**
- `search_term` (string, required): Term to search for
- `limit` (number, optional): Max results per table (default: 50)

**Example:**
```javascript
{
  "search_term": "Bosch",
  "limit": 20
}
```

**Returns:**
```json
[
  {
    "TableName": "TEILE",
    "Teil": "10.1.000040",
    "Art": "2",
    "Gruppe": "CA",
    "Bez": "ITT1 Bosch LST-Motorkabel 15m",
    "Bez2": "ITT1 Bosch LST motor cable 15m",
    "Hersteller": "SDS",
    "WarenNr": null
  },
  ...
]
```

**Searches in:**
- Teil (Part number)
- Bez (Description)
- Bez2 (Description 2)
- Hersteller (Manufacturer)

**Use Cases:**
- Quick part lookup
- Find parts by manufacturer
- Search by description
- Find part numbers

---

## 🔒 Security Features

All tools enforce read-only access:
- ✅ Only SELECT queries allowed
- ✅ Blocks INSERT, UPDATE, DELETE, DROP, etc.
- ✅ Prevents query chaining with semicolons
- ✅ Blocks stored procedure execution
- ✅ SQL injection protection with parameter escaping

---

## 📝 Usage in Cursor/AI

The AI can now use these tools automatically. Examples:

**Question:** "Show me all Bosch parts"
**AI will use:** `search_parts` tool with `{ "search_term": "Bosch" }`

**Question:** "What columns does TEILE have?"
**AI will use:** `describe_table` tool with `{ "table_name": "TEILE" }`

**Question:** "List all tables in the database"
**AI will use:** `list_tables` tool

**Question:** "Find all parts with weight over 1kg"
**AI will use:** `execute_sql` tool with a custom query

---

## 🧪 Testing the MCP Server

### Test Tool Listing
```bash
# Use Cursor's MCP inspector or call the server directly
# The server should list all 4 tools
```

### Test Execute SQL
Query:
```json
{
  "name": "execute_sql",
  "arguments": {
    "query": "SELECT TOP 5 Teil, Bez FROM TEILE"
  }
}
```

### Test Search Parts
Query:
```json
{
  "name": "search_parts",
  "arguments": {
    "search_term": "Kabel",
    "limit": 10
  }
}
```

### Test List Tables
Query:
```json
{
  "name": "list_tables",
  "arguments": {}
}
```

### Test Describe Table
Query:
```json
{
  "name": "describe_table",
  "arguments": {
    "table_name": "TEILE"
  }
}
```

---

> Note: The former import tables `SDS_Teile` and `SDS_Teile_**` are no longer used.  
> All queries should now use the productive `TEILE` table instead.

---

## 🔄 Restart MCP Server

After making changes, restart Cursor to reload the MCP server:
1. Close Cursor completely
2. Reopen Cursor
3. The MCP server will start automatically

Or check Cursor's MCP server status in Settings → MCP Servers

---

## 📊 Tool Selection Guide

| Task | Best Tool | Why |
|------|----------|-----|
| Quick part search | `search_parts` | Optimized for common searches |
| Complex filtering | `execute_sql` | Full SQL flexibility |
| Explore database | `list_tables` | See what's available |
| Check columns | `describe_table` | Understand table structure |
| Joins/aggregations | `execute_sql` | Custom query needed |
| Multi-table search | `search_parts` | Searches across tables |

---

## 🎯 Example Workflows

### Workflow 1: Find a Part
1. Use `search_parts` to find parts by keyword
2. Use `describe_table` if you need more column details
3. Use `execute_sql` for precise filtering

### Workflow 2: Explore New Table
1. Use `list_tables` to see all tables
2. Use `describe_table` to understand structure
3. Use `execute_sql` to query data

### Workflow 3: Complex Analysis
1. Use `describe_table` to check available columns
2. Use `execute_sql` with JOINs/aggregations
3. Use `search_parts` for quick validation

---

## 🚨 Error Handling

All tools return helpful error messages:

**Error Example:**
```json
{
  "error": "Forbidden keyword detected: DELETE. Only SELECT queries are allowed!"
}
```

**Common Errors:**
- "Only SELECT queries are allowed" → Tried to modify data
- "Multiple statements not allowed" → Query contains semicolon
- "Table not found" → Table name doesn't exist
- "Invalid column name" → Column doesn't exist in table

---

## 📈 Performance Tips

1. **Use LIMIT:** Add `TOP N` to queries for faster results
2. **Specific columns:** Select only needed columns, not `*`
3. **Index-aware:** Filter on Teil (likely indexed) when possible
4. **Use search_parts:** For simple searches, it's optimized
5. **Avoid LIKE %term%:** If possible, use `LIKE 'term%'` (faster)

---

## 🔐 Best Practices

1. ✅ **Use describe_table** before complex queries
2. ✅ **Start with small limits** (TOP 10) when testing
3. ✅ **Validate table names** with list_tables first
4. ✅ **Use search_parts** for simple part lookups
5. ✅ **Keep queries focused** - one question per query
6. ❌ **Don't** try to modify data (will be blocked)
7. ❌ **Don't** chain multiple queries with semicolons
8. ❌ **Don't** use stored procedures or functions