AI_INSTRUCTIONS_CLEAR.md•9.06 kB
# 🚨 CRITICAL AI INSTRUCTIONS - SRT TRANSLATION MCP SERVER 🚨
## ⚠️ IMMEDIATE ATTENTION REQUIRED ⚠️
**READ THIS ENTIRE DOCUMENT BEFORE USING ANY FUNCTIONS**
This document provides **CRYSTAL CLEAR** instructions for AI systems to avoid the common mistakes that lead to placeholder text instead of actual translations.
---
## 🎯 THE FUNDAMENTAL RULE
### ❌ NEVER DO THIS:
- ❌ Try to extract text from `detect_conversations` responses
- ❌ Expect translated text from metadata functions
- ❌ Use `detect_conversations` for actual translation
- ❌ Try to read subtitle content from analysis responses
### ✅ ALWAYS DO THIS:
- ✅ Use `detect_conversations` ONLY for planning and analysis
- ✅ Use `translate_srt` for actual translation
- ✅ Use `get_next_chunk` for retrieving actual text content
- ✅ Follow the exact workflow steps below
---
## 🔥 FUNCTION PURPOSE MATRIX
| Function | Purpose | Returns | Use For |
|----------|---------|---------|---------|
| `detect_conversations` | **ANALYSIS ONLY** | Metadata, chunk info, language detection | Planning, understanding file structure |
| `get_next_chunk` | **TEXT RETRIEVAL** | Actual subtitle text content | Getting real text for translation |
| `translate_srt` | **ACTUAL TRANSLATION** | Complete translated SRT file | Producing final translated output |
| `todo_management` | **PROGRESS TRACKING** | Task status updates | Managing workflow progress |
---
## 📋 STEP-BY-STEP WORKFLOW (FOLLOW EXACTLY)
### STEP 1: ANALYZE FILE (METADATA ONLY)
```json
{
"tool": "detect_conversations",
"parameters": {
"content": "path/to/file.srt",
"storeInMemory": true,
"createTodos": true
}
}
```
**What you get back:**
- ✅ File structure analysis
- ✅ Language detection results
- ✅ Chunk boundaries and timing
- ✅ Translation priorities
- ❌ **NO ACTUAL TEXT CONTENT**
- ❌ **NO TRANSLATED TEXT**
**What to do with this:**
- Review the metadata to understand the file
- Note the language distribution
- Plan your translation strategy
- **DO NOT try to extract text from this response**
### STEP 2: GET ACTUAL TEXT CONTENT
```json
{
"tool": "get_next_chunk",
"parameters": {
"sessionId": "session-id-from-step-1"
}
}
```
**What you get back:**
- ✅ **ACTUAL SUBTITLE TEXT CONTENT**
- ✅ Chunk index and progress info
- ✅ Real subtitle data for translation
**What to do with this:**
- Use the actual text content for translation
- This contains the real subtitle text you need to translate
### STEP 3: PREPARE FOR AI TRANSLATION (HELPER TOOL)
```json
{
"tool": "translate_srt",
"parameters": {
"content": "ACTUAL_CHUNK_CONTENT_FROM_STEP_2",
"targetLanguage": "es",
"sourceLanguage": "en"
}
}
```
**What you get back:**
- ✅ **STRUCTURED DATA FOR AI TRANSLATION**
- ✅ Original text with translation instructions
- ✅ Timing and formatting information
- ❌ **NO TRANSLATED TEXT** (AI must do the translation)
### STEP 4: AI TRANSLATION WORK
- AI assistant translates the text content from the structured data
- AI assistant combines results into final SRT file
---
## 🚨 COMMON MISTAKES AND HOW TO AVOID THEM
### MISTAKE 1: Trying to extract text from metadata
```javascript
// ❌ WRONG - This will give you placeholders
const metadata = await detect_conversations({content: "file.srt"});
const text = metadata.chunks[0].content; // This doesn't exist!
```
```javascript
// ✅ CORRECT - Get actual text content
const chunk = await get_next_chunk({sessionId: "session-id"});
const text = chunk.chunk.content; // This contains real text
```
### MISTAKE 2: Expecting translation from helper tools
```javascript
// ❌ WRONG - translate_srt is a helper tool only
const result = await translate_srt({content: "file.srt", targetLanguage: "es"});
// This returns structured data, NOT translated text!
```
```javascript
// ✅ CORRECT - AI assistant does the translation
const prepared = await translate_srt({
content: "actual_subtitle_content",
targetLanguage: "es"
});
// AI assistant translates the prepared data
const translated = await aiTranslate(prepared);
```
### MISTAKE 3: Not following the workflow
```javascript
// ❌ WRONG - Skipping steps
const translated = await translate_srt({
content: "file.srt", // This is a file path, not content!
targetLanguage: "es"
});
```
```javascript
// ✅ CORRECT - Follow the complete workflow
// Step 1: Analyze
const analysis = await detect_conversations({
content: "file.srt",
storeInMemory: true
});
// Step 2: Get actual content
const chunk = await get_next_chunk({
sessionId: analysis.sessionId
});
// Step 3: Prepare for AI translation
const prepared = await translate_srt({
content: chunk.chunk.content,
targetLanguage: "es"
});
// Step 4: AI assistant translates the prepared data
const translated = await aiTranslate(prepared);
```
---
## 🎯 COMPLETE WORKFLOW EXAMPLE
Here's a complete example that will work correctly:
```javascript
// STEP 1: Analyze the file (METADATA ONLY)
const analysis = await mcp_call('detect_conversations', {
content: 'English.srt',
storeInMemory: true,
createTodos: true
});
console.log('Analysis complete. Session ID:', analysis.sessionId);
console.log('Language distribution:', analysis.languageDistribution);
console.log('Total chunks:', analysis.chunkCount);
// STEP 2: Process chunks one by one
let chunkIndex = 0;
let translatedChunks = [];
while (true) {
// Get the next chunk with actual text content
const chunk = await mcp_call('get_next_chunk', {
sessionId: analysis.sessionId
});
if (!chunk.hasMore) {
break; // No more chunks
}
console.log(`Processing chunk ${chunkIndex + 1} of ${chunk.totalChunks}`);
// STEP 3: Prepare for AI translation
const prepared = await mcp_call('translate_srt', {
content: chunk.chunk.content, // This is the actual text!
targetLanguage: 'es',
sourceLanguage: 'en'
});
// STEP 4: AI assistant translates the prepared data
const translated = await aiTranslate(prepared);
translatedChunks.push(translated);
chunkIndex++;
}
// Combine all translated chunks
const finalTranslation = translatedChunks.join('\n\n');
console.log('Translation complete!');
```
---
## 🔍 DEBUGGING GUIDE
### If you're getting placeholder text:
1. **Check what function you're calling:**
- `detect_conversations` = Metadata only (no text)
- `translate_srt` = Actual translation (real text)
2. **Check your workflow:**
- Did you call `detect_conversations` first?
- Did you get a `sessionId`?
- Did you call `get_next_chunk` to get actual text?
- Did you pass the actual text to `translate_srt`?
3. **Check your parameters:**
- Are you passing file content, not file paths?
- Are you using the correct session ID?
- Are you passing actual subtitle text to translate?
### If you're getting errors:
1. **File not found:** Make sure the file path is correct
2. **Session ID invalid:** Make sure you're using the session ID from `detect_conversations`
3. **Empty content:** Make sure you're passing actual text content, not metadata
---
## 📊 RESPONSE STRUCTURE REFERENCE
### detect_conversations Response:
```json
{
"sessionId": "srt-session-123456789",
"chunkCount": 59,
"languageDistribution": {"en": 59},
"chunks": [
{
"id": "chunk-0",
"startTime": "0:0:2",
"endTime": "0:0:13",
"languageInfo": {"primary": "en", "confidence": 0.95},
"translationPriority": "high",
"complexity": "medium",
"topicKeywords": ["hello", "world", "this"]
// ❌ NO ACTUAL TEXT CONTENT HERE
}
]
}
```
### get_next_chunk Response:
```json
{
"chunk": {
"id": "chunk-0",
"content": "1\n00:00:02,000 --> 00:00:07,000\nHello world\n\n2\n00:00:07,000 --> 00:00:13,000\nThis is a test",
"startTime": "0:0:2",
"endTime": "0:0:13"
},
"chunkIndex": 0,
"totalChunks": 59,
"hasMore": true,
"message": "Retrieved chunk 1 of 59"
}
```
### translate_srt Response:
```json
{
"content": [
{
"type": "text",
"text": "1\n00:00:02,000 --> 00:00:07,000\nHola mundo\n\n2\n00:00:07,000 --> 00:00:13,000\nEsto es una prueba"
}
]
}
```
---
## 🎯 FINAL REMINDER
**THE GOLDEN RULE:**
- `detect_conversations` = Planning and analysis (metadata only)
- `get_next_chunk` = Getting actual text content
- `translate_srt` = Producing actual translated text
**FOLLOW THE WORKFLOW:**
1. Analyze with `detect_conversations`
2. Get text with `get_next_chunk`
3. Translate with `translate_srt`
**NEVER SKIP STEPS OR MIX FUNCTIONS!**
---
## 🆘 EMERGENCY TROUBLESHOOTING
If you're still getting placeholder text:
1. **Stop and read this document again**
2. **Check which function you're calling**
3. **Verify you're following the exact workflow**
4. **Make sure you're passing actual text content to translate_srt**
Remember: The system is designed to prevent context overflow by separating analysis from translation. Follow the workflow exactly, and you'll get real translated text every time.