Agent Knowledge MCP

Instructions

Implementation Reference

• src/elasticsearch/sub_servers/elasticsearch_document.py:34-77 (handler)

  The primary handler implementation for the 'delete_document' tool. Includes the @app.tool decorator for registration and input schema definition using Pydantic's Annotated and Field. Executes Elasticsearch delete operation with comprehensive error handling and user-friendly messages.

  @app.tool(
      description="Delete a document from Elasticsearch index by document ID",
      tags={"elasticsearch", "delete", "document"}
  )
  async def delete_document(
          index: Annotated[str, Field(description="Name of the Elasticsearch index containing the document")],
          doc_id: Annotated[str, Field(description="Document ID to delete from the index")]
  ) -> str:
      """Delete a document from Elasticsearch index."""
      try:
          es = get_es_client()
  
          result = es.delete(index=index, id=doc_id)
  
          return f"✅ Document deleted successfully:\n\n{json.dumps(result, indent=2, ensure_ascii=False)}"
  
      except Exception as e:
          # Provide detailed error messages for different types of Elasticsearch errors
          error_message = "❌ Failed to delete document:\n\n"
  
          error_str = str(e).lower()
          if "connection" in error_str or "refused" in error_str:
              error_message += "🔌 **Connection Error**: Cannot connect to Elasticsearch server\n"
              error_message += f"📍 Check if Elasticsearch is running at the configured address\n"
              error_message += f"💡 Try: Use 'setup_elasticsearch' tool to start Elasticsearch\n\n"
          elif (
                  "not_found" in error_str or "not found" in error_str or "does not exist" in error_str) or "index_not_found_exception" in error_str or "no such index" in error_str:
              # Check if it's specifically an index not found error
              if ("index" in error_str and (
                      "not found" in error_str or "not_found" in error_str or "does not exist" in error_str)) or "index_not_found_exception" in error_str or "no such index" in error_str:
                  error_message += f"📁 **Index Not Found**: Index '{index}' does not exist\n"
                  error_message += f"📍 The target index has not been created yet\n"
                  error_message += f"💡 Try: Use 'list_indices' to see available indices\n\n"
              else:
                  error_message += f"📄 **Document Not Found**: Document ID '{doc_id}' does not exist\n"
                  error_message += f"📍 Cannot delete a document that doesn't exist\n"
                  error_message += f"💡 Try: Check document ID or use 'search' to find documents\n\n"
          else:
              error_message += f"⚠️ **Unknown Error**: {str(e)}\n\n"
  
          error_message += f"🔍 **Technical Details**: {str(e)}"
  
          return error_message

• src/elasticsearch/elasticsearch_server.py:27-51 (registration)

  Mounting/registration of the elasticsearch_document sub-server app (containing delete_document tool) into the unified Elasticsearch FastMCP server app.

  from .sub_servers.elasticsearch_document import app as document_app
  from .sub_servers.elasticsearch_index import app as index_app
  from .sub_servers.elasticsearch_search import app as search_app
  from .sub_servers.elasticsearch_batch import app as batch_app
  
  # Create unified FastMCP application
  app = FastMCP(
      name="AgentKnowledgeMCP-Elasticsearch",
      version="2.0.0",
      instructions="Unified Elasticsearch tools for comprehensive knowledge management via modular server mounting"
  )
  
  # ================================
  # SERVER MOUNTING - MODULAR ARCHITECTURE
  # ================================
  
  print("🏗️ Mounting Elasticsearch sub-servers...")
  
  # Mount all sub-servers into unified interface
  app.mount(snapshots_app)           # 3 tools: snapshot management
  app.mount(index_metadata_app)      # 3 tools: metadata governance  
  app.mount(document_app)            # 3 tools: document operations
  app.mount(index_app)               # 3 tools: index management
  app.mount(search_app)              # 2 tools: search & validation
  app.mount(batch_app)               # 2 tools: batch operations

• src/main_server.py:74-85 (registration)

  Mounting of the unified elasticsearch_server_app (which includes the delete_document tool via sub-server mounting) into the main FastMCP server.

  # Mount Elasticsearch server with 'es' prefix
  # This provides: es_search, es_index_document, es_create_index, etc.
  app.mount(elasticsearch_server_app)
  
  # Mount Administrative operations server with 'admin' prefix
  # This provides: admin_get_config, admin_update_config, admin_server_status, etc.
  app.mount(admin_server_app)
  
  # Mount Prompt server for AgentKnowledgeMCP guidance
  # This provides: usage_guide, help_request (prompts for LLM assistance)
  app.mount(prompt_server_app)

• src/confirmation/confirmation.py:96-99 (helper)

  Configuration listing 'delete_document' as a destructive operation requiring user confirmation via the middleware system.

  "destructive_operations": {
      "tools": ["delete_file", "delete_directory", "delete_index", "delete_document"],
      "require_confirmation": True,
      "timeout_minutes": 30