agent-knowledge-mcp 1.0.3

A comprehensive MCP server for AI knowledge management with Elasticsearch, file operations, and version control

Elasticsearch MCP Server 🔍

The complete knowledge management solution
Powerful Model Context Protocol server for Elasticsearch integration with comprehensive file management and version control.

🚀 What is Elasticsearch MCP Server?

The most comprehensive MCP server that transforms your AI assistant into a powerful knowledge management system. The key advantage? It combines everything you need—Elasticsearch search, file operations, document validation, and version control in one unified solution.

🔑 Complete Knowledge Management:

• ✅ Elasticsearch Integration: Full-featured search, indexing, and document management
• ✅ File System Control: Comprehensive file operations with cross-platform support
• ✅ Document Validation: Schema-enforced document structure with strict validation modes
• ✅ Configuration Management: Complete config control with validation and reloading
• ✅ Version Control: Git and SVN support with intelligent file tracking
• ✅ Security First: Sandboxed operations with configurable restrictions
• ✅ Production Ready: Battle-tested with comprehensive error handling

✨ Key Benefits:

• 🎯 31 Powerful Tools: Everything from search to version control and config management with strict schema validation
• 🔄 Universal AI Support: Works with Claude, ChatGPT, Cursor, and any MCP-compatible AI
• 📊 Smart Document Management: Auto-validation, templates, and structured data with configurable strict schema control
• 🛡️ Enterprise Security: Path validation, access controls, and audit trails
• ⚡ Zero Dependencies: Optional Elasticsearch - works standalone for file operations

🌐 AI Assistant Support

Works with any MCP-compatible AI assistant:

• ✅ Claude Desktop
• ✅ ChatGPT Plus (with MCP support)
• ✅ Cursor IDE
• ✅ Windsurf
• ✅ VS Code (with MCP extension)
• ✅ Any MCP client

Perfect for developers who want to automate knowledge management and teams who need structured document workflows!

🎬 What You Can Do

Real workflows you can try today:

📚 Knowledge Management

• "Search all documents for information about API authentication and create a comprehensive guide"
• "Index this technical document with proper categorization and tags"
• "Find all documents related to deployment and generate a deployment checklist"
• "Create a new document template for API documentation with required fields"

📁 File Operations & Organization

• "Organize all markdown files by category and move them to appropriate directories"
• "Read all configuration files and create a settings summary document"
• "Find duplicate files in the project and list them for cleanup"
• "Create a project structure document listing all important files"

🔄 Version Control & History

• "Setup Git repository for this knowledge base and commit all current documents"
• "Check what changes were made to the user manual in the last version"
• "Commit these updated API docs with a descriptive message"
• "Show me the previous version of this configuration file"

🤖 Development & Documentation

• "Index all code documentation and make it searchable"
• "Create a changelog from Git commit history"
• "Validate all documents follow our schema requirements"
• "Generate project documentation from README files"

🔍 Configuration & Schema Management

• "Update configuration to enable strict schema validation for all documents"
• "Show me the current configuration settings and validation rules"
• "Validate this configuration before applying it to prevent errors"
• "Disable extra fields in documents to enforce strict schema compliance"

🔍 Advanced Search & Analysis

• "Search across all documents and files for security-related information"
• "Find all TODO comments in code files and create a task list"
• "Analyze document metadata and generate a content report"
• "Search for outdated information and flag it for review"

⚡ Quick Start

1. Installation

🎉 NEW: Now Available on PyPI!

# Super easy installation with uvx
uvx agent-knowledge-mcp

# Or install as a tool for persistent use
uv tool install agent-knowledge-mcp

Alternative installation methods:

# Install from GitHub (latest development)
uvx --from git+https://github.com/itshare4u/AgentKnowledgeMCP.git agent-knowledge-mcp

# Traditional installation
git clone https://github.com/itshare4u/AgentKnowledgeMCP.git
cd AgentKnowledgeMCP
pip install -r requirements.txt

2. Configuration

# Copy and edit configuration
cp src/config.json.example src/config.json
nano src/config.json

3. Connect to Your AI Assistant

For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "agent-knowledge": {
      "command": "uvx",
      "args": ["agent-knowledge-mcp"]
    }
  }
}

Alternative configurations:

{
  "mcpServers": {
    "agent-knowledge-github": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/itshare4u/AgentKnowledgeMCP.git", "agent-knowledge-mcp"]
    }
  }
}

For Cursor, add to settings:

{
  "cursor.mcp.servers": [
    {
      "name": "agent-knowledge",
      "command": "uvx",
      "args": ["agent-knowledge-mcp"]
    }
  ]
}

Alternative (if installed manually):

{
  "cursor.mcp.servers": [
    {
      "name": "agent-knowledge",
      "command": "python3",
      "args": ["/path/to/AgentKnowledgeMCP/src/server.py"],
      "workingDirectory": "/path/to/AgentKnowledgeMCP"
    }
  ]
}

For VS Code, install MCP extension and configure:

{
  "mcp.servers": {
    "agent-knowledge": {
      "command": "uvx",
      "args": ["agent-knowledge-mcp"]
    }
  }
}

Alternative (if installed manually):

{
  "mcp.servers": {
    "agent-knowledge": {
      "command": "python3",
      "args": ["/path/to/AgentKnowledgeMCP/src/server.py"],
      "cwd": "/path/to/AgentKnowledgeMCP"
    }
  }
}

For Windsurf, add to ~/.windsurf/config.json:

{
  "mcp": {
    "servers": {
      "agent-knowledge": {
        "command": "uvx",
        "args": ["agent-knowledge-mcp"]
      }
    }
  }
}

Alternative (if installed manually):

{
  "mcp": {
    "servers": {
      "agent-knowledge": {
        "command": "python3",
        "args": ["/path/to/AgentKnowledgeMCP/src/server.py"],
        "env": {
          "PYTHONPATH": "/path/to/AgentKnowledgeMCP"
        }
      }
    }
  }
}

� Quick VS Code Installation

For quick installation in VS Code, click the installation buttons below:

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P (or Cmd + Shift + P on macOS) and typing Preferences: Open Settings (JSON).

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

Note that the mcp key is needed when using the mcp.json file.

UV Installation (Recommended)

{
  "mcp": {
    "servers": {
      "agent-knowledge": {
        "command": "uvx",
        "args": ["agent-knowledge-mcp"]
      }
    }
  }
}

Manual Installation

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "server_path",
        "description": "Path to AgentKnowledgeMCP server.py",
        "default": "${workspaceFolder}/src/server.py"
      }
    ],
    "servers": {
      "agent-knowledge": {
        "command": "python3",
        "args": [
          "${input:server_path}"
        ],
        "cwd": "${workspaceFolder}"
      }
    }
  }
}

�🛠️ Capabilities

Elasticsearch MCP Server provides 31 powerful tools across 4 categories:

🔍 Elasticsearch Operations (9 tools)

• Smart Search - Multi-field queries with boosting and relevance scoring
• Document Management - Index, retrieve, update, delete with validation
• Index Administration - Create, configure, manage Elasticsearch indices
• Schema Validation - Enforce document structure and data types
• Template Generation - Auto-create document templates with required fields

📁 File System Management (11 tools)

• File Operations - Read, write, append, delete, move, copy with safety checks
• Directory Management - Create, list, navigate directory structures
• Path Intelligence - Relative/absolute path conversion and validation
• File Discovery - Search files by name, content, or metadata
• Cross-Platform - Windows, macOS, Linux compatibility

🎛️ System Administration (8 tools)

• Configuration Management - Complete config viewing, modification, and validation with strict schema controls
• Security Controls - Access restrictions and path validation
• Health Monitoring - System status and Elasticsearch connectivity
• Auto-Setup - Intelligent Elasticsearch configuration
• Environment Management - Directory permissions and structure
• Strict Schema Control - Configurable document validation to prevent unauthorized field additions

🔄 Version Control (3 tools)

• Repository Setup - Git/SVN initialization with best practices
• File Tracking - Intelligent commit with change detection
• History Access - Retrieve any previous version of files
• Multi-VCS - Support for both Git and SVN workflows

💬 Example Prompts to Try

Once everything is set up, try asking your AI:

Knowledge Discovery:

"Search all indexed documents for information about user authentication and summarize the key points"

Document Creation:

"Create a new API documentation template and index it with proper categorization"

File Management:

"Find all configuration files in the project and create a backup in the configs directory"

Version Control:

"Setup version control for this knowledge base and commit all current documents with proper organization"

Content Analysis:

"Analyze all markdown files for outdated information and create a list of files that need updates"

Project Documentation:

"Read all README files in subdirectories and create a comprehensive project overview document"

🏗️ Architecture

AgentKnowledgeMCP/
├── src/
│   ├── server.py                    # Main MCP server
│   ├── config.json                  # Configuration
│   ├── config.json.example          # Configuration template
│   ├── tools.py                     # Tool definitions (28 tools)
│   ├── elasticsearch_handlers.py    # Elasticsearch operations
│   ├── file_handlers.py            # File system operations
│   ├── admin_handlers.py           # Admin operations
│   ├── version_control_handlers.py # VCS operations
│   ├── document_schema.py          # Document validation
│   ├── elasticsearch_client.py     # ES client management
│   └── security.py                 # Security & validation
├── tests/
│   ├── run_all_tests.py            # Test runner
│   ├── test_file_paths.py          # File operations tests
│   ├── test_validation.py          # Document validation tests
│   ├── test_version_control.py     # VCS comprehensive tests
│   ├── test_simple_vcs.py          # VCS demo tests
│   ├── test_strict_validation.py   # Strict schema validation tests
│   ├── demo_agent_workflow.py      # Complete workflow demo
│   ├── demo_config_management.py   # Config management demo
│   └── README.md                   # Test documentation
├── .knowledges/                    # Knowledge base storage
├── setup.py                       # Quick setup script
├── requirements.txt                # Python dependencies
├── CHANGELOG.md                    # Version history
└── README.md                      # This file

graph TD
    A[AI Assistant] --> B[MCP Server]
    B --> C[Elasticsearch Client]
    B --> D[File System Handler]
    B --> E[Version Control Handler]
    B --> F[Document Validator]
    
    C --> G[Elasticsearch Cluster]
    D --> H[Local File System]
    E --> I[Git/SVN Repository]
    F --> J[Schema Validation]

Modern, Modular Design:

1. MCP Protocol - Standard communication with AI assistants
2. Elasticsearch Integration - Full-featured search and indexing
3. File System Safety - Sandboxed operations with validation
4. Version Control - Git/SVN support with intelligent workflows
5. Document Validation - Schema enforcement and template generation

🔒 Security & Privacy

Enterprise-grade security:

• ✅ Sandboxed Operations - All file operations restricted to configured directories
• ✅ Path Validation - Prevent directory traversal and unauthorized access
• ✅ Access Controls - Configurable permissions and restrictions
• ✅ Audit Trails - Full logging of operations and changes
• ✅ No Cloud Dependencies - Everything runs locally

Configuration Example:

{
  "security": {
    "allowed_base_directory": "/your/safe/directory",
    "restrict_file_operations": true,
    "log_all_operations": true
  }
}

🛡️ Strict Schema Validation

NEW: Configurable strict schema validation to prevent unwanted data corruption:

{
  "document_validation": {
    "strict_schema_validation": true,
    "allow_extra_fields": false,
    "required_fields_only": false,
    "auto_correct_paths": true
  }
}

Features:

• ✅ Strict Mode - Reject documents with extra fields beyond the schema
• ✅ Flexible Control - Enable/disable validation per use case
• ✅ Schema Compliance - Ensure all documents follow defined structure
• ✅ Clear Error Messages - Detailed validation feedback with examples
• ✅ Backward Compatibility - Works with existing documents

Benefits:

• 🛡️ Data Integrity - Prevent agents from adding arbitrary fields
• 📊 Consistent Structure - Maintain clean, predictable document schemas
• 🔧 Easy Management - Toggle validation modes through configuration
• 🚀 Production Ready - Ideal for enterprise knowledge management

Example validation error:

❌ Document validation failed!
Extra fields not allowed in strict mode: custom_field, extra_data
Allowed fields: id, title, summary, file_path, priority, tags, source_type

📊 Tool Reference

Category	Count	Tools
Elasticsearch	9	search, index_document, create_index, get_document, delete_document, list_indices, delete_index, validate_document_schema, create_document_template
File System	11	read_file, write_file, append_file, delete_file, move_file, copy_file, list_directory, create_directory, delete_directory, file_info, search_files
Administration	8	get_config, update_config, validate_config, get_allowed_directory, set_allowed_directory, reload_config, setup_elasticsearch, elasticsearch_status
Version Control	3	setup_version_control, commit_file, get_previous_file_version

Total: 31 tools for comprehensive knowledge management!

🧪 Testing & Validation

Comprehensive test suite included:

# Run all tests
python3 tests/run_all_tests.py

# Run individual tests
python3 tests/test_file_paths.py           # File operations
python3 tests/test_validation.py           # Document validation  
python3 tests/test_version_control.py      # Version control
python3 tests/test_simple_vcs.py           # VCS demo
python3 tests/test_strict_validation.py    # Strict schema validation

# Demo workflows
python3 tests/demo_agent_workflow.py       # Complete workflow
python3 tests/demo_config_management.py    # Config management demo

Quality Assurance:

• ✅ Unit Tests - All core functionality tested
• ✅ Integration Tests - End-to-end workflow validation
• ✅ Error Handling - Comprehensive error scenarios covered
• ✅ Cross-Platform - Tested on Windows, macOS, Linux

🤝 Contributing

Love to have your help making Elasticsearch MCP Server even better!

Quick Development Setup

git clone https://github.com/yourusername/AgentKnowledgeMCP.git
cd AgentKnowledgeMCP

# Install dependencies
pip install -r requirements.txt

# Run tests
python3 test_file_paths.py

# Start development server
python3 src/server.py

Ways to Contribute

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features for new tools or capabilities
• 🔧 Add new tools or improve existing ones
• 📖 Improve documentation and examples
• 🧪 Test with different AI assistants and share results

Development Guidelines

• Modular Design - Each tool category in separate handlers
• Comprehensive Testing - Test all new functionality
• Security First - Validate all inputs and file operations
• Cross-Platform - Ensure compatibility across operating systems

📦 Installation Options

✨ Easy Installation with UV (Recommended):

# Install directly from GitHub
uvx --from git+https://github.com/itshare4u/AgentKnowledgeMCP.git agent-knowledge-mcp

# After package is published to PyPI:
uvx agent-knowledge-mcp

🔧 Manual Installation:

git clone https://github.com/itshare4u/AgentKnowledgeMCP.git
cd AgentKnowledgeMCP
python3 -m pip install -e .

📋 Requirements:

• Python 3.8+
• Elasticsearch (optional - server works without it for file operations)
• Git (for version control features)

🚀 Publishing to PyPI

For maintainers who want to publish this package:

# Build the package
uv build

# Publish to Test PyPI first
uv publish --repository testpypi --token <your-test-pypi-token>

# Test installation from Test PyPI
uvx --index https://test.pypi.org/simple/ agent-knowledge-mcp

# Publish to main PyPI
uv publish --token <your-pypi-token>

After publishing, users can install with:

uvx agent-knowledge-mcp

📝 License

MIT License - see LICENSE for details.

---

Ready to supercharge your AI assistant with comprehensive knowledge management? Get started today! 🚀

Transform your AI into a powerful knowledge management system with Elasticsearch search, intelligent file operations, and version control - all in one unified MCP server.