https://github.com/sofianedjerbi/knowledge-tree-mcp
MCP server for hierarchical project knowledge management with priority-based organization and real-time web interface
https://github.com/sofianedjerbi/knowledge-tree-mcp
Last synced: 6 months ago
JSON representation
MCP server for hierarchical project knowledge management with priority-based organization and real-time web interface
- Host: GitHub
- URL: https://github.com/sofianedjerbi/knowledge-tree-mcp
- Owner: sofianedjerbi
- Created: 2025-08-02T22:29:32.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-08-05T21:01:55.000Z (6 months ago)
- Last Synced: 2025-08-12T12:09:24.424Z (6 months ago)
- Language: TypeScript
- Size: 309 KB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🌳 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.
[](https://www.npmjs.com/package/@sofianedjerbi/knowledge-tree-mcp)
[](https://opensource.org/licenses/MIT)
---
## ✨ 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)
```bash
# 🎯 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
```bash
# 📦 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 ` → Documentation directory (default: `./docs`)
- `--port, -p ` → Web interface port (enables UI at http://localhost:PORT)
- `--help, -h` → Show help
---
## 🛠️ Core Tools
📝 add_knowledge - Create entries with auto-generated paths
**Create knowledge entries from Markdown with automatic categorization**
```typescript
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:**
```markdown
---
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_knowledge - Find entries with advanced filtering
**Search with field-specific targeting and multi-criteria filtering**
```typescript
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):**
```bash
# 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"
```
🏷️ manage_categories - Dynamic category management
**Add, update, remove, and merge categories for better organization**
```typescript
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):**
```bash
# 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"
```
🔗 link_knowledge - Connect related entries
**Create typed relationships between knowledge entries**
```typescript
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
🗺️ index_knowledge - Browse knowledge structure
**Get comprehensive overview of your knowledge base**
```typescript
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
📊 usage_analytics - Track usage patterns
**Analyze how your knowledge base is being used**
```typescript
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
✅ More Tools - Additional capabilities
- **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`:
```javascript
// 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
```bash
# 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](LICENSE) file
---
## 👨💻 Author
**Created by [sofianedjerbi](https://github.com/sofianedjerbi)**
---
**🌟 Star this project if it helps organize your AI assistant's knowledge!**