lukehollenback/mcp-mycelium

MCP Mycelium

A sophisticated Model Context Protocol (MCP) server for managing markdown-based knowledge bases with intelligent indexing, graph relationships, and AI-friendly operations.

Overview

MCP Mycelium transforms your markdown files into an intelligent knowledge graph that AI assistants can navigate, search, and analyze. It provides semantic search, relationship mapping, content validation, and comprehensive graph analytics—all while working directly with your existing markdown files.

Key Features

🔍 Intelligent Search

• Hybrid Search: Combines semantic similarity with text matching and metadata relevance
• Semantic Understanding: Uses embeddings to find conceptually related content
• Advanced Filtering: Search by tags, paths, date ranges, and custom criteria
• Configurable Ranking: Adjust weights for different relevance signals

🌐 Knowledge Graph

• Automatic Link Detection: Supports WikiLinks [[Note]] and markdown links
• Tag Relationships: Hierarchical tags with co-occurrence tracking
• Graph Analytics: PageRank, community detection, and centrality metrics
• Path Analysis: Find connections between any two pieces of content

📝 Content Management

• Multi-Vault Support: Manage multiple knowledge bases simultaneously
• Template System: Automatic content scaffolding based on file paths
• Validation Rules: Ensure content quality with built-in and custom rules
• Real-time Sync: Automatic indexing as you edit files

🤖 AI Integration

• 25+ MCP Tools: Comprehensive interface for AI assistants
• Structured Responses: Consistent, machine-readable outputs
• Bulk Operations: Efficient batch processing for large tasks
• Error Handling: Clear, actionable error messages

Installation

Global Installation

npm install -g mcp-mycelium

Local Usage

npx mcp-mycelium ./my-vault

Quick Start

1. Initialize a New Vault

mcp-mycelium init ./my-knowledge-base
cd my-knowledge-base

2. Start the MCP Server

mcp-mycelium ./my-knowledge-base

3. Configure Your AI Client

Add to your MCP client configuration:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "mcp-mycelium",
      "args": ["./my-knowledge-base"]
    }
  }
}

Usage Examples

Basic Operations

# Multiple vaults
mcp-mycelium ./work-notes ./personal-notes

# Custom configuration
mcp-mycelium --config ./config ./vault1 ./vault2

# Validation and maintenance
mcp-mycelium validate ./my-vault --fix
mcp-mycelium reindex ./my-vault --embeddings

MCP Tools

Once connected, AI assistants can use tools like:

• search_content - Find relevant content across your knowledge base
• get_backlinks - Discover connections between notes
• analyze_communities - Find clusters of related content
• suggest_tags - Get AI-powered tag recommendations
• validate_file - Check content quality and consistency

Configuration

Global Settings (config/settings.yaml)

server:
  embeddings:
    provider: "local"  # or "openai"
    model: "all-MiniLM-L6-v2"
  search:
    ranking_weights:
      semantic: 0.4
      tags: 0.3
      recency: 0.2
      backlinks: 0.1

Vault-Specific Config (config/vaults/my-vault.yaml)

name: "My Knowledge Base"
templates:
  - pattern: "^daily/\\d{4}-\\d{2}-\\d{2}\\.md$"
    frontmatter:
      required: ["date", "mood"]
    content_template: |
      ## Today's Focus
      
      ## Accomplishments
      
      ## Tomorrow's Plan

Architecture

MCP Mycelium is built with a modular architecture:

• Vault Manager: Coordinates multiple knowledge bases
• Indexer: Efficient content parsing and indexing
• Search Engine: Hybrid semantic and text search
• Graph Engine: Relationship analysis and metrics
• Template Engine: Content consistency and scaffolding
• Validation System: Quality assurance with custom rules

Performance

Designed for large knowledge bases:

• ✅ Index 1000+ files in under 30 seconds
• ✅ Search responses under 500ms
• ✅ Real-time updates with debounced batching
• ✅ Memory-efficient with configurable limits
• ✅ Concurrent request handling

Embedding Providers

Local Models (Default)

• Privacy: No data leaves your machine
• Cost: Free to use
• Setup: Automatic with sentence-transformers
• Quality: Good for most use cases

OpenAI API

• Quality: State-of-the-art embeddings
• Speed: Fast cloud processing
• Cost: Pay per token
• Setup: Requires API key

Development

Build from Source

git clone https://github.com/your-org/mcp-mycelium
cd mcp-mycelium
npm install
npm run build

Run Tests

npm test
npm run test:coverage
npm run test:performance

Type Checking

npm run typecheck
npm run lint

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run the full test suite
5. Submit a pull request

Roadmap

v1.1

• Vector database backends (Pinecone, Weaviate)
• Advanced graph visualizations
• Custom embedding model support
• Plugin system for extensions

v1.2

• Collaborative features
• Version control integration
• Advanced analytics dashboard
• Mobile companion app

Support

• Documentation: Full documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Community Discord

License

MIT License - see for details.

Acknowledgments

• Built on the Model Context Protocol
• Powered by sentence-transformers
• Inspired by tools like Obsidian, Roam Research, and Logseq