icon for mcp server

Agent Knowledge

STDIO

Comprehensive MCP server for Elasticsearch integration, file management, and version control with 34 tools

Agent Knowledge MCP 🔍

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

Python Version MCP Compatible License: MIT Buy Me Coffee GitHub Sponsors

🚀 What is Agent Knowledge MCP?

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:

  • 🎯 34 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"

☕ Support This Project

If you find this MCP server useful, consider supporting its development:

Buy Me A Coffee GitHub Sponsors PayPal Ko-fi

💝 Why Support?

  • 🚀 Faster development of new features and improvements
  • 🐛 Priority bug fixes and technical support
  • 📚 Better documentation and comprehensive tutorials
  • 🎯 Community-requested features implementation
  • 🛡️ Enhanced security and stability updates
  • 🌟 Long-term project sustainability

🎁 Sponsor Benefits

TierAmountBenefits
☕ Coffee$5Thank you mention in README + priority issue responses
🚀 Supporter$15Feature request consideration + early access to updates
💎 Sponsor$30Logo in README + special recognition in releases
🌟 Gold Sponsor$50+Custom benefits discussion + direct communication channel

Every contribution helps maintain and improve this open-source project! 🙏

⚡ Quick Start

1. Installation

# Install with uvx (recommended)
uvx agent-knowledge-mcp

2. Configuration

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

3. Connect to Your AI Assistant

Claude Desktop - Add to claude_desktop_config.json:

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

VS Code - Quick install buttons:

Install in VS Code Install in VS Code Insiders

Other AI Assistants - Add similar configuration:

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

Note: The server has built-in update mechanisms accessible through admin tools.

️ Capabilities

Agent Knowledge MCP provides 34 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 (11 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
  • Server Management - Check status, upgrade MCP server

🔄 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"

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

CategoryCountTools
Elasticsearch9search, index_document, create_index, get_document, delete_document, list_indices, delete_index, validate_document_schema, create_document_template
File System11read_file, write_file, append_file, delete_file, move_file, copy_file, list_directory, create_directory, delete_directory, file_info, search_files
Administration11get_config, update_config, validate_config, get_allowed_directory, set_allowed_directory, reload_config, setup_elasticsearch, elasticsearch_status, server_status, server_upgrade, server_uninstall
Version Control3setup_version_control, commit_file, get_previous_file_version

Total: 34 tools for comprehensive knowledge management!

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 Agent Knowledge MCP 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

📝 License

MIT License - see LICENSE for details.

💖 Contributing & Support

🤝 How to Contribute

  • 🐛 Report bugs via GitHub Issues
  • 💡 Suggest features for new tools or capabilities
  • 🔧 Submit pull requests for improvements
  • 📖 Improve documentation and examples
  • 🧪 Test with different AI assistants and share feedback

☕ Financial Support

If this project saves you time or helps your workflow:

Buy Me A Coffee GitHub Sponsors

🌟 Special Thanks

  • All our amazing contributors and supporters
  • The Model Context Protocol community
  • Elasticsearch team for their excellent search engine
  • Python ecosystem for powerful development tools

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.

Be the First to Experience MCP Now