Sakeliga/advanced-elastic-mcp-api

Elasticsearch Advanced MCP Documentation

📚 Documentation Index

Welcome to the documentation for the Elasticsearch Advanced MCP Server and API. This system provides both Model Context Protocol (MCP) tools and REST API endpoints for semantic search and document management using Elasticsearch with ELSER v2.

Core Documentation

Additional Resources

---

🚀 What Can You Do?

With REST API

• Search Operations

  • Semantic search with ELSER v2
  • File-filtered search
  • Document discovery by topic

• Document Management

  • Write single documents
  • Bulk write multiple documents
  • Automatic ELSER indexing

With MCP Tools

• AI Assistant Integration

  • Direct tool access in Claude
  • Natural language interaction
  • Complex workflow automation

• Same Functionality

  • All API features available as MCP tools
  • Consistent behavior across interfaces
  • Full feature parity maintained

---

🎯 Choose Your Path

I want to...

Build a web application →

Use our REST API to integrate Elasticsearch semantic search into your application.

Use with Claude/AI assistants →

Connect AI assistants directly to your Elasticsearch data.

Get started quickly →

Set up and run your first search in 5 minutes.

Understand the architecture →

Learn how ELSER v2, LangChain, and our system components work together.

---

🔑 Key Features

Semantic Search with ELSER v2

• Context-aware search - Find documents by meaning, not just keywords
• 18% better relevance than traditional BM25 search
• No training required - Pre-trained model from Elastic
• Sparse vectors - More efficient than dense embeddings

Document Intelligence

• Admiralty Code ratings - Standard intelligence credibility scoring
• Security classifications - RESTRICTED, CONFIDENTIAL, SECRET
• Rich metadata - Track sources, timestamps, and properties
• Document relationships - Link chunks to parent documents

Dual Interface

• REST API - Standard HTTP endpoints for any application
• MCP Tools - Direct integration with AI assistants
• Feature parity - All features available in both interfaces
• Consistent behavior - Same results regardless of interface

---

📊 System at a Glance

┌─────────────────────────────────────────────────────┐
│                    Your Application                  │
│                         or                           │
│                    AI Assistant (Claude)             │
└─────────────┬────────────────────┬──────────────────┘
              │                    │
              ▼                    ▼
      ┌──────────────┐    ┌──────────────┐
      │   REST API   │    │  MCP Tools   │
      │  Port: 8001  │    │  Port: 8000  │
      └──────┬───────┘    └──────┬───────┘
              │                    │
              └────────┬───────────┘
                       ▼
            ┌─────────────────────┐
            │  Core Search Engine  │
            │   (ELSER v2 + ES)   │
            └─────────────────────┘
                       ▼
            ┌─────────────────────┐
            │  Elasticsearch Cloud │
            │   Your Documents     │
            └─────────────────────┘

---

🛠️ Technology Stack

---

📈 Performance Characteristics

---

🔒 Security Features

Document Classification

• Three-tier system: RESTRICTED, CONFIDENTIAL, SECRET
• Mandatory classification: Every document must be classified
• Filter by classification: Search within security levels

Credibility Scoring (Admiralty Code)

• Source reliability: A (completely reliable) to F (unknown)
• Information credibility: 1 (confirmed) to 6 (unknown)
• Industry standard: Used by intelligence agencies worldwide

Access Control

• Environment configuration: Writable index protected
• No index injection: Users cannot specify target indices
• API authentication ready: Add your auth layer

---

📞 Getting Help

Quick Links

• Issues: GitHub Issues
• Source Code: GitHub Repository
• Elasticsearch Docs: Elastic.co
• ELSER Guide: ELSER Documentation

Common Questions

Q: Should I use the API or MCP tools? A: Use the API for traditional applications, MCP for AI assistants. Both offer identical functionality.

Q: How do I choose credibility scores? A: See the in our MCP documentation.

Q: Why are searches taking 2+ seconds? A: ELSER v2 semantic processing adds overhead but provides much better relevance than keyword search.

Q: Can I specify which index to write to? A: No, for security the writable index is configured via environment variables only.

---

🎓 Learning Path

1. Start Here: - Get running in 5 minutes
2. Choose Interface: or documentation
3. Understand Design: - How it all works
4. Deep Dive: - Detailed specifications

---

🚀 Ready to Start?

→ to get your first search running in minutes!

---

Last updated: January 2025 | Version: 0.1.0