312 lines
6.4 KiB
Markdown
312 lines
6.4 KiB
Markdown
# 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
|
|
|
|
|