InitalCommit
This commit is contained in:
311
MCP_TOOLS.md
Normal file
311
MCP_TOOLS.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user