{"openapi":"3.0.1","info":{"title":"Kakoo RAG MCP Service API","description":"Professional RAG implementation with MCP server for Kakoo project documentation","contact":{"name":"Kakoo Team","email":"support@kakoo.com"},"license":{"name":"MIT License","url":"https://opensource.org/licenses/MIT"},"version":"1.0.0"},"servers":[{"url":"http://localhost:8080/kakoo-rag","description":"Local Development"},{"url":"https://your-domain.com/kakoo-rag","description":"Production"}],"security":[{"basicAuth":[]}],"tags":[{"name":"MCP Server","description":"Model Context Protocol server with SSE support"},{"name":"RAG Chat","description":"RAG-powered chat endpoints for Kakoo documentation"},{"name":"Actuator","description":"Monitor and interact","externalDocs":{"description":"Spring Boot Actuator Web API Documentation","url":"https://docs.spring.io/spring-boot/docs/current/actuator-api/html/"}},{"name":"Documents","description":"Document management for Kakoo RAG system"},{"name":"Health","description":"System health and status checks"}],"paths":{"/api/rag/simple-chat":{"post":{"tags":["RAG Chat"],"summary":"Simple chat without RAG","description":"Direct chat with AI model without document retrieval (for testing)","operationId":"simpleChat","requestBody":{"content":{"application/json":{"schema":{"type":"string","description":"Chat message"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}},"/api/rag/chat":{"post":{"tags":["RAG Chat"],"summary":"Ask question about Kakoo","description":"Submit question and get AI-powered answer based on Kakoo documentation","operationId":"askQuestion","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}}}}},"/api/mcp/execute":{"post":{"tags":["MCP Server"],"summary":"Execute MCP tool","description":"Execute MCP tool and stream results via SSE","operationId":"executeTool","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}},"/api/mcp/broadcast":{"post":{"tags":["MCP Server"],"summary":"Broadcast message","description":"Broadcast message to all connected MCP clients","operationId":"broadcastMessage","parameters":[{"name":"eventType","in":"query","description":"Event type","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Message data"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}},"/api/documents/{id}/reprocess":{"post":{"tags":["Documents"],"summary":"Reprocess document","description":"Regenerate chunks and embeddings for existing document","operationId":"reprocessDocument","parameters":[{"name":"id","in":"path","description":"Document ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}},"/api/documents/upload":{"post":{"tags":["Documents"],"summary":"Upload document","description":"Upload PDF, Word, or text document for RAG processing","operationId":"uploadDocument","parameters":[{"name":"description","in":"query","description":"Document description","required":false,"schema":{"type":"string"}},{"name":"autoProcess","in":"query","description":"Auto-process document after upload","required":false,"schema":{"type":"boolean","default":true}},{"name":"generateEmbeddings","in":"query","description":"Generate embeddings","required":false,"schema":{"type":"boolean","default":true}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"required":["file"],"type":"object","properties":{"file":{"type":"string","description":"Document file (PDF, DOC, DOCX, TXT)","format":"binary"}}}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}}}}},"/api/rag/health":{"get":{"tags":["RAG Chat"],"summary":"RAG service health check","operationId":"healthCheck","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}},"/api/mcp/tools":{"get":{"tags":["MCP Server"],"summary":"Get available tools","description":"List all available MCP tools and their descriptions","operationId":"getAvailableTools","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}}}}},"/api/mcp/status":{"get":{"tags":["MCP Server"],"summary":"Get MCP server status","description":"Get current status of MCP server and active connections","operationId":"getStatus","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}}}}},"/api/mcp/connect":{"get":{"tags":["MCP Server"],"summary":"Connect to MCP server","description":"Establish SSE connection for real-time MCP communication","operationId":"connect","parameters":[{"name":"sessionId","in":"query","description":"Session ID (optional)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/SseEmitter"}}}}}}},"/api/health":{"get":{"tags":["Health"],"summary":"General health check","operationId":"health","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}}}}},"/api/health/detailed":{"get":{"tags":["Health"],"summary":"Detailed health check with component status","operationId":"detailedHealth","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}}}}},"/api/documents":{"get":{"tags":["Documents"],"summary":"Get all documents","description":"Retrieve list of all uploaded documents","operationId":"getAllDocuments","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentResponse"}}}}}}}},"/api/documents/{id}":{"get":{"tags":["Documents"],"summary":"Get document by ID","description":"Retrieve specific document details","operationId":"getDocument","parameters":[{"name":"id","in":"path","description":"Document ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}}}},"delete":{"tags":["Documents"],"summary":"Delete document","description":"Delete document and its associated chunks and embeddings","operationId":"deleteDocument","parameters":[{"name":"id","in":"path","description":"Document ID","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}},"/api/documents/status/{status}":{"get":{"tags":["Documents"],"summary":"Get documents by status","description":"Retrieve documents filtered by processing status","operationId":"getDocumentsByStatus","parameters":[{"name":"status","in":"path","description":"Document status: UPLOADED, PROCESSING, PROCESSED, ERROR","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DocumentResponse"}}}}}}}},"/api/documents/stats":{"get":{"tags":["Documents"],"summary":"Get processing statistics","description":"Get document processing statistics and metrics","operationId":"getProcessingStats","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ProcessingStats"}}}}}}},"/actuator":{"get":{"tags":["Actuator"],"summary":"Actuator root web endpoint","operationId":"links","responses":{"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Link"}}}},"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Link"}}}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Link"}}}}}}}}},"/actuator/metrics":{"get":{"tags":["Actuator"],"summary":"Actuator web endpoint 'metrics'","operationId":"metrics","responses":{"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object"}}}}}}},"/actuator/metrics/{requiredMetricName}":{"get":{"tags":["Actuator"],"summary":"Actuator web endpoint 'metrics-requiredMetricName'","operationId":"metrics-requiredMetricName","parameters":[{"name":"requiredMetricName","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object"}}}}}}},"/actuator/info":{"get":{"tags":["Actuator"],"summary":"Actuator web endpoint 'info'","operationId":"info","responses":{"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object"}}}}}}},"/actuator/health":{"get":{"tags":["Actuator"],"summary":"Actuator web endpoint 'health'","operationId":"health","responses":{"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object"}}}}}}},"/actuator/health/**":{"get":{"tags":["Actuator"],"summary":"Actuator web endpoint 'health-path'","operationId":"health-path","responses":{"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object"}}}}}}},"/actuator/env":{"get":{"tags":["Actuator"],"summary":"Actuator web endpoint 'env'","operationId":"env","responses":{"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object"}}}}}}},"/actuator/env/{toMatch}":{"get":{"tags":["Actuator"],"summary":"Actuator web endpoint 'env-toMatch'","operationId":"env-toMatch","parameters":[{"name":"toMatch","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/vnd.spring-boot.actuator.v3+json":{"schema":{"type":"object"}},"application/json":{"schema":{"type":"object"}},"application/vnd.spring-boot.actuator.v2+json":{"schema":{"type":"object"}}}}}}},"/api/mcp/disconnect/{sessionId}":{"delete":{"tags":["MCP Server"],"summary":"Disconnect MCP client","description":"Close SSE connection for specific session","operationId":"disconnect","parameters":[{"name":"sessionId","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ChatRequest":{"required":["question"],"type":"object","properties":{"question":{"maxLength":2000,"minLength":0,"type":"string"},"sessionId":{"maxLength":100,"minLength":0,"type":"string"},"includeSourceReferences":{"type":"boolean"},"maxResults":{"type":"integer","format":"int32"},"similarityThreshold":{"type":"number","format":"double"}}},"ChatResponse":{"type":"object","properties":{"answer":{"type":"string"},"question":{"type":"string"},"sessionId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"hasRelevantSources":{"type":"boolean"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceReference"}},"responseType":{"type":"string","enum":["RAG_ANSWER","NO_RELEVANT_INFO","ERROR","PARTIAL_ANSWER"]},"processingTimeMs":{"type":"string"},"ragMetrics":{"$ref":"#/components/schemas/RagMetrics"}}},"RagMetrics":{"type":"object","properties":{"totalChunksSearched":{"type":"integer","format":"int32"},"relevantChunksFound":{"type":"integer","format":"int32"},"retrievalTimeMs":{"type":"integer","format":"int64"},"generationTimeMs":{"type":"integer","format":"int64"},"averageRelevanceScore":{"type":"number","format":"double"}}},"SourceReference":{"type":"object","properties":{"documentId":{"type":"integer","format":"int64"},"documentName":{"type":"string"},"chunkContent":{"type":"string"},"relevanceScore":{"type":"number","format":"double"},"chunkIndex":{"type":"integer","format":"int32"},"startPosition":{"type":"integer","format":"int32"},"endPosition":{"type":"integer","format":"int32"}}},"McpRequest":{"required":["toolName"],"type":"object","properties":{"toolName":{"type":"string"},"parameters":{"type":"object","additionalProperties":{"type":"object"}},"sessionId":{"type":"string"},"streamResponse":{"type":"boolean"}}},"DocumentResponse":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"fileName":{"type":"string"},"originalFileName":{"type":"string"},"contentType":{"type":"string"},"fileSize":{"type":"integer","format":"int64"},"description":{"type":"string"},"status":{"type":"string","enum":["UPLOADED","PROCESSING","PROCESSED","ERROR","ARCHIVED"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"chunkCount":{"type":"integer","format":"int32"},"processingMessage":{"type":"string"}}},"SseEmitter":{"type":"object","properties":{"timeout":{"type":"integer","format":"int64"}}},"ProcessingStats":{"type":"object","properties":{"totalDocuments":{"type":"integer","format":"int64"},"processedDocuments":{"type":"integer","format":"int64"},"processingDocuments":{"type":"integer","format":"int64"},"errorDocuments":{"type":"integer","format":"int64"},"totalChunks":{"type":"integer","format":"int64"},"chunksWithEmbeddings":{"type":"integer","format":"int64"}}},"Link":{"type":"object","properties":{"href":{"type":"string"},"templated":{"type":"boolean"}}}},"securitySchemes":{"basicAuth":{"type":"http","description":"Basic Authentication with username and password","scheme":"basic"}}}}