{"id":30184374,"url":"https://github.com/sofianedjerbi/knowledge-tree-mcp","last_synced_at":"2025-08-25T21:13:37.555Z","repository":{"id":307900340,"uuid":"1031048490","full_name":"sofianedjerbi/knowledge-tree-mcp","owner":"sofianedjerbi","description":"MCP server for hierarchical project knowledge management with priority-based organization and real-time web interface","archived":false,"fork":false,"pushed_at":"2025-08-05T21:01:55.000Z","size":316,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-12T12:09:24.424Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sofianedjerbi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-02T22:29:32.000Z","updated_at":"2025-08-05T21:01:58.000Z","dependencies_parsed_at":"2025-08-02T22:51:28.556Z","dependency_job_id":"ec1b4031-498c-42d0-a907-2a4fad35c2c0","html_url":"https://github.com/sofianedjerbi/knowledge-tree-mcp","commit_stats":null,"previous_names":["sofianedjerbi/knowledge-tree-mcp"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/sofianedjerbi/knowledge-tree-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sofianedjerbi%2Fknowledge-tree-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sofianedjerbi%2Fknowledge-tree-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sofianedjerbi%2Fknowledge-tree-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sofianedjerbi%2Fknowledge-tree-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sofianedjerbi","download_url":"https://codeload.github.com/sofianedjerbi/knowledge-tree-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sofianedjerbi%2Fknowledge-tree-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272132104,"owners_count":24879051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-12T12:07:17.341Z","updated_at":"2025-08-25T21:13:37.508Z","avatar_url":"https://github.com/sofianedjerbi.png","language":"TypeScript","readme":"# 🌳 Knowledge MCP Server\n\n\u003e **Hierarchical knowledge management system for AI assistants**  \n\u003e Transform scattered project insights into an organized, searchable knowledge base with intelligent relationships and priority-based organization.\n\n[![npm version](https://img.shields.io/npm/v/@sofianedjerbi/knowledge-tree-mcp)](https://www.npmjs.com/package/@sofianedjerbi/knowledge-tree-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n---\n\n## ✨ Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\"\u003e\n\n### 🏗️ **Smart Organization**\nAuto-categorized paths with custom overrides and project-specific categories\n\n\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\n\n### 🎯 **Priority System**\nFour-tier priority system: **CRITICAL** → **REQUIRED** → **COMMON** → **EDGE-CASE**\n\n\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\n\n### 🔗 **Relationship Mapping**\nSix relationship types with bidirectional validation and automatic linking\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n### 🔍 **Advanced Search**\nFull-text search with regex, field-specific targeting, and multi-criteria filtering\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n### 📊 **Usage Analytics**\nTrack access patterns, search trends, and tool usage with privacy-first design\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n### 🌐 **Interactive Dashboard**\nReal-time web UI with graph visualization, tree explorer, and analytics\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🚀 Quick Start\n\n### Using with Claude Desktop (Recommended)\n\n```bash\n# 🎯 Simple installation\nclaude mcp add knowledge -- npx @sofianedjerbi/knowledge-tree-mcp\n\n# 🎨 With web interface on port 9000\nclaude mcp add knowledge -- npx @sofianedjerbi/knowledge-tree-mcp -- --port 9000 --docs ./docs\n\n# 📁 Custom port and docs location\nclaude mcp add knowledge -- npx @sofianedjerbi/knowledge-tree-mcp -- --port 9000 --docs /path/to/docs\n```\n\n### Local Development\n\n```bash\n# 📦 Setup\ngit clone https://github.com/sofianedjerbi/knowledge-tree-mcp\ncd knowledge-tree-mcp\nnpm install \u0026\u0026 npm run build\n\n# 🏃 Run with web interface\nnpm start -- --port 9000\n\n# 🧪 Run tests\nnpm test\n```\n\n**CLI Options:**\n- `--docs, -d \u003cpath\u003e` → Documentation directory (default: `./docs`)\n- `--port, -p \u003cnumber\u003e` → Web interface port (enables UI at http://localhost:PORT)\n- `--help, -h` → Show help\n\n---\n\n## 🛠️ Core Tools\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📝 add_knowledge\u003c/b\u003e - Create entries with auto-generated paths\u003c/summary\u003e\n\n**Create knowledge entries from Markdown with automatic categorization**\n\n```typescript\nadd_knowledge({\n  content: string,     // Markdown with frontmatter\n  path?: string        // Optional: override auto-generated path\n})\n```\n\n**Auto-Path Generation Examples:**\n- \"How to implement JWT authentication\" → `security/authentication/jwt-implementation.json`\n- \"Fix Redis connection timeout\" → `database/redis/troubleshooting/connection-timeout.json`\n- \"React hooks best practices\" → `frontend/react/best-practices/hooks.json`\n\n**Markdown Format:**\n```markdown\n---\ntitle: Implement JWT refresh token rotation\npriority: REQUIRED\ntags: [jwt, authentication, security]\n---\n\n# Problem\nJWT tokens expire but users need seamless authentication\n\n# Context\nMobile apps and SPAs need to maintain auth state without frequent logins\n\n# Solution\nImplement refresh token rotation with secure storage...\n\n# Examples\n```typescript\n// Token rotation implementation\nconst refreshToken = async () =\u003e {\n  // Implementation here\n}\n```\n```\n\n**Path Override Options (Ask your AI assistant):**\n```bash\n# Full custom path\n\"Add this JWT guide to security/auth/my-jwt-guide\"\n\n# Directory only (filename from title)\n\"Add this authentication knowledge to the security/auth/ directory\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔍 search_knowledge\u003c/b\u003e - Find entries with advanced filtering\u003c/summary\u003e\n\n**Search with field-specific targeting and multi-criteria filtering**\n\n```typescript\nsearch_knowledge({\n  query?: string,              // Search text (supports regex)\n  searchIn?: string[],         // Fields to search\n  priority?: string[],         // Filter by priorities\n  category?: string,           // Filter by category\n  sortBy?: string,            // Sort results\n  limit?: number,             // Max results\n  regex?: boolean,            // Enable regex mode\n  caseSensitive?: boolean     // Case sensitivity\n})\n```\n\n**Search Fields:**\n- `title`, `problem`, `solution`, `context`, `code`, `tags`, `path`, `all`\n\n**Examples (Ask your AI assistant):**\n```bash\n# Simple search\n\"Search for authentication patterns\"\n\n# Field-specific search  \n\"Find entries with JWT in the title or tags\"\n\n# Multi-criteria filtering\n\"Show me all CRITICAL and REQUIRED security vulnerabilities\"\n\n# Regex search\n\"Search for React hooks usage in code (useState, useEffect, useMemo)\"\n\n# Find all entries\n\"Show me all knowledge entries\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🏷️ manage_categories\u003c/b\u003e - Dynamic category management\u003c/summary\u003e\n\n**Add, update, remove, and merge categories for better organization**\n\n```typescript\nmanage_categories({\n  action: \"add\" | \"update\" | \"remove\" | \"list\" | \"merge\",\n  category?: string,\n  keywords?: string[],\n  subcategories?: string[],\n  scope?: \"project\" | \"system\" | \"both\",\n  description?: string\n})\n```\n\n**Examples (Ask your AI assistant):**\n```bash\n# List all categories\n\"Show me all available categories\"\n\n# Add project-specific category\n\"Add a payment-gateway category for Stripe and PayPal integrations\"\n\n# Merge keywords without replacing\n\"Add Svelte and SvelteKit to the frontend category keywords\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔗 link_knowledge\u003c/b\u003e - Connect related entries\u003c/summary\u003e\n\n**Create typed relationships between knowledge entries**\n\n```typescript\nlink_knowledge({\n  from: string,\n  to: string,\n  relationship: string,\n  description?: string\n})\n```\n\n**Relationship Types:**\n- 🤝 `related` → General connection (bidirectional)\n- ⬆️ `supersedes` → This replaces the target\n- ⬇️ `superseded_by` → This is replaced by target\n- ⚡ `conflicts_with` → Conflicting approaches (bidirectional)\n- 🔧 `implements` → Implementation of a pattern\n- 📋 `implemented_by` → Has implementations\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🗺️ index_knowledge\u003c/b\u003e - Browse knowledge structure\u003c/summary\u003e\n\n**Get comprehensive overview of your knowledge base**\n\n```typescript\nindex_knowledge({\n  format?: \"tree\" | \"list\" | \"summary\" | \"categories\",\n  include_content?: boolean,\n  max_entries?: number\n})\n```\n\n**Formats:**\n- 🌳 `tree` → Hierarchical folder structure\n- 📋 `list` → Flat list with metadata\n- 📊 `summary` → Statistics and overview\n- 📁 `categories` → Grouped by category\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📊 usage_analytics\u003c/b\u003e - Track usage patterns\u003c/summary\u003e\n\n**Analyze how your knowledge base is being used**\n\n```typescript\nusage_analytics({\n  days?: number,\n  include?: string[]\n})\n```\n\n**Analytics Types:**\n- 👁️ `access` → Entry access patterns\n- 🔍 `searches` → Search query analysis\n- 🛠️ `tools` → Tool usage statistics\n- 🌐 `interface` → Web UI interactions\n- 📈 `patterns` → Usage trends over time\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e✅ More Tools\u003c/b\u003e - Additional capabilities\u003c/summary\u003e\n\n- **update_knowledge** → Modify existing entries\n- **delete_knowledge** → Remove entries with cleanup\n- **validate_knowledge** → Check consistency and fix issues\n- **export_knowledge** → Generate documentation (MD/HTML/JSON)\n- **stats_knowledge** → Get detailed statistics\n- **recent_knowledge** → View recent changes\n- **setup_project** → Configure project settings\n- **help** → Get contextual guidance\n\n\u003c/details\u003e\n\n---\n\n## 🌐 Web Dashboard\n\nAccess the interactive dashboard at `http://localhost:9000` (when using `--port 9000`)\n\n### Features:\n- 📊 **Overview Dashboard** → KPIs, activity metrics, tag cloud\n- 🕸️ **Knowledge Graph** → Interactive network visualization with physics simulation\n- 🌲 **Knowledge Explorer** → Hierarchical tree view with expand/collapse\n- 🔍 **Search Interface** → Real-time search with filters\n- 📈 **Analytics View** → Usage patterns and trends\n- 🔄 **Recent Activity** → Latest additions and modifications\n\n### Graph Visualization:\n- **Continuous Physics** → Nodes auto-arrange to prevent overlaps\n- **Priority Colors** → Visual distinction by importance\n- **Relationship Lines** → See connections between entries\n- **Fullscreen Mode** → Maximize for large knowledge bases\n- **Search \u0026 Filter** → Find specific nodes with dimming highlight\n\n---\n\n## 🏗️ Project Configuration\n\nThe AI assistant can configure project-specific settings using `setup_project`:\n\n```javascript\n// Ask your AI assistant to run this:\n\"Initialize project configuration for our Next.js app with Stripe payments\"\n\n// The AI will execute:\nsetup_project({\n  action: \"init\",\n  name: \"My Project\",\n  pathPrefix: \"my-project\",\n  technologies: [\"nodejs\", \"react\", \"postgres\"],\n  categories: {\n    \"payments\": {\n      keywords: [\"stripe\", \"billing\", \"subscription\"],\n      subcategories: [\"webhooks\", \"invoices\"]\n    }\n  }\n})\n```\n\nThis creates `.knowledge-tree.json` in your docs directory for:\n- Custom categories and keywords\n- Auto-tagging rules\n- Path prefix for all entries\n- Technology stack awareness\n\n---\n\n## 📂 Example Directory Structure\n\nThe system automatically organizes knowledge based on content. Here's a typical structure:\n\n```\ndocs/\n├── .knowledge-tree.json      # Project configuration (auto-created)\n├── logs/\n│   └── usage.jsonl          # Usage analytics (gitignored)\n├── frontend/                 # Auto-detected from React/Vue/UI content\n│   ├── react/\n│   │   └── hooks/\n│   └── performance/\n├── backend/                  # Auto-detected from server/API content\n│   ├── api/\n│   ├── database/\n│   └── security/\n├── testing/                  # Auto-detected from test-related content\n│   ├── unit/\n│   └── integration/\n└── architecture/             # Auto-detected from design/pattern content\n    ├── patterns/\n    └── decisions/\n```\n\n**Note:** Directories are created automatically as you add knowledge. You don't need to create this structure manually!\n\n---\n\n## 🔐 Privacy \u0026 Security\n\n- **Local First**: All data stored locally in your project\n- **No Telemetry**: Zero external data collection\n- **Git Friendly**: JSON format for version control\n- **Private Analytics**: Usage logs in `.gitignore` by default\n\n---\n\n## 🧪 Development\n\n```bash\n# Run tests\nnpm test\n\n# Run with file watching\nnpm run dev\n\n# Build TypeScript\nnpm run build\n\n# Lint \u0026 format\nnpm run lint\nnpm run format\n\n# Type checking\nnpm run typecheck\n```\n\n### Architecture:\n- **TypeScript** with strict mode\n- **Modular design** with clear separation of concerns\n- **MCP SDK** for Claude integration\n- **Fastify** for web server\n- **Vis.js** for graph visualization\n- **WebSockets** for real-time updates\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file\n\n---\n\n## 👨‍💻 Author\n\n**Created by [sofianedjerbi](https://github.com/sofianedjerbi)**\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**🌟 Star this project if it helps organize your AI assistant's knowledge!**\n\n\u003c/div\u003e","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsofianedjerbi%2Fknowledge-tree-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsofianedjerbi%2Fknowledge-tree-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsofianedjerbi%2Fknowledge-tree-mcp/lists"}