🌳 Knowledge MCP Server

Hierarchical knowledge management system for AI assistants
Transform scattered project insights into an organized, searchable knowledge base with intelligent relationships and priority-based organization.

✨ Features

🏗️ Smart Organization

Auto-categorized paths with custom overrides and project-specific categories

🎯 Priority System

Four-tier priority system: CRITICAL → REQUIRED → COMMON → EDGE-CASE

🔗 Relationship Mapping

Six relationship types with bidirectional validation and automatic linking

🔍 Advanced Search

Full-text search with regex, field-specific targeting, and multi-criteria filtering

📊 Usage Analytics

Track access patterns, search trends, and tool usage with privacy-first design

🌐 Interactive Dashboard

Real-time web UI with graph visualization, tree explorer, and analytics

🚀 Quick Start

Using with Claude Desktop (Recommended)

# 🎯 Simple installation
claude mcp add knowledge -- npx @sofianedjerbi/knowledge-tree-mcp

# 🎨 With web interface on port 9000
claude mcp add knowledge -- npx @sofianedjerbi/knowledge-tree-mcp -- --port 9000 --docs ./docs

# 📁 Custom port and docs location
claude mcp add knowledge -- npx @sofianedjerbi/knowledge-tree-mcp -- --port 9000 --docs /path/to/docs

Local Development

# 📦 Setup
git clone https://github.com/sofianedjerbi/knowledge-tree-mcp
cd knowledge-tree-mcp
npm install && npm run build

# 🏃 Run with web interface
npm start -- --port 9000

# 🧪 Run tests
npm test

CLI Options:

• --docs, -d <path> → Documentation directory (default: ./docs)
• --port, -p <number> → Web interface port (enables UI at http://localhost:PORT)
• --help, -h → Show help

🛠️ Core Tools

Create knowledge entries from Markdown with automatic categorization

add_knowledge({
  content: string,     // Markdown with frontmatter
  path?: string        // Optional: override auto-generated path
})

Auto-Path Generation Examples:

• "How to implement JWT authentication" → security/authentication/jwt-implementation.json
• "Fix Redis connection timeout" → database/redis/troubleshooting/connection-timeout.json
• "React hooks best practices" → frontend/react/best-practices/hooks.json

Markdown Format:

---
title: Implement JWT refresh token rotation
priority: REQUIRED
tags: [jwt, authentication, security]
---

# Problem
JWT tokens expire but users need seamless authentication

# Context
Mobile apps and SPAs need to maintain auth state without frequent logins

# Solution
Implement refresh token rotation with secure storage...

# Examples
```typescript
// Token rotation implementation
const refreshToken = async () => {
  // Implementation here
}

**Path Override Options (Ask your AI assistant):**
```bash
# Full custom path
"Add this JWT guide to security/auth/my-jwt-guide"

# Directory only (filename from title)
"Add this authentication knowledge to the security/auth/ directory"

Search with field-specific targeting and multi-criteria filtering

search_knowledge({
  query?: string,              // Search text (supports regex)
  searchIn?: string[],         // Fields to search
  priority?: string[],         // Filter by priorities
  category?: string,           // Filter by category
  sortBy?: string,            // Sort results
  limit?: number,             // Max results
  regex?: boolean,            // Enable regex mode
  caseSensitive?: boolean     // Case sensitivity
})

Search Fields:

• title, problem, solution, context, code, tags, path, all

Examples (Ask your AI assistant):

# Simple search
"Search for authentication patterns"

# Field-specific search  
"Find entries with JWT in the title or tags"

# Multi-criteria filtering
"Show me all CRITICAL and REQUIRED security vulnerabilities"

# Regex search
"Search for React hooks usage in code (useState, useEffect, useMemo)"

# Find all entries
"Show me all knowledge entries"

Add, update, remove, and merge categories for better organization

manage_categories({
  action: "add" | "update" | "remove" | "list" | "merge",
  category?: string,
  keywords?: string[],
  subcategories?: string[],
  scope?: "project" | "system" | "both",
  description?: string
})

Examples (Ask your AI assistant):

# List all categories
"Show me all available categories"

# Add project-specific category
"Add a payment-gateway category for Stripe and PayPal integrations"

# Merge keywords without replacing
"Add Svelte and SvelteKit to the frontend category keywords"

Create typed relationships between knowledge entries

link_knowledge({
  from: string,
  to: string,
  relationship: string,
  description?: string
})

Relationship Types:

• 🤝 related → General connection (bidirectional)
• ⬆️ supersedes → This replaces the target
• ⬇️ superseded_by → This is replaced by target
• ⚡ conflicts_with → Conflicting approaches (bidirectional)
• 🔧 implements → Implementation of a pattern
• 📋 implemented_by → Has implementations

Get comprehensive overview of your knowledge base

index_knowledge({
  format?: "tree" | "list" | "summary" | "categories",
  include_content?: boolean,
  max_entries?: number
})

Formats:

• 🌳 tree → Hierarchical folder structure
• 📋 list → Flat list with metadata
• 📊 summary → Statistics and overview
• 📁 categories → Grouped by category

Analyze how your knowledge base is being used

usage_analytics({
  days?: number,
  include?: string[]
})

Analytics Types:

• 👁️ access → Entry access patterns
• 🔍 searches → Search query analysis
• 🛠️ tools → Tool usage statistics
• 🌐 interface → Web UI interactions
• 📈 patterns → Usage trends over time

• update_knowledge → Modify existing entries
• delete_knowledge → Remove entries with cleanup
• validate_knowledge → Check consistency and fix issues
• export_knowledge → Generate documentation (MD/HTML/JSON)
• stats_knowledge → Get detailed statistics
• recent_knowledge → View recent changes
• setup_project → Configure project settings
• help → Get contextual guidance

🌐 Web Dashboard

Access the interactive dashboard at http://localhost:9000 (when using --port 9000)

Features:

• 📊 Overview Dashboard → KPIs, activity metrics, tag cloud
• 🕸️ Knowledge Graph → Interactive network visualization with physics simulation
• 🌲 Knowledge Explorer → Hierarchical tree view with expand/collapse
• 🔍 Search Interface → Real-time search with filters
• 📈 Analytics View → Usage patterns and trends
• 🔄 Recent Activity → Latest additions and modifications

Graph Visualization:

• Continuous Physics → Nodes auto-arrange to prevent overlaps
• Priority Colors → Visual distinction by importance
• Relationship Lines → See connections between entries
• Fullscreen Mode → Maximize for large knowledge bases
• Search & Filter → Find specific nodes with dimming highlight

🏗️ Project Configuration

The AI assistant can configure project-specific settings using setup_project:

// Ask your AI assistant to run this:
"Initialize project configuration for our Next.js app with Stripe payments"

// The AI will execute:
setup_project({
  action: "init",
  name: "My Project",
  pathPrefix: "my-project",
  technologies: ["nodejs", "react", "postgres"],
  categories: {
    "payments": {
      keywords: ["stripe", "billing", "subscription"],
      subcategories: ["webhooks", "invoices"]
    }
  }
})

This creates .knowledge-tree.json in your docs directory for:

• Custom categories and keywords
• Auto-tagging rules
• Path prefix for all entries
• Technology stack awareness

📂 Example Directory Structure

The system automatically organizes knowledge based on content. Here's a typical structure:

docs/
├── .knowledge-tree.json      # Project configuration (auto-created)
├── logs/
│   └── usage.jsonl          # Usage analytics (gitignored)
├── frontend/                 # Auto-detected from React/Vue/UI content
│   ├── react/
│   │   └── hooks/
│   └── performance/
├── backend/                  # Auto-detected from server/API content
│   ├── api/
│   ├── database/
│   └── security/
├── testing/                  # Auto-detected from test-related content
│   ├── unit/
│   └── integration/
└── architecture/             # Auto-detected from design/pattern content
    ├── patterns/
    └── decisions/

Note: Directories are created automatically as you add knowledge. You don't need to create this structure manually!

🔐 Privacy & Security

• Local First: All data stored locally in your project
• No Telemetry: Zero external data collection
• Git Friendly: JSON format for version control
• Private Analytics: Usage logs in .gitignore by default

🧪 Development

# Run tests
npm test

# Run with file watching
npm run dev

# Build TypeScript
npm run build

# Lint & format
npm run lint
npm run format

# Type checking
npm run typecheck

Architecture:

• TypeScript with strict mode
• Modular design with clear separation of concerns
• MCP SDK for Claude integration
• Fastify for web server
• Vis.js for graph visualization
• WebSockets for real-time updates

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

📄 License

MIT License - see LICENSE file

👨‍💻 Author

Created by sofianedjerbi

🌟 Star this project if it helps organize your AI assistant's knowledge!