🌳 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

$3 Auto-categorized paths with custom overrides and project-specific categories	$3 Four-tier priority system: CRITICAL → REQUIRED → COMMON → EDGE-CASE	$3 Six relationship types with bidirectional validation and automatic linking
$3 Full-text search with regex, field-specific targeting, and multi-criteria filtering	$3 Track access patterns, search trends, and tool usage with privacy-first design	$3 Real-time web UI with graph visualization, tree explorer, and analytics

---

🚀 Quick Start

$3

``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
`

$3

`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)

$3

- 📊 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

$3

- 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
``

$3

- 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

---