agent-knowledge-mcp 1.0.4

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

Agent Knowledge MCP 🔍

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

[

• 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, and uninstall MCP server via uvxds.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

🚀 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:

💝 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

Tier	Amount	Benefits
☕ Coffee	$5	Thank you mention in README + priority issue responses
🚀 Supporter	$15	Feature request consideration + early access to updates
💎 Sponsor	$30	Logo 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

🎉 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": ["--upgrade", "agent-knowledge-mcp"]
    }
  }
}

Alternative configurations:

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

For Cursor, add to settings:

{
  "cursor.mcp.servers": [
    {
      "name": "agent-knowledge",
      "command": "uvx",
      "args": ["--upgrade", "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": ["--upgrade", "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": ["--upgrade", "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 & Updates

📥 Installation Buttons:

🔄 Auto-Update Configuration:

The above buttons install with --upgrade flag to always get the latest version!

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 with Auto-Update (Recommended)

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

UV Installation (Stable Version)

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

Pin Specific Version

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

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

🔄 Keeping Up-to-Date

🚀 Auto-Update Method (Recommended):

Use --upgrade flag in your configuration to always get the latest version:

uvx --upgrade agent-knowledge-mcp

📋 Manual Update Commands:

For all AI assistants with uvx configuration:

# Update to latest version
uvx --upgrade agent-knowledge-mcp

# Then restart your AI assistant to reload the server

For VS Code specifically:

# Method 1: Quick reload
Ctrl+Shift+P → "Developer: Reload Window"

# Method 2: Update and reload 
uvx --upgrade agent-knowledge-mcp
# Then: Ctrl+Shift+P → "MCP: Reload Servers"

For Claude Desktop:

# Update package
uvx --upgrade agent-knowledge-mcp

# Restart Claude Desktop application

🔍 Check Current Version:

# Check installed version
uvx --version agent-knowledge-mcp

# Check latest available version
uvx --dry-run --upgrade agent-knowledge-mcp

📌 Version Management:

Latest stable (recommended):

"args": ["--upgrade", "agent-knowledge-mcp"]

Pin specific version:

"args": ["agent-knowledge-mcp==1.0.3"]

Development version:

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

⚠️ Important Notes:

• VS Code/Cursor: Requires restart or "Reload Window" after updates
• Claude Desktop: Requires application restart after updates
• Auto-update: Only works with --upgrade flag in configuration
• Version conflicts: Use uvx --force if you encounter caching issues

🛠️ 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

🔄 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	11	get_config, update_config, validate_config, get_allowed_directory, set_allowed_directory, reload_config, setup_elasticsearch, elasticsearch_status, server_status, server_upgrade, server_uninstall
Version Control	3	setup_version_control, commit_file, get_previous_file_version

Total: 34 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 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

📦 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.

💖 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:

🌟 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.